This is the legacy documentation for Google Ads scripts. Go to the current docs.

Ads

Stay organized with collections Save and categorize content based on your preferences.

Add an expanded text ad

function addExpandedTextAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    adGroup.newAd().expandedTextAdBuilder()
        .withHeadlinePart1('First headline of ad')
        .withHeadlinePart2('Second headline of ad')
        .withDescription('Ad description')
        .withPath1('path1')
        .withPath2('path2')
        .withFinalUrl('http://www.example.com')
        .build();
    // ExpandedTextAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_expandedtextadbuilder
  }
}

Add an image ad

function addImageAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var mediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() && mediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var image = mediaIterator.next();
    adGroup.newAd().imageAdBuilder()
        .withName('Ad name')
        .withImage(image)
        .withDisplayUrl('http://www.example.com')
        .withFinalUrl('http://www.example.com')
        .build();
    // ImageAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_imageadbuilder
  }
}

Add an HTML5 ad

function addHtml5Ad() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var mediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_MEDIA_BUNDLE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() && mediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var mediaBundle = mediaIterator.next();
    adGroup.newAd().html5AdBuilder()
        .withName('Ad name')
        .withMediaBundle(mediaBundle)
        .withEntryPoint('someDirectory/index.html')
        .withDimensions('300x250')
        .withDisplayUrl('http://www.example.com')
        .withFinalUrl('http://www.example.com')
        .build();
    // HTML5AdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_html5adbuilder
  }
}

Add a Gmail image ad

function addGmailImageAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var imageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      imageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var image = imageMediaIterator.next();
    adGroup.newAd().gmailImageAdBuilder()
        .withName('Ad name')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withLogo(logo)
        .withImage(image)
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailImageAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailimageadbuilder
  }
}

Add a Gmail single promotion ad

function addGmailSinglePromotionAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var imageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      imageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var image = imageMediaIterator.next();
    adGroup.newAd().gmailSinglePromotionAdBuilder()
        .withName('Ad name')
        .withContent('Content')
        .withHeadline('Headline')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withCallToAction('Call to action')
        .withLogo(logo)
        .withImage(image)
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailSinglePromotionAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailsinglepromotionadbuilder
  }
}

Add a Gmail multi-product ad

function addGmailMultiProductAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  var logoMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_LOGO_IMAGE_NAME_HERE"')
      .get();
  var itemImageMediaIterator = AdsApp.adMedia().media()
      .withCondition('Name = "INSERT_ITEM_1_IMAGE_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext() &&
      logoMediaIterator.hasNext() &&
      itemImageMediaIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var logo = logoMediaIterator.next();
    var item1Image = itemImageMediaIterator.next();
    adGroup.newAd().gmailMultiProductAdBuilder()
        .withName('Ad name')
        .withAdvertiser('Advertiser')
        .withSubject('Subject')
        .withDescription('Description')
        .withHeadline('Headline')
        .withLogo(logo)
        .withItemImages([item1Image])
        .withItemTitles(['Item 1 title'])
        .withItemButtonCallsToAction(['Item 1 button text'])
        .withItemButtonFinalUrls(['http://www.example.com/item_1_button'])
        .withFinalUrl('http://www.example.com')
        .withDisplayUrl('http://www.example.com')
        .build();
    // GmailMultiProductAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_gmailmultiproductadbuilder
  }
}

Add a responsive display ad

