Version: 8.14.0

Google Dynamic Ad Insertion (DAI)

Google DAI is a Server-Side Ad-Insertion solution offered by Google where THEOplayer is pre-integrated and offers playback for HLS and DASH Streams. A demo can be found at https://demo.theoplayer.com/google-dai.

SDKs

Web SDK	Android SDK	iOS SDK	tvOS SDK	Android TV SDK	Chromecast SDK
Yes	Yes	Yes	Yes	Yes	Yes

Web SDK

Prerequisites

Your THEOplayer SDK needs to have the google-dai module enabled.
You need to include the Google DAI JavaScript SDK as this is a dependency.

Starting Template

The first thing you need is a valid THEOplayer setup. If you have no experience with setting up our player, we have an excellent getting started guide.

To get THEOplayer to work, you only need to do three things:

Reference the THEOplayer JavaScript library (and optionally the default CSS styles).
Add a container which can hold your video player with HTML.
Create your player through JavaScript using our API.

A basic HTML page with a working THEOplayer could like the following:

<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="UTF-8">
        <title>THEOplayer Web SDK: Getting Started</title>
        <metaname="viewport"content="width=device-width, initial-scale=1.0">
        <link rel="stylesheet" type="text/css" href='/path/to/ui.css'><!-- ads THEOplayer CSS -->
    </head>
    <body>

        <div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

        <script type='text/javascript' src='/path/to/THEOplayer.js'></script><!-- ads THEOplayer library -->
        <script>

            var element = document.querySelector('.theoplayer-container');
            var player = new THEOplayer.Player(element);

            player.source = {
                sources : [{
                    src : 'your.m3u8',
                    type : 'application/x-mpegurl'
                }]
            };

        </script>
    </body>
</html>

Pretty self-explanatory, isn't it?

<link rel="stylesheet" type="text/css" href="/path/to/ui.css" />

<script type="text/javascript" src="/path/to/THEOplayer.js"></script>

The two snippets above are the references to the JS and CSS library.

<div class="theoplayer-container video-js theoplayer-skin theo-seekbar-above-controls"></div>

The snippet above is your HTML container.

<script>

var element = document.querySelector('.theoplayer-container');
var player = new THEOplayer.Player(element);

player.source = {
    sources : [{
        src : 'your.mpd',
        type : 'application/dash+xml'
    }]
};

</script>

The snippet above initializes your player, including a HLS source.

Integrating Google DAI

Add a Google DAI JavaScript library.

<script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>

Add a Google DAI ad configuration to the sources.

const TYPES = {
  hls: 'application/vnd.apple.mpegurl',
  dash: 'application/dash+xml',
};

// example and reference tester at https://developers.google.com/interactive-media-ads/docs/sdks/html5/dai/vastinspector
const SOURCES = {
  dash: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
  hls: {
    vod: {
      integration: 'google-dai',
      availabilityType: 'vod',
      apiKey: null,
      contentSourceID: '<contentSourceID>',
      videoID: '<videoID>',
    },
    live: {
      integration: 'google-dai',
      availabilityType: 'live',
      apiKey: null,
      assetKey: '<assetKey>',
    },
  },
};
// Configure THEOplayer Source
const MANIFEST_TYPE = 'hls'; // 'hls' / 'dash'
const AVAILABILITY_TYPE = 'vod'; // 'vod' or 'live'

player.source = {
  sources: {
    type: TYPES[MANIFEST_TYPE],
    ssai: SOURCES[MANIFEST_TYPE][AVAILABILITY_TYPE],
  },
};

Android SDK

Using Google DAI in the Android SDK consists of 3 steps:

Importing Google DAI feature module

Add implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+' to your module build.gradle file, as demonstrated below:

dependencies {
    // ...
    implementation 'com.theoplayer.theoplayer-sdk-android:core:+'
    implementation 'com.theoplayer.theoplayer-sdk-android:integration-ads-dai:+'
    // ...
}

Creating an instance of Google DAI Integration

tip

If you're using automatic integrations, you can skip this step.

Create a GoogleDaiIntegration through the GoogleDaiIntegrationFactory, and add it to your player instance, as demonstrated below:

val theoplayerView = THEOplayerView(context)
val daiIntegration = GoogleDaiIntegrationFactory.createGoogleDaiIntegration(theoplayerView)
theoplayerView.player.addIntegration(daiIntegration)

Using a Google DAI Source

Use a GoogleDaiVodConfiguration or GoogleDaiLiveConfiguration to create a GoogleDaiTypedSource to request stream, as demonstrated below:

theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiVodConfiguration.Builder("api_key", "content_source_id", "video_id")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()

or:

theoplayerView.player.source = SourceDescription.Builder(
    GoogleDaiTypedSource.Builder(
        GoogleDaiLiveConfiguration.Builder("api_key", "asset_key")
            .build()
    )
    .type(SourceType.DASH)
    .build()
).build()

Notes

The Google DAI integration exposes events through the Ads API. More information is available at "How to subscribe to ad events".

The integration exposes a number of additional methods. These are available directly on the GoogleDaiIntegration object, or indirectly through player.ads.dai (only for Kotlin). For example:

requestStream(StreamRequest, AdsRenderingSettings) can be used to request stream through the native Google DAI API.
contentTimeForStreamTime(double) / streamTimeForContentTime(double) can be used to convert content time to stream time and vice versa.

iOS SDK

To use Google DAI with the THEOplayer iOS SDK, the THEOplayer GoogleIMA Integration should be integrated. For instructions on installation, importing and adding the integration, please refer to this guide.

Usage

Define a GoogleDAITypedSource and a GoogleDAIVodConfiguration to pass to theoplayer's source:

let daiConfig = GoogleDAIVodConfiguration(videoID: "tears-of-steel", contentSourceID: "2548831", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)

let daiConfig = GoogleDAILiveConfiguration(assetKey: "c-rArva4ShKVIAkNfy6HUQ", apiKey: "", authToken: nil, streamActivityMonitorID: nil, adTagParameters: nil)
let typedSource = GoogleDAITypedSource(ssai: daiConfig)
theoplayer.source = SourceDescription(source: typedSource)

And THEOplayer will take care of the rest.

Additional DAI APIs can be found on the imaIntegration.dai endpoint.

Conclusion

THEOplayer SDK and Google DAI are fully pre-integrate to deliver Server-Side Ad Insertion solution, allowing customers to play streams in a breeze.

Extra resources:

SDKs​

Web SDK​

Prerequisites​

Starting Template​

Integrating Google DAI​

Android SDK​

Importing Google DAI feature module​

Creating an instance of Google DAI Integration​

Using a Google DAI Source​

Notes​

iOS SDK​

Usage​

Conclusion​