IMA SDK für die dynamische Anzeigenbereitstellung einrichten

Mit den IMA SDKs lassen sich Multimedia-Anzeigen ganz einfach in Ihre Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-konformen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Contentvideos – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie das Umschalten zwischen Anzeigen- und Inhaltsvideo in Ihrer App nicht verwalten müssen.

Wählen Sie die DAI-Lösung aus, die Sie interessiert

Komplettservice für die dynamische Anzeigenbereitstellung

In dieser Anleitung wird gezeigt, wie Sie das IMA DAI SDK in eine Videoplayer-App einbinden. Wenn Sie sich ein vollständiges Beispiel für die Integration ansehen oder es nachvollziehen möchten, laden Sie das einfache Beispiel von GitHub herunter.

IMA DAI – Übersicht

Die Implementierung des IMA DAI SDK umfasst zwei Hauptkomponenten, wie in dieser Anleitung beschrieben:

  • StreamRequest: entweder ein VODStreamRequest- oder ein LiveStreamRequest-Objekt, das eine Streamanfrage definiert. Streamanfragen können entweder für Video-on-Demand- oder Livestreams erfolgen. In Livestream-Anfragen wird ein Asset-Schlüssel angegeben, in VOD-Anfragen eine CMS-ID und eine Video-ID. Beide Anfragetypen können optional einen API-Schlüssel enthalten, der für den Zugriff auf die angegebenen Streams erforderlich ist, sowie einen Google Ad Manager-Netzwerkcode, damit das IMA SDK Anzeigen-IDs gemäß den Google Ad Manager-Einstellungen verarbeiten kann.
  • StreamManager: Ein Objekt, das Streams für die dynamische Anzeigenbereitstellung und Interaktionen mit dem Backend für die dynamische Anzeigenbereitstellung verarbeitet. Der Stream-Manager verarbeitet auch Tracking-Pings und leitet Stream- und Anzeigenereignisse an den Publisher weiter.

Vorbereitung

  • Drei leere Dateien
    • dai.html
    • dai.css
    • dai.js
  • Python auf Ihrem Computer installiert oder ein Webserver zum Testen

Entwicklungsserver starten

Da das IMA DAI 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 über eine Befehlszeile im Verzeichnis mit Ihrer index.html-Datei Folgendes aus:

    python -m http.server 8000

  2. Rufen Sie in einem Webbrowser http://localhost:8000/ auf.

    Sie können auch einen anderen Webserver verwenden, z. B. den Apache HTTP Server.

Videoplayer erstellen

Ändern Sie zuerst dai.html, um ein HTML5-Videoelement und ein Div-Element für den Clickthrough zu erstellen. Im folgenden Beispiel wird das IMA DAI SDK importiert. Weitere Informationen finden Sie unter IMA DAI SDK importieren.

Fügen Sie außerdem die erforderlichen Tags hinzu, um die Dateien dai.css und dai.js zu laden und den hls.js-Videoplayer zu importieren. Anschließend können Sie dai.css ändern, um die Größe und Position der Seitenelemente festzulegen. Definieren Sie schließlich in dai.js Variablen für die Informationen zur Streamanfrage, eine initPlayer()-Funktion, die beim Laden der Seite ausgeführt wird, und richten Sie die Schaltfläche „Wiedergabe“ so ein, dass beim Klicken auf sie ein Stream angefordert wird.

<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/hls.js@latest"></script>
  <script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
  <script src="dai.js"></script>
  <link rel="stylesheet" href="dai.css">
</head>
<body onLoad="initPlayer()">
  <h2>IMA SDK DAI Demo (HLS.JS)</h2>
  <video id="video"></video>
  <div id="adUi"></div>
  <button id="play-button">Play</button>
</body>
</html>


dai.html
 
#video,
#adUi {
  width: 640px;
  height: 360px;
  position: absolute;
  top: 35px;
  left: 0;
}

#adUi {
  cursor: pointer;
}

#play-button {
  position: absolute;
  top: 400px;
  left: 15px;
}

dai.css
 
