AdWords API
Hide

Extension Setting Services

Using extension setting services

Assume that you're advertising a restaurant in AdWords. You've already set up an AdWords campaign, but want to show extra information about your business, thus improving your ad's visibility. You wish to show the following extra information about your restaurant:

  • Store hours: This link takes users to http://www.example.com/storehours.
  • Nutrition data: This link takes users to http://www.example.com/menu/nutritiondata, where nutritional value of menu items are listed.
  • Happy hours: This link takes users to http://www.example.com/happyhours, and should only be shown during these hours: 6pm to 9pm, Monday thru Friday; and 5pm to 8pm on Saturday.
  • Thanksgiving special: You plan to have a special Thanksgiving menu from November 27 to 28. This link should be displayed only from November 20 to 27 so that users can make their reservation at http://www.example.com/thanksgiving

Each of the items above is an ad extension in AdWords. You can manage extensions using the extension setting services in the AdWords API.

Add ad extensions

Ad extensions enhance ads by showing extra information about the business. Ad extensions can be added at the account, campaign, or ad group level; though not all extension types are available at all levels. Ad extensions come in several formats, for this example, we will use sitelinks.

The following code snippet shows how to add new ad extensions to a campaign using CampaignExtensionSettingService.

// Get the CampaignExtensionSettingService.
CampaignExtensionSettingService campaignExtensionSettingService =
    (CampaignExtensionSettingService) user.GetService(
         AdWordsService.v201506.CampaignExtensionSettingService);

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;
campaignExtensionSetting.extensionType = FeedType.SITELINK;

SitelinkFeedItem link1 = new SitelinkFeedItem() {
sitelinkText = "Store Hours",
    sitelinkUrl = "http://www.example.com/storehours"
};

SitelinkFeedItem link2 = new SitelinkFeedItem() {
sitelinkText = "Thanksgiving Specials",
sitelinkUrl = "http://www.example.com/thanksgiving",
    startTime = "20141120 000000 EST",
    endTime = "20141127 235959 EST"
};

SitelinkFeedItem link3 = new SitelinkFeedItem() {
    sitelinkText = "Nutrition Data",
    sitelinkUrl = "http://www.example.com/menu/nutritiondata"
};

SitelinkFeedItem link4 = new SitelinkFeedItem() {
    sitelinkText = "Happy hours",
    sitelinkUrl = "http://www.example.com/happyhours",
    scheduling = new FeedItemSchedule[] {
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.MONDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.TUESDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.WEDNESDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.THURSDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.FRIDAY,
            startHour = 18,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        },
        new FeedItemSchedule() {
            dayOfWeek = AdWords.v201506.DayOfWeek.SATURDAY,
            startHour = 17,
            startMinute = MinuteOfHour.ZERO,
            endHour = 21,
            endMinute = MinuteOfHour.ZERO
        }
    }
};

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] {
        link1, link2, link3, link4
    },
};

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
    operand = campaignExtensionSetting,
    @operator = Operator.ADD,
};

CampaignExtensionSettingReturnValue retVal = campaignExtensionSettingService.mutate(
    new CampaignExtensionSettingOperation[] {operation});

Other ad extension types can be added in a similar manner, as shown below.

Call extensions

You can list a business phone number alongside your ads that customers can call directly from the ad--using a CallFeedItem extension. The following code snippet shows how to do this:

CallFeedItem callFeedItem = new CallFeedItem() {
    callCountryCode = "1",
    callPhoneNumber = "212-565-0000",
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { callFeedItem },
};

Review extensions

Business reviews can be listed alongside your ads using a review extension. The following code snippet shows how to create a review extension:

ReviewFeedItem reviewFeeditem = new ReviewFeedItem() {
    reviewSourceName = "Example Food review magazine",
    reviewSourceUrl =
        "http://www.example.com/reviews/2014/03/the-amazing-example-hotel",
    reviewText = "The best food in New York city!",
    reviewTextExactlyQuoted = true
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { reviewFeeditem },
};

Callout extensions

The callout ad extension lets you provide additional details, such as what products or services you offer, through text right below your search ads. The following code snippet shows how to create a callout extension:

CalloutFeedItem freeDeliveryCallout = new CalloutFeedItem() {
   calloutText = "Free delivery",
};
CalloutFeedItem kidsCallout = new CalloutFeedItem() {
   calloutText = "Kids eat free",
};

CampaignExtensionSetting campaignExtensionSetting = new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;
campaignExtensionSetting.extensionType = FeedType.CALLOUT;
campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] {
        freeDeliveryCallout, kidsCallout
    }
};

