Ad Types

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, which creates builders for supported ad types.

The following snippet demonstrates how to create an expanded text ad:

var 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 finds the description of every expanded text ad:

var iterator = AdsApp.ads().withCondition("Type = EXPANDED_TEXT_AD").get();
while (iterator.hasNext()) {
  var ad = iterator.next();
  var expandedTextAd = ad.asType().expandedTextAd();
  var 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()) {
  var expandedTextAd = ad.asType().expandedTextAd();
  var headlinePart1 = expandedTextAd.getHeadlinePart1();
  var headlinePart2 = expandedTextAd.getHeadlinePart2();
}

Handling legacy responsive display ads

Creating an ad iterator with condition Type = RESPONSIVE_DISPLAY_AD will currently iterate over legacy ads only. This condition is deprecated; please update existing code to explicitly use Type = LEGACY_RESPONSIVE_DISPLAY_AD. To create an ad iterator over ads that support multiple text, image, and video assets, use the condition Type = MULTI_ASSET_RESPONSIVE_DISPLAY_AD.

The following snippet illustrates some of the API differences and similarities between the two types of responsive display ads. Please read the Responsive Display Ad reference for more details.

// var legacyRdaIterator = AdsApp.ads().withCondition("Type = RESPONSIVE_DISPLAY_AD").get();
var legacyRdaIterator = AdsApp.ads().withCondition("Type = LEGACY_RESPONSIVE_DISPLAY_AD").get();
while (legacyRdaIterator.hasNext()) {
  var responsiveDisplayAd = legacyRdaIterator.next().asType().responsiveDisplayAd();

  // Legacy responsive display ads have just one long headline.
  var longHeadline = responsiveDisplayAd.getLongHeadline();

  // And they have one short headline, too.
  var shortHeadline = responsiveDisplayAd.getShortHeadline();

  // This call to .getHeadlines() returns null, because the method is not
  // meaningful when called on a legacy responsive display ad.
  assert(responsiveDisplayAd.getHeadlines() === null);

  // ... etc. ...
}

var rdaIterator = AdsApp.ads().withCondition("Type = MULTI_ASSET_RESPONSIVE_DISPLAY_AD").get();
while (rdaIterator.hasNext()) {
  var responsiveDisplayAd = rdaIterator.next().asType().responsiveDisplayAd();

  // Responsive display ads have just one long headline.
  var longHeadline = responsiveDisplayAd.getLongHeadline();

  // But they can have multiple short headline text assets.
  var shortHeadlineAssets = responsiveDisplayAd.getHeadlines();

  // This call to .getShortHeadline() returns null, because the method is only
  // meaningful when called on a legacy responsive display ad.
  assert(responsiveDisplayAd.getShortHeadline() === null);

  // ... etc. ...
}

var rdaAndLegacyIterator = AdsApp.ads().withCondition("Type IN [LEGACY_RESPONSIVE_DISPLAY_AD, MULTI_ASSET_RESPONSIVE_DISPLAY_AD]").get();
while (rdaAndLegacyIterator.hasNext()) {
  var responsiveDisplayAd = legacyRdaIterator.next().asType().responsiveDisplayAd();
  var longHeadline = responsiveDisplayAd.getLongHeadline();

  // The .isLegacy() method can be used to differentiate between responsive
  // display ad types within an iterator over both.
  if (responsiveDisplayAd.isLegacy()) {
    var shortHeadline = responsiveDisplayAd.getShortHeadline();
    // ... etc. ...
  } else {
    var shortHeadlineAssets = responsiveDisplayAd.getHeadlines();
    // ... etc. ...
  }
}

Reporting

The AD_PERFORMANCE_REPORT can also be used to query type-specific ad fields in addition to regular stats, such as expanded text ad fields. The following snippet shows how to retrieve the stats for all expanded text ads that contain "Discount Sales" in headline 1:

var report = AdsApp.report(
    "SELECT AdGroupId, Id, HeadlinePart1, HeadlinePart2, Clicks, Impressions, Cost " +
    "FROM   AD_PERFORMANCE_REPORT " +
    "WHERE HeadlinePart1 CONTAINS 'Discount Sales' " +
    "DURING LAST_7_DAYS");

var rows = report.rows();
while (rows.hasNext()) {
  var row = rows.next();
  var headlinePart1 = row["HeadlinePart1"];
  var headlinePart2 = row["HeadlinePart2"];
  ...
}

See the reports guide for more information on reporting in scripts.