Google Ads API is returning to beta status. Please read our blog post for more details.

Customizing Text Ads

Ad customizers are a very powerful tool that allows you to customize the text content of extended text ads and responsive search ads by using text placeholders, countdowns and IF functions.

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 dynamically injected in your ads at serve time.

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

Ad Customizers

A common use case for ad customizers is promoting sale prices on items during specific date ranges. 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 feed items accordingly.

When setting up an ad, you reference the feed item, its name attribute, and its sale price attribute in the ad text fields, and Google Ads 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 Google Ads 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, and Google Ads will automatically populate the ad with the name, price, and end date from the feed item.

This will allow you to reuse the ad with another product sale or with the next sale of the same product, by updating your feed item's price and end date values, instead of creating a new ad for each product or for each sale.

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

  • Set up the feed and its attributes
  • Map the feed to the "Ad Customizer" placeholder type
  • Create feed items with the values you want to appear in your ads
  • Target feed items to a specific campaign, ad group or keyword
  • Use the feed in an ad
  • Add a countdown
  • Add an IF function

Set up the feed

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

Take note of the resource name for the feed and the IDs for the feed attributes, as you'll need them when setting up the feed items. You can retrieve the feed attributes with a GAQL query that uses the resource name to filter results:

SELECT feed.attributes, feed.name FROM feed WHERE feed.resource_name = '%s'

We are going to use the attribute IDs later, so we store them in a structure that allows us to retrieve them by attribute name.

Create a FeedMapping

The next step is declaring that the feed you just created is to be used for ad customizing by mapping it to the AdCustomizer placeholder type and each of its fields to a specific AdCustomizerPlaceholderField:

Create Feed Items

At this point you can create two different feed items, for two different product sales, that will be dynamically inserted in your expanded text ads:

The helper function creates a FeedItemOperation object and sets the value of each feed attribute:

Set Up Feed Item Targeting

To be sure that the items will be fetched only for a specific ad group, their targeting can be restricted by creating a FeedItemTarget that binds a feed item to an ad group:

Feed item targets can restrict feed items to be fetched for several different resource types, like campaigns, ad groups, keywords, devices and locations: to see the complete list of possible resources that a feed item can target, see the FeedItemTarget resource.

Use the feed in 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}:

The references to the feed with name feedName are populated at serving time with matching data from a feed item within that feed that is targeted to match 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 specified 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.

Ads using customizers are subject to approvals just like any 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.

Using countdowns

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, the description of the ad example above is set to 'Offer ends in {=COUNTDOWN(feedName.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 instance, 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.

Using IF functions

For an easier way to customize your ads, IF functions let you insert a customized message in your ad based on who is searching and what device they're searching on, all without using a feed. The default text is optional.

Dimension Criteria Syntax Example
device mobile {=IF(device=mobile,text to insert):optional default text} {=IF(device=mobile,"Quick, Easy, Mobile Booking"):"Best price guarantee"}
audience Any valid user list name in your account (if list name matches multiple lists in advertiser account, we will randomly pick any) {=IF(audience IN (userlist1,userlist2),text to insert):optional default text} {=IF(audience IN (returning visitors,cart abandoners),30%):25%}