Google Ads supports a variety of ad types, such as text, image, and mobile ads. This guide covers how to create, retrieve, and report on ads using Google Ads scripts. For an overview of all ad types supported by Google Ads, see the API guide.
Creation
Scripts can create ads using the
newAd()
method on
AdGroup
instances. This returns an
AdBuilderSpace
that creates builders for
supported ad types.
The following snippet demonstrates how to create an expanded text ad:
let adOperation = adGroup.newAd().expandedTextAdBuilder()
.withHeadlinePart1("First headline part")
.withHeadlinePart2("Second headline part")
.withDescription("Ad description")
.withFinalUrl("http://www.example.com")
.withPath1("path1") // optional
.withPath2("path2") // optional
.build();
Inspection
Some information associated with all ad types is immediately available from an
Ad
, such as an
ad's ID and approval status. Additionally, any ad can be paused, enabled, or
removed.
To access fields specific to an ad's type, such as an expanded text ad's
description, use the
asType()
method to create an
AdViewSpace
.
This provides access to an extended version of the
Ad
that exposes
type-specific methods.
The following snippet gets the description of every expanded text ad:
const iterator = AdsApp.ads().withCondition("Type = EXPANDED_TEXT_AD").get();
while (iterator.hasNext()) {
let ad = iterator.next();
let expandedTextAd = ad.asType().expandedTextAd();
let description = expandedTextAd.getDescription();
}
Notice that the condition Type = EXPANDED_TEXT_AD
ensures every ad from the
iterator is an expanded text ad. Attempting to view an ad with an incorrect
type will result in an error that stops your script's execution, so it's
important to view type-specific fields only when an ad's type is known.
The following snippet shows how to determine if an ad is of the correct type
using the
Ad.isType()
method:
if (ad.isType().expandedTextAd()) {
let expandedTextAd = ad.asType().expandedTextAd();
let headlinePart1 = expandedTextAd.getHeadlinePart1();
let headlinePart2 = expandedTextAd.getHeadlinePart2();
}
Reporting
The ad_group_ad
view can also be
used to query type-specific ad fields in addition to regular stats, such as
ad_group_ad.expanded_text_ad.headline_part1
.
The following snippet shows how to retrieve the stats for all expanded text ads
that contain "Discount Sales" in headline 1:
const results = AdsApp.search(
"SELECT ad_group_ad.ad_group.id, " +
"ad_group_ad.id, " +
"ad_group_ad.expanded_text_ad.headline_part1, " +
"ad_group_ad.expanded_text_ad.headline_part2, " +
"metrics.clicks, " +
"metrics.impressions, " +
"metrics.cost" +
"FROM ad_group_ad " +
"WHERE ad_group_ad.expanded_text_ad.headline_part1 = 'Discount Sales' " +
"AND segments.date DURING LAST_7_DAYS");
while (results.hasNext()) {
let row = results.next();
let headlinePart1 = row.adGroupAd.expandedTextAd.headlinePart1;
let headlinePart2 = row.adGroupAd.expandedTextAd.headlinePart2;
...
}
See the reports guide for more information on reporting in scripts.