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):
Type of ad extensions in the account | |
---|---|
Only feed-based ad extensions | Feed-based ad extensions will be returned by default |
Only asset-based ad extensions | Asset-based ad extensions will be returned by default |
Both feed-based and asset-based ad extensions | Asset-based ad extensions 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:
Class | Deprecated methods |
---|---|
Callout | No deprecated methods |
MobileApp | getSchedules |
PhoneNumber | getEndDate getStartDate |
Price | getEndDate getSchedules getStartDate |
Sitelink | No deprecated methods |
Snippet | getEndDate getSchedules getStartDate |
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:
Class | Deprecated methods |
---|---|
Callout | No deprecated methods |
MobileApp | setSchedules |
PhoneNumber | clearEndDate clearStartDate setEndDate setStartDate |
Price | clearEndDate clearStartDate setEndDate setSchedules setStartDate |
Sitelink | No deprecated methods |
Snippet | clearEndDate clearStartDate setEndDate setSchedules setStartDate |
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):
Type of ad extensions in the account | |
---|---|
Only feed-based ad extensions | Feed-based ad extensions will be created by default |
Only asset-based ad extensions | Asset-based ad extensions will be created by default |
Both feed-based and asset-based ad extensions | Asset-based ad extensions 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:
Class | Deprecated methods |
---|---|
CalloutBuilder | withMobilePreferred |
MobileAppBuilder | withMobilePreferred withSchedules |
PhoneNumberBuilder | withEndDate withMobilePreferred withStartDate |
PriceBuilder | withEndDate withMobilePreferred withSchedules withStartDate |
SitelinkBuilder | withMobilePreferred |
SnippetBuilder | withEndDate withMobilePreferred withSchedules withStartDate |