IMA SDK für die dynamische Anzeigenbereitstellung einrichten

Mit den IMA SDKs lassen sich 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 senden Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie das Umschalten zwischen Anzeigen- und Inhaltsvideo in Ihrer App nicht verwalten müssen.

Wählen Sie die DAI-Lösung aus, die Sie interessiert

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung

In diesem Leitfaden wird gezeigt, wie Sie einen DAI-Pod-Auslieferungsstream für Live- oder VOD-Inhalte mit dem IMA DAI SDK für HTML5 und einem Videoplayer abspielen, der für die Wiedergabe auf hls.js basiert. Ein Beispiel für eine abgeschlossene Integration mit Unterstützung für HLS.js und die Safari-Wiedergabe finden Sie im Beispiel für die HLS-Pod-Bereitstellung. Informationen zur DASH.js-Unterstützung finden Sie im Beispiel für die Bereitstellung von DASH-Pods. Sie können diese Beispiel-Apps von der GitHub-Releaseseite für HTML5 DAI herunterladen.

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung – Übersicht

Die Implementierung der Pod-Auslieferung mit dem IMA DAI SDK umfasst zwei Hauptkomponenten, die in diesem Leitfaden beschrieben werden:

  • PodStreamRequest / PodVodStreamRequest: Ein Objekt, das eine Streamanfrage an die Werbeserver von Google definiert. In Anfragen wird ein Network Code angegeben. Für die PodStreamRequest ist außerdem ein Custom Asset Key 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 übernimmt, z. B. das Senden von Tracking-Pings und das Weiterleiten von Streamereignissen an den Publisher.

Vorbereitung

Für den Start ist Folgendes erforderlich:

  • Drei leere Dateien:

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

  • Python auf Ihrem Computer installiert 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 einen Webserver verwenden, um Ihre App zu testen. Eine schnelle Möglichkeit, einen lokalen Entwicklungsserver zu starten, ist die Verwendung des in Python integrierten Servers.

  1. Führen Sie in der Befehlszeile im Verzeichnis mit der Datei index.html folgenden Befehl aus:

    python -m http.server 8000

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

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

Videoplayer erstellen

Ändern Sie zuerst dai.html, um ein HTML5-Videoelement und ein Div für die Anzeigen-UI-Elemente zu erstellen. Fügen Sie 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 die Größe und Position der Seitenelemente festzulegen. Definieren Sie schließlich in dai.js Variablen für die Streamanfrageinformationen und eine initPlayer()-Funktion, die beim Laden der Seite ausgeführt wird.

Die Konstanten für Streamanfragen sind:

  • BACKUP_STREAM: Eine URL für einen Backup-Stream, der wiedergegeben werden soll, falls beim Anzeigenprozess ein schwerwiegender Fehler auftritt.

  • STREAM_URL: Wird nur für Livestreams verwendet. Die vom Manifestbearbeitungstool oder vom Drittanbieterpartner bereitgestellte Videostream-URL für die Pod-Auslieferung. Sie sollten die vom IMA DAI SDK bereitgestellte Stream-ID einfügen müssen, bevor Sie eine Anfrage senden. In diesem Fall enthält die Stream-URL einen Platzhalter, [[STREAMID]], der vor dem Senden einer Anfrage durch die Stream-ID ersetzt wird.

  • NETWORK_CODE: Der Netzwerkcode für Ihr Ad Manager 360-Konto.

  • CUSTOM_ASSET_KEY: Wird nur für Livestreams verwendet. Der benutzerdefinierte Assetschlüssel, mit dem Ihr Pod-Serving-Ereignis in Ad Manager 360 identifiziert wird. Sie kann von Ihrer Manifestbearbeitung oder einem Drittanbieter-Partner für die Pod-Auslieferung 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="adUi"></div>
</body>
</html>

dai.css

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

#adUi {
  cursor: pointer;
}

dai.js

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

// Stream Config.
const STREAM_URL = "";
const NETWORK_CODE = "";
const CUSTOM_ASSET_KEY = "";
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

Fügen Sie als Nächstes das DAI-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 eine Anfrage für einen Live- oder VOD-Stream stellen

Bereitstellung von Livestream-Pods

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie ein ima.dai.api.StreamManager, das für das Anfordern und Verwalten von DAI-Streams zuständig ist. Der Konstruktor akzeptiert ein Videoelement und die resultierende Instanz akzeptiert ein Anzeigen-UI-Element zur Verarbeitung von Anzeigeninteraktionen.

Definieren Sie dann eine Funktion, um den Pod-Serving-Livestream anzufordern. Diese Funktion erstellt zuerst ein PodStreamRequest, konfiguriert es mit den in Schritt 2 bereitgestellten streamRequest-Parametern und ruft dann streamManager.requestStream() mit diesem Anfrageobjekt auf.

dai.js

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);
}

Pod-Auslieferung bei VOD

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie ein ima.dai.api.StreamManager, das für das Anfordern und Verwalten von DAI-Streams zuständig ist. Der Konstruktor akzeptiert ein Videoelement und die resultierende Instanz akzeptiert ein Anzeigen-UI-Element zur Verarbeitung von Anzeigeninteraktionen.

Definieren Sie dann eine Funktion, um den Pod-Serving-VOD-Stream anzufordern. Diese Funktion erstellt zuerst ein PodVodStreamRequest, konfiguriert es mit den in Schritt 2 bereitgestellten streamRequest-Parametern und ruft dann streamManager.requestStream() mit diesem Anfrageobjekt auf.

dai.js

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);
}

Stream-Ereignisse verarbeiten

Bereitstellung von Livestream-Pods

Als Nächstes implementieren Sie Event-Listener für wichtige Videoereignisse. In diesem Beispiel werden die Ereignisse STREAM_INITIALIZED, ERROR, AD_BREAK_STARTED und AD_BREAK_ENDED durch Aufrufen einer onStreamEvent()-Funktion verarbeitet. Diese Funktion verarbeitet das Laden von Streams und Fehler und deaktiviert die Player-Steuerelemente während der Anzeigenwiedergabe, was vom SDK erforderlich ist. Wenn der Stream geladen wird, lädt und spielt der Videoplayer die angegebene URL mithilfe einer loadStream()-Funktion ab.

dai.js

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);
}

Pod-Auslieferung bei VOD

Als Nächstes implementieren Sie Event-Listener für wichtige Videoereignisse. In diesem Beispiel werden die Ereignisse STREAM_INITIALIZED, LOADED, ERROR, AD_BREAK_STARTED und AD_BREAK_ENDED durch Aufrufen einer onStreamEvent()-Funktion verarbeitet. Diese Funktion verarbeitet das Laden von Streams und Fehler sowie das Deaktivieren der Player-Steuerelemente während der Anzeigenwiedergabe, was vom SDK erforderlich ist.

Außerdem muss bei VOD-Pod-Serving-Streams als Reaktion auf das STREAM_INITIALIZED-Ereignis StreamManager.loadStreamMetadata() aufgerufen werden. Außerdem müssen Sie eine Stream-URL von Ihrem Videotechnologiepartner anfordern. Wenn der loadStreamMetadata()-Aufruf erfolgreich ist, wird ein LOADED-Ereignis ausgelöst. In diesem Fall sollten Sie eine loadStream()-Funktion mit Ihrer Stream-URL aufrufen, um den Stream zu laden und abzuspielen.

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);
}

Streammetadaten verarbeiten

In diesem Schritt implementieren Sie Event-Listener für Metadaten, um das SDK zu benachrichtigen, wenn Werbeereignisse auftreten. Das Abhören von In-Stream-Metadatenereignissen kann je nach Streamformat (HLS oder DASH), Streamtyp (Live- oder VOD-Stream), Playertyp und verwendetem DAI-Backend variieren. Weitere Informationen finden Sie in unserem Leitfaden zu zeitgesteuerten Metadaten.

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

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

Wenn das Video automatisch abgespielt werden soll, nachdem alles geladen und bereit ist, müssen Sie auf das MANIFEST_PARSED-Ereignis von HLS.js warten, 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, Livestream- und VOD-Streamtyp)

Wenn Sie einen DASH.js-Player verwenden, müssen Sie unterschiedliche 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 Videosteuerung automatisch angezeigt werden soll, nachdem alles geladen und bereit ist, müssen Sie auf das MANIFEST_LOADED-Ereignis von DASH.js warten.

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-Streamformat)

Wenn Sie Shaka Player für die Livestreamwiedergabe verwenden, können Sie mit dem String 'emsg' auf Metadatenereignisse warten. Verwenden Sie dann die Daten der Ereignisnachricht in Ihrem Aufruf von 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-Stream-Format)

Wenn Sie Shaka Player für die Wiedergabe von VOD-Streams verwenden, können Sie mit dem String 'timelineregionenter' auf Metadatenereignisse warten. Verwenden Sie dann die Daten der Ereignisnachricht 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 dem Videoelement Ereignis-Listener für die Ereignisse pause und start hinzu, damit der Nutzer die Wiedergabe fortsetzen kann, wenn das SDK während 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';
  }
}

Assets für die dynamische Anzeigenbereitstellung mit IMA bereinigen

Wenn Sie Anzeigen in einem Stream mit Pod-Bereitstellung mit dem IMA DAI SDK erfolgreich angefordert und ausgeliefert haben, empfehlen wir, alle Ressourcen nach Abschluss der Pod-Bereitstellungssitzung zu bereinigen. Rufen Sie StreamManager.destroy() auf, um die Streamwiedergabe zu beenden, das gesamte Ad-Tracking zu stoppen und alle geladenen Stream-Assets freizugeben.

Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.