Experiment with ads in v201101

When introduced last year, AdWords Campaign Experiments (ACE) allowed for experimental changes to be applied to ad groups and criteria. To allow for even greater flexibility, in v201101 we’ve added the ability to apply experimental changes to individual ads as well. Just like other entities, experiment data can be added to an AdGroupAd to indicates its status in the experiment. For example, the following code can be used to add an existing ad to the experimental split.

// Create ad using an existing ID.
$ad = new Ad();
$ad->id = $adId;

// Create ad group ad.
$adGroupAd = new AdGroupAd();
$adGroupAd->adGroupId = $adGroupId;
$adGroupAd->ad = $ad;
$adGroupAd->status = 'ENABLED';

// Create experiment data for experiment-only split.
$experimentData = new AdGroupAdExperimentData();
$experimentData->experimentId = $experimentId;
$experimentData->experimentDeltaStatus = 'EXPERIMENT_ONLY';
$adGroupAd->experimentData = $experimentData;

// Create operation.
$operation = new AdGroupAdOperation();
$operation->operator = 'SET';
$operation->operand = $adGroupAd;
$operations = array($operation);

// Update ad.
$result = $adGroupAdService->mutate($operations);

Experiment data can only be used to include or exclude an ad from an experiment; all other properties of the ad will remain the same. If you have any questions about setting up experiments with the API you can ask us on the forum.

- Eric Koleda, 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

Discover v201008: Product ads and criteria

We’ve recently released additional product advertising options in Google AdWords, and have exposed features in AdWords API v201008 to enable you to leverage these new ad formats. Product extensions enhance your existing text ads with relevant production information, while product listing ads expose your entire product catalog with minimal setup and maintenance. You can read further about the differences between these ad formats here.

In this post we’ll discuss how product ads can be created using the API. Note: both features require that you first link your Google Merchant Center account to your AdWords account. This is done through the Google Merchant Center web interface using these instructions.

Product extensions

Like other extensions, product extensions are represented as CampaignAdExtensions using the type ProductExtension. The CampaignAdExtensionService can be used to retrieve or delete product extensions, but at this time they can only be created through the AdWords web interface. Once they have been created they will be automatically applied to all text ads in the campaign, and utilize existing keyword targeting.

Product listing ads

The API type ProductAd corresponds to a product listing ad, and can be manipulated using the AdGroupAdService. Unlike other ad types, a majority of the information displayed in the ad is not stored in the AdWords system but is pulled from the Google Merchant Center when the ad is served. For this reason the ad is very simple, introducing only an optional promotionLine field. Additionally, the fields url and displayUrl aren’t supported for product listing ads, as these values are populated based on the product that is being shown.

The Product criterion (known as a “product target” in the web interface) is what allows you to control which products are eligible to be shown with a product listing ad and what the bid should be for those products. This criterion contains conditional rules used to filter your product catalog, limited to the following product attributes: product_type, brand, adwords_grouping, condition, and adwords_labels. It’s worth noting that a single Product criterion usually corresponds to multiple different products in the catalog.

Let’s take the example of a merchant that wants to advertise their line of store-made premium chocolates for Valentine’s day. Using the PHP client library they would first add the product listing ad to the ad group, with a promotional message for the holiday.

// Create product listing ad.
$productAd = new ProductAd();
$productAd->promotionLine = 'Order some sweets for your sweet!';

// Create ad group ad.
$adGroupAd = new AdGroupAd();
$adGroupAd->adGroupId = $adGroupId;
$adGroupAd->ad = $productAd;

// Create operation.
$operation = new AdGroupAdOperation();
$operation->operand = $adGroupAd;
$operation->operator = 'ADD';
$operations = array($operation);

// Add ad.
$result = $adGroupAdService->mutate($operations);

They would then add a product criterion to the ad group, filtering for products that are chocolates in their premium brand.

// Create product conditions.
$productTypeCondition = new ProductCondition('Chocolate',
new ProductConditionOperand('product_type'));
$brandCondition = new ProductCondition('Acme Premium',
new ProductConditionOperand('brand'));

// Create product criterion.
$product = new Product();
$product->conditions = array($productTypeCondition, $brandCondition);

// Create biddable ad group criterion.
$adGroupCriterion = new BiddableAdGroupCriterion();
$adGroupCriterion->adGroupId = $adGroupId;
$adGroupCriterion->criterion = $product;

// Create operation.
$operation = new AdGroupCriterionOperation();
$operation->operand = $adGroupCriterion;
$operation->operator = 'ADD';
$operations = array($operation);

// Add ad group criteria.
$result = $adGroupCriterionService->mutate($operations);

Using only this single ad and criterion all of their premium chocolates are ready to be advertised.

Additional information on how you can set up your campaigns to use product listing ads is available here. If you have any question about how to use product ad features in the API you can reach us on the forum.

Best,
- Eric Koleda, AdWords API Team

Reintroducing Video Ads

