Video Campaigns

Google Ads scripts lets you 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.

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:

const campaignName = "My first video campaign";

const campaignIterator = AdsApp.videoCampaigns()
    .withCondition(`campaign.name = "${campaignName}"`)
    .get();

for (const campaign of campaignIterator) {
  ...
}

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

const adGroupIterator = campaign.videoAdGroups()
    .withCondition(`ad_group.name = "${adGroupName}"`)
    .get();

for (const adGroup of adGroupIterator) {
  ...
}

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

const adGroupIterator = AdsApp.videoAdGroups()
    .withCondition(`campaign.name = "${campaignName}" AND ad_group.name = "${adGroupName}")
    .get();

for (const adGroup of adGroupIterator) {
  ...
}

Creating video ads

Google Ads scripts lets you 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

Supported video ad formats 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:

const campaignIterator = 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:

const campaignIterator = 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:

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

Create the video asset

Video ads generally need to reference a video asset. This determines which video will be played for the ad. You cannot upload a video using scripts, but you can link an existing YouTube video you've previously uploaded for usage in your ads. You do this by creating an Asset with the YouTubeVideoAssetBuilder.

const assetOperation = AdsApp.adAsset().newYouTubeVideoAssetBuilder()
   .withName("name")
   // This is the ID in the URL for the YouTube video.
   .withYouTubeVideoId(youTubeVideoId)
   .build();
const videoAsset = assetOperation.getResult();

Build the ad

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

Example:

const videoAd = videoAdGroup.newVideoAd()
    .inStreamAdBuilder()
    .withAdName("Video Ad")
    .withFinalUrl(
        "http://www.example.com/video-ad")
    // Specify the video asset created in the last step.
    .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 through 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 with the videoTargeting() method on the campaign or ad group, and 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 VideoCampaignTargeting, you cannot manage these criteria with scripts.

Here's an example for excluding 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().

Here's an example for excluding a specific gender from an ad group:

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