The basic usage of the client library is as follows:

## Installation

The recommended way to install the library is by using [Bundler](https://bundler.io/). Add a line
to your `Gemfile` (replacing `x.y.z` with the version number you want to use):

    gem 'google-ads-googleads', '~> x.y.z'

Then run:

    bundle install

This command uses Bundler to update your `Gemfile.lock`, locking to the exact
version of the gem and all dependencies of the gem that were installed. The
pessimistic version operator `"~> x.y.z"` ensures that `bundle install` or
`bundle update` only installs new patch versions in the `x.y.*` series, so you
must manually opt into new minor or major versions by updating your `Gemfile`.

### Other installation options

If you are not using Bundler, you can use one of these options:

1. Install this library using RubyGems:

       gem install google-ads-googleads

2. Download the gem from the [Releases page](https://github.com/googleads/google-ads-ruby/releases) and install it from the local
   file:

       gem install google-ads-googleads-[version].gem

## Set up authentication

To authenticate your API calls, configure your `google_ads_config.rb` file and
follow the instructions on the
[Authentication and authorization](https://developers.google.com/google-ads/api/docs/client-libs/ruby/authentication) page.

## Usage

Starting in `google-ads-googleads` v41.1.0, the gem supports Bundler
autorequire (`Bundler.require`). In versions prior to v41.1.0 (or when not
using `Bundler.require`), explicitly require the gem in your code:

    require 'google/ads/google_ads'

Initialize the client (which loads configuration from `~/google_ads_config.rb`
by default) and fetch a specific service, such as `CampaignService`:

    # Initialize the client using ~/google_ads_config.rb.
    client = Google::Ads::GoogleAds::GoogleAdsClient.new

    # Fetch the CampaignService client.
    campaign_service = client.service.campaign

See the [examples on GitHub](https://github.com/googleads/google-ads-ruby/blob/HEAD/examples) for more detailed demonstrations of how to use
the library.

After you're familiar with the examples, explore
[factories](https://developers.google.com/google-ads/api/docs/client-libs/ruby/factories), which provide a set of
high-level convenience methods for working with the Google Ads API.

## Error handling

Not every API call succeeds. The server raises exceptions if your API calls
fail. It is important to capture API errors and handle them appropriately.

A `Google::Ads::GoogleAds::Errors::GoogleAdsError` instance is raised when an
API error occurs. It contains details to help you determine what went wrong, and
you can set up a helper function to handle the errors. See an example of an
[error handler on GitHub](https://github.com/googleads/google-ads-ruby/blob/HEAD/examples/shared/error_handler.rb).