Back in 2007, we first introduced support for video ads (Click-to-Play Video) in the AdWords API. This required a dedicated VideoAd type, which made it less adaptive to future video formats. The AdWords API has significantly improved since then with more flexible support for handling various ad types.

Video ads in the API are now supported through a new type, the TemplateAd. Template ads allow for an easy way to introduce new ad types, defined through template ad formats, without having to add new ad types. In turn, this makes it possible to release new ad features and updates much faster without waiting for the next version of the API.

Before a video ad can be created, the campaign must be set to show ads on the content network. As in previous versions, the video itself must be uploaded to your account via the web interface (see instructions). Once your video is uploaded, it is assigned a media ID, one of the elements required to create a video ad, which can be retrieved through the MediaService’s get() method. Now you have everything you need to create a video ad via the AdGroupAdService using the Click-to-Play Video template ad format. The client libraries have examples for retrieving a media ID and creating video

ads in various languages. Here’s an example in Python,

operations = [
    {
        'operator': 'ADD',
        'operand': {
            'type': 'AdGroupAd',
            'adGroupId': ad_group_id,
            'ad': {
                'type': 'TemplateAd',
                'templateId': '9',
                'templateElements': [{
                    'uniqueName': 'adData',
                    'fields': [
                        {
                            'name': 'startImage',
                            'type': 'IMAGE',
                            'fieldMedia': {
                                'mediaTypeDb': 'IMAGE',
                                'name': 'Starting Image',
                                'data': image_data
                            }
                        },
                        {
                            'name': 'displayUrlColor',
                            'type': 'ENUM',
                            'fieldText': '#ffffff'
                        },
                        {
                            'name': 'video',
                            'type': 'VIDEO',
                            'fieldMedia': {
                                'mediaId': video_media_id,
                                'mediaTypeDb': 'VIDEO'
                            }
                        }
                    ]
                }],
                'dimensions': {
                    'width': '300',
                    'height': '250'
                },
                'name': 'VideoAdTemplateExample',
                'url': 'http://www.example.com',
                'displayUrl': 'www.example.com'
            }
        }
    }
]
ads = ad_group_ad_service.Mutate(operations)

As always, post any questions you have regarding this topic or other aspects of the API to the forum.

-- Stan Grinberg, AdWords API Team

Discover v2009: New Ad Types

The release of the new v200909 included a number of improvements and new features. Among these additions are new ad types: DeprecatedAd, LocalBusinessAd, MobileImageAd, and TemplateAd, which are all part of the AdGroupAdService.

DeprecatedAd:
The idea behind deprecated ads is to have a consistency in returning ads that are no longer supported. For example, if your ad group has a Click To Call ad (this ad format was deprecated on Dec. 3, 2007) and you try to fetch this particular ad via API, we will return it as a DeprecatedAd type and allow you to delete it. This is a quick and easy way for cleaning up your outdated inventory using API.

Note that deprecated ads can be deleted, but can not be created.

MobileImageAd:
This is a new format of ads that can appear on mobile websites. When users click on your ad, they will be sent to your mobile webpage. Below is a Python snippet of code that shows how to add a mobile image ad for T-Mobile and Verizon carriers in US.

  operations = [{
    'operator': 'ADD',
    'operand': {
      'type': 'AdGroupAd',
      'adGroupId': '123456789',
      'ad': {
        'type': 'MobileImageAd',
        'markupLanguages': ['HTML'],
        'mobileCarriers': ['T-Mobile@US', 'Verizon@US'],
        'image': {
          'dimensions': [{
            'key': 'SHRUNKEN',
            'value': {'width': '192', 'height': '53'}
          }],
          'name': 'image_192x53.jpg',
          'data': MOBILE_IMAGE_DATA
        },
        'url': 'http://www.mywebsite.com/mobile',
        'displayUrl': 'www.mywebsite.com'
      }
    }
  }]
  ad_group_ad_service.Mutate(operations)

LocalBusinessAd:

This ad type represents a legacy local business ad format. When edited via the AdWords interface, the legacy ad will be converted to create a new text ad with ad-level location extension and the original local business ad will be deleted. The location extension itself is created at campaign level with the association for that ad at the ad-level. The usage of the LocalBusinessAd format will allow you to perform the conversion via API of your existing legacy local business ads into the new location extensions. We plan to spend more time talking about the new location extension format in one of our upcoming posts.

Note that local business ads can be deleted or paused/unpaused, but can not be modified.

TemplateAd:
The template ad is an easy way to add new formats to the AdWords interface. In a nutshell, we come up with an idea for an ad format, a set of required input data elements is created, and that's all. There is now a new ad format that is available in AdWords.

Note that template ads run only on content network.

To help you get started, we've included support for these and other ad types in our client libraries. As always, we are here to answer your questions, collect feedback, and assist with migration to v200909 of the AdWords API.

Keep an eye on the blog for the next part of the "Discover v2009" series.

--Stan Grinberg, AdWords API Team