Migrating Ad Extension Scripts

This document describes the migration process for scripts that access or manage ad extensions. Starting March 28, 2022, customers with scripts updating ad extensions will have their feed-based extensions migrated to new asset-based extensions. Starting May 13, 2022, customers with scripts fetching ad extensions (and no scripts updating ad extensions) will have their feed-based extensions migrated to new asset-based extensions.

Overview

The existing feed-based extensions paradigm is deprecated in favor of asset-based extensions. Feed-based extensions are referred to as "Legacy" extensions in the Google Ads UI while asset-based extensions are referred to as "Upgraded" extensions in the Google Ads UI.

Starting March 28, 2022, Feed-based extensions will be migrated to new asset-based extensions - once migrated, feed-based extensions will stop serving. This guide will outline the migration whether you have both feed-based and asset-based ad extensions in your Google Ads account or only have feed-based ad extensions in your account.

Migration details

In order to start accessing or updating asset-based ad extensions, you must use the new Google Ads Scripts experience. For information on the new Google Ads Scripts experience, see the Getting Started guide.

Fetching ad extensions

The existing set of Ad Extension selectors (for example, the SitelinkSelector are capable of fetching either feed-based ad extensions or asset-based ad extensions. By default, these selectors will return whichever type of ad extension is currently serving. The following table summarizes the type of ad extension that is currently serving (and thus will be returned by default):

After all feed-based ad extensions have been migrated, all ad extension selectors will return asset-based ad extensions by default. It will still be possible to fetch feed-based ad extensions by the withOnlyLegacy method. This is useful for collecting historical metrics.

// This will return feed-based sitelink extensions before and after
// March 28, 2022.
const sitelinks = AdsApp.extensions().sitelinks().withOnlyLegacy().get();

In most cases, no code changes should be required before or after feed-based ad extensions have been migrated. However, there are a few scenarios where code changes could be required.

Filtering ad extensions by ID

When a feed-based ad extension is migrated, the corresponding asset-based ad extension will have a different ID. This means if your script currently filters ad extensions by ID, it will be unable to fetch asset-based ad extensions.

// If these IDs belong to feed-based sitelink extensions, this code will return
// an empty iterator on or after March 28, 2022 (once the extensions have been
// migrated).
const ids = [123, 456, 789];
const sitelinks = AdsApp.extensions().sitelinks().withIds(ids).get();

To address this, you should either filter by a different attribute or update your code to use the asset-based ad extensions' IDs instead.

Filtering ad extensions by stats

When a feed-based ad extension is migrated, the corresponding asset-based ad extension will have its stats reset. You should take this into consideration when filtering ad extensions by stats. For example, if you request sitelink extensions with Clicks > 100 in the LAST_MONTH, you could see fewer ad extensions than normal if your feed-based ad extensions were recently migrated.

You should also keep this in mind when generating performance reports for your ad extensions. Your reports could see significant shifts or drops when your feed-based ad extensions are migrated.

Deprecated methods

As part of the migration, several fields are no longer supported. For example, start date and end date have been deprecated from Snippet extensions. Calls to getStartDate() will return null. Additionally, a warning message will be logged. See the following table to understand which methods are deprecated:

Updating ad extensions

As part of the migration, several fields are no longer supported. For example, start date and end date have been deprecated from Snippet extensions. Calls to setStartDate will have no affect on the ad extension. Additionally, a warning message will be logged. See the following table to understand which methods are deprecated:

Creating ad extensions

The existing set of Ad Extension builders (for example, the SitelinkBuilder are capable of creating either feed-based ad extensions or asset-based ad extensions. By default, these builders will create whichever type of ad extension is currently serving. The following table summarizes the type of ad extension that is currently serving (and thus will be created by default):

After a customer has their extensions migrated, all ad extension builders will create asset-based ad extensions by default. Creation of feed-based ad extensions will no longer be supported since feed-based ad extensions will no longer serve.

If you wish to create a feed-based extension rather than rely on default behavior, you can do so by calling build(true) rather than build(), for example:

const phoneNumberBuilder = AdsApp.extensions().newPhoneNumberBuilder();
const newPhoneNumber = phoneNumberBuilder
  .withCountry("US")
  .withPhoneNumber("4085550000")
  .withCallOnly(false)
  // Calling build(true) means this will create a legacy phone number extension.
  .build(true)
  .getResult();

If you wish to create an asset-based extension and your account currently only has feed-based extensions, you can either wait until March 28 or call build(false).

const phoneNumberBuilder = AdsApp.extensions().newPhoneNumberBuilder();
const newPhoneNumber = phoneNumberBuilder
  .withCountry("US")
  .withPhoneNumber("4085550000")
  .withCallOnly(false)
  // Calling build(false) means this will create an asset-based phone number extension
  // even if the account currently only has feed-based extensions.
  .build(false)
  .getResult();

Unsupported fields

As part of the ad extension migration, certain fields have been deprecated. For example, start date and end date have been deprecated from Snippet extensions. Calls to withEndDate or withStartDate will not have any affect on the extension—instead a warning message will be logged. See the following table to understand which methods are deprecated for each class: