Mit Pod-Auslieferung mit dynamischer Anzeigenbereitstellung einrichten

Plattform auswählen: HTML5 Android iOS tvOS Cast Roku

In diesem Leitfaden wird gezeigt, wie Sie einen Stream mit Pod-Auslieferung mit dynamischer Anzeigenbereitstellung für Live- oder VOD-Inhalte abspielen. Dazu verwenden Sie das IMA DAI SDK für HTML5 mit einem Videoplayer, der hls.js für die Wiedergabe nutzt. Eine vollständige Beispielintegration mit Unterstützung für die Wiedergabe mit HLS.js und Safari finden Sie im Beispiel für die HLS-Pod-Bereitstellung. Informationen zur Unterstützung von DASH.js finden Sie im Beispiel für die Pod-Auslieferung bei DASH. Sie können diese Beispiel-Apps von der HTML5-DAI-GitHub-Release-Seite herunterladen.

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung

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 Ad-Server von Google definiert. In Anfragen wird ein Netzwerkcode angegeben. 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 übernimmt, z. B. das Auslösen von Tracking-Pings und das Weiterleiten von Stream-Ereignissen 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 einen Webserver oder eine andere gehostete Entwicklungsumgebung, die Sie zum Testen verwenden können

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 integrierten Servers von Python.

  1. Führen Sie in der Befehlszeile im Verzeichnis, das die Datei index.html enthält, Folgendes aus:

    python -m http.server 8000

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

    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-Element für 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 Videoplayer hls.js zu importieren.

Ä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 zur Streamanfrage und eine initPlayer()-Funktion, die beim Seitenaufbau ausgeführt werden soll.

Die Konstanten für die Streamanfrage sind:

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

  • STREAM_URL: Wird nur für Livestreams verwendet. Die URL des Videostreams, die von Ihrem Manifestbearbeitungsdienst oder Drittanbieter über die Pod-Auslieferung bereitgestellt wird. Sie müssen die vom IMA DAI SDK bereitgestellte Stream-ID einfügen, bevor Sie eine Anfrage stellen. 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 Asset-Schlüssel, mit dem Ihr Pod-Auslieferungsereignis in Ad Manager 360 identifiziert wird. Diese kann von Ihrem Manifestbearbeitungstool oder einem Drittanbieter 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 hinzu.

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

Livestream-Pod-Bereitstellung

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie ein ima.dai.api.StreamManager, das für das Anfordern und Verwalten von Streams für die dynamische Anzeigenbereitstellung verantwortlich ist. Der Konstruktor verwendet ein Videoelement und die resultierende Instanz ein Anzeigen-UI-Element, um Anzeigeninteraktionen zu verarbeiten.

Definieren Sie dann eine Funktion, um den Pod Serving-Livestream anzufordern. Diese Funktion erstellt zuerst ein PodStreamRequest-Objekt, konfiguriert es mit den in Schritt 2 angegebenen 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 für 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 Streams für die dynamische Anzeigenbereitstellung verantwortlich ist. Der Konstruktor verwendet ein Videoelement und die resultierende Instanz ein Anzeigen-UI-Element, um Anzeigeninteraktionen zu verarbeiten.

Definieren Sie dann eine Funktion, um den Pod-Serving-VOD-Stream anzufordern. Diese Funktion erstellt zuerst ein PodVodStreamRequest-Objekt, konfiguriert es mit den in Schritt 2 angegebenen 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);
}

Streamereignisse verarbeiten

Livestream-Pod-Bereitstellung

Implementieren Sie als Nächstes Ereignis-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 übernimmt das Laden des Streams und die Fehlerbehandlung. Außerdem werden die Steuerelemente des Videoplayers während der Wiedergabe einer Anzeige deaktiviert, was vom SDK gefordert wird. Wenn der Stream geladen wird, lädt der Videoplayer die angegebene URL und spielt sie mit 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 für VOD

Implementieren Sie als Nächstes Ereignis-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 übernimmt das Laden des Streams und die Fehlerbehandlung. Außerdem werden die Steuerelemente des Videoplayers während der Wiedergabe einer Anzeige deaktiviert, was vom SDK gefordert wird.

Außerdem muss bei VOD-Pod-Bereitstellungsstreams StreamManager.loadStreamMetadata() als Reaktion auf das Ereignis STREAM_INITIALIZED aufgerufen werden. Außerdem müssen Sie eine Stream-URL von Ihrem Videotechnologiepartner (VTP) anfordern. Sobald der loadStreamMetadata()-Aufruf erfolgreich ist, wird ein LOADED-Ereignis ausgelöst. Hier 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);
}

Stream-Metadaten verarbeiten

In diesem Schritt implementieren Sie Event-Listener für Metadaten, um das SDK zu benachrichtigen, wenn Anzeigenereignisse auftreten. Das Abhören von In-Stream-Metadatenereignissen kann je nach Streamformat (HLS oder DASH), Streamtyp (Live- oder VOD-Stream), Player-Typ und Typ des verwendeten Backends für die dynamische Anzeigenbereitstellung variieren. Weitere Informationen findest du 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 HLS.js-Ereignis FRAG_PARSING_METADATA, 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, können Sie das HLS.js-Ereignis MANIFEST_PARSED verwenden, 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 Sie einen DASH.js-Player verwenden, müssen Sie unterschiedliche Strings verwenden, um auf ID3-Metadaten für Live- oder VOD-Streams zu warten:

  • 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 eingeblendet werden sollen, sobald alles geladen und bereit ist, kannst du das DASH.js-Ereignis MANIFEST_LOADED verwenden.

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 den Shaka Player für die Livestream-Wiedergabe verwenden, verwenden Sie den String 'emsg', um auf Metadatenereignisse zu 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-Streamformat)

Wenn Sie den Shaka Player für die Wiedergabe von VOD-Streams 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 Ereignissen pause und start des Videoelements Event-Listener 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';
  }
}

IMA-DAI-Assets bereinigen

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

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