Using the Video Stitcher API, you create a live session each time you start playback of a livestream in which ads are dynamically stitched during ad breaks. The response contains the playback URL and the configuration of the live session.
This page describes how to create and manage a live session that is not enabled by Google Ad Manager. For more information on these types of live sessions, see Manage a live session enabled by Google Ad Manager.
Before you begin
Create a live session
To create a live session, use the
projects.locations.liveSessions.create
method.
When you create a live session, the following fields are optional:
adTagMacros
: a list of key-value pairs for ad tag macro replacement; see the ad tag macros sectionmanifestOptions
: specifies which video renditions are generated in the stitched video manifest and the ordering of the renditions; see the manifest options documentation
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
LIVE_CONFIG_ID
: the user-defined identifier for the live 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/liveSessions/SESSION_ID", "playUri": "PLAY_URI", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_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 response is a live session object. The
playUri
is the URL the client device uses to play the ad stitched stream for
this live session.
The Video Stitcher API generates a unique session ID for each request. A
session expires if the playUri
is not requested within the past 5 minutes.
An ad must be encoded before it can be stitched into a live 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. 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.
If you're generating a session on behalf of your customers' devices, you can set the following parameters using HTTP headers:
Parameter | HTTP Header |
---|---|
CLIENT_IP |
x-forwarded-for |
REFERRER_URL |
referer |
USER_AGENT |
user-agent |
You can add the following headers to the preceding curl
request:
-H "x-forwarded-for: CLIENT_IP" \ -H "referer: REFERRER_URL" \ -H "user-agent: USER_AGENT" \
If the x-forwarded-for
header is not provided, the Video Stitcher API uses the
client's IP address in ad metadata requests. Be aware that the client's IP
address may not match the IP of your customers' devices if sessions are
generated on behalf of your customers' devices.
Ad tag macros
An ad tag can contain macros, which can produce 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 live config.
To substitute the value in the ad tag macro, provide a mapping in the
adTagMacros
field. For example, if you want to replace the
[my-key]
macro with the string my-value
, you need to provide the following:
{ ... "adTagMacros": { "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 live session, use the
projects.locations.liveSessions.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 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
SESSION_ID
: the identifier for the live 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/liveSessions/SESSION_ID", "playUri": "ad-stitched-live-stream-uri", "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_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 live playlist before ad-stitching:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:32:00Z",DURATION=60,SCTE35-OUT=0xF...
#EXTINF:10.010
segment_00007.ts
#EXTINF:10.010
segment_00008.ts
#EXT-X-DATERANGE:ID="2415919105",START-DATE="2021-06-22T08:39:20Z",SCTE35-IN=0xF...
#EXTINF:10.010
segment_00009.ts
The following shows a sample source live playlist after ad-stitching:
#EXTM3U
#EXT-X-TARGETDURATION:10
#EXT-X-VERSION:4
#EXT-X-MEDIA-SEQUENCE:5
#EXTINF:10.010
segment_00005.ts
#EXTINF:10.010
segment_00006.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-1/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:6.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-1.ts
#EXTINF:5.000
https://ads.us-west1.cdn.videostitcher.goog/ad-2/seg-2.ts
#EXT-X-DISCONTINUITY
#EXTINF:10.010
segment_00009.ts
Handle client-side ad tracking
When client ad tracking is enabled, the player is responsible for triggering ad tracking events. Ad metadata provided by the Video Stitcher API includes ad tracking and companion ads information. The Video Stitcher API parses this information from the ad tag response.
Get the HLS ad metadata URI from manifest
In an HLS rendition manifest, an AdMetadataURI
is encoded in attribute
X-VAST-META
of tag #EXT-X-DATERANGE
. The #EXT-X-DATERANGE
tag can be found
before the first stitched segment of each ad.
The following is an example HLS timed metadata tag:
#EXT-X-DATERANGE:ID="id123",START-DATE=2014-03-05T11:15:00Z,DURATION=15,X-VAST-META="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"
The value of an X-VAST-META
attribute is a base64-encoded JSON string. After
decoding, you could extract the AdMetadataURI
from the JSON.
The following example shows the decoded X-VAST-META
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
Get the DASH ad metadata URI from the manifest
In a DASH manifest, each stitched ad period contains one VAST ad, and its ad
metadata URI can be extracted from within the EventStream
tag. AdMetadataURI
is encoded in attribute messageData
of the Event
element. Event
is an
element inside tag EventStream
with a schemeIdUri
of
urn:videostitcher:admetadata:202008
.
The following is an example DASH event stream tag:
<EventStream schemeIdUri="urn:videostitcher:admetadata:202008" timescale="1000">
<Event duration="5000" messageData="eyJBZE1ldGFkYXRhVXJpIjogImh0dHBzOi8vZXhhbXBsZS5jb20vdjFhbHBoYS9wcm9qZWN0cy8xMjMvbG9jYXRpb25zL3VzLWNlbnRyYWwxL2xpdmVTZXNzaW9ucy9hYmMzMjEvYWRNZXRhZGF0YS9pZDEyMyJ9"></Event>
</EventStream>
Use base64 to decode the messageData
to JSON.
The following example shows the decoded messageData
:
{
"AdMetadataUri": "https://example.com/v1/projects/123/locations/us-central1/liveSessions/abc321/adMetadata/id123"
}
Retrieve and process ad tracking events
After you get AdMetadataURI
, you can fetch ad metadata.
The following example shows the ad metadata:
{
"activityEvents": [
{
"type": "PAUSE",
"uri": "https://example.com/pause"
}
],
"progressiveEvents": [
{
"timeOffset": "0s",
"events": [
{
"type": "IMPRESSION",
"uri": "https://example.com/impression"
},
{
"type": "START",
"uri": "https://example.com/start"
}
]
},
{
"timeOffset": "2.500s",
"events": [
{
"type": "FIRST_QUARTILE",
"uri": "https://example.com/firstquartile"
}
]
}
],
"adDuration": "10s"
}
In the preceding example, the client should do the following:
- Request
https://example.com/start
at the start of the ad video - Request
https://example.com/impression
at the start of the ad video - Request
https://example.com/pause
whenever the viewer pauses the ad video - Request
https://example.com/firstQuartile
2.5 seconds into the ad video
Inspect live sessions
This section describes how to inspect live sessions and the ad tag details for a given live session. For more details, see the REST documentation.
The Video Stitcher API sends requests to ad providers specified in the ad tags in the body of a live session request. Request and response metadata for these requests is saved for 14 days and can be viewed by inspecting the live session.
The Video Stitcher API composes the ad tag detail using the following:
- The requested ad tag URL in a given ad break (or the default ad tag if none is specified)
- The configured ad tag macros from the live session request
- Additional user metadata
This information, along with the body and metadata of the response, provides insight to the behavior of the Video Stitcher API.
List ad tag details
To list the ad tag details for a live session, use the
projects.locations.liveSessions.liveAdTagDetails.list
method.
Consider the following response for a previously-created live session (some fields are omitted):
{ "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID", ... }
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 live session
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "liveAdTagDetails" : [ { "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] } ] }
Copy the returned LIVE_AD_TAG_DETAILS_ID
. You need it to
get the details for a single ad tag.
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.
Get ad tag details
To get the details for a single ad tag details in a live session, use the
projects.locations.liveSessions.liveAdTagDetails.get
method.
The following example demonstrates viewing a single ad tag detail for a live session using the name of an ad tag detail returned from a previous request:
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 live sessionLIVE_AD_TAG_DETAILS_ID
: the ID for the live ad tag details
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/liveSessions/SESSION_ID/liveAdTagDetails/LIVE_AD_TAG_DETAILS_ID", "adRequests": [ { "uri": "REQUEST_URL", "requestMetadata": "AD_TAG_REQUEST_METADATA", "responseMetadata": "AD_TAG_RESPONSE_METADATA" } ] }
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.