Insert ads into a livestream with Pod Serving API

  • The Pod Serving API facilitates the integration of adaptive-bitrate video ad pods directly into HLS or MPEG DASH media playlists for advanced publishers and video technology partners.

  • Implementing the Pod Serving API involves three core components: Google Ad Manager, which handles ad delivery and tracking; a client video player, which manages stream initialization and playback; and a manifest manipulation server, which modifies and serves the stream manifest.

  • Before using the API, a livestream event must be created via the Google Ad Manager UI or the live-event API, serving as a configuration resource for the livestream.

  • The client video player is responsible for initializing the stream, requesting the manifest, polling for ad pod metadata, and forwarding timed metadata events to Ad Manager.

  • The manifest manipulation server handles manifest delivery, requests ad period templates, and inserts Ad Manager-hosted ad segment URLs or ad periods into the stream manifest during ad breaks.

To implement server-side ad insertion (SSAI) with HLS or DASH livestream, use the Pod Serving API to request adaptive bitrate ad pods. For supported resolutions and bitrates, see Video and audio formats and transcoding.

This page covers using the Pod Serving API for livestream.

Prerequisites

Before you continue, you must have the following:

  • Configure a livestream event with the Pod serving redirect Dynamic Ad Insertion (DAI) type. Choose either of the following options:

  • A client app running in a web browser, mobile device or TV, to load the stream and handle events, such as play, pause, click, or tap.

  • A manifest manipulator to handle stream requests from the client app. Important: For your manifest service, we recommend the advanced serving flow.

  • A Google Ad Manager account with Pod serving DAI enabled.

Basic serving flow

To deliver your stream, choose a streaming protocol and do the following:

HLS

  1. To register a session, make a stream request from your video player to Google Ad Manager.

  2. Start polling ad metadata for upcoming ad events.

  3. Request the livestream manifest from your manifest manipulator.

  4. Optional: Send an early ad break notification to Google Ad Manager. Important: We recommend this step for enhanced fill rate.

  5. When your manifest manipulator detects an ad break marker, construct the ad segment URLs and stitch them into the manifest.

    • During an ad break, your client video player requests an ad segment and follows the segment redirect URL to download the ad segment file.

  6. Extract the ad event IDs from ID3 tags to find and send media verification pings to Google.

Pod serving redirect with HLS - Basic serving flow

DASH

  1. Follow all steps in the HLS tab.

  2. Request a DASH period template once and cache the template. This approach builds the periods for all ad breaks of the session.

Pod serving redirect with DASH - Basic serving flow

Advanced serving flow

To deliver your stream, choose a streaming protocol:

HLS

  1. To register a session, make a stream request from your client video player to Google Ad Manager.

  2. Start polling ad metadata for upcoming ad events.

  3. Request the livestream manifest from your manifest manipulator.

  4. Optional: Send an early ad break notification to Google Ad Manager for enhanced fill rate.

  5. Make an ad pod timing metadata (ATM) request to Google Ad Manager.

  6. Retrieve the precise ad pod and slate time to construct the ad segment URLs.

  7. Stitch the ad segment URLs into the manifest.

  8. When your manifest manipulator detects an ad break marker, construct the ad segment URLs and stitch the URLs into the manifest.

    • During an ad break, your client video player requests an ad segment and follows the segment redirect URL to download the ad segment file.

  9. Extract the ad event IDs from ID3 tags to find and send media verification pings to Google.

Pod serving redirect with HLS - Advanced serving flow

DASH

  1. Follow all steps in the HLS tab.

  2. Use the Ad pod Timing Metadata (ATM) responses for additional required fields to build the DASH periods.

Pod serving redirect with DASH - Advanced serving flow

Step by step instructions

For details on API endpoints, example request and response data, see Client video player app for livestreams and Manifest manipulator for livestreams.