Client Library Updates

We have recently made the following changes to the AdWords client libraries.

Ruby

• Made performance improvements.
• Added unit spend information to responses.
• Added support for Proxy servers.

Python

• Updated common module to version 2.1.0, which may impact your code. See the ChangeLog for more details.
• Fixed issues 161, 162, 163 in version 14.2.3.
• Added a tarball in the download section that collects all the required modules for this client library into a single download with an installer script.

You can download updated versions of the AdWords API client libraries from their respective sites, or see a list of all the client libraries.

If you have any questions or would like to discuss these changes, please post on the forum.

Kevin Winter, AdWords API Team

Resolving Conflicts after Google Apps Account Migration

Recently, we have migrated the Google Apps accounts to a new infrastructure that includes all Personal Google accounts. This has introduced a conflict for API users who have the same email address for both types of accounts. As a result, you will not be able to generate a ClientLogin token and will be presented with an error message such as “Either this object does not exist, or this user does not have permission to access it”, “Invalid client email specified” or an AuthenticationError.CLIENT_EMAIL_INVALID in the SOAP response. You can also verify whether your account is in conflict by making a request directly to the Client Login API.

Request:
https://www.google.com/accounts/ClientLogin?accountType=GOOGLE&Email=my_email_address&Passwd=my_password

Response:
Error=Unknown
Url=https://www.google.com/accounts/ErrorMsg?Email=my_email_address&service=gam&id=unknown

Before the migration, it was possible to have a Google Apps account with your domain (jane@altostrat.com) and a Personal Google account for AdWords, Picasa, Reader, etc. with the same email address. With the new infrastructure, both types of accounts are in one unified system so when you try to generate a ClientLogin token with jane@altostrat.com, we do not know which account you are trying to use. More details about conflicting accounts can be found at the Google Accounts Help Article.

To differentiate between your conflicting accounts, we have created a temporary account (jane%altostrat.com@gtempaccount.com) for you to temporarily hold your data. You can log into http://www.google.com/accounts with your gtempaccount and use the wizard to resolve your conflicts. A full walkthrough on the data migration wizard can be found at the Data Migration Getting Started Guide.

Please note that this issue will only affect tools built using clientEmail as a header to identify accounts. If you use clientCustomerId, the tool will not be affected. We recommend using clientCustomerId instead of clientEmail as a best practice.

As always, please post any questions to the forum.

Kevin Winter, AdWords API Team

Tablet Targeting in v201101

Last month the device targeting options in AdWords were expanded to include new settings for tablets.  Previously tablets had counted as mobile devices, with the iPad listed as one such device.  The AdWords API worked the same way, using the PlatformTarget HIGH_END_MOBILE for both mobile devices and tablets and the MobilePlatformTarget "iPad" for the iPad specifically.  Representing these new tablet settings in the current v201101 version of the API is tricky, and in this blog post we’ll cover the behavior you can expect.

The first thing to note is that there is no PlatformTarget that represents tablets, since enum values can’t be added to an existing version.  You can look at the MobilePlatformTargets returned to get a better idea of what’s being targeted, but be aware that the meaning of some of the values have changed.  Specifically, the value "iPad" now represents any tablet, and the value "iPhone" represents any iOS device.

The tables below show the PlatformTargets and MobilePlatformTargets returned for every combination of device and operating system that can be set in the UI.

	Computers	Mobile	Tablets
Android	DESKTOP (None)	HIGH_END_MOBILE Android	HIGH_END_MOBILE Android, iPad
iOS	DESKTOP (None)	HIGH_END_MOBILE iPhone	HIGH_END_MOBILE iPhone, iPad
webOS	DESKTOP (None)	HIGH_END_MOBILE Palm	HIGH_END_MOBILE Palm, iPad
All	DESKTOP (None)	HIGH_END_MOBILE (None)	HIGH_END_MOBILE iPad

	Computers & Mobile	Computers & Tablets	Mobile & Tablets	All
Android	(None) Android	DESKTOP Android, iPad	HIGH_END_MOBILE Android, iPad	(None) Android, iPad
iOS	(None) iPhone	DESKTOP iPhone, iPad	HIGH_END_MOBILE iPhone, iPad	(None) iPhone, iPad
webOS	(None) Palm	DESKTOP Palm, iPad	HIGH_END_MOBILE Palm, iPad	(None) Palm, iPad
All	(None) (None)	DESKTOP (None)	HIGH_END_MOBILE (None)	(None) (None)

As you can see there are certain states in the UI that appear identical in the API. This is unfortunate behavior that is due to the limited values available in the current version of the API.  Specifically, it’s not possible to distinguish:

