Using the Video Stitcher API, you create a video-on-demand (VOD) session each time you dynamically insert ads served by Google Ad Manager prior to delivery to client devices. When you create a session, the response includes the playback URL and information about the ads that you inserted into the video.
This page describes how to create and manage a VOD session that is enabled by Google Ad Manager. For information on VOD sessions that don't use Google Ad Manager, see Manage a VOD session.
Before you begin
- Create a VOD config. For the integration with
Google Ad Manager, ensure that the
gamVodConfig
object is set.
Create a session
You can create a VOD session by using the IMA SDK (which calls the Video Stitcher API) or by using the Video Stitcher API directly.
Use the IMA SDK
If you are integrating with the IMA SDK, the IMA SDK creates the VOD session.
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamManager.requestStream(streamRequest); }
VOD sessions enabled by Google Ad Manager must use client-side ad tracking.
You can set or override the following optional parameters per session:
manifestOptions
: specifies which video renditions are generated in the stitched video manifest and the ordering of the renditions; see the manifest options documentationadTagMacroMap
: a list of key-value pairs for ad tag macro replacement; see the ad tag macros section
See the next section to learn how to set these parameters using the IMA SDK.
Optional parameters and overrides
function requestVodVideoStitcherStream() { const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest(); streamRequest.vodConfigId = 'VOD_CONFIG_ID'; streamRequest.region = 'LOCATION'; streamRequest.projectNumber = 'PROJECT_NUMBER'; streamRequest.oAuthToken = 'OAUTH_TOKEN'; streamRequest.networkCode = 'NETWORK_CODE'; streamRequest.videoStitcherSessionOptions = { manifestOptions: { "includeRenditions": [ { "bitrateBps": 150000, "codecs": "hvc1.1.4.L126.B0" }, { "bitrateBps": 440000, "codecs": "hvc1.1.4.L126.B0" }, ], "bitrateOrder": "descending", }, "adTagMacroMap": { "my-key": "my-value" } }; streamManager.requestStream(streamRequest); }
Use the API directly
To create a session for an ad-stitched video, use the
projects.locations.vodSessions.create
method.
REST
Before using any of the request data, make the following replacements:
PROJECT_NUMBER
: your Google Cloud project number located in the Project number field on the IAM Settings pageLOCATION
: the location in which to create your session; use one of the supported regionsShow locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
VOD_CONFIG_ID
: the user-defined identifier for the VOD config
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "sessionContent": { "duration": "60s" } }, "playUri": "PLAY_URI", # This is the ad-stitched VOD URI "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
C#
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Before trying this sample, follow the Python setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Python API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
The Video Stitcher API generates a unique session ID for each request. A session expires after 4 hours.
The response should now be similar to the following:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "adBreaks": [ { "progressEvents": [ { "timeOffset": "0s", "events": [ { "type": "IMPRESSION", "uri": "https://securepubads.g.doubleclick.net/pcs/view..." }, { "type": "START", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, ... ] }, ... ], "ads": [ { "duration": "10s", "activityEvents": [ { "type": "ERROR", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, { "type": "CLICK_THROUGH", "uri": "https://pubads.g.doubleclick.net/pcs/click...", "id": "GDFP" }, ... ] } ], "endTimeOffset": "10s", "startTimeOffset": "0s" } ], "sessionContent": { "duration": "70s" } }, "playUri": "PLAY_URI", "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
The response is a
VodSession
object
that contains the following fields:
- A
name
field that shows the VOD SESSION_ID. Use this ID to get the session. - An
interstitials
field that contains metadata about the ads that were inserted (see the ad metadata concepts). - A
playUri
field that shows the URL that the client device uses to play the conditioned video asset.
If you're generating a session on behalf of your customers' devices, set the following parameters using HTTP headers:
Parameter | HTTP Header |
---|---|
CLIENT_IP | x-user-ip |
REFERRER_URL | referer |
USER_AGENT | user-agent |
You can add the following headers to the preceding curl
request:
-H "x-user-ip: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
Ad tag macros
An ad tag can contain macros, which can result in a different ad tag for each session. Macros are denoted by square brackets in the ad tag, as illustrated by the following example:
AD_TAG_URI¯o=[my-key]
The adTagUri
is defined in the VOD config.
To substitute the value in the ad tag macro, provide a mapping in the
adTagMacroMap
field. For example, if you want to replace
the [my-key]
macro with the string my-value
, you need to provide the
following:
{ ... "adTagMacroMap": { "my-key": "my-value" }, ... }
When the Video Stitcher API requests the ad metadata, it uses the following ad tag:
AD_TAG_URI¯o=my-value
Get a session
To get the session for an ad-stitched video, use the
projects.locations.vodSessions.get
method.
REST
Before using any of the request data, make the following replacements:
PROJECT_NUMBER
: your Google Cloud project number located in the Project number field on the IAM Settings pageLOCATION
: the location of your session; use one of the supported regionsShow locationsus-central1
us-east1
us-west1
asia-east1
asia-south1
asia-southeast1
europe-west1
southamerica-east1
SESSION_ID
: the identifier for the VOD session
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/SESSION_ID", "interstitials": { "adBreaks": [ { "progressEvents": [ { "timeOffset": "0s", "events": [ { "type": "IMPRESSION", "uri": "https://securepubads.g.doubleclick.net/pcs/view..." }, { "type": "START", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, ... ] }, ... ], "ads": [ { "duration": "10s", "activityEvents": [ { "type": "ERROR", "uri": "https://pubads.g.doubleclick.net/pagead/interaction/..." }, { "type": "CLICK_THROUGH", "uri": "https://pubads.g.doubleclick.net/pcs/click...", "id": "GDFP" }, ... ] } ], "endTimeOffset": "10s", "startTimeOffset": "0s" } ], "sessionContent": { "duration": "70s" } }, "playUri": "PLAY_URI", "sourceUri": "VOD_URI", "adTagUri": "AD_TAG_URI", "assetId": "ASSET_ID", "adTracking": "SERVER", "vodConfig": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID" }
C#
Before trying this sample, follow the C# setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API C# API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
Before trying this sample, follow the Go setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Go API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Before trying this sample, follow the Java setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Java API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Before trying this sample, follow the Node.js setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Node.js API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
PHP
Before trying this sample, follow the PHP setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API PHP API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Before trying this sample, follow the Python setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Python API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Ruby
Before trying this sample, follow the Ruby setup instructions in the Video Stitcher API quickstart using client libraries. For more information, see the Video Stitcher API Ruby API reference documentation.
To authenticate to Video Stitcher API, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Sample ad-stitched playlist
The following shows a sample source VOD playlist before ad-stitching:
#EXTM3U
#EXT-X-TARGETDURATION:6
#EXT-X-VERSION:4
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-ENDLIST
The following shows a sample source VOD playlist after ad stitching with pre-roll, mid-roll, and post-roll ads:
#EXTM3U
#EXT-X-VERSION:4
#EXT-X-TARGETDURATION:6
#EXT-X-PLAYLIST-TYPE:VOD
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_01.ts
#EXTINF:6.000,
segment_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:0.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-DISCONTINUITY
#EXTINF:6.000,
segment_03.ts
#EXTINF:6.000,
segment_04.ts
#EXTINF:6.000,
segment_05.ts
#EXTINF:6.000,
segment_06.ts
#EXT-X-DISCONTINUITY
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:4.000,
https://redirector.googlevideo.com/videoplayback/...
#EXTINF:1.990,
https://redirector.googlevideo.com/videoplayback/...
#EXT-X-ENDLIST
Handle client-side ad tracking
The IMA SDK will automatically handle the client-side ad tracking.
Inspect VOD sessions enabled by Google Ad Manager
To inspect VOD sessions and the ad tag details for these sessions, use the Stream activity monitor in Ad Manager.