Einführung in das IMA DAI SDK

Mit IMA SDKs kannst du ganz einfach Multimedia-Anzeigen in deine Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Videoinhalte – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie nicht zwischen Anzeigen- und Inhaltsvideo in Ihrer App wechseln müssen.

Wählen Sie die gewünschte dynamische Anzeigenbereitstellungslösung aus.

Vollständige dynamische Anzeigenbereitstellung

In dieser Anleitung wird gezeigt, wie du das IMA DAI SDK in eine einfache Videoplayer-App einbindest. Wenn du dir eine fertige Beispielintegration ansehen oder diese Schritt für Schritt nachvollziehen möchtest, lade das einfache Beispiel von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung des IMA DAI SDK umfasst zwei Hauptkomponenten, wie in dieser Anleitung gezeigt:

  • StreamRequest – entweder ein VODStreamRequest oder ein LiveStreamRequest: Ein Objekt, das eine Streamanfrage definiert. Streamanfragen können sich auf Video-on-Demand- oder Livestreams beziehen. In Anfragen werden eine Content-ID sowie ein API-Schlüssel oder ein Authentifizierungstoken und andere Parameter angegeben.
  • StreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem DAI-Backend verarbeitet. Der Streammanager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Vorbereitung

  • Drei leere Dateien
    • dai.html
    • dai.css
    • dai.js
  • Python auf Ihrem Computer oder ein Webserver zum Testen

Entwicklungsserver starten

Da das IMA DAI SDK Abhängigkeiten mit demselben Protokoll wie die Seite lädt, von der es geladen wird, müssen Sie einen Webserver verwenden, um Ihre App zu testen. Sie können einen lokalen Entwicklungsserver schnell starten, indem Sie den integrierten Server von Python verwenden.

  1. Führen Sie in einer Befehlszeile im Verzeichnis, in dem sich die Datei index.html befindet, Folgendes aus:

    python -m http.server 8000

  2. Rufen Sie in einem Webbrowser http://localhost:8000/ auf.

    Sie können auch einen anderen Webserver verwenden, z. B. den Apache HTTP-Server.

Einfachen Videoplayer erstellen

Ändern Sie zuerst dai.html, um ein einfaches HTML5-Videoelement und ein Div-Element für den Klick zu erstellen. Füge außerdem die erforderlichen Tags hinzu, um die Dateien dai.css und dai.js zu laden und den hls.js-Videoplayer zu importieren. Ändern Sie dann dai.css, um Größe und Position der Seitenelemente anzugeben. Definiere abschließend in dai.js Variablen für die Informationen zur Streamanfrage und eine initPlayer()-Funktion, die beim Laden der Seite ausgeführt wird.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA DAI SDK DAI Demo (HLS.JS)</h2>
    <video id="video"></video>
    <div id="ad-ui"></div>
</body>
</html>

dai.css

#video,
#ad-ui {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#ad-ui {
  cursor: pointer;
}

dai.js

var BACKUP_STREAM =
    'https://storage.googleapis.com/interactive-media-ads/media/bbb.m3u8'

// Livestream asset key.
var TEST_ASSET_KEY = "sN_IYUG8STe1ZzhIIE_ksA";

// VOD content source and video IDs.
var TEST_CONTENT_SOURCE_ID = "2548831";
var TEST_VIDEO_ID = "tears-of-steel";

var hls = new Hls(); // hls.js video player
var videoElement;
var adUiElement;
var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
}

IMA DAI SDK laden

Füge als Nächstes das IMA-Framework mit einem Script-Tag in dai.html vor dem Tag für dai.js ein.

dai.html

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script type="text/javascript" src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css" type="text/css">
</head>

StreamManager initialisieren und Streamanfrage stellen

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie eine ima.dai.api.StreamManager. Diese ist für das Anfordern und Verwalten von dynamischen Anzeigenformat-Streams verantwortlich. Der Konstruktor nimmt ein Videoelement und die resultierende Instanz ein Anzeigen-UI-Element zur Verarbeitung von Anzeigenklicks an.

Definieren Sie dann Funktionen, die Streams anfordern. Dieses Beispiel enthält Funktionen sowohl für VOD als auch für Livestreams, die jeweils Instanzen von VODStreamRequest und LiveStreamRequest erstellen und dann streamManager.requestStream() mit den streamRequest-Parametern aufrufen. Bei Livestreams musst du außerdem einen Handler hinzufügen, um auf zeitgesteuerte Metadatenereignisse zu warten und sie an die StreamManager weiterzuleiten. Sie können den Code kommentieren oder den Kommentar entfernen, um ihn an Ihren Anwendungsfall anzupassen. Für beide Methoden kann ein optionaler API-Schlüssel verwendet werden. Wenn du einen geschützten Stream verwendest, musst du einen Authentifizierungsschlüssel für die dynamische Anzeigenbereitstellung erstellen.

Da keiner der Streams in diesem Beispiel geschützt ist, wird apiKey nicht verwendet.

dai.js

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement)

  // Timed metadata is only used for LIVE streams.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in the metadata, pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, null);
  // Uncomment the line below and comment out the one above to request a
  // LIVE stream instead of a VOD stream.
  //requestLiveStream(TEST_ASSET_KEY, null);
}

function requestVODStream(cmsId, videoId, apiKey) {
  var streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

function requestLiveStream(assetKey, apiKey) {
  var streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

Stream-Ereignisse verarbeiten

Schließlich müssen Sie Ereignis-Listener für wichtige Videoereignisse implementieren. In diesem einfachen Beispiel werden die Ereignisse LOADED, ERROR, AD_BREAK_STARTED und AD_BREAK_ENDED durch Aufrufen einer onStreamEvent()-Funktion verarbeitet. Diese Funktion kümmert sich um das Stream-Laden und Fehler und deaktiviert die Playersteuerung, während eine Anzeige wiedergegeben wird. Das ist vom SDK erforderlich. Wenn der Stream geladen wird, lädt der Videoplayer die angegebene URL mit einer loadUrl()-Funktion und spielt sie ab.

Du kannst auch Ereignis-Listener für die Ereignisse pause und start des Videoelements einrichten, damit der Nutzer die Wiedergabe fortsetzen kann, wenn die IMA während Werbeunterbrechungen pausiert.

Damit die dynamische Anzeigenbereitstellung funktioniert, muss dein benutzerdefinierter Player ID3-Ereignisse für Livestreams an die IMA DAI SDKs übergeben, wie im Beispielcode gezeigt.

dai.js

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);

  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.LOADED,
     google.ima.dai.api.StreamEvent.Type.ERROR,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
     google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED],
    onStreamEvent,
    false);
...
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      isAdBreak = true;
      videoElement.controls = false;
      adUiElement.style.display = 'block';
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      isAdBreak = false;
      videoElement.controls = true;
      adUiElement.style.display = 'none';
      break;
    default:
      break;
  }
}

function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}

function onStreamPause() {
  console.log('paused');
  if (isAdBreak) {
    videoElement.controls = true;
    adUiElement.style.display = 'none';
  }
}

function onStreamPlay() {
  console.log('played');
  if (isAdBreak) {
    videoElement.controls = false;
    adUiElement.style.display = 'block';
  }
}

Fertig! Sie fordern jetzt Anzeigen über das IMA DAI SDK an und schalten sie. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.