// This stream will be played if ad-enabled playback fails.
const BACKUP_STREAM =
    'http://storage.googleapis.com/testtopbox-public/video_content/bbb/' +
    'master.m3u8';

// Live stream asset key.
// const TEST_ASSET_KEY = 'c-rArva4ShKVIAkNfy6HUQ';

// VOD content source and video IDs.
const TEST_CONTENT_SOURCE_ID = '2548831';
const TEST_VIDEO_ID = 'tears-of-steel';

// Ad Manager network code.
const NETWORK_CODE = '21775744923';
const API_KEY = null;

// StreamManager which will be used to request ad-enabled streams.
let streamManager;

// hls.js video player
const hls = new Hls();

// Video element
let videoElement;

// Ad UI element
let adUiElement;

// The play/resume button
let playButton;

// Whether the stream is currently in an ad break.
let adBreak = false;

/**
 * Initializes the video player.
 */
function initPlayer() {
  videoElement = document.getElementById('video');
  playButton = document.getElementById('play-button');
  adUiElement = document.getElementById('adUi');
  createStreamManager();
  listenForMetadata();

  // Show the video controls when the video is paused during an ad break,
  // and hide them when ad playback resumes.
  videoElement.addEventListener('pause', () => {
    if (adBreak) {
      showVideoControls();
    }
  });
  videoElement.addEventListener('play', () => {
    if (adBreak) {
      hideVideoControls();
    }
  });

  playButton.addEventListener('click', () => {
    console.log('initiatePlayback');
    requestStream();
    // Hide this play button after the first click to request the stream.
    playButton.style.display = 'none';
  });
}
dai.js

Wenn Sie die Wiedergabe während pausierter Werbeunterbrechungen fortsetzen möchten, richten Sie Event-Listener für die Ereignisse pause und start des Videoelements ein, um die Player-Steuerelemente ein- und auszublenden.

/**
 * Hides the video controls.
 */
function hideVideoControls() {
  videoElement.controls = false;
  adUiElement.style.display = 'block';
}

/**
 * Shows the video controls.
 */
function showVideoControls() {
  videoElement.controls = true;
  adUiElement.style.display = 'none';
}
dai.js

IMA DAI SDK laden

Fügen Sie als Nächstes das IMA-Framework mit einem Script-Tag in dai.html vor dem Tag für dai.js ein.

<script src="//imasdk.googleapis.com/js/sdkloader/ima3_dai.js"></script>
dai.html

StreamManager initialisieren

Wenn Sie eine Reihe von Anzeigen anfordern möchten, erstellen Sie ein ima.dai.api.StreamManager, das für das Anfordern und Verwalten von DAI-Streams zuständig ist. Der Konstruktor akzeptiert ein Videoelement und ein UI-Element für Anzeigen, um Anzeigenklicks zu verarbeiten.

/**
 * Create the StreamManager and listen to stream events.
 */
function createStreamManager() {
  streamManager =
      new google.ima.dai.api.StreamManager(videoElement, adUiElement);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.LOADED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.ERROR, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED, onStreamEvent);
  streamManager.addEventListener(
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED, onStreamEvent);
}
dai.js

Streaminganfrage stellen

Funktionen zum Anfordern von Streams definieren Dieses Beispiel enthält Funktionen für VOD und Livestreams, die Instanzen der Klasse VODStreamRequest und der Klasse LiveStreamRequest erstellen. Rufen Sie nach der Instanziierung von streamRequest die Methode streamManager.requestStream() mit der Streamanfrageinstanz auf.

/**
 * Makes a stream request and plays the stream.
 */
function requestStream() {
  requestVODStream(TEST_CONTENT_SOURCE_ID, TEST_VIDEO_ID, NETWORK_CODE, API_KEY);
  // Uncomment line below and comment one above to request a LIVE stream.
  // requestLiveStream(TEST_ASSET_KEY, NETWORK_CODE, API_KEY);
}

/**
 * Requests a Live stream with ads.
 * @param {string} assetKey
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestLiveStream(assetKey, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.LiveStreamRequest();
  streamRequest.assetKey = assetKey;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}

/**
 * Requests a VOD stream with ads.
 * @param {string} cmsId
 * @param {string} videoId
 * @param {?string} networkCode
 * @param {?string} apiKey
 */
