Ad customizers are a feed-based solution to inject dynamic information into your ads. You can set up a feed with targeting options for specific campaigns, ad groups, and/or keywords, and then set up ads to reference the information in those feeds so that the values there are shown at serve time. This feature will replace ad params in the future.
You can put strings, prices, numbers, and even a countdown to a specific date/time in your ad. Replacements can occur in ad titles and description lines, but you cannot perform replacements using this feature on the display or final URLs.
For example, suppose you often promote a sale price on an item for a specific date range. You can set up your feed to include a string attribute for the item name, another string attribute for the price, and a date attribute for the date your sale ends, and populate a feed item accordingly. Next, when setting up your ad, you simply reference the feed item, its name attribute and its sale price attribute, and AdWords will automatically populate the ad with the name and price from the feed item. To use the feed item's end date, you simply include the date attribute in a function that tells AdWords to display a countdown to the end date in your ad. Next, when setting up your ad, you simply reference the feed item and its name/sale price/end date attributes, and AdWords will automatically populate the ad with the name, price and end date from the feed item. When you have your next sale, instead of creating a new ad, you can re-use this one with a new date by updating your feed item's price and end date values.
This guide will go through a complete example of how to set up the feed and its attributes, how to add feed items to the feed, how to map it to your campaign, and how to set up an ad.
Importing the data into AdWords
Telling AdWords what kind of data you want to use
The first step is to create a feed with all of the attributes you'll need to customize your ad.
customizer_feed = {
:name => 'AdCustomizerFeed',
:attributes => [
{:type => 'STRING', :name => 'Name'},
{:type => 'STRING', :name => 'Price'},
{:type => 'DATE_TIME', :name => 'Date'}
]
}
When added via the FeedService, this feed will have three attributes; two of
type STRING and one of type DATE_TIME. Later, using placeholders within the
mapping, we will see how to differentiate the different types of STRING
attributes.
Make sure that you take note of the IDs for the feed itself and for its
attributes, as these will be important when setting up the feed item. You can
fetch these directly from the result of the mutate call.
feed_srv = adwords.service(:FeedService, API_VERSION)
response = feed_srv.mutate([
{:operator => 'ADD', :operand => customizer_feed}
])
if response
feed = response[:value].first
feed_id = feed[:id]
name_id = feed[:attributes][0][:id]
price_id = feed[:attributes][1][:id]
date_id = feed[:attributes][2][:id]
end
The returned attributes will be in the same order you specified them when
creating the feed.
Adding data to AdWords
You'll notice we included no attributes that would help with targeting specific campaigns, ad groups, or keywords. These will be taken care of when setting up the feed items. Using the campaignTargeting, adGroupTargeting, or keywordTargeting attributes of the FeedItem, you can restrict each feed item to only apply to a specific campaign, ad group, or keyword.
Using the IDs retrieved when creating the feed in the step above, you can add a feed item like this:
feed_item = {
:feed_id => feed_id,
:attribute_values => [
{
:feed_attribute_id => name_id,
:string_value => 'Some Name'
},
{
:feed_attribute_id => price_id,
:string_value => '$12.34'
},
{
:feed_attribute_id => date_id,
:string_value => '20140601 000000'
}
],
:ad_group_targeting => {
:targeting_ad_group_id => ad_group_id
}
}
You can fill in the targeting_ad_group_id above with any ad group for the
customer. That will restrict this feed item to only be fetched within the
context of that ad group. Whenever any ad from that ad group serves, it will
match this feed item, and use this feed item to do the dynamic replacements.
Mapping the data so AdWords knows what it's for
As with other feeds, you need to map a placeholder type to the feed and its attributes so that the Adwords API can characterize the data you're giving it. You can reference our placeholders reference page for a complete listing of placeholders. Only the relevant ones for our example will be shown here.
feed_mapping = {
:placeholder_type => 10, # AD placeholder ID
:feed_id => feed_id,
:attribute_field_mappings => [
{
:feed_attribute_id => name_id,
:field_id => 5 # STRING placeholder field ID
},
{
:feed_attribute_id => price_id,
:field_id => 3 # PRICE placeholder field ID
},
{
:feed_attribute_id => date_id,
:field_id => 4 # DATE placeholder field ID
}
]
}
All we're doing here, essentially, is telling the system what kind of information each attribute of the feed contains. The feed itself is mapped with a placeholder ID of 10, which means that it's used for ad customizers. Then the fieldId for each attribute is specified to a separate placeholder field ID to signify the kind of data it is storing. Name is a string, price is a monetary value, and date is a date-time. Our system will validate the format of the feed items using these mappings. These are required in order for the ad to be able to reference the feed.
You also have to link the mapped feed to the customer.
customer_feed = {
:feed_id => feed_id,
:matching_function => {
:operator => 'IDENTITY',
:lhs_operand => [
{
:xsi_type => 'ConstantOperand',
:type => 'BOOLEAN',
:boolean_value => true
}
]
},
:placeholder_types => [10]
}
We use the IDENTITY operator with a value of true to signify that we aren't
doing any specific logic with the matching function. This means that every feed
item will match in every context, at least as far as the matching function is
concerned. However, since we set up the TargetingAdGroupId on our feed items,
they will still be restricted to the correct contexts.
Setting up an Ad
Once the feed is set up, you can reference it from any ad in the system.
Reference the data you set up before
When setting up the ad, you reference the feed you want to use and the
attributes of that feed by name, not by ID. This is different from the other
steps, where you were keeping track of the system-generated IDs. The syntax for
inserting a custom value from a feed is {=FeedName.AttributeName}. For
example, using our feed above, if we wanted to insert the price of an object in
the string, we would use {=AdCustomizerFeed.Price}. Here's an example of what
this would look like in code:
text_ad = {
:xsi_type => 'TextAd',
:headline => 'Luxury Cruise to {=AdCustomizerFeed.Name}',
:description1 => 'Only {=AdCustomizerFeed.Price}',
:description2 => 'Offer ends soon!',
:url => 'http://www.example.com',
:display_url => 'www.example.com',
}
This ad could be added via the AdGroupAdService, and at serving time, the
references to AdCustomizerFeed would be populated with matching data from a
feed item within that feed that matches the current ad group. It will not serve
this ad if there is no match.
Some validation will be performed when adding an ad that includes references to ad customizers. If no feed with this name is mapped to the ad placeholder type, or no attribute with this name exists within the feed, the ad will be rejected. If you change the name of a feed when ads are referencing it, the ads will automatically be updated to reference the new feed name. Finally, if you delete a feed when ads are referencing it, those ads will no longer be able to serve.
More advanced functions
Currently, one function that performs some special formatting is available when
inserting customizers into ads. The COUNTDOWN function provides the ability to
dynamically change the way you display a date field so it shows how much time
(days, hours) is left. For example, you could change the description2 of the ad
example above to 'Offer ends in {=COUNTDOWN(AdCustomizerFeed.Date)}!' When
this renders at serve time, it could show "Offer ends in 5 days!" or "Offer ends
in 4 hours!"; it will vary based on the time left.
Once you are past the date specified in the countdown, this ad will no longer serve until the date is updated again.
The countdown function takes 3 arguments, but only the first is required.
timestamp: The date to which you are counting down. This value can be a reference to a feed attribute or a specific date literal.language: The localization in which the countdown should be displayed. If unspecified, this defaults toen-US.days_before: The number of days before thetimestampthat this ad can start serving. For example, if it's 6 days before the specified time, but this field is set to 5, then the ad will not serve. If unspecified, then no restrictions will be added.
For example, you could use {=COUNTDOWN(AdCustomizerFeed.Date, 'es', 3)} to
change the language to Spanish, and restrict the ad so it doesn't appear in
search results until 3 days before the date specified.
There is a variant of the COUNTDOWN function called GLOBAL_COUNTDOWN that
takes all the same parameters. The COUNTDOWN function counts down to an event
in the timezone of the user making the query, whereas the GLOBAL_COUNTDOWN
function counts down to a specific instant in time in your account's time zone.
Caveats
There are a lot of moving parts in this feature, so here are some more things to keep in mind when you're setting all this up.
If multiple feed items match in a given context, we will pick one automatically. The exact algorithm for making this selection may vary over time. If you want more fine-grained control over which feed items are used for which contexts, make sure you use specific targeting within the feed items.
Additionally, ads created this way are subject to approvals just like other ads. Feed items and ads can both be disapproved separately, either of which would prevent your ad from serving. In rare cases where each is individually fine, but the combination of the two is a violation, then the ad will be disapproved to prevent serving. Remember, you must have an ad in each ad group that doesn't use ad customizers that can serve as backup to the other ads.
