Discover v2009: Setting ad parameters with the AdParamService

In a blog post yesterday we introduced ad parameters, a new AdWords feature that allows for dynamic insertion of numeric and currency values into ads while retaining ad history. To manage ad parameters, a new service was added to the v200909 API: the AdParamService.

In the example introduced earlier, you own a business selling antique cups that wants to add price and inventory information to your ads. To leverage ad parameters you create a text ad like:

and you configure the following ad parameters on your keywords:

keyword	param1	param2
antique cups	$80	18

A user searching for "antique cups" would will see the following ad text:

Text ads, even those with ad parameter placeholders, can be created using the normal methods of the AdGroupAdService. The AdParamService is only used for setting ad parameter values on keywords. This service allows for the getting and setting of AdParam objects, which contain the ad group ID and criterion ID for the target keyword, the insertion text, and the parameter index.

For example, to set the ad parameters for "antique cups" we would use the following PHP code (using the AdWords API PHP Client Library):

$adParam1 = new AdParam($adGroupId, $criterionId, '$80', 1);

$adParam2 = new AdParam($adGroupId, $criterionId, '18', 2);

$operation1 = new AdParamOperation($adParam1, 'SET');

$operation2 = new AdParamOperation($adParam2, 'SET');

$adParams = $adParamService->mutate(array($operation1, $operation2));

Existing ad params can be selected by ad group ID or by ad group ID and criterion ID. To get the ad parameters set above we would run the following:

$selector = new AdParamSelector(array($adGroupId), array($criterionId));

$adParamPage = AdParamServiceTest::$service->get($selector);

Some key points to remember about the ad parameters and the AdParamService are:

• Ad parameters are set on keywords, not ads.
• Ad parameters can only accept numerical and currency values, but the default text of the placeholder in the ad can be any string.
• The length of the default text in the placeholder contributes to the total length of the line in the ad, but the curly braces, parameters name, and colon do not.
• Ad parameters are 1-based indexed, meaning the two parameters are "1" and "2".
• The AdParamOperation should always use the "SET" operator, even when you are setting the parameters for the first time.

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

More Dynamic Ads with Ad parameters

We're excited to announce that a new feature of the v2009 API, called Ad parameters, is now available. Ad parameters enable you to change numeric information (for example: prices, discount percentages, etc.) within your text ad, while keeping the history and statistics associated with the ad.

Here's a hypothetical scenario illustrating how Ad parameters might help you make your ads more specific and appealing:

Let's say that you sell high-end antique tea cups on your website and it is important for you to qualify users before they even click on your ads. After running some tests, you have found that you can attract serious buyers to your website by including a starting price in your ads. You also want to include the number of varieties of tea cups you currently have in stock, to make your ad appear fresh.

You would like to update your ad text via the AdWords API in response to price and availability fluctuations within your inventory system, but you don't want to lose the statistics associated with your ad. Ad parameters can solve this problem for you.

With Ad parameters, you can specify an ad like this:

Notice that you can specify default values for param1 and param2 within the ad text. You need to set dynamic numeric values for param1 and param2 at the keyword level via the AdParamService of the v2009 API.

On a certain day, if your inventory of tea cups starts at $80 with 18 designs in stock, you can set these values for the relevant keywords within your ad group, as follows:

keyword	param1	param2
antique cups	$80	18

A user searching for "antique cups" subsequently will see the following ad:

For more information on using Ad parameters, be sure to check out our Discover v2009 blog post on this topic (coming soon).

Finally, a few notes about this feature:

• Ad parameters can only be updated via the AdWords API. Updates are not currently supported in AdWords Editor or in the AdWords interface
• You can specify at most two parameters
• While the default value of the parameters (specified within the ad text) can be non-numeric, the dynamic value of the parameters (specified via the AdWords API) must always be numeric. Currency symbols are allowed
  
• As usual, your ads must comply with our AdWords Advertising Policies

-- Shreyas Doshi, Product Manager, AdWords API