Einführung in das IMA DAI SDK

Mit IMA SDKs können Sie Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. IMA SDKs können Anzeigen von beliebigen VAST-kompatiblen Ad-Server bereitstellen und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit IMA SDKs für die dynamische Anzeigenbereitstellung Streamanfrage für Anzeigen- und Contentvideo (VOD- oder Livecontent) Das SDK gibt dann kombinierten Videostream, sodass Sie nicht zwischen Anzeige und Contentvideo wechseln müssen. in Ihrer App.

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

Dynamische Anzeigenbereitstellung für die Pod-Auslieferung

In dieser Anleitung wird gezeigt, wie du einen Stream mit dynamischer Anzeigenbereitstellung und Pod-Auslieferung für Live- oder VOD-Inhalte mit dem IMA DAI SDK für HTML5 und einem Videoplayer abspielst, der für die Wiedergabe auf hls.js angewiesen ist. Eine fertige Beispielintegration mit Unterstützung für HLS.js und Safari-Wiedergabe findest du im Beispiel für das HLS-Pod-Serving. Informationen zur Unterstützung für DASH.js finden Sie im Beispiel für die DASH-Pod-Auslieferung. Sie können diese Beispiel-Apps aus dem GitHub-Release für die dynamische Anzeigenbereitstellung von HTML5 herunterladen. .

Pod-Auslieferung mit dynamischer Anzeigenbereitstellung – Übersicht

Die Implementierung der Pod-Auslieferung mit dem IMA DAI SDK umfasst zwei Hauptkomponenten: werden in diesem Leitfaden erläutert:

  • PodStreamRequest / PodVodStreamRequest: Ein Objekt, das eine Streamanfrage für die Werbeserver von Google. Anfragen geben einen Netzwerkcode an und der PodStreamRequest erfordert außerdem einen benutzerdefinierten Asset-Schlüssel und einen optionalen API-Schlüssel: 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 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 oder ein Webserver oder eine andere gehostete Entwicklungsumgebung zum Testen

Entwicklungsumgebung konfigurieren

Da das SDK Abhängigkeiten mit demselben Protokoll lädt wie die Seite aus müssen Sie einen Webserver verwenden, um Ihre Anwendung zu testen. Eine kurze ist die Verwendung des integrierten Python-Servers eine Möglichkeit, einen lokalen Entwicklungsserver zu starten.

  1. Über eine Befehlszeile aus dem Verzeichnis, das die Datei index.html enthält Dateiausführung:

    python -m http.server 8000

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

    Sie können auch jede andere gehostete Entwicklungsumgebung oder einen anderen Webserver verwenden, z. B. Apache HTTP Server.

Einfachen Videoplayer erstellen

Ändern Sie zuerst dai.html, um ein einfaches HTML5-Videoelement und ein div-Element zu erstellen, das die für UI-Elemente der Anzeigen verwendet werden können. Fügen Sie außerdem die erforderlichen Tags zum Laden von dai.css hinzu. und dai.js-Dateien zu speichern und den hls.js-Videoplayer 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 zu den Streamanfragen. 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 Back-up-Stream, der abgespielt werden soll, falls der Anzeigenprozess verarbeitet wird. ein schwerwiegender Fehler auftritt.

  • STREAM_URL: Wird nur für Livestreams verwendet. Die Video-Stream-URL, die von Ihre Manifestbearbeitung oder den Drittanbieter mit der Pod-Auslieferung. Er sollte müssen Sie 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 Assetschlüssel, das Pod-Auslieferungsereignis in Ad Manager 360 identifiziert. Dieser kann von deinem Manifest-Bearbeiter oder deinem Drittanbieter für die Bereitstellung von Pods erstellt werden.

  • API_KEY: Wird nur für Livestreams verwendet. Optionaler API-Schlüssel, der zum Abrufen einer Stream-ID aus dem IMA DAI SDK erforderlich sein kann.

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

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 Live- oder VOD-Streamanfrage stellen

Pod-Bereitstellung im Livestream

Um eine Gruppe von Anzeigen anzufordern, erstellen Sie eine ima.dai.api.StreamManager, die ist für das Anfordern und Verwalten von Streams für die dynamische Anzeigenbereitstellung zuständig. Der Konstruktor nimmt Ein Videoelement und in der resultierenden Instanz wird ein UI-Element verwendet, um die Anzeige zu verarbeiten. Interaktionen.

Definiere dann eine Funktion, um den Livestream für die Bereitstellung des Pods anzufordern. Diese Funktion erstellt zuerst eine PodStreamRequest, konfiguriert sie 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);
}

VOD-Pod-Auslieferung

Um eine Gruppe von Anzeigen anzufordern, erstellen Sie eine ima.dai.api.StreamManager, die ist für das Anfordern und Verwalten von Streams für die dynamische Anzeigenbereitstellung zuständig. Der Konstruktor nimmt Ein Videoelement und in der resultierenden Instanz wird ein UI-Element verwendet, um die Anzeige zu verarbeiten. Interaktionen.

Definieren Sie dann eine Funktion, um den VOD-Stream zur Pod-Auslieferung anzufordern. Diese Funktion Erstellt zuerst ein PodVodStreamRequest und konfiguriert es mit der streamRequest Parameter, die in Schritt 2 angegeben wurden, und ruft dann streamManager.requestStream() auf mit diesem Anfrageobjekt.

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

Livestream-Pod-Auslieferung

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 verarbeitet Streams und Fehler beheben sowie die Steuerelemente des Videoplayers deaktivieren, während eine Anzeige gespielt wird, was für das SDK erforderlich ist. Wenn der Stream geladen ist, wird das Video Der Player lädt die angegebene URL und gibt sie mithilfe einer loadStream()-Funktion wieder.

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

VOD-Pod-Auslieferung

Implementiere 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 verarbeitet das Stream-Laden und Fehler und deaktiviert die Playersteuerung, während eine Anzeige wiedergegeben wird. Dies ist vom SDK erforderlich.

Außerdem muss bei der Bereitstellung von VOD-Pod-Streams StreamManager.loadStreamMetadata() als Reaktion auf das Ereignis STREAM_INITIALIZED aufgerufen werden. Sie müssen auch eine Stream-URL von Ihrem, Video Technology Partner (VTP). Nach einem erfolgreichen loadStreamMetadata()-Aufruf wird das Ereignis LOADED ausgelöst. Hier solltest du eine loadStream()-Funktion mit deiner 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, Anzeigenereignisse auftreten. Das Warten auf In-Stream-Metadatenereignisse kann je nach das Streamformat (HLS oder DASH), den Streamtyp (Live- oder VOD-Stream), den den Playertyp und den Typ des verwendeten Backends für die dynamische Anzeigenbereitstellung. Weitere Informationen finden Sie im Artikel mit zeitlicher Festlegung Metadaten für weitere Informationen.

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

Wenn du einen HLS.js-Player verwendest, warte auf das HLS.js-Ereignis FRAG_PARSING_METADATA, um ID3-Metadaten zu erhalten und sie mit StreamManager.processMetadata() an das SDK weiterzuleiten.

Wenn das Video automatisch abgespielt werden soll, nachdem alle Inhalte geladen und bereit sind, warte 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-Streams-Format, Live- und VOD-Streamtyp)

Wenn du einen DASH.js-Player verwendest, müssen verschiedene Strings verwendet werden, um die ID3-Metadaten für Live- oder VOD-Inhalte zu überwachen. Streams:

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

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

Wenn die Videosteuerelemente automatisch eingeblendet werden sollen, nachdem alles geladen wurde und fertig ist, auf das DASH.js-Ereignis MANIFEST_LOADED warten zu können.

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 du für die Livestreamwiedergabe den Shaka-Player verwendest, verwende den String 'emsg', um auf Metadatenereignisse zu warten. Verwende dann die Daten der Ereignisnachricht in deinem 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 du den Shaka-Player für die Wiedergabe von VOD-Streams verwendest, verwende den String 'timelineregionenter', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Daten aus Ereignisnachrichten in Ihrem Aufruf, um StreamManager.processMetadata() durch den 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);
       }
}

Player-Ereignisse verarbeiten

Füge den Ereignissen pause und start des Videoelements Ereignis-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';
  }
}

Fertig! Sie fordern jetzt Anzeigen in einem Pod-Auslieferungsstream mit das IMA DAI SDK für HTML5. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Leitfäden oder in den Beispielen auf GitHub.