function requestVODStream(cmsId, videoId, networkCode, apiKey) {
  const streamRequest = new google.ima.dai.api.VODStreamRequest();
  streamRequest.contentSourceId = cmsId;
  streamRequest.videoId = videoId;
  streamRequest.networkCode = networkCode;
  streamRequest.apiKey = apiKey;
  streamManager.requestStream(streamRequest);
}
dai.js

Für beide Methoden für Streamanfragen ist ein optionaler API-Schlüssel erforderlich. Wenn Sie einen geschützten Stream verwenden, müssen Sie einen Authentifizierungsschlüssel für die dynamische Anzeigenbereitstellung erstellen. Weitere Informationen finden Sie unter Anfragen für Videostreams der dynamischen Anzeigenbereitstellung authentifizieren. Keiner der Streams in diesem Beispiel ist mit einem Authentifizierungsschlüssel für die dynamische Anzeigenbereitstellung geschützt. Daher wird apiKey nicht verwendet.

Streammetadaten parsen

Außerdem müssen Sie einen Handler hinzufügen, um auf Ereignisse mit Zeitstempel zu reagieren und die Ereignisse an die StreamManager-Klasse für IMA weiterzuleiten, damit während Werbeunterbrechungen Werbeereignisse ausgegeben werden:

/**
 * Set up metadata listeners to pass metadata to the StreamManager.
 */
function listenForMetadata() {
  // Timed metadata is handled differently by different video players, and the
  // IMA SDK provides two ways to pass in metadata,
  // StreamManager.processMetadata() and StreamManager.onTimedMetadata().
  //
  // Use StreamManager.onTimedMetadata() if your video player parses
  // the metadata itself.
  // Use StreamManager.processMetadata() if your video player provides raw
  // ID3 tags, as with hls.js.
  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });
}
dai.js

In diesem Leitfaden wird der hls.js-Player für die Streamwiedergabe verwendet. Die Implementierung von Metadaten hängt jedoch vom verwendeten Player ab.

Stream-Ereignisse verarbeiten

Implementieren Sie Event-Listener für wichtige Videoereignisse. In diesem Beispiel werden die Ereignisse LOADED, ERROR, AD_BREAK_STARTED und AD_BREAK_ENDED durch Aufrufen einer onStreamEvent()-Funktion verarbeitet. Diese Funktion kümmert sich um das Laden des Streams, Streamfehler und das Deaktivieren der Player-Steuerelemente während der Anzeigenwiedergabe, was für das IMA SDK erforderlich ist.

/**
 * Responds to a stream event.
 * @param {!google.ima.dai.api.StreamEvent} e
 */
function onStreamEvent(e) {
  switch (e.type) {
    case google.ima.dai.api.StreamEvent.Type.LOADED:
      console.log('Stream loaded');
      loadUrl(e.getStreamData().url);
      break;
    case google.ima.dai.api.StreamEvent.Type.ERROR:
      console.log('Error loading stream, playing backup stream.' + e);
      loadUrl(BACKUP_STREAM);
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED:
      console.log('Ad Break Started');
      adBreak = true;
      hideVideoControls();
      break;
    case google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED:
      console.log('Ad Break Ended');
      adBreak = false;
      showVideoControls();
      break;
    default:
      break;
  }
}

/**
 * Loads and plays a Url.
 * @param {string} url
 */
function loadUrl(url) {
  console.log('Loading:' + url);
  hls.loadSource(url);
  hls.attachMedia(videoElement);
  hls.on(Hls.Events.MANIFEST_PARSED, function() {
    console.log('Video Play');
    videoElement.play();
  });
}
dai.js

Wenn der Stream geladen wird, lädt der Videoplayer die angegebene URL und gibt sie mit der Funktion loadUrl() wieder.

Geschafft! Sie fordern jetzt Anzeigen mit dem IMA DAI SDK an und präsentieren sie. Weitere Informationen zu erweiterten SDK-Funktionen finden Sie in den anderen Anleitungen oder in den Beispielen auf GitHub.