AdWords Position Preference feature is being retired

As part of the retirement of the Position Preference bidding feature, this feature can no longer be enabled via the AdWords API.

Starting tomorrow, calling CampaignService with BiddingStrategy ManualCPC.PositionPreference set to ON will return the error

BiddingError.POSITION_PREFERENCE_NOT_ENABLED.

This feature can still be used, however, to disable Position preference for a campaign.

Then, starting in May, the PositionPreference field will be disabled entirely, meaning that calling CampaignService with BiddingStrategy ManualCPC.PositionPreference set to any value will return the error BiddingError.POSITION_PREFERENCE_NOT_ENABLED. This change is timed to coincide with the removal of the feature from the AdWords web interface.

We appreciate your understanding and your continued support of AdWords.

As always, please post any questions to the AdWords API Forum

Posted by Stan Grinberg, AdWords API Team

Concurrency Management in the AdWords API

Has a call from your application ever returned a CONCURRENT_MODIFICATION error but you can’t figure out why? Let’s look at concurrency management in the API to understand what might have happened.

The AdWords API uses an optimistic concurrency control mechanism.  When the server begins to process a request, it checkpoints the current state of the relevant account, then executes the business logic and validation rules in the request.  Before committing the requested change, the server again checkpoints the account. If the “before and after” checks don’t match, the server returns a concurrency error to ensure that the request doesn’t introduce data inconsistency.

A concurrency issue occurs when two different applications or two different instances or threads of the same application attempt to change a single piece of data at the same time. Let’s say that request1 and request2 both want to operate on the same original version of some data. If request1 changes the data first and is committed, request2 becomes invalid, because it’s trying to operate on data that is now out-of-date.

A concurrency issue doesn’t occur only when your application tries to modify an entity that’s changed during processing. A problem can also occur if the entity that your request modifies has a dependency on another entity that’s been changed.  For example, an ad group entity references a campaign. If your request modifies an ad group and the referenced campaign is modified while your request is executing, you’ll get an error.   

In an exception to this general rule, we’ve recently introduced the ability to make concurrent changes to some services, such as AdGroupCriterionService and AdGroupAdService. However, the principle still applies at the field level: field-level changes are exclusive to one request at a time.

In the past, you might have gotten a CONCURRENT_MODIFICATION error even when using a single-threaded application to modify one account at a time. The problem was likely due to background processing, such as approvals, which also modified the account’s entities. We’ve made some changes that should reduce the likelihood of these errors occurring

To summarize, when you get a concurrency error, consider whether the application has done one of the following:

• Run multiple threads that attempted to modify the same entity
• Modified an entity on which another entity is dependent 

As always, if you have more questions, feel free to post them to AdWords API Forum.

Posted by Dan H. and Nina Silk, AdWords API Team

Understand errors with the new troubleshooting guide

One of the most critical and complicated aspects of using an API is error handling. To help address this, we’ve included detailed information about each type of error in the reference documentation and posted articles discussing general error handling best practices. While these resources are great at helping to determine what the an error is, we’ve heard from you on the forum that they often don’t provide enough context as to why the error occurred and what you can do to prevent it in the future.

With this in mind, we’ve put together a new troubleshooting guide for the most common errors in the AdWords API. Each error includes a brief summary of what went wrong, some common causes, a recommended tip for handling the error when it occurs, and steps you can take to prevent the error from occurring.

We hope that this guide will be your first stop when you get an error you haven’t encountered before. We’ll continue to update it based on community feedback and the errors you run into most often. If after reviewing these resources you still have questions, please post them to the forum.

Best,
- Eric Koleda, AdWords API Team