Friday, June 17, 2011

AdWords API JavaScript library - Getting started

Recently, we launched the AdWords API JavaScript Client library. This blog post discusses its basic usage by explaining the GetAllCampaigns example.

Including required scripts

AdWords API JS library comes with the following compiled scripts that you can include in your web page:
  • awapi.js: This is the AdWords API JS library, combined into a single script.
  • v201101.js: This is the compiled script for AdWords API v201101. There are compiled scripts for each supported API version.
  • config.js: This is optional; if included, you can define your application configuration in this file.
Importing the required types

To use any type provided by the AdWords API JS library, you need to import it. For instance, to import the CampaignService object, use
<script type="text/javascript">
  goog.require('google.ads.adwords.v201101.CampaignService');
</script>
All the goog.require statements should be put together in a single <script> tag.

Creating a User and obtaining a service instance

In the AdWords API JS library, each AdWords account is represented using a User object. The User object allows you to create various services provided by the AdWords API and make calls against the AdWords account associated with this user. The code to do this is given below:
var user = new google.ads.adwords.User();
var campaignService = user.getService(google.ads.adwords.AdWordsService.v201101.
    CampaignService);
The user takes a config object as its constructor argument. If you don't provide one, then the config definition from config.js is used.

Calling the method and displaying results

The code to construct a selector and get all the campaigns is shown below:
// Create a selector.
var selector = new google.ads.adwords.v201101.Selector();
selector.fields = ["Id", "Name", "Status"];

campaignService.get(selector,
    goog.bind(function(page) {
      if (page && page.entries && page.entries.length > 0) {
        for (var i = 0, len = page.entries.length; i < len; i++) {
          var campaignValue = page.entries[i];
          alert(goog.string.format('Campaign with id = "%s", name = "%s" ' +
              'and status = "%s" was found.', campaignValue.id,
              campaignValue.name, campaignValue.status));
        }
      } else {
        alert('No campaigns were found.');
      }
      callback();
    }, this),
    goog.bind(function(soapException) {
      alert(goog.string.format('Failed to get campaign(s). Soap Fault ' +
         'says "%s"', soapException.getInnerException().getFaultString()));
         callback();
    }, this)
);
The important thing to note here is that unlike other languages, JavaScript client library implements all API calls as asynchronous methods. Each method accepts an onSuccess callback and an onFailure callback which will be called when a call succeeds or fails respectively. The prototype of onSuccess and onFailure callbacks are as shown below:
function onSuccess(results) {
}

function onFailure(soapException) {
  // soapException is an object of type ApiException
}
Setting up an HttpWebTransport

To make the AdWords API calls, the client library needs to POST xml data to the AdWords API Server. The exact mechanism for making these calls depend on the environment your code is running. You can set an appropriate HttpWebTransport in your config.js to tell the client library how to make its calls to the AdWords API server. The relevant snippet is given below:
HttpWebTransport: 'google.system.net.HttpWebTransportForServerProxy',
HttpWebTransportSettings: {
   ProxyUrl: '/awapi-js-lib/proxy.php'
}
When writing code for a normal website, you need to use HttpWebTransportForServerProxy as transport mechanism. This HttpWebTransport forwards your calls through a server-side proxy script. This is required since all modern browsers implement same origin policy that prevents the library from making a cross-domain XmlHttpRequest.

When writing code for a Chrome extension, you can make cross-domain xhr calls, if the domain is specified in the manifest file. In such cases, you can use HttpWebTransportForExtensions instead. You can refer to the README file for details on various HttpWebTransports provided by the library.

Please join us on the AdWords API forum to discuss the new client library and the Chrome extension and report any bugs on the project’s issue tracker or forum.

  --Anash P. Oommen, AdWords API Team

at