1. Tablets vs. Mobile & Tablets
2. Mobile with all operating systems vs. Mobile & Tablets with all operating systems
3. Computers vs. Computers & Tablets with all operating systems
4. Computer & Mobile with all operating systems vs. All devices with all operating systems

Likewise, using these values in a mutate request may inadvertently change the targeting options of the campaign since the system will always apply the broadest targeting that matches the input.  For example, let’s say you have a campaign that was configured in the AdWords web interface to target just Android tablets.  If you called CampaignTargetService.get() you would get back the PlatformTarget "HIGH_END_MOBILE" and the MobilePlatformTargets "Android" and "iPad".  If you then call CampaignTargetService.mutate()using those same values, the campaign will be updated to target both tablets and mobile devices that run Android.

What this means is that there are certain targeting combinations that can’t be determined or applied accurately in the v201101 version of the API.  In the next version of the API we plan to update these target types to support the new tablet settings, which will make reading and writing these combinations much simpler.  As always, if you have any questions about this topic you can reach us on the AdWords API forum.

- Eric Koleda, AdWords API Team

Client Library Updates

This is another edition of our bi-weekly client library updates blog post.

DotNet

• Client library now supports OAuth 1.0a as an authentication mechanism.
• Added support for caching authTokens.
• Will now automatically retry for GOOGLE_ACCOUNT_COOKIE_INVALID error.
• Additionally, a number of issues were fixed: 51, 62, and 65.

PHP

• Support has been added to generate classes from the WSDL using pseudo-namespaces, to avoid conflicts with other classes. The library must be built from source with this option. Please see the README for more information. This addresses issue 4.
• Improved type conversion to better handle ID values on 32-bit systems. This addresses issue 62.

Ruby

• First release based on Savon backend (0.4.0).
• Includes OAuth 1.0a support and Ruby 1.9 compatibility.

You can download updated versions of the AdWords API client libraries from their respective sites, or see a list of all the client libraries.

If you have any questions or would like to discuss these changes, please post on the forum.

Kevin Winter, AdWords API Team

Fine grained partial failure in the BulkMutateJobService

Since its introduction the BulkMutateJobService has provided support for partial failures, allowing some operations to succeed even though others have failed. Over the next few weeks we'll be rolling out improvements to this functionality, allowing for more granular failures when possible.

Bulk mutate jobs process operations in batches, and a failed operation will cause the entire batch to fail, but not the rest of the job. The results for a failed batch start with a FailureResult that holds all the errors generated by the operations in that batch. It is followed by a series of BatchFailureResults which act as placeholders for the rest of the operations in the batch. More information about how these failures are reported can be found in a previous blog post we did on the topic.

In v201008 we enabled partial failure support for the synchronous AdGroupCriterionService. Unlike the behavior in the BulkMutateJobService, this version of partial failure allows individual operations to fail without affecting successful ones. This method of partial failure is preferred as it cuts down on the number of retries needed.

While we can't update the BulkMutateJobService to process all operations this way, we are able to enable it for operations that use an underlying service that does support granular partial failures. Starting August 1st, operations of type AdGroupCriterionOperation and AdGroupAdOperation processed by the BulkMutateJobService may start failing granularly instead of in batches.

Let's see how this will change the results returned.

Existing partial failure behavior

Operation	Result
AdGroupCriterionOperation	FailureResult cause.errors[0].fieldPath = "operations[1]..." cause.errors[1].fieldPath = "operations[2]..."
AdGroupCriterionOperation (Invalid)	BatchFailureResult operationIndexInBatch = 1
AdGroupCriterionOperation (Invalid)	BatchFailureResult operationIndexInBatch = 2
AdGroupCriterionOperation	BatchFailureResult operationIndexInBatch = 3

Before the change the invalid operations will cause other valid operations to fail. The FailureResult is the first result in the batch, even if the operation at the position was valid. The field path of the errors indicates the index of the invalid operations relative to the start of the batch.

New granular partial failure behavior

Operation	Result
AdGroupCriterionOperation	ReturnValueResult
AdGroupCriterionOperation (Invalid)	FailureResult cause.errors[0].fieldPath = "operations[0]..."
AdGroupCriterionOperation (Invalid)	FailureResult cause.errors[0].fieldPath = "operations[0]..."
AdGroupCriterionOperation	ReturnValueResult

After the change invalid operations will not affect other valid operations in the same batch. Each invalid operation will have a corresponding FailureResult. There may still be cases where BatchFailureResults are returned for these operations, such as if there is a general error with the account that cannot be attributed to any specific operation.

