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 einen kombinierten Videostream zurück, sodass Sie in Ihrer App nicht zwischen Anzeigen- und Inhaltsvideo 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 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. Wenn Sie sich eine fertige Stichprobe ansehen oder mit ihr einhergehen möchten mit Unterstützung für HLS.js und die Safari-Wiedergabe, finden Sie Beispiel für die HLS-Pod-Auslieferung Informationen zur Unterstützung von DASH.js findest du im Beispiel für das DASH-Pod-Bereitstellen. 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 des Pod-Auslieferungs mit dem IMA DAI SDK umfasst zwei Hauptkomponenten, die in diesem Leitfaden veranschaulicht werden:

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

• StreamManager: Ein Objekt, das die Kommunikation zwischen den Videostream und das IMA DAI SDK verwenden, z. B. durch das Auslösen von Tracking-Pings und Stream-Ereignisse an den Publisher weiterleiten.

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 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 der integrierte Server von Python.

1. Führen Sie in einer Befehlszeile im Verzeichnis, in dem sich die Datei index.html befindet, Folgendes aus:

   python -m http.server 8000
   

2. Rufen Sie 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 für die Anzeigen-UI zu erstellen. 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. Du solltest die vom IMA DAI SDK bereitgestellte Stream-ID eingeben müssen, bevor du eine Anfrage sendest. 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: 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: 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

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 zu benachrichtigen, Anzeigenereignisse 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 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 alles geladen wurde und fertig ist, hören Sie 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, musst du unterschiedliche Strings verwenden, um nach ID3-Metadaten für Live- oder VOD-Streams zu suchen:

• 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 Videosteuerung automatisch angezeigt werden soll, nachdem alles geladen und bereit ist, musst du das DASH.js-Ereignis MANIFEST_LOADED überwachen.

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. 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-Streams-Format)

Wenn Sie den Shaka-Player für Wiedergabe des VOD-Streams. Verwenden Sie den String 'timelineregionenter', um auf Metadatenereignisse. 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 findest du in der Anleitungen oder die Beispiele auf GitHub