Use a custom integration

Before you begin

This document covers only the playback instructions in the absence of the IMA DAI SDK.

Make sure you have already completed the steps in Integrate Google Ad Manager (GAM) with VOD assets beforehand.

If the IMA SDK is not available for your intended platform, you'll need your application to call the required APIs and trigger the ad media verifications itself.

In order to do this, you'll need the following information:

OAUTH_TOKEN

Make a stream registration request to Ad Manager

Make a POST request to the stream registration endpoint. In return, you receive a JSON response containing the stream ID to send to your manifest manipulation server and associated Pod Serving API endpoints.

API endpoint

POST: /ondemand/pods/api/v1/network/NETWORK_CODE/stream_registration
Host: dai.google.com
Content-Type: application/json

Path parameters

JSON-encoded body parameters

targeting_parameters

A set of optional json-encoded targeting parameters.

Response JSON

Example request (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

Example response

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

In case of errors, standard HTTP error codes are returned with no JSON response body.

Parse the JSON response and store the relevant values.

Generate a Cloud Video Stitcher VOD session

Make a POST request to the VOD session registration endpoint. In return, you receive a JSON response containing the stream manifest URI and the metadata regarding ad breaks, ads, and ad events.

API endpoint

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Path parameters

JSON-encoded body parameters

{
  "networkCode":"NETWORK_CODE",
  "streamId":"STREAM_ID"
}
      

Response JSON

Example request (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Example Response

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

After the response is received, you can play the ad-stitched live stream by referencing the URI from the playUri field of the response object.

Request ad pod metadata from Ad Manager

Make a GET request to the metadata_url that you received when you registered your stream with Ad Manager. This step must occur after you've received the stitched manifest from playback URI.

You in turn receive a JSON object describing the stream's ad breaks, ads, and ad events.

API Endpoint

GET: METADATA_URL
Host: dai.google.com

Response JSON

Example request (cURL)

curl METADATA_URL

Example JSON response

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Store these values to associate with timed metadata events within your video stream.

Listen to ID3 events and track playback events

To verify that specific events have occurred in a video stream, follow these steps to handle ID3 events:

1. Store the media events in a queue, saving each media ID along with its timestamp, if surfaced by the player.
2. On each time update from the player or at a set frequency (500 ms recommended), check the media events queue for recently played events by comparing the event timestamps to the playhead.
3. For media events that you confirm have played, check the type by looking up the media ID in the stored ad break tags. Keep in mind that the ad break tags object only contains a truncated version of the media ID, limited to the first 10 digits after the google_ prefix, so there is not a direct match between ID3 media verification IDs and keys in the tags object. This is to prevent event verification pings from being sent before the ID3 event arrives. To generate the complete media verification URL of an ad event, append the full ad event ID to the media_verification_url value from the stream creation response.
4. Use "progress" events to keep track of whether a user is inside an ad break. Do not send these events to the media verification endpoint to avoid an HTTP error code. For other event types, append the media ID to the media verification url and make a GET request to track playback.
5. Remove the media event from the queue.

API endpoint

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Path parameters

Expected return values

Example request (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Example response

HTTP/1.1 204 No Content

Limitations

If using the API within webviews, the following limitations apply with respect to targeting:

• UserAgent: The user agent parameter is passed as a browser-specific value instead of the underlying platform.
• rdid, idtype, is_lat: The device ID is not properly passed, which limits the functionality of the following features:
  • Frequency capping
  • Sequential ad rotation
  • Audience segmentation and targeting