App extensions

If your business developed an Android or iOS application to target mobile-savvy customers, you can display links to the app alongside your ads using an app extension. App extensions are shown only to users who are currently logged in to Google, and who haven't yet installed your app. Clicking the app extension link will take them to the Google Play or Apple iTunes page for your app. The following code snippet shows how to create an app extension for an application on Google Play:

AppFeedItem appFeedItem = new AppFeedItem() {
    appId = "com.example.mobileapp",
    appStore = AppFeedItemAppStore.GOOGLE_PLAY,
    appLinkText = "Install our mobile app!",
    appUrl = "https://play.google.com/store/apps/details?id=com.example.mobileapp"
};

CampaignExtensionSetting campaignExtensionSetting =
    new CampaignExtensionSetting();
campaignExtensionSetting.campaignId = campaignId;

campaignExtensionSetting.extensionSetting = new ExtensionSetting() {
    extensions = new ExtensionFeedItem[] { appFeedItem },
};

Update ad extensions

Suppose that you decided to change your restaurant's happy hours on Saturday to from 5pm to 10pm. Since your campaign already has ad extensions, you need to use the SET operation to update the ad extensions without overwriting existing settings. The first step is to retrieve the list of existing settings:

// Get the CampaignExtensionSettingService.
CampaignExtensionSettingService campaignExtensionSettingService =
    (CampaignExtensionSettingService) user.GetService(
         AdWordsService.v201506.CampaignExtensionSettingService);

Selector selector = new Selector() {
    fields = new string[] { "CampaignId", "ExtensionType", "ExtensionSetting" },
    predicates = new Predicate[] {
        new Predicate() {
            field = "CampaignId",
            @operator = PredicateOperator.EQUALS,
            values = new string[] {campaignId.ToString()}
        },
        new Predicate() {
            field = "ExtensionType",
            @operator = PredicateOperator.EQUALS,
            values = new string[] {"SITELINK"}
        },
    }
};

CampaignExtensionSettingPage page = campaignExtensionSettingService.get(selector);

Next, update the desired sitelink:

CampaignExtensionSetting campaignExtensionSetting = page.entries[0];
foreach (SitelinkFeedItem siteLink in
     campaignExtensionSetting.extensionSetting.extensions) {
  if (siteLink.sitelinkText == "Happy hours") {
    foreach (FeedItemSchedule schedule in siteLink.scheduling) {
      if (schedule.dayOfWeek == AdWords.v201506.DayOfWeek.SATURDAY) {
         schedule.startHour = 17;
         schedule.startMinute = MinuteOfHour.ZERO;
         schedule.endHour = 21;
         schedule.endMinute = MinuteOfHour.ZERO;
      }
    }
  }
}

Finally, send the modified campaignExtensionSetting to the server.

CampaignExtensionSettingOperation operation = new CampaignExtensionSettingOperation() {
  operand = campaignExtensionSetting,
  @operator = Operator.SET,
};

Remember to send back all feed items, even if you are modifying just one item, to prevent the new settings from overwriting the old settings.

Track ad extension performance

Use the placeholder report or placeholder feeditem report to track the performance of your ad extensions. To identify your ad extensions use the FeedItemId column.

Migrate ad extensions to extension setting services

For the rest of this guide, we cover the pros and cons of extension setting services to help you decide whether to start using them or stay with feed services. We also cover details on how to migrate to the new services.

Extension setting services provide a simplified layer over the existing feed-based ad extensions. The new services:

  • Support concrete types for all supported ad extensions.
  • Provide a simplified API that allows you to manage ad extensions for a campaign or ad group.

Should I migrate?

Extension setting services cover all ad extension functionalities that are available on the AdWords user interface today. Most users will benefit from spending some time to rewrite their services and migrate their data to use the simplified extension setting services. The following section will help you decide whether or not to migrate to the extension setting services.

When are extension setting services preferred?

If you simply need to add ad extensions to a campaign or ad group, set its device preference, or manage its schedule, then we recommend using extension setting services. An added benefit when using extension setting services is that unlike feed services, we maintain your feed's schema and data, so you won't have to keep up with the underlying feed structure.

When are legacy feed services preferred?

We recommend using the legacy feed services if you need to use one or more of the features listed below:

  • Location extensions: Extension setting services do not include support for location extensions.
  • Custom fields or matching functions: Extension setting services don't support custom fields in Feeds or writing custom matching functions.
  • Multiple feeds: Extension setting services only support one feed per extension type that is managed by the system.

