Introducing MCC accounts multiple links feature

Wednesday, June 29, 2011


We’ve just released a new My Client Center (MCC) feature called multiple links, which makes it easier for agencies, SEMs, AdWords API developers, other 3rd party providers and clients to work together while taking advantage of the benefits of the MCC structure. It enables up to five MCCs to link to and manage a single AdWords account as necessary. Multiple links also removes the distinction that Google currently has between UI and API and API-only links.

Note this change affects Advertiser accounts only. MCC accounts can have only one manager as before.

Changes for the API users

There are a few API changes introduced by this new feature:
  • All new Account links are now of the UI_AND_API type. Existing API_ONLY links were not updated and are still valid as defined.
  • Every managing account with an API token will now receive 100% of free units (if eligible) for each linked client account based on its monthly spend. Previously, UI_AND_API type of links provided only 10% of free units quota.

For FAQ and billing-related information check out the AdWords Blog post.


Danial Klimkin, AdWords API Team.

Enhanced documentation for selectors and reports

Wednesday, June 22, 2011


We understand the importance of documentation when navigating a system as complex as the AdWords API; for this reason we’ve been working to expand our reference materials to include even more information.

First off, we’ve published a new Selector Fields page that provides information about the fields that can be used in generic selectors. This information was always available on an object’s individual reference page, but now we’ve aggregated it together across entire services for quicker lookups.


Additional information on how to migrate from the service-specific selectors used in versions v200909 through v201008 is available in the Selector Migration Reference.

Next, we’ve added more notes to the Report Types page to indicate which fields will prevent zero-impression rows from being returned in the downloaded report. In general, any field that is a property of an impression or click (such as the date, network, etc) will prevent rows with no impressions from being returned, but we decided to explicitly mark these fields so that the behavior is clear.


Finally, we’ve added new tips to our Best Practices Guide on topics such as deleting entities and using gzip compression. The guide is a great resource for developers starting an AdWords API project, but is also useful for established developers trying to increase the efficiency of their applications.

We’re always looking to expand and improve our documentation, so if you have any feedback for us please post it to the forum.

- Eric Koleda, AdWords API Team

AdWords API JavaScript library - Getting started

Friday, June 17, 2011


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

Statistics in reports

Tuesday, June 14, 2011


A common question for the AdWords API Team is “when is the best time to run reports” (and for that matter, when to retrieve statistical data via the API). The quick answer is: it depends on the type of data and report. Read on for details.

The reporting system is very complex and statistical data is not available in realtime. For most reports and API services, the statistical data for a given date is expected to stabilize three hours after midnight in the account's local time zone. The information below applies specifically to post-V13 reports.

For some reports, the underlying statistical data is populated in daily batch operations. These operations take a while to finish, which means the statistical data won’t be available as quickly. These reports will have their data ready at 6pm PST the following day and include the following:


All other reports should have their statistical data ready three hours after midnight in the account’s local time zone.

Conversions are a special case. Every day we start a batch process to recalculate all statistical data up until the job begins. This process will be complete by 6pm PST but will only include data up until 10am PST (when the process starts). Please note that since conversions can occur weeks later, these will never be completely stable, but will always take into account the latest data.

Note that due to ongoing operations such as click fraud detection, some of the data, such as clicks, may change for up to a month later. Statistical data is “frozen” on the first day of every month and will not change after this time, except for conversions that do not incur cost.

Please see this page for more information about reports. If you have any questions about using reports with the API, you can ask us on the forum.

Kevin Winter, AdWords API Team

New client library launch: AdWords API JavaScript library

Friday, June 10, 2011


We are excited to announce the release of a new AdWords API JavaScript client library. The AdWords API JavaScript library allows you to develop JavaScript applications and browser extensions that use the AdWords API. The client library is built using Google’s Closure library, and is compatible with other major JavaScript libraries like jQuery, Dojo, etc.

Getting the AdWords API JS library

The AdWords API JS library is listed on the AdWords API client libraries page, and is hosted at http://code.google.com/p/google-api-adwords-js.

The library distribution is available for download from the downloads page: http://code.google.com/p/google-api-adwords-js/downloads/list.

You can find installation and running instructions as well as usage examples on the project wiki page: http://code.google.com/p/google-api-adwords-js/wiki/Readme


Features

The following are the main features of the AdWords API JS library:

  • Full support for AdWords API versions v201008 and v201101.
  • Code examples for all the common AdWords tasks, similar to other client libraries.
  • Tested to work in Internet Explorer, Firefox, and Chrome. See the project wiki for details.
  • Includes minified JS scripts, compiled and optimized using the Closure compiler.
  • JSDoc documentation for the entire library.


Sample AdWords API JS Chrome extension

We believe that Chrome and Firefox browser extension developers will benefit most from this client library. Keeping this in mind, we developed a Chrome extension that allows an AdWords user to browse his Campaigns, Ad Groups, Ads and Keyword statistics. The extension is being made available as a code example at this address. You can refer to the wiki article at http://code.google.com/p/google-api-adwords-js/wiki/ObjectStatsExtensionReadme for details on its installation and use.






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 & David Torres, AdWords API Team.

Changes to Required Minimum Functionality for AdWords API Clients

Monday, June 06, 2011


Today we released the v060611 update to the Required Minimum Functionality (RMF) for AdWords API Clients. As a reminder, the goal of the RMF is to ensure that advertisers have access to many of the unique and valuable features that AdWords has to offer. We update the Required Minimum Functionality list approximately every six months, and the last update was over 9 months ago in August 2010.

Note: End-Advertiser-Only AdWords API Clients and Internal-Only AdWords API Clients (each as defined in the Terms & Conditions) are not required to fully implement the required AdWords API features outlined below, and described in detail here.

All other AdWords API Clients (as defined in the Terms & Conditions) must fully implement the required AdWords API features outlined below, and described in detail here, by October 15, 2011.

The key changes we have made in this update to the RMF are:
  • Added more features and report types
          We have added several features that we believe to be of high value for advertisers. These include sitelinks, conversion tracking, conversion optimizer, and enhanced CPC. We have also added new reports such as search performance and geographic reports.

  • Requirements for use of the BulkOpportunityService, TrafficEstimatorService and TargetingIdeaService
          BulkOpportunityService, TargetingIdeaService and TrafficEstimatorService are useful services to get new ideas for expanding and refining an AdWords account. We have added a requirement that if you use any of these services you must also implement creation functionality and management functionality for either Search or Display.

  • Advance Notice of Planned Changes
          We feel strongly that our advertisers should have the best possible user experience with AdWords and therefore have added the requirement that you send us mocks for any material changes to your tool at least 2 weeks in advance of making these changes. These mocks can be sent to: 3P-Compliance@google.com. Note that you don’t need to wait for approval to launch these changes.

More details on all these changes are available here. To maintain RMF compliance, all new required features must be added by October 15, 2011. If you have any questions about RMF please submit them to the forum.

Also, per our terms and conditions, Google retains the right to modify the terms and conditions at any time. In an ongoing effort to improve clarity, we have updated the AdWords API Terms & Conditions. For example, we are now more explicit in allowing third-party tools to enable bulk editing of common fields (like keyword bids, or campaign budgets) across networks. Please review the complete Terms & Conditions here. Note that continued use of the API means that you accept these terms. You can refuse to accept the terms by ceasing to use the API.

-The Google AdWords API Team