Einführung in das IMA DAI SDK

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre 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 stellen Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD oder Livecontent. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie in Ihrer App nicht zwischen Anzeigen- und Contentvideo wechseln müssen.

Wählen Sie die gewünschte Lösung für die dynamische Anzeigenbereitstellung aus.

Dynamische Anzeigenbereitstellung für die Pod-Auslieferung

In diesem Leitfaden wird erläutert, wie Sie mit dem IMA DAI SDK für HTML5 einen Stream mit Pod-Auslieferung für die dynamische Anzeigenbereitstellung für Live- oder VOD-Inhalte in einem Videoplayer wiedergeben, der für die Wiedergabe hls.js benötigt. Wenn Sie eine abgeschlossene Beispielintegration mit Unterstützung für HLS.js und die Safari-Wiedergabe ansehen oder verfolgen möchten, sehen Sie sich das Beispiel für die HLS-Pod-Bereitstellung an. Die DASH.js-Unterstützung finden Sie im Beispiel für die DASH-Podbereitstellung. Sie können diese Beispiel-Apps von der GitHub-Releaseseite für die HTML5-DAI herunterladen.

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung – Übersicht

Das Implementieren der Pod-Auslieferung mit dem IMA DAI SDK umfasst zwei Hauptkomponenten, die in dieser Anleitung beschrieben werden:

• PodStreamRequest / PodVodStreamRequest: Ein Objekt, das eine Streamanfrage an die Werbeserver von Google definiert. Anfragen enthalten einen Netzwerkcode. Für die PodStreamRequest sind außerdem ein benutzerdefinierter Asset-Schlüssel und ein optionaler API-Schlüssel erforderlich. Beide enthalten weitere optionale Parameter.

• StreamManager: Ein Objekt, das die Kommunikation zwischen dem Videostream und dem IMA DAI SDK verwaltet, z. B. das Auslösen von Tracking-Pings und das Weiterleiten von Streamereignissen an den Publisher.

Voraussetzungen

Für den Start ist Folgendes erforderlich:

• Drei leere Dateien:

  • dai.html
  • dai.css
  • dai.js

• Python, die auf Ihrem Computer installiert ist, oder ein Webserver oder eine andere gehostete Entwicklungsumgebung zum Testen

Entwicklungsumgebung konfigurieren

Da das SDK Abhängigkeiten mit demselben Protokoll wie die Seite lädt, von der es geladen wird, müssen Sie Ihre Anwendung mit einem Webserver testen. Der einfachste Weg, einen lokalen Entwicklungsserver zu starten, ist die Verwendung des integrierten Python-Servers.

1. Führen Sie über eine Befehlszeile in dem Verzeichnis, das die Datei index.html enthält, folgenden Befehl aus:

   python -m http.server 8000
   

2. Rufe in einem Webbrowser http://localhost:8000/ auf.

   Sie können auch eine beliebige andere gehostete Entwicklungsumgebung oder einen anderen gehosteten Webserver wie Apache HTTP Server verwenden.

Einfachen Videoplayer erstellen

Ändern Sie zuerst dai.html, um ein einfaches HTML5-Videoelement und ein div-Element für die Anzeigen-UI-Elemente zu erstellen. Füge außerdem die Tags hinzu, die zum Laden der Dateien dai.css und dai.js sowie zum Importieren des Videoplayers hls.js erforderlich sind.

Ändern Sie dann dai.css, um die Größe und Position der Seitenelemente anzugeben. Definieren Sie schließlich in dai.js Variablen für die Informationen der Streamanfrage und eine initPlayer()-Funktion, die beim Laden der Seite ausgeführt wird.

Die Streamanfragekonstanten sind:

• BACKUP_STREAM: Eine URL für einen Reservestream, der abgespielt wird, wenn beim Anzeigenprozess ein schwerwiegender Fehler auftritt.

• STREAM_URL: Wird nur für Livestreams verwendet. Die Videostream-URL, die von Ihrer Manifestbearbeitung oder einem Drittanbieter mit Pod-Auslieferung bereitgestellt wird. Sie sollten die Stream-ID aus dem IMA DAI SDK einfügen, bevor Sie eine Anfrage stellen. In diesem Fall enthält die Stream-URL den Platzhalter [[STREAMID]], der vor dem Senden einer Anfrage durch die Stream-ID ersetzt wird.