// You create responsive display ads in two steps:
//   1. Create or retrieve assets (marketing images, square marketing images,
//      optional logos, optional landscape logos, and optional YouTube videos)
//   2. Create the ad.
//
// The following function assumes you have not already created named assets.
function addResponsiveDisplayAd() {
  // If you have multiple adGroups with the same name, this snippet will
  // pick an arbitrary matching ad group each time. In such cases, just
  // filter on the campaign name as well:
  //
  // AdsApp.adGroups()
  //     .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
  //     .withCondition('CampaignName = "INSERT_CAMPAIGN_NAME_HERE"')
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();

  // If you have already created named image assets, select them like this:
  //
  // var marketingImages = [];
  // var marketingImageIterator = AdsApp.adAssets()
  //     .assets()
  //     .withCondition('Name IN ["INSERT_FIRST_ASSET_NAME_HERE",
  //                              "INSERT_SECOND_ASSET_NAME_HERE"]')
  //     .get();
  // while (marketingImageIterator.hasNext()) {
  //   marketingImages.push(marketingImageIterator.next());
  // }

  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adGroupBuilder = adGroup.newAd()
        .responsiveDisplayAdBuilder()
        .withBusinessName('Your business name')
        .withFinalUrl('http://www.example.com')
        .withHeadlines(['First headline', 'Second headline'])
        .withDescriptions(
            ['First description', 'Second description', 'Third description']);

    // If you selected assets with a snippet as shown above, then provide those
    // assets here like this:
    //
    // adGroupBuilder = adGroupBuilder.withMarketingImages(marketingImages);

    adGroupBuilder
        .addMarketingImage(
            buildImageAsset("rectangular image asset", "https://goo.gl/3b9Wfh"))
        .addSquareMarketingImage(
            buildImageAsset("square image asset", "https://goo.gl/mtt54n"))
        .build();

    // ResponsiveDisplayAdBuilder has additional options.
    // For more details, see
    // https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_responsivedisplayadbuilder
  }
}

function buildImageAsset(assetName, imageUrl) {
  var imageBlob = UrlFetchApp.fetch(imageUrl).getBlob();
  return AdsApp.adAssets().newImageAssetBuilder()
      .withData(imageBlob)
      .withName(assetName)
      .build()
      .getResult();
}

Pause ads in an ad group

function pauseAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads().get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      ad.pause();
    }
  }
}

Get expanded text ads in an ad group

function getExpandedTextAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads()
      .withCondition('Type=EXPANDED_TEXT_AD')
      .get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next().asType().expandedTextAd();
      logExpandedTextAd(ad);
    }
  }
}

function logExpandedTextAd(expandedTextAd) {
  Logger.log('Headline part 1 : ' + expandedTextAd.getHeadlinePart1());
  Logger.log('Headline part 2 : ' + expandedTextAd.getHeadlinePart2());
  Logger.log('Description : ' + expandedTextAd.getDescription());
  Logger.log('Path 1 : ' + expandedTextAd.getPath1());
  Logger.log('Path 2 : ' + expandedTextAd.getPath2());
  Logger.log('Final URL : ' + expandedTextAd.urls().getFinalUrl());
  Logger.log('Mobile final URL : ' + expandedTextAd.urls().getFinalUrl());
  Logger.log('Final URL : ' + expandedTextAd.urls().getMobileFinalUrl());
  Logger.log('Tracking template : ' +
      expandedTextAd.urls().getTrackingTemplate());
  Logger.log('Custom parameters : ' +
      expandedTextAd.urls().getCustomParameters());
  Logger.log('Approval Status : ' +
      expandedTextAd.getApprovalStatus());
  Logger.log('Enabled : ' + expandedTextAd.isEnabled());
}

Get text ads in an ad group

function getTextAdsInAdGroup() {
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    // You can filter for ads of a particular type, using the AdType selector.
    // See https://developers.google.com/google-ads/scripts-legacy/docs/reference/adsapp/adsapp_adselector#withCondition_1
    // for possible values.

    var adsIterator = adGroup.ads().withCondition('Type=TEXT_AD').get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      logAd(ad);
    }
  }
}

function logAd(ad) {
  Logger.log('Headline : ' + ad.getHeadline());
  Logger.log('Line1 : ' + ad.getDescription1());
  Logger.log('Line2 : ' + ad.getDescription2());
  Logger.log('Final URL : ' + ad.urls().getFinalUrl());
  Logger.log('Display URL : ' + ad.getDisplayUrl());
  Logger.log('Approval Status : ' + ad.getApprovalStatus());
  Logger.log('Mobile preferred : ' + ad.isMobilePreferred());
  Logger.log('Enabled : ' + ad.isEnabled());
}

Get stats for ads in an ad group

function getAdStats() {
  var adGroupIterator = AdsApp.adGroups()
        .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
        .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    // If you want to restrict your search to some ads only, then you could
    // apply a label and retrieve ads as
    //
    //   var label = AdsApp.labels()
    //             .withCondition('Name="INSERT_LABEL_NAME_HERE"')
    //             .get()
    //             .next();
    //   var adsIterator = label.ads().get();

    var adsIterator = adGroup.ads().get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next();
      // You can also request reports for pre-defined date ranges. See
      // https://developers.google.com/adwords/api/docs/guides/awql,
      // DateRangeLiteral section for possible values.
      var stats = ad.getStatsFor('LAST_MONTH');
      Logger.log(adGroup.getName() + ', ' +
          stats.getClicks() + ', ' + stats.getImpressions());
    }
  }
}

Get responsive display ads in an ad group

function getResponsiveDisplayAdsInAdGroup() {
  // Responsive display ads can include multiple text and multiple media assets
  // in the ad, while legacy responsive display ads cannot. Use a condition
  // 'Type = "MULTI_ASSET_RESPONSIVE_DISPLAY_AD"' to select the former and
  // condition 'Type = "LEGACY_RESPONSIVE_DISPLAY_AD"' to select the
  // latter. 'Type = "RESPONSIVE_DISPLAY_AD"' will also select legacy responsive
  // display ads, but the syntax is deprecated.
  //
  // When an ad iterator includes both responsive display ads and legacy
  // responsive display ads, use the ad.isLegacy() method to determine the style
  // of the ad.
  var adGroupIterator = AdsApp.adGroups()
      .withCondition('Name = "INSERT_ADGROUP_NAME_HERE"')
      .get();
  if (adGroupIterator.hasNext()) {
    var adGroup = adGroupIterator.next();
    var adsIterator = adGroup.ads()
        .withCondition('Type IN ["MULTI_ASSET_RESPONSIVE_DISPLAY_AD",
                                 "LEGACY_RESPONSIVE_DISPLAY_AD"]')
        .get();
    while (adsIterator.hasNext()) {
      var ad = adsIterator.next().asType().responsiveDisplayAd();
      if (ad.isLegacy()) {
        logLegacyResponsiveDisplayAd(ad);
      } else {
        logResponsiveDisplayAd(ad);
      }
    }
  }
}

function logLegacyResponsiveDisplayAd(ad) {
  Logger.log('Long headlines : ' + ad.getLongHeadline());
  Logger.log('Short headline : ' + ad.getShortHeadline());
  Logger.log('Description : ' + ad.getDescription());
  Logger.log('Business name : ' + ad.getBusinessName());
  Logger.log('Marketing image : ' + ad.getMarketingImage().getName());
  Logger.log('Logo image : ' + ad.getLogoImage().getName());
  Logger.log('Approval status : ' + ad.getApprovalStatus());
  Logger.log('Enabled : ' + ad.isEnabled());
}

function logResponsiveDisplayAd(ad) {
  Logger.log('Long headline : ' + ad.getLongHeadline());
  logTextAssets('Short headline ', ad.getHeadlines());
  logTextAssets('Description ', ad.getDescriptions());
  Logger.log('Business name : ' + ad.getBusinessName());
  logImageAssets('Marketing image ', ad.getMarketingImages());
  logImageAssets('Square marketing image ', ad.getSquareMarketingImages());
  logImageAssets('Logo image ', ad.getLogoImages());
  logImageAssets('Landscape logo image ', ad.getLandscapeLogoImages());
  logYouTubeAssets('YouTube video ', ad.getYouTubeVideos());
  Logger.log('Approval status : ' + ad.getApprovalStatus());
  Logger.log('Enabled : ' + ad.isEnabled());
}

function logTextAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].text);
  }
}

function logImageAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].getName());
  }
}

function logYouTubeAssets(prefix, assetArray) {
  for (var i = 0; i < assetArray.length; i++) {
    Logger.log(prefix + i + ' : ' + assetArray[i].getYouTubeVideoId());
  }
}