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

Video Campaigns

Google Ads scripts allow you to manage and report on your YouTube-based Video campaigns. You can use scripts to manage existing video campaigns, create and manage ad groups and ads, set up targeting for campaigns, and run reports. However, you can't use scripts to create video campaigns or upload new video media.

Retrieving video campaigns and ad groups

Video campaigns are available through the videoCampaigns collection of an AdsApp object. You can retrieve them as you would normally retrieve campaigns in scripts:

var campaignName = "My first video campaign";

var campaignIterator = AdsApp.videoCampaigns()
    .withCondition("CampaignName = '" + campaignName + "'")
    .get();

while (campaignIterator.hasNext()) {
  var campaign = campaignIterator.next();
  ...
}

Once you've retrieved a campaign, you can get its ad groups in a similar manner:

var adGroupIterator = campaign.videoAdGroups()
    .withCondition("AdGroupName = '" + adGroupName + "'")
    .get();

while (adGroupIterator.hasNext()) {
  var adGroup = adGroupIterator.next();
  ...
}

Alternatively, you can use the AdsApp.videoAdGroups() method:

var adGroupIterator = AdsApp.videoAdGroups()
    .withCondition("CampaignName = '" + campaignName +
        "' and AdGroupName = '" + adGroupName + "'")
    .get();

while (adGroupIterator.hasNext()) {
  var adGroup = adGroupIterator.next();
  ...
}

Creating video ads

Google Ads scripts allow you to retrieve your video ads using the videoAds() method of VideoAdGroup. You can create new video ads using the newVideoAd() method of VideoAdGroup.

Video ad formats

The video ad formats supported differ by the type of video campaign. To ensure you're selecting the right kind of video campaign, add a withCondition call on AdvertisingChannelSubType.

Some video campaigns have subtypes which restrict the kinds of ads that are supported within that campaign. Specifically, VIDEO_ACTION campaigns only support the VIDEO_RESPONSIVE ad type, and VIDEO_NON_SKIPPABLE campaigns only support the NON_SKIPPABLE_INSTREAM_VIDEO_AD ad type.

The best way to operate on specific types of campaigns is to use a withCondition clause in your selector. You can update the AdvertisingChannelSubType for the campaign type of interest:

AdsApp.videoCampaigns()
  .withCondition("AdvertisingChannelSubType = VIDEO_ACTION")
  .get();

Video campaigns with no subtype support the following video ad formats:

  • TrueView in-stream
  • TrueView video discovery
  • Bumper

You can select these campaigns using a withCondition as follows:

AdsApp.videoCampaigns()
  .withCondition("AdvertisingChannelSubType = null")
  .get();

In-stream video ads can play before, during, or after other videos, giving users the option to skip after a specified time. Video discovery ads appear on the Display Network and various YouTube pages and will only play if a user actively clicks on the ad thumbnail first. Bumper ads are 6-seconds or shorter and can appear on YouTube videos, or on videos on partner sites and apps on the Display Network. For complete details on each of these ad types, see About video ad formats.

Build the ad group

You create a video ad group through the newVideoAdGroupBuilder() method of a video campaign. You need to specify an ad group type and an ad group name when creating the ad group. The ad group type must be one of the following, and cannot be changed after the ad group is created:

  • TRUE_VIEW_IN_STREAM
  • TRUE_VIEW_IN_DISPLAY
  • BUMPER
  • VIDEO_RESPONSIVE (for VIDEO_ACTION campaigns only)
  • NON_SKIPPABLE_INSTREAM_VIDEO_AD (for VIDEO_NON_SKIPPABLE campaigns only)

Example:

var videoAdGroup =
    videoCampaign.newVideoAdGroupBuilder()
    .withAdGroupType("TRUE_VIEW_IN_STREAM")
    .withName("Video Ad Group")
    .build()
    .getResult();

Build the ad

To create a new ad, use the builder method matching the ad group type (chained after newVideoAd()):

Example:

var videoAd = videoAdGroup.newVideoAd()
    .inStreamAdBuilder()
    .withAdName("Video Ad")
    .withFinalUrl(
        "http://www.example.com/video-ad")
    .withVideo(video)
    .build()
    .getResult();

Video targeting

There are two different types of relevant targeting for video campaigns. The VideoCampaignTargeting represents any targeting that is done at the account level for video campaigns in general, and is accessed using AdsApp.videoCampaignTargeting(). This cannot be modified via scripts, but can be viewed.

The other type of targeting lets you specify criteria for video campaigns and video ad groups individually. This can be accessed via the videoTargeting() method on the campaign or ad group. This provides access to selectors and builders for both positive and negative criteria for all types applicable to that level of targeting. The AdsApp.videoTargeting() method also exists to view criteria at the account level, and includes a different set of criteria from AdsApp.videoCampaignTargeting(). Like the VideoCampaignTargeting, you cannot manage these criteria with scripts.

For example, if you want to exclude a specific placement in a campaign:

videoCampaign.videoTargeting().newPlacementBuilder()
    .withUrl("http://www.example.com")
    .exclude();

Criteria for demographics (age, gender) work a little differently than the other criteria types. When a new ad group is created, criteria for each possible age and gender value are created automatically, and that ad group targets all of them. You can exclude a demographic by fetching the existing targeting and calling the exclude() method on it, and you can re-include an excluded demographic by finding the existing exclusion targeting and calling include().

For example, if you want to exclude a specific gender from an ad group:

var videoGenderIterator = videoAdGroup.videoTargeting()
    .genders()
    .withCondition('GenderType = "GENDER_MALE"')
    .get();
if (videoGenderIterator.hasNext()) {
  var videoGender = videoGenderIterator.next();
  videoGender.exclude();
}