So how does this affect code you've already written to process BulkMutateJob results? The good news is that if you've written your code to allow for a variable batch size (no hard coded batch size) then no changes are needed! Invalid operations are essentially processed as batches of one, and the same logic that you use to process the results today should work perfectly with these new granular failures. If your application is currently expecting a batch of a specific size then you should update it to detect the start and end of batches dynamically.

If you have any questions about how these new granular failures work, or feedback on how we can further improve the error handling in the API, add a post to the AdWords API forum.

Update 2011-08-25
This change has been fully deployed and all BulkMutateJobs will be processed with granular partial failures enabled.

- Eric Koleda, AdWords API Team

Discover v201101: Experiment Reports

Back in September of 2010, we added support to manage AdWords Campaign Experiments (ACE) via the API. With the release of v201101, we are extending the API to allow you to fully manage your experiments, as we’ve included new experiment fields for use in reports. You can now segment your report statistics by the experiment splits as well as obtain experiment statistical significance on every statistical field (i.e. clicks, impressions, conversions, etc).

Segmentation

A new field called AdvertiserExperimentSegmentationBin is now available for you to segment your report rows in OUTSIDE_OF_EXPERIMENT, CONTROL and EXPERIMENT. Rows reported as OUTSIDE_OF_EXPERIMENT refer to statistics captured outside the experiment lifespan, which will occur when your report dateRange covers a broader time period than your experiment. Data reported as part of the CONTROL segment includes statistical values that belong to the percentage of traffic that you have configured as part of your control split. Likewise, values for the experimental split are reported with the EXPERIMENT value.

Keep in mind that adding AdvertiserExperimentSegmentationBin to your reports may potentially multiply their size by three, so make sure you use report predicates to control exactly what you want back and to define your reports in one of the GZIP compressed formats, if possible.

Statistical Significance

For every available statistical field (i.e. Clicks, Impressions, Conversions, CPC, CPM, etc) a Statistical Significance field pair is now available for you to use in some reports. These new field pairs have, with a few exceptions, the form of [field singular name]Significance, so for example Clicks has ClickSignificance as its pair. For more information about the available Statistical Significance fields per report see our Report Types page.

Significance fields have a specific range of values that goes from -3 to 3, values that correspond to three
, two and one (down and up) arrows respectively in the AdWords interface, while 0 is represented by a grayed up and down arrow.  To learn more about  Statistical Significance and its meaning visit our Help Center FAQ page. Also keep in mind that negative values don’t mean your experiment isn’t going as expected since fields that imply cost, like CPC, you most likely want to have a negative variation.

Life of your experiment data

Your experiment segmented statistics will exist as long as your experiment does, so as soon as your experiment is either promoted or deleted you will no longer able to retrieve experiment statistics. Hence, we recommend you download a last set of experiment reports right before the experiment gets promoted or deleted.

Reports Types Included

AdWords Campaign Experiments are applied at the Campaign level, therefore reports that apply to Campaigns, AdGroups, Ads and Keywords have included experiment specific fields. Specifically, the following reports have been enhanced with experiment fields: Ad Performance, Ad Group Performance, Campaign Performance, Keyword Performance and Managed Placements Performance.

As always, feel free to contact us at the AdWords API Forum.

- David Torres, AdWords API Team

Client Library Updates

We often make changes to the AdWords API client libraries that do not merit a full blog post. We’d like to start publishing a summary blog post every other week to highlight changes that might otherwise go unnoticed.

Python

• Added support for OAuth as an authentication mechanism. This will allow developers to access the API without requiring a username and password. See the new code example for more information on how to integrate OAuth with your application.
• Additionally, a number of issues were fixed: 115, 142, 144, and 145.

Perl

• Fixed some bugs that prevented usage of multiple Client objects.
• Full XPath support was added; XPath queries can now be done through the entire tree of results.
• OAuth support was also added.

Ruby

• Improved support for UTF reports in download extensions.
• New logger interface.
• Updates have been made to the code examples.

PHP

• Updated OAuth support to allow for alternative OAuth libraries, including the bundled Andy Smith library.
• The logging functionality has been updated to support filtering for levels. The default logging behavior has been changed to only log SOAP XML if an error occurs.
• New methods were added to AdWordsUser for additional logging configuration. The AdWords Get*Service() methods were replaced with a single GetService() method. Backwards compatibility was maintained using __call(). All examples and tests were updated to use the new method.
• Additionally, 2 issues were fixed: 55 and 59.

You can download updated versions of the AdWords API client libraries from their respective sites, or see a list of all the client libraries using this link.

If you have any questions or would like to discuss these changes, please post on the forum.

Kevin Winter, AdWords API Team