Migration steps

If you've only used feeds created by the AdWords user interface, you can use extension setting services immediately.

However, if you've created custom feeds with the API, you'll need to first perform the following steps:

  1. Retrieve feed items in your custom feeds.
  2. Identify feed items you want to keep.
  3. Delete the CustomerFeeds, CampaignFeeds and AdGroupFeeds that use the feed items from the custom feeds.
  4. Create CustomerExtensionSettings, CampaignExtensionSettings and AdGroupExtensionSettings that use the new ExtensionFeedItems.
  5. (Optional) Delete feed items that are no longer in use.

The rest of this guide focuses on upgrading ad extensions at the campaign level, but the same process applies to upgrading ad extensions at the ad group level.

Retrieve feed items in your custom feeds

In order to retrieve feed items in your custom feeds, you need to first identify all custom feeds that you've created using the AdWords API as follows:

private Feed[] GetFeeds(AdWordsUser user) {
  FeedService feedService = (FeedService)user.GetService(
      AdWordsService.v201506.FeedService);
  FeedPage page = feedService.query("SELECT Id, Name, Attributes where " +
      "Origin='USER' and FeedStatus='ENABLED'");
  return page.entries;
}

Next, retrieve feed items in these feeds. For ease of discussion, we will limit the examples to sitelinks, but the approach is similar for the other ad extensions.

private FeedItem[] GetFeedItems(AdWordsUser user, long feedId) {
  FeedItemService feedItemService = (FeedItemService) user.GetService(
      AdWordsService.v201506.FeedItemService);
  FeedItemPage page = feedItemService.query(string.Format("Select FeedItemId, " +
      "AttributeValues, Scheduling where Status = 'ENABLED' and FeedId = '{0}'", feedId));
  return page.entries;
}

For ease of handling, let's load the values into a locally defined class named SitelinkFromFeed:

class SiteLinkFromFeed {
  public long FeedId {get;set;}
  public long FeedItemId { get; set; }
  public string Text { get; set; }
  public string Url { get; set; }
  public string[] FinalUrls { get; set; }
  public string[] FinalMobileUrls { get; set; }
  public string TrackingUrlTemplate { get; set; }
  public string Line2 { get; set; }
  public string Line3 { get; set; }
  public FeedItemSchedule[] Scheduling { get; set; }
}

Let's also define a few constants to help us to better parse the FeedMappings. You can find these placeholder values on our feed placeholder page.

const int PLACEHOLDER_TYPE_SITELINKS = 1;

class SiteLinkFields {
  public const long TEXT = 1;
  public const long URL = 2;
  public const long LINE2 = 3;
  public const long LINE3 = 4;
  public const long FINAL_URLS = 5;
  public const long FINAL_MOBILE_URLS = 6;
  public const long TRACKING_URL_TEMPLATE = 7;
};

To convert a FeedItem into a SitelinksFromFeed object, we need to retrieve the FeedMapping for the feed, and then map each attribute into the corresponding object properties:

private Dictionary<long, SiteLinkFromFeed> GetSiteLinksFromFeed(AdWordsUser user,
    long feedId) {
  Dictionary<long, SiteLinkFromFeed> siteLinks =
      new Dictionary<long, SiteLinkFromFeed>();

  Dictionary<long, long> feedMappings = GetFeedMapping(user, feedId,
      PLACEHOLDER_TYPE_SITELINKS);
  FeedItem[] feedItems = GetFeedItems(user, feedId);

  if (feedItems != null) {
    foreach (FeedItem feedItem in feedItems) {
      SiteLinkFromFeed sitelinkFromFeed = new SiteLinkFromFeed() {
        FeedId = feedItem.feedId,
        FeedItemId = feedItem.feedItemId
      };
      foreach (FeedItemAttributeValue attributeValue in feedItem.attributeValues) {
        switch (attributeValue.feedAttributeId) {
          case SiteLinkFields.TEXT:
            sitelinkFromFeed.Text = attributeValue.stringValue;
            break;

          case SiteLinkFields.URL:
            sitelinkFromFeed.Url = attributeValue.stringValue;
            break;

          case SiteLinkFields.FINAL_URLS:
            sitelinkFromFeed.FinalUrls = attributeValue.stringValues;
            break;

          case SiteLinkFields.FINAL_MOBILE_URLS:
            sitelinkFromFeed.FinalMobileUrls = attributeValue.stringValues;
            break;

          case SiteLinkFields.TRACKING_URL_TEMPLATE:
            sitelinkFromFeed.TrackingUrlTemplate = attributeValue.stringValue;
            break;

          case SiteLinkFields.LINE2:
            sitelinkFromFeed.Line2 = attributeValue.stringValue;
            break;

          case SiteLinkFields.LINE3:
            sitelinkFromFeed.Text = attributeValue.stringValue;
            break;
        }
      }
      sitelinkFromFeed.Scheduling = feedItem.scheduling;
      siteLinks.Add(feedItem.feedItemId, sitelinkFromFeed);
    }
  }
  return siteLinks;
}

private Dictionary<long, long> GetFeedMapping(AdWordsUser user, long feedId,
    long placeHolderType) {
  FeedMappingService feedMappingService = (FeedMappingService) user.GetService(
      AdWordsService.v201506.FeedMappingService);
  FeedMappingPage page = feedMappingService.query(string.Format(
      "SELECT FeedMappingId,AttributeFieldMappings where FeedId='{0}' " +
      "and PlaceholderType={1} and Status='ENABLED'",
      feedId, placeHolderType));

  Dictionary<long, long> attributeMappings = new Dictionary<long, long>();

  if (page.entries != null) {
    foreach (FeedMapping feedMapping in page.entries) {
      foreach (AttributeFieldMapping attributeMapping in
          feedMapping.attributeFieldMappings) {
        attributeMappings.Add(attributeMapping.feedAttributeId,
            attributeMapping.fieldId);
      }
    }
  }
  return attributeMappings;
}

Identify feed items you want to keep

We need to identify the list of feed items associated with a campaign. This can be done by retrieving the CampaignFeed associated with the campaign and parsing its matchingFunction. Since matching functions allow you to write a general-purpose expression tree, writing a parser for a general case is complex and we won't cover it in this guide. We'll instead pick the simplest case, where a few feed items from a single feed have been associated with a campaign. This matching function takes the form

FEEDITEM_ID IN (FEEDITEM_ID_1, FEEDITEM_ID_2…)

private CampaignFeed[] GetCampaignFeeds(AdWordsUser user, Feed feed, int placeholderType) {
  CampaignFeedService campaignFeedService = (CampaignFeedService) user.GetService(
      AdWordsService.v201506.CampaignFeedService);

  CampaignFeedPage page = campaignFeedService.query(string.Format(
      "SELECT CampaignId, MatchingFunction, PlaceholderTypes where Status='ENABLED' " +
      "and FeedId = '{0}' and PlaceholderTypes CONTAINS_ANY[{1}]", feed.id, placeholderType));
  return page.entries;
}

private List<long> GetFeedItemsForCampaign(CampaignFeed campaignFeed) {
  List<long> feedItems = new List<long>();
  if (campaignFeed.matchingFunction.lhsOperand.Length == 1 &&
      campaignFeed.matchingFunction.lhsOperand[0] is RequestContextOperand &&
      (campaignFeed.matchingFunction.lhsOperand[0] as
           RequestContextOperand).contextType ==
           RequestContextOperandContextType.FEED_ITEM_ID &&
      campaignFeed.matchingFunction.@operator == FunctionOperator.IN) {
    foreach (ConstantOperand argument in campaignFeed.matchingFunction.rhsOperand) {
      feedItems.Add(argument.longValue);
    }
  }
  return feedItems;
}

Delete existing CampaignFeed

Before you add extension settings to a campaign, you need to delete the campaign's existing CampaignFeed. This is required since AdWords supports only one CampaignFeed per extension type for a campaign. Deleting your manually created CampaignFeed allows the CampaignExtensionSettingService to create a new system-managed CampaignFeed when you add extension settings.

private CampaignFeed DeleteCampaignFeed(AdWordsUser user, CampaignFeed campaignFeed) {
  CampaignFeedService campaignFeedService = (CampaignFeedService) user.GetService(
      AdWordsService.v201506.CampaignFeedService);

  CampaignFeedOperation operation = new CampaignFeedOperation() {
    operand = campaignFeed,
    @operator = Operator.REMOVE,
  };

  return campaignFeedService.mutate(
       new CampaignFeedOperation[] { operation }).value[0];
}

Add extension settings

You can now create extension settings corresponding to the old feed items:

private static void CreateExtensionSetting(AdWordsUser user,
    Dictionary<long, SiteLinkFromFeed> feedItems, CampaignFeed campaignFeed,
    List<long> feedItemIds) {
  CampaignExtensionSetting extensionSetting = new CampaignExtensionSetting() {
    campaignId = campaignFeed.campaignId,
    extensionType = FeedType.SITELINK,
    extensionSetting = new ExtensionSetting() {
    }
  };

  List<ExtensionFeedItem> extensionFeedItems = new List<ExtensionFeedItem>();

  foreach (long feedItemId in feedItemIds) {
    SiteLinkFromFeed feedItem = feedItems[feedItemId];
    SitelinkFeedItem newFeedItem = new SitelinkFeedItem() {
      sitelinkText = feedItem.Text,
      sitelinkUrl = feedItem.Url,
      sitelinkFinalUrls = feedItem.FinalUrls,
      sitelinkFinalMobileUrls = feedItem.FinalMobileUrls,
      sitelinkTrackingUrlTemplate = feedItem.TrackingUrlTemplate,
      sitelinkLine2 = feedItem.Line2,
      sitelinkLine3 = feedItem.Line3,
      scheduling = feedItem.Scheduling
    };
    extensionFeedItems.Add(newFeedItem);
  }
  extensionSetting.extensionSetting.extensions = extensionFeedItems.ToArray();

  CampaignExtensionSettingService campaignExtensionSettingService =
      (CampaignExtensionSettingService) user.GetService(
          AdWordsService.v201506.CampaignExtensionSettingService);
  CampaignExtensionSettingOperation operation =
      new CampaignExtensionSettingOperation() {
        operand = extensionSetting,
        @operator = Operator.ADD
      };

  campaignExtensionSettingService.mutate(
      new CampaignExtensionSettingOperation[] {operation});
  return;
}

Keep in mind that this process does not de-duplicate the extension settings; you may want to enhance this code to exclude duplicate items.

Delete old FeedItems

Finally, delete the old FeedItems:

private void DeleteOldFeedItems(AdWordsUser user, List<long> feedItemIds,
    long feedId) {
  if (feedItemIds.Count == 0) {
    return;
  }
  List<FeedItemOperation> operations = new List<FeedItemOperation>();
  foreach (long feedItemId in feedItemIds) {
    FeedItemOperation operation = new FeedItemOperation() {
      @operator = Operator.REMOVE,
      operand = new FeedItem() {
        feedItemId = feedItemId,
        feedId = feedId
      }
    };
    operations.Add(operation);
  }
  FeedItemService feedItemService = (FeedItemService) user.GetService(
      AdWordsService.v201506.FeedItemService);
  feedItemService.mutate(operations.ToArray());
  return;
}

This is an optional step, but we recommend deleting unused feed items to keep the number of active feed items under system limits.

Putting it all together: The main loop

The main loop of this program is pretty straightforward, and corresponds to the sequence of steps we discussed earlier:

Feed[] feeds = GetFeeds(user);
foreach (Feed feed in feeds) {
  Dictionary<long, SiteLinkFromFeed> feedItems = GetSiteLinksFromFeed(user, feed.id);
  CampaignFeed[] campaignFeeds = GetCampaignFeeds(user, feed,
      PLACEHOLDER_TYPE_SITELINKS);

  if (campaignFeeds != null) {
    HashSet<long> allFeedItemsToDelete = new HashSet<long>();
    foreach (CampaignFeed campaignFeed in campaignFeeds) {
      // Optional: Replace with custom logic that upgrades only selected
      // feed items.
      List<long> feedItemIds = GetFeedItemsForCampaign(campaignFeed);
      DeleteCampaignFeed(user, campaignFeed);
      CreateExtensionSetting(user, feedItems, campaignFeed, feedItemIds);
      allFeedItemsToDelete.UnionWith(feedItemIds);
    }
    DeleteOldFeedItems(user, new List<long>(allFeedItemsToDelete), feed.id);
  }
}

Code examples

Refer to the following code examples in our client libraries to learn more about Extension Setting services.

Library AddSitelinks example MigrateToExtensionSettings example
Java AddSiteLinks.java MigrateToExtensionSettings.java
Perl add_site_links.pl migrate_to_extension_settings.pl
PHP AddSitelinks.php MigrateToExtensionSettings.php
Python add_site_links.py migrate_to_extension_settings.py
Ruby add_site_links.rb migrate_to_extension_settings.rb
.NET (C#) AddSitelinks.cs MigrateToExtensionSettings.cs
.NET (VB) AddSitelinks.vb MigrateToExtensionSettings.vb

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.

Send feedback about...

This page
Documentation feedback
AdWords API
Product feedback