Documentation
Bitmovin PlatformPlaybackEncodingBitmovin Dashboard

Server-Guided Ad Insertion (SGAI)

Deliver server-guided ad breaks using HLS Interstitials

Server-Guided Ad Insertion (SGAI) lets a server-side streaming workflow signal ad opportunities to the player while the player handles client-side ad playback and measurement.

The current Bitmovin Player SDK implementation described here is based on HLS interstitials. For these streams, the player reads interstitial metadata from the HLS manifest, schedules the referenced ad assets, and exposes playback through the same ad event model used for client-side ad insertion.

How HLS Interstitials Work

  1. The stream signals interstitial opportunities in the HLS manifest
  2. The player resolves the interstitial position from the source timeline and schedules the ad break
  3. During playback, the player emits ad events, fires configured tracking, and returns to the main content according to the manifest metadata

Tracking metadata can be supplied through SVTA X-AD-CREATIVE-SIGNALING or through custom interstitial attributes.

Manifest Shape

HLS interstitials are signaled with EXT-X-DATERANGE tags using CLASS="com.apple.hls.interstitial".

A single-asset interstitial uses X-ASSET-URI:

#EXT-X-DATERANGE:ID="midroll-1",CLASS="com.apple.hls.interstitial",START-DATE="2026-07-01T12:00:15Z",DURATION=10.0,X-ASSET-URI="https://example.com/ads/ad-1.m3u8",CUE="ONCE"

An asset-list interstitial uses X-ASSET-LIST:

#EXT-X-DATERANGE:ID="midroll-2",CLASS="com.apple.hls.interstitial",START-DATE="2026-07-01T12:01:00Z",DURATION=20.0,X-ASSET-LIST="https://example.com/ads/midroll-2.json",CUE="ONCE"
{
  "ASSETS": [
    {
      "URI": "https://example.com/ads/ad-1.m3u8",
      "DURATION": 10
    },
    {
      "URI": "https://example.com/ads/ad-2.m3u8",
      "DURATION": 10
    }
  ]
}

For the full HLS interstitial manifest schema, see the HLS 2nd Edition Internet-Draft.

Platform Guides

Integration Checklist

  • Use an HLS source with valid interstitial EXT-X-DATERANGE tags
    • Remember to set the date range class: CLASS="com.apple.hls.interstitial"
    • Provide exactly one of X-ASSET-URI or X-ASSET-LIST for each interstitial
    • Ensure the playback device can access all interstitial asset and asset-list URLs
  • Use manifest controls such as CUE, X-RESTRICT, X-RESUME-OFFSET, and X-PLAYOUT-LIMIT when you need specific cueing, seeking, resume, or playout behavior
  • Add tracking metadata, such as SVTA X-AD-CREATIVE-SIGNALING, for required measurement events
  • Test playback, seeking over interstitial positions, replay, and live-edge behavior for target platforms