Create a configuration for a live stream event

For Ad Manager integration, you need to create a live configuration for a given live stream event. The Video Stitcher API registers this config with Ad Manager.

Source manifest requirements

The Video Stitcher API registers the config with Ad Manager by parsing the source manifest. The source manifest must have certain characteristics depending on the format.

HLS

Container format should be either FMP4 or muxed MPEG-TS
At least one rendition in the manifest with the following (properly populated) fields:
- codecs
- bandwidth

MPEG-DASH

MPD@type set to dynamic (@type="dynamic")
MPD@profiles includes the ISO Live profile urn:mpeg:dash:profile:isoff-live:2011
One or more Periods each containing one or more Adaptation Sets
Each Adaptation Set contains one or more Representations
The Representations contain or inherit a SegmentTemplate with the $Number$ or the $Time$ identifier
@segmentAlignment set to true for all Adaptation Sets
Representations must be non-empty

Create the live config

To create the config, use the projects.locations.liveConfigs.create method.

Before using any of the request data, make the following replacements:

PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
LOCATION: the location in which to create your live config; use one of the supported regions:
- us-central1
- us-east1
- us-west1
- asia-east1
- asia-south1
- asia-southeast1
- europe-west1
- southamerica-east1
LIVE_CONFIG_ID: A user-defined identifier for the live config. This ID can only contain lower-case letters, numbers, and hyphens. The first character must be a letter, the last character must be a letter or a number, and the entire ID has a 63 character maximum.
SOURCE_LIVESTREAM_URI: The source URL to the live stream video manifest. This must be accessible to the Video Stitcher API. The URL must either be publicly accessible or, if URL signing is enabled for the CDN, a registered CDN key has been provided to the Video Stitcher API. If you created a test live stream using the Live Stream API, then this is the URI to the main.m3u8 or main.mpd file in the Cloud Storage bucket.
AD_TAG_URI: (Paste this value into the Request JSON code block below.) The URL for ad metadata retrieved from ad servers; for Ad Manager integration, this must be a valid Ad Manager live video ad tag. To get a valid ad tag, follow the steps on Generate video and audio ad tags with these modifications:
- For Live traffic, enable live traffic.
- For the Player SDK type, select Google IMA SDK.
- Add the parameter ad_rule=0 to the tag (for example, add &ad_rule=0 to the end).
NETWORK_CODE: The numeric identifier for your Ad Manager network; you can find this in the Global settings for the publisher account.

Request JSON body:

{
  "sourceUri": "SOURCE_LIVESTREAM_URI",
  "adTagUri": "AD_TAG_URI",
  "gamLiveConfig": {
    "networkCode": "NETWORK_CODE",
  },
  "adTracking": "CLIENT"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login, or by using Cloud Shell, which automatically logs you into the gcloud CLI. You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "sourceUri": "SOURCE_LIVESTREAM_URI",
  "adTagUri": "AD_TAG_URI",
  "gamLiveConfig": {
    "networkCode": "NETWORK_CODE",
  },
  "adTracking": "CLIENT"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs?liveConfigId=LIVE_CONFIG_ID"

PowerShell (Windows)

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "sourceUri": "SOURCE_LIVESTREAM_URI",
  "adTagUri": "AD_TAG_URI",
  "gamLiveConfig": {
    "networkCode": "NETWORK_CODE",
  },
  "adTracking": "CLIENT"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs?liveConfigId=LIVE_CONFIG_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.common.OperationMetadata",
    "createTime": CREATE_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
    "verb": "create",
    "cancelRequested": false,
    "apiVersion": "v1"
  },
  "done": false
}

This command creates a long-running operation (LRO) that you can query to track progress. Copy the returned OPERATION_ID, which is the last part of the name field, to use in the next section.

Check for the result

The Video Stitcher API asynchronously registers the config on your Ad Manager account. This may take a couple of minutes.

Use the projects.locations.operations.get method to check if the live config has been created. If the response contains "done: false", repeat the command until the response contains "done: true".

Before using any of the request data, make the following replacements:

PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
LOCATION: the location of the data; use one of the supported regions:
- us-central1
- us-east1
- us-west1
- asia-east1
- asia-south1
- asia-southeast1
- europe-west1
- southamerica-east1
OPERATION_ID: the identifier for the operation

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: PROJECT_NUMBER" \
    "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_NUMBER" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.media.asset.v1.OperationMetadata",
    "createTime": CREATE_TIME,
    "endTime": END_TIME,
    "target": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
    "verb": "create",
    "cancelRequested": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.video.stitcher.v1main.LiveConfig",
    "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
    "sourceUri": "SOURCE_LIVESTREAM_URI",
    "adTagUri": "AD_TAG_URI",
    "gamLiveConfig": {
      "networkCode": "NETWORK_CODE",
      "assetKey": "ASSET_KEY",
      "customAssetKey": "PROJECT_NUMBER-LOCATION-LIVE_CONFIG_ID"
    },
    "state": "READY",
    "adTracking": "CLIENT",
    "stitchingPolicy": "CUT_CURRENT"
  }
}

Get the config

To get the config, use the projects.locations.liveConfigs.get method.

Before using any of the request data, make the following replacements:

PROJECT_NUMBER: your Google Cloud project number; this is located in the Project number field on the IAM Settings page
LOCATION: the location of the live config; use one of the supported regions:
- us-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:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID" | Select-Object -Expand Content

You should receive a JSON response similar to the following:

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "sourceUri": "SOURCE_LIVESTREAM_URI",
  "adTagUri": "AD_TAG_URI",
  "gamLiveConfig": {
    "networkCode": "NETWORK_CODE",
    "assetKey": "ASSET_KEY",
    "customAssetKey": "PROJECT_NUMBER-LOCATION-LIVE_CONFIG_ID"
  },
  "state": "READY",
  "adTracking": "CLIENT",
  "stitchingPolicy": "CUT_CURRENT"
}

Find the customAssetKey field and copy the returned CUSTOM_ASSET_KEY. You send these values to the Interactive Media Ads (IMA) SDK in a subsequent step.

Set up CDN keys for Media CDN

Prepare for your client application to work with Google Ad Manager