Customizing Text Ads

Customizing standard and expanded text ads can be done through ad customizers, countdowns.

An ad customizer is a feed-based solution for injecting dynamic information into your ads. You can set up a feed with targeting options for specific campaigns, ad groups, and/or keywords, and then create ads that reference the information in the feed, so the values in the feed are shown at serve time.

You can put strings, prices, numbers, and even a countdown to a specific date or time in your ad.

Use case

A common use case for ad customizers is promoting a sale price on an item during a specific date range. To do this, you set up a feed with a string attribute for the item name, another string attribute for the price, and a date attribute for the date your sale ends, then populate a feed item accordingly.

When setting up your ad, you reference the feed item, its name attribute, and its sale price attribute: AdWords automatically populates the ad with the name and price from the feed item.

To use the feed item's end date, you include the date attribute in a function that tells AdWords to display a countdown to the end date in your ad. When creating the ad, reference the feed item and its name, sale price, and end date attributes: AdWords automatically populates the ad with the name, price, and end date from the feed item.

When you have your next sale, you can re-use the ad by updating your feed item's price and end date values, instead of creating a new ad each time.

The following sections describe all phases of this use case, including how to:

  • Set up the feed and its attributes
  • Map the feed to a campaign, ad group, keyword, or location
  • Map the data types in the feed using placeholders
  • Set up an ad that references the feed items
  • Add a countdown

Setting up the feed

The first step is to create a feed with all of the attributes you'll need to customize your ad.

The feed below has four attributes; three of type STRING and one of type DATE_TIME.

customizer_feed = {
  :name => 'AdCustomizerFeed',
  :attributes => [
    {:type => 'STRING', :name => 'PricePoint'},
    {:type => 'STRING', :name => 'Destination'},
    {:type => 'STRING', :name => 'Price'},
    {:type => 'DATE_TIME', :name => 'Date'}
  ]
}

Take note of the IDs for the feed itself and for its attributes, as you'll need them when setting up the feed item. You can fetch these attributes 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]
  pricepoint_id = feed[:attributes][0][:id]
  destination_id = feed[:attributes][1][:id]
  price_id = feed[:attributes][2][:id]
  date_id = feed[:attributes][3][:id]
end

The returned attributes appear in the same order you specified when creating the feed.

Mapping the feed using FeedItem

Create a FeedItem to restrict the feed to only a specific campaign, ad group, keyword, or location, using the campaignTargeting, adGroupTargeting, keywordTargeting, or geoTargeting attributes of the FeedItem.

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 => pricepoint_id,
      :string_value => 'Cheap'
    },
    {
      :feed_attribute_id => destination_id,
      :string_value => 'Mars'
    },
    {
      :feed_attribute_id => price_id,
      :string_value => '$100.00'
    },
    {
      :feed_attribute_id => date_id,
      :string_value => '20160601 000000'
    }
  ],
  :ad_group_targeting => {
    :targeting_ad_group_id => ad_group_id
  }
}

This item will be fetched only for the ad group specified for the targeting_ad_group_id. Any ad in that ad group will use this feed item for the dynamic replacements.

Mapping the data with placeholders

As with other feeds, you must map the feed and its attributes to placeholders, that indicate the type of information the feed and its attributes contain. The placeholders reference page contains a complete list of placeholders.

The placeholders for our example are shown below.

feed_mapping = {
  :placeholder_type => 10, # AD placeholder ID
  :feed_id => feed_id,
  :attribute_field_mappings => [
    {
      :feed_attribute_id => pricepoint_id,
      :field_id => 5 # STRING placeholder field ID
    },
    {
      :feed_attribute_id => destination_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
    }
  ]
}

In the example, the feed itself is mapped with a placeholder ID of 10, indicating it's used for ad customizers. The field_id for each attribute is mapped to a placeholder field ID to signify its data type: Price point and destination are both strings, price is a monetary value, and date is a date-time. The format of the feed items is validated by the system to ensure ads can 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]
}

The IDENTITY operator has a value of true to signify that we aren't doing any specific logic with the matching function. In this case 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.

Building an ad

Once the feed is set up, you can reference it from any ad in the system.

When setting up an ad, you reference a feed and its attributes by name, not by ID. This is different from the other steps, where you use the system-generated IDs.

The syntax for inserting a custom value from a feed is {=FeedName.AttributeName}. If you want to specify a default value, the syntax would be {=FeedName.AttributeName:default value}. For example, using our feed above, if you want to insert the price of an object in the string with a default of $10, use {=AdCustomizerFeed.Price:$10}:

text_ad = {
  :xsi_type => 'TextAd',
  :headline => '{=AdCustomizerFeed.PricePoint} Cruise to {=AdCustomizerFeed.Destination}',
  :description1 => 'Only {=AdCustomizerFeed.Price:$10}',
  :description2 => 'Offer ends soon!',
  :url => 'http://www.example.com',
  :display_url => 'www.example.com',
}

If this ad is added via the AdGroupAdService, the references to AdCustomizerFeed are populated at serving time with matching data from a feed item within that feed that matches the current ad group. The ad won't serve if no match is found.

The API validates ads that include references to ad customizers: If no feed with the specificied name is mapped to the ad placeholder type, or no attribute with a specified name exists in the feed, the ad is rejected.

If you change the name of a feed when ads are referencing it, the ads are automatically updated to reference the new feed name. If you delete a feed when ads are referencing it, those ads will no longer serve.

Adding a countdown

The COUNTDOWN function allows you 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)}!' At serve time, the ad will show "Offer ends in 5 days!" or "Offer ends in 4 hours!" based on the time left.

Once the date specified in the countdown is past, the ad will no longer serve until the date is updated again.

The countdown function takes three 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 to en-US.
  • days_before: The number of days before the timestamp that this ad can start serving. For example, if it's 6 days before the specified time, but this field is set to 5, the ad won't serve. If unspecified, no restrictions are 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.

The COUNTDOWN function counts down to an event in the timezone of the user making the query. A variant of COUNTDOWN, called GLOBAL_COUNTDOWN, counts down to a specific time in your account's time zone. GLOBAL_COUNTDOWN takes all the same parameters as COUNTDOWN.

Final thoughts

If multiple feed items match in a given context, the system uses an algorithm to pick one automatically. This algorithm may vary over time. If you want greater control over which feed items are used for which contexts, make sure to use specific targeting within the feed items.

Ads using customizers are subject to approvals just like other ads. Feed items and ads can both be disapproved separately, though disapproval of either will prevent the ad from serving. In rare cases where each is individually fine, but the combination of the two is a violation, the ad will be disapproved to prevent serving. Remember, you must have an ad in each ad group that doesn't use ad customizers, to serve as a backup for the ads with customizers.

Send feedback about...

This page
Documentation feedback
AdWords API
AdWords API
Product feedback
Need help? Visit our support page.