Using the Video Stitcher API, you create a video-on-demand (VOD) session each time you dynamically insert ads 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 document describes how to create a VOD session. For more details, see the REST documentation.
Before you begin
Define a session
To create a VOD session, supply the following fields:
vodConfig
: Required. Specifies the VOD config for the session.adTracking
: Required. Determines if the client player is expected to trigger playback and activity events or if the Video Stitcher API is expected to trigger playback events on behalf of the client player. For more information on client-side ad tracking, see Handle VOD client ad tracking.manifestOptions
: Optional. Specifies which video renditions are generated in the stitched video manifest. The field also supports the ordering of the renditions in the stitched video manifest. For more information, see the manifest options documentation.
Create a session
To create a session for an ad-stitched video, use the
projects.locations.vodSessions.create
method. The following example uses server-side ad tracking.
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.
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.
The Video Stitcher API generates a unique session ID for each request. A session expires after 4 hours.
An ad must be encoded before it can be stitched into a VOD session. When you create a session for an ad-stitched video, the Video Stitcher API determines if the ad has already been encoded from a previous session. If it has, the JSON response will indicate ad break events. The API only looks for encoded ads created by sessions associated with your Google Cloud project. For more information on this process, see the Overview.
Look at the JSON response. This response indicates that an ad was not stitched into the session. If this is the case, wait 5 minutes (for ad encoding) and then re-run the create session command. 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 via 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=[value]
To substitute the value in the ad tag macro, provide a mapping in the
adTagMacroMap
field. For example, if you want to replace [value]
with the string bar
, you need to provide the following:
{ ... "adTagUri": "AD_TAG_URI¯o=[value]", "adTagMacroMap": { "value": "bar" }, ... }
When the Video Stitcher API requests the ad metadata, it uses the following ad tag:
AD_TAG_URI¯o=bar
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,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_01.ts
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_02.ts
#EXTINF:1.99,
https://ads.us-west1.cdn.videostitcher.goog/preroll_ad/seg_03.ts
#EXT-X-DISCONTINUITY
#EXTINF:6,
segment_01.ts
#EXTINF:6,
segment_02.ts
#EXT-X-DISCONTINUITY
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/midroll_ad/seg_01.ts
#EXTINF:0.99,
https://ads.us-west1.cdn.videostitcher.goog/midroll_ad/seg_02.ts
#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,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_01.ts
#EXTINF:4,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_02.ts
#EXTINF:1.99,
https://ads.us-west1.cdn.videostitcher.goog/postroll_ad/seg_03.ts
#EXT-X-ENDLIST