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 jedem VAST-kompatiblen Ad-Server anfordern und die Anzeigenwiedergabe in Ihren Apps verwalten. Mit IMA DAI SDKs senden Apps Streamanfragen für Anzeigen- und Contentvideos – entweder für VOD oder Livecontent. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie in Ihrer App nicht mehr zwischen Anzeige- und Contentvideo wechseln müssen.

Gewünschte Lösung für die dynamische Anzeigenbereitstellung auswählen

Dynamische Anzeigenbereitstellung für die Pod-Auslieferung

In dieser Anleitung wird beschrieben, wie Sie einen Pod-Bereitstellungsstream für die dynamische Anzeigenbereitstellung für Live- oder VOD-Inhalte mithilfe des IMA DAI SDK für HTML5 mit einem Videoplayer wiedergeben, der für die Wiedergabe hls.js verwendet. Wenn Sie sich eine abgeschlossene Beispielintegration ansehen oder an einer abgeschlossenen Beispielintegration mit Unterstützung für HLS.js und die Safari-Wiedergabe interessiert sind, sehen Sie sich das Beispiel für die HLS-Pod-Auslieferung an. Informationen zur Unterstützung für DASH.js finden Sie im Beispiel für die DASH-Pod-Auslieferung. Sie können diese Beispielanwendungen von der GitHub-Versionsseite für die 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 erläutert werden:

• PodStreamRequest/PodVodStreamRequest: Ein Objekt, das eine Streamanfrage an die Werbeserver von Google definiert. Anfragen geben einen Netzwerkcode an. Die PodStreamRequest erfordert außerdem einen benutzerdefinierten Asset-Schlüssel und einen optionalen API-Schlüssel. Beide enthalten andere optionale Parameter.

• StreamManager: Ein Objekt, das die Kommunikation zwischen dem Videostream und dem IMA DAI SDK steuert, 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, das auf Ihrem Computer installiert ist, oder einen 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. Eine schnelle Möglichkeit, einen lokalen Entwicklungsteam zu starten, ist die Verwendung des integrierten Python-Servers.

1. Führen Sie in einer 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 andere gehostete Entwicklungsumgebung oder 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 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 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 Laden der Seite ausgeführt wird.

Die Konstanten für die Streamanfragen lauten wie folgt:

• BACKUP_STREAM: Eine URL für einen Back-up-Stream, der abgespielt werden soll, wenn beim Anzeigenprozess ein schwerwiegender Fehler auftritt.

• STREAM_URL: Nur für Livestreams verwendet Die Videostream-URL, die von der Manifestbearbeitung oder einem Drittanbieter mit Pod-Auslieferung bereitgestellt wird. Sie müssen die vom IMA DAI SDK bereitgestellte Stream-ID einfügen, bevor Sie eine Anfrage stellen können. In diesem Fall enthält die Stream-URL den Platzhalter [[STREAMID]], der vor der Anfrage durch die Stream-ID ersetzt wird.

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

• CUSTOM_ASSET_KEY: Nur für Livestreams verwendet Das ist der Schlüssel für das benutzerdefinierte Asset, mit dem das Pod-Auslieferungsereignis in Ad Manager 360 identifiziert wird. Sie kann von Ihrem Manifestbearbeitungsmanager oder einem Drittanbieter für die Pod-Auslieferung erstellt werden.

• API_KEY: 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 
  <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 mit einem Skript-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 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);
}

Streammetadaten verarbeiten

In diesem Schritt implementieren Sie Event-Listener für Metadaten, um das SDK über Anzeigenereignisse zu benachrichtigen. Das Warten auf In-Stream-Metadatenereignisse kann je nach Streamformat (HLS oder DASH), Streamtyp (Live- oder VOD-Stream), Playertyp und Typ des verwendeten Back-Ends für die dynamische Anzeigenbereitstellung variieren. Weitere Informationen finden Sie unter Metadaten mit zeitlicher Festlegung.

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 mit StreamManager.processMetadata() an das SDK zu übergeben.

Damit das Video automatisch wiedergegeben wird, nachdem alles geladen 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-Streams-Format, Live- und VOD-Streamtyp)

Wenn Sie einen DASH.js-Player verwenden, müssen Sie unterschiedliche Strings verwenden, um die ID3-Metadaten für Live- oder VOD-Streams zu überwachen:

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

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

Warten Sie auf das DASH.js-Ereignis MANIFEST_LOADED, damit die Videosteuerelemente automatisch angezeigt werden, nachdem alles geladen und bereit ist.

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 den Shaka-Player für die Livestreamwiedergabe verwenden, verwenden Sie den String 'emsg', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Daten zu Ereignisnachrichten im 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 den Shaka-Player für die VOD-Streamwiedergabe verwenden, verwenden Sie den String 'timelineregionenter', um auf Metadatenereignisse zu warten. Verwenden Sie dann die Ereignisnachrichtendaten in Ihrem StreamManager.processMetadata()-Aufruf 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);
       }
}

Player-Ereignisse 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 Werbeunterbrechungen pausiert wird.

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 verwenden jetzt das IMA DAI SDK für HTML5, um Anzeigen in einem Pod-Auslieferungsstream anzufordern und auszuliefern. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Leitfäden oder in den Beispielen auf GitHub.