• NETWORK_CODE: Das ist der Netzwerkcode für Ihr Ad Manager 360-Konto.

• CUSTOM_ASSET_KEY: Wird nur für Livestreams verwendet. Der benutzerdefinierte Assetschlüssel, der das Pod-Auslieferungsereignis in Ad Manager 360 identifiziert. Dies kann von Ihrem Manifestbearbeitungsprogramm oder einem Drittanbieter-Pod-Bereitstellungspartner erstellt werden.

• API_KEY: Wird nur für Livestreams verwendet. Ein optionaler API-Schlüssel, der erforderlich sein kann, um eine Stream-ID aus dem IMA DAI SDK abzurufen.

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 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'

// Stream Config.
const STREAM_URL = "https://encodersim.sandbox.google.com/masterPlaylist/...&stream_id=[[STREAMID]]";
const NETWORK_CODE = "51636543";
const CUSTOM_ASSET_KEY = "google-sample";
const API_KEY = "";

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

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

IMA DAI SDK laden

Als Nächstes fügen Sie das Framework für die dynamische Anzeigenbereitstellung mithilfe eines Skript-Tags 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 eine Live- oder VOD-Streamanfrage stellen

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

  requestLivePodStream(NETWORK_CODE, CUSTOM_ASSET_KEY, API_KEY);
}

function requestLivePodStream(networkCode, customAssetKey, apiKey) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving live Stream Request
  const streamRequest = new google.ima.dai.api.PodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.customAssetKey = customAssetKey;
  streamRequest.apiKey = apiKey;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

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

  requestVodPodStream(NETWORK_CODE);
}

function requestVodPodStream(networkCode) {
  // clear HLS.js instance, if in use
  if (hls) {
    hls.destroy();
  }

  // Generate a Pod Serving VOD Stream Request
  const streamRequest = new google.ima.dai.api.PodVodStreamRequest();
  streamRequest.networkCode = networkCode;
  streamRequest.format = 'hls';
  streamManager.requestStream(streamRequest);
}

Streamereignisse verarbeiten

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      console.log('Stream initialized');
      loadStream(e.getStreamData().streamId);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream('');
      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 loadStream(streamID) {
  var url;
  if(streamID) {
    url = STREAM_URL.replace('[[STREAMID]]', streamID);
  } else {
    console.log('Stream Initialization Failed');
    url = BACKUP_STREAM;
  }
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
}

var isAdBreak;

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  
  streamManager.addEventListener(
    [google.ima.dai.api.StreamEvent.Type.STREAM_INITIALIZED,
    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.STREAM_INITIALIZED:
      const streamId = e.getStreamData().streamId;
      // 'vtpInterface' is a place holder for your own video technology
      //  partner (VTP) API calls.
      vtpInterface.requestStreamURL({
        'streamId': streamId,
      })
      .then( (vtpStreamUrl) => {
        streamUrl = vtpStreamUrl;
        streamManager.loadStreamMetadata();
      }, (error) => {
        // Handle the error.
      });
      break;
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      loadStream(streamUrl);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadStream();
      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 loadStream(url) {
  if(url) {
    console.log('Loading:' + url);
    hls.loadSource(url);
  } else {
    console.log('Stream Initialization Failed');
    hls.loadSource(BACKUP_STREAM);
  }
  hls.attachMedia(videoElement);
}

Stream-Metadaten verarbeiten

In diesem Schritt implementieren Sie Ereignis-Listener für Metadaten, um das SDK über Anzeigenereignisse zu informieren. Die Überwachung auf In-Stream-Metadatenereignisse kann je nach Streamformat (HLS oder DASH), Streamtyp (Live- oder VOD-Stream), Playertyp und verwendetem Back-End für die dynamische Anzeigenbereitstellung variieren. Weitere Informationen finden Sie im Leitfaden zu zeitgesteuerten Metadaten.

HLS-Streamformat (Live- und VOD-Streams, HLS.js-Player)

Wenn Sie einen HLS.js verwenden, warten Sie auf das HLS.js-Ereignis FRAG_PARSING_METADATA, um ID3-Metadaten abzurufen und sie mit StreamManager.processMetadata() an das SDK zu übergeben.

Wenn das Video automatisch wiedergegeben werden soll, nachdem alles geladen wurde und bereit ist, warten Sie auf das HLS.js-Ereignis MANIFEST_PARSED, um die Wiedergabe auszulösen.

function loadStream(streamID) {
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  
  // Timed metadata is passed HLS stream events to the streamManager.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, parseID3Events);
  hls.on(Hls.Events.MANIFEST_PARSED, startPlayback);
}

function parseID3Events(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((sample) => {
      streamManager.processMetadata('ID3', sample.data, sample.pts);
    });
  }
}

function startPlayback() {
  console.log('Video Play');
  videoElement.play();
}

DASH.js (DASH-Streamformat, Live- und VOD-Streamtyp)

Wenn du einen DASH.js-Player verwendest, musst du verschiedene Strings verwenden, um ID3-Metadaten für Live- oder VOD-Streams zu erfassen:

• Livestreams: 'https://developer.apple.com/streaming/emsg-id3'
• VOD-Streams: 'urn:google:dai:2018'

Übergeben Sie die ID3-Metadaten mit StreamManager.processMetadata() an das SDK.

Wenn die Videosteuerelemente automatisch angezeigt werden sollen, nachdem alles geladen wurde und bereit ist, warten Sie auf das DASH.js-Ereignis MANIFEST_LOADED.

const googleLiveSchema = 'https://developer.apple.com/streaming/emsg-id3';
const googleVodSchema = 'urn:google:dai:2018';
dashPlayer.on(googleLiveSchema, processMetadata);
dashPlayer.on(googleVodSchema, processMetadata);
dashPlayer.on(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);

function processMetadata(metadataEvent) {
  const messageData = metadataEvent.event.messageData;
  const timestamp = metadataEvent.event.calculatedPresentationTime;

  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with dash.js.
  streamManager.processMetadata('ID3', messageData, timestamp);
}

function loadlistener() {
  showControls();

  // This listener must be removed, otherwise it triggers as addional
  // manifests are loaded. The manifest is loaded once for the content,
  // but additional manifests are loaded for upcoming ad breaks.
  dashPlayer.off(dashjs.MediaPlayer.events.MANIFEST_LOADED, loadlistener);
}

Shaka-Player mit Livestreams (DASH-Stream-Format)

Wenn Sie für die Livestream-Wiedergabe einen Shaka-Player verwenden, verwenden Sie den String 'emsg', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Daten zu Ereignisnachrichten in Ihrem Aufruf an StreamManager.onTimedMetadata().

shakaPlayer.addEventListener('emsg', (event) => onEmsgEvent(event));

function onEmsgEvent(metadataEvent) {
  // Use StreamManager.onTimedMetadata() if your video player provides
  // processed metadata, as with Shaka player livestreams.
  streamManager.onTimedMetadata({'TXXX': metadataEvent.detail.messageData});
}

Shaka Player mit VOD-Streams (DASH-Streamformat)

Wenn Sie für die Wiedergabe des VOD-Streams den Shaka-Player verwenden, verwenden Sie den String 'timelineregionenter', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Ereignisnachrichtendaten in Ihrem Aufruf von StreamManager.processMetadata() mit dem String 'urn:google:dai:2018'.

shakaPlayer.addEventListener('timelineregionenter', (event) => onTimelineEvent(event));

function onTimelineEvent(metadataEvent) {
  const detail = metadataEvent.detail;
  if ( detail.eventElement.attributes &&
       detail.eventElement.attributes['messageData'] &&
       detail.eventElement.attributes['messageData'].value ) {
        const mediaId = detail.eventElement.attributes['messageData'].value;
        const pts = detail.startTime;
        // Use StreamManager.processMetadata() if your video player provides raw
        // ID3 tags, as with Shaka player VOD streams.
        streamManager.processMetadata('urn:google:dai:2018', mediaId, pts);
       }
}

Spielerereignisse verarbeiten

Fügen Sie den pause- und start-Ereignissen des Videoelements Ereignis-Listener hinzu, damit der Nutzer die Wiedergabe fortsetzen kann, wenn das SDK während der Werbeunterbrechungen pausiert.

function loadStream(streamUrl) {
  ...
  
  videoElement.addEventListener('pause', onStreamPause);
  videoElement.addEventListener('play', onStreamPlay);
}

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 mit dem IMA DAI SDK für HTML5 Anzeigen in einem Pod-Auslieferungsstream an und präsentieren sie. Informationen zu erweiterten SDK-Features finden Sie in den anderen Leitfäden oder in den Beispielen auf GitHub.