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 <ph type="x-smartling-placeholder"></ph> 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.

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

Dynamische Anzeigenbereitstellung für die Pod-Auslieferung

In dieser Anleitung wird gezeigt, wie Sie einen Pod-Auslieferungsstream für die dynamische Anzeigenbereitstellung für Live- oder VOD-Streams wiedergeben. IMA DAI SDK für HTML5 mit einem Videoplayer verwenden, der auf hls.js basiert für die Wiedergabe. 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 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 andere 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, Webserver oder anderes gehostetes Entwicklungsprogramm Testumgebung

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 die Streamanfragen lauten wie folgt:

• 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: 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]], die 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 Der benutzerdefinierte Asset-Schlüssel, der das Pod-Auslieferungsereignis in Ad Manager 360 identifiziert. Dies kann erstellt werden, indem Ihren Partner für die Manifestbearbeitung oder den Pod-Auslieferungspartner.

• API_KEY: Nur für Livestreams verwendet Ein optionaler API-Schlüssel, der erforderlich, 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="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 Framework für die dynamische Anzeigenbereitstellung mit einem Skript-Tag in dai.html vor dem Tag hinzu. für dai.js.

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 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 Sie einen HLS.js-Player verwenden, hören Sie das HLS.js-Ereignis FRAG_PARSING_METADATA, um ID3-Metadaten abzurufen und an den SDK mit StreamManager.processMetadata().

Wenn das Video automatisch abgespielt werden soll, nachdem alles geladen wurde und fertig ist, hören Sie 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'

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

Damit die Videosteuerelemente automatisch angezeigt werden, 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 Sie den Shaka-Player für für die Livestream-Wiedergabe 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 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ügen Sie den pause- und start-Ereignissen des Videoelements Ereignis-Listener hinzu, um diese zuzulassen. Die Wiedergabe wird fortgesetzt, wenn das SDK während der Werbeunterbrechungen eine Pause macht.

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