Google AdWords and DoubleClick Ad Exchange Buyer Client Library

Welcome to the next generation Google-developed Ruby client library for the AdWords and DoubleClick Ad Exchange Buyer API!

Please note that this is an early PREVIEW of the client library, still under development.

It contains full support for v13, v200909, v201003, v201008 and v201101, with full stubs, and a simplified programming interface that lets you handle everything in native Ruby collections, instead of forcing you to deal with SOAP library-generated objects.

Docs for Users

1 - Installation:

google-adwords-api and google-adx-buyer-api are ruby gems.

See http://docs.rubygems.org/read/book/1

Install them using the gem install command:

$ gem install --remote google-adwords-api
$ gem install --remote google-adx-buyer-api

Please note the google-adx-buyer-api gem contains only DoubleClick Ad Exchange Buyer client library examples. You need the AdWords library in order to use it which is installed automatically as a dependency.

The following gem libraries are required:

  • soap4r v1.5.8

  • httpclient v2.1.2 or greater

  • google-ads-common v0.4.0 or later.

2 - Using the client library:

It’s pretty easy to use. See docs.rubygems.org/read/chapter/3#page70 for how to set the rubygem environment.

$ export RUBYOPT=rubygems

or

$ ruby -rubygems my_program_that_uses_gems

If you are running Ruby 1.8 and do not use the rubygems option, you need to add

require 'rubygems'

at the beginning of your programs.

Then:

gem 'google-adwords-api'
require 'adwords_api'

adwords = AdwordsApi::Api.new

creates an Api object that will grant you access to all the services for all of the currently supported vesions of the APIs. It uses a config file in: ENV/adwords_api.yml to read all of your configurations. There is an example configuration file shipped with these libraries.

You can also pass API a manually constructed config hash like:

adwords = AdwordsApi::Api.new({
  :authentication => {
      :method => 'ClientLogin',
      :developer_token => 'DEVELOPER_TOKEN',
      :user_agent => 'Ruby Sample',
      :password => 'PASSWORD',
      :email => '[email protected]',
      :client_email => '[email protected]'
  },
  :service => {
    :environment => 'PRODUCTION'
  }
})

Then, just specify which service you’re looking to use, and which version:

campaign_srv = adwords.service(:CampaignService, :v201101)

and you should now be able to just use the API methods in the object you were returned:

campaigns = campaign_srv.get({})    # Empty selector to get all

See the code in the examples directory for working examples you can build from.

Note: if your setup requires you to send connections through a proxy server, please set the appropriate options in the config file or config hash. E.g.:

config[:connection] = {
  :proxy => 'http://user:password@proxy_hostname:8080/path'
}

2.1 - Ruby names for a Ruby library:

In order to make things more Ruby-like for our Ruby developers, we’ve renamed API objects and methods to more closely match Ruby conventions. This means using snake_case for methods and parameters, and UpperCamelCase for class names.

For example, the ‘getReportFields’ method of the ReportDefinitionService is named ‘get_report_fields’ in the client library. You invoke it by doing:

response = report_def_srv.get_report_fields(report_type)

The ‘get’ method, on the other hand, returns a ReportDefinitionPage object which has an ‘entries’ and a ‘total_num_entries’ field. So, to access the return values, you would do:

response = report_def_srv.get(selector)
num_entries = response[:total_num_entries]

Essentially, all you have to do is follow Ruby conventions, and the library will do the rest. All of the examples are written following this standard.

If, however, you would prefer to use the names as provided in the AdWords documentation, please disable the ‘use_ruby_names’ option under the ‘service’ category in the config:

config[:service][:use_ruby_names] = false

Disabling Ruby names is an experimental feature, and it is not recommended.

2.2 - Using the Sandbox:

In order to use the sandbox, make sure that the ‘environment’ parameter under ‘service’ in the configuration is set to Sandbox.

config[:service] = {
  :environment => 'SANDBOX'
}

2.3 - Logging:

It is often useful to see a trace of the raw SOAP XML being sent and received. The quickest way of achieving this when debugging your application is by setting the library.log_level configuration variable to ‘DEBUG’:

config[:library] = {
  :log_level => 'DEBUG'
}

or via configuration file (see example).

This will output the SOAP XML to stderr, which will usually show up in your terminal window.

There’s also an option of logging requests and XML to a file. In order to enable this, you should create a standard Logger object and pass it to the library:

require 'logger'
logger = Logger.new('path/to/log_filename')
logger.level = Logger::DEBUG
adwords = AdwordsApi::Api.new
adwords.logger = logger

Request details and units spend are logged at the INFO log level, while raw HTTP headers and XML dumps are logged at the DEBUG log level. For more details on using Logger refer to the Ruby Logger documentation.

Docs for Developers

Rake targets

$ rake getwsdl

to get the wsdl files

$ rake generate

to regenerate the bindings if needed

$ rake package

to package the gem and create a release

$ rake test

to run unit tests on the library

Where do I submit bug reports and feature requests?

Bug reports and feature requests can be posted on the library page:

http://code.google.com/p/google-api-ads-ruby/issues

Questions can be asked on forum

http://groups.google.com/group/adwords-api

Copyright/License Info

Licence

Copyright 2011, Google Inc. All Rights Reserved.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Authors

Authors:

api.sgomes (Sérgio Gomes)
api.dklimkin@gmail.com (Danial Klimkin)

Maintainer:

api.dklimkin@gmail.com (Danial Klimkin)