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
(forVIDEO_ACTION
campaigns only)NON_SKIPPABLE_INSTREAM_VIDEO_AD
(forVIDEO_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()
):
inStreamAdBuilder()
videoDiscoveryAdBuilder()
bumperAdBuilder()
responsiveVideoAdBuilder()
(forVIDEO_ACTION
campaigns only)nonSkippableAdBuilder()
(forVIDEO_NON_SKIPPABLE
campaigns only)
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();
}