We recently released upgrades to some Ad Extension types. This guide explains how to upgrade a legacy ad extension using Feed Services introduced in v201302. This guide refers extensively to the UpgradeLegacySitelinks.java code example available as part of the AdWords API Java library.

Upgrading your Sitelinks

We now walk through how to upgrade sitelinks. Upgrading other types of ad extensions will be similar; the main differences will be in the placeholder type and field IDs when mapping your feed.

1. Create or retrieve a feed

   If you've previously created a Feed for sitelinks, reuse that feed for all your sitelinks. You can use getExistingFeed() method in the code example to retrieve feeds that have been mapped for sitelinks.

   If you don't already have a sitelinks feed, create a feed as shown in the createSiteLinksFeed() method and then map it to sitelinks as shown in the createSiteLinksFeedMapping() method of code example.

   Note: There is a limit of 20 feeds per account, so we recommend you use one feed per ad extension type.

2. Retrieve your existing sitelinks

   You can now retrieve your legacy sitelinks using the CampaignAdExtensionService. The getLegacySitelinksForCampaign() method of the code example shows how this is done.

Add upgraded sitelinks to your campaign

You can now add upgraded sitelinks to your campaign using CampaignFeedService. This is done by creating a CampaignFeed to associate the feed with the campaign. Since we are using a single feed to hold sitelinks for multiple campaigns, we will use a custom matching function to match a subset of the feed items as sitelinks for a given campaign. The associateSitelinkFeedItemsWithCampaign() method of the code example shows how this is done.

Delete your legacy sitelinks

Once you have added upgraded sitelinks to your campaign, the legacy sitelinks won't show in your ads. You can monitor your account to see if the upgraded sitelinks are showing correctly in your ads. If everything looks fine, you can delete your legacy sitelinks using CampaignAdExtensionService. The deleteLegacySitelinks() method in code example shows how this is done. In case you need to roll back your changes, you can delete the CampaignFeed you created in the previous step, and your legacy sitelinks will start serving again.

Migrating other ad extensions

The basic process for migrating other ad extensions is very similar to the sitelinks migration process we explained above. However, you need to make changes to the code example to deal with ad extension specific features. For instance, to migrate call extensions:

1. Modify getExistingFeed() method to filter for PlaceholderType = 2. You can refer to the list of feed placeholder IDs for details.
2. Modify createSiteLinksFeed() and createSiteLinksFeedMapping() methods to use placeholders specific to call extensions.
3. To retrieve call extensions, modify the Selector fields in getLegacySitelinksForCampaign() method, as well as filter for AdExtensionType = "MOBILE_EXTENSION".
4. Modify newSiteLinkFeedItemAddOperation() to construct an appropriate FeedItem from a MobileExtension
5. Modify associateSitelinkFeedItemsWithCampaign() method to set the CampaignFeed's placeholderType to 2. You can refer to the list of feed placeholder IDs for details.

Tracking performance for upgraded ad extensions

Version v201302 of AdWords API introduces Placeholder Feed Item Report to track the performance of upgraded ad extensions. This report allows you to track performance for each Feed item rather than aggregating results by extension type.

Java code example

We've provided a complete sitelinks migration script for this guide here.