Einführung in das IMA DAI SDK

Mit IMA SDKs kannst du ganz einfach Multimedia-Anzeigen in deine Websites und Apps einbinden. Mit IMA SDKs können Anzeigen von jedem VAST-kompatiblen Ad-Server angefordert und die Anzeigenwiedergabe in Ihren Apps verwaltet werden. Mit IMA DAI SDKs senden Apps eine Streamanfrage für Anzeigen- und Videoinhalte – entweder VOD- oder Liveinhalte. Das SDK gibt dann einen kombinierten Videostream zurück, sodass Sie nicht zwischen Anzeigen- und Inhaltsvideo in Ihrer App wechseln müssen.

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

Vollständiger Dienst Pod-Auslieferung Cloud Stitching API Live Cloud Stitching API VOD

VOD-Streams abspielen, die bei der Google Cloud Video Stitcher API registriert sind

In diesem Leitfaden wird gezeigt, wie du mit dem IMA DAI SDK für HTML5 eine Google Cloud VOD-Stream-Sitzung anforderst und wiedergibst.

In diesem Leitfaden wird das einfache Beispiel aus dem Einstiegsleitfaden für die dynamische Anzeigenbereitstellung in IMA erweitert.

Informationen zur Einbindung in andere Plattformen oder zur Verwendung der clientseitigen IMA SDKs finden Sie unter Interactive Media Ads SDKs.

Wenn du dir eine fertige Beispielintegration ansehen oder folgen möchtest, lade das Beispiel für den Cloud-Video-Stitcher für HLS oder DASH herunter.

Hinweis:Das IMA DAI SDK für HTML5 unterstützt sowohl HLS- als auch DASH-Streams. Für die Wiedergabe ist jedoch ein anderer Mediaplayer oder eine andere Erweiterung wie HLS.js oder DASH.js mit unterschiedlichen Implementierungen erforderlich.

In dieser Anleitung wird beschrieben, wie du HLS.js und das IMA DAI SDK für die Wiedergabe eines HLS-Streams konfigurierst. Außerdem findest du hier wichtige Hinweise zu Implementierungsunterschieden für DASH.

Die IMA DASH.js-Beispielanwendung ist ein Ausgangspunkt für die Implementierung von DASH-DAI-Streams mit IMA.

Google Cloud-Projekt einrichten

Richten Sie ein Google Cloud-Projekt ein und konfigurieren Sie Dienstkonten für den Zugriff auf das Projekt.

Gib die folgenden Variablen für die Verwendung im IMA SDK ein:

Standort

Die Google Cloud-Region, in der deine VOD-Konfiguration erstellt wurde: LOCATION

Projektnummer

Die Google Cloud-Projektnummer, in der die Video Stitcher API verwendet wird: PROJECT_NUMBER

OAuth-Token

Das kurzlebige OAuth-Token eines Dienstkontos mit der Nutzerrolle „Video Stitcher“:

OAUTH_TOKEN

Weitere Informationen zum Erstellen kurzlebiger OAuth-Tokens Das OAuth-Token kann für mehrere Anfragen wiederverwendet werden, solange es nicht abgelaufen ist.

Netzwerkcode

Der Ad Manager-Netzwerkcode zum Anfordern von Anzeigen: NETWORK_CODE

VOD-Konfigurations-ID

Die VOD-Konfigurations-ID für den VOD-Stream: VOD_CONFIG_ID

Weitere Informationen zum Erstellen der VOD-Konfigurations-ID findest du im Leitfaden zum Erstellen einer VOD-Konfiguration für die Cloud-Stitching-Funktion.

Entwicklungsumgebung konfigurieren

Wichtig: Die IMA DAI-Klasse VideoStitcherVodStreamRequest unterstützt sowohl HLS-Streams als auch DASH-Streams mit mehreren Zeiträumen. Werbeunterbrechungen werden nur zwischen DASH-Zeiträumen eingefügt.

Die IMA-Beispiel-Apps zeigen nur HLS-Streamanfragen. Du kannst weiterhin DASH-Streams verwenden, wenn du die VideoStitcherVodStreamRequest-Klasse erstellst. Wenn du deinen DASH-kompatiblen Player einrichtest, musst du einen Listener für die Fortschrittsereignisse des Videoplayers einrichten, der die Metadaten des Videos an StreamManager.processMetadata() weitergeben kann. Diese Funktion verwendet drei Parameter:

1. type: Ein String, der für HLS-Streams auf 'ID3' und für DASH-Streams auf 'urn:google:dai:2018' festgelegt werden muss.

2. data: Bei DASH-Ereignisnachrichten ist dies der Nachrichtendatenstring.

3. timestamp: Eine Zahl, die der Startzeit der Ereignisnachricht für DASH-Streams entspricht.

Sende die Metadaten so schnell und so oft wie möglich, sobald sie von deinen Spielerereignissen verfügbar sind. Wenn Metadaten fehlen oder falsch sind, werden über das IMA DAI SDK möglicherweise keine Anzeigenereignisse ausgelöst. Das kann zu falsch erfassten Anzeigenereignissen führen.

Laden Sie die Beispiele für IMA-DAUs für HTML5 herunter und entpacken Sie die ZIP-Datei hls_js/simple in einen neuen Ordner. Dieses Beispiel ist eine Webanwendung, die Sie zu Testzwecken lokal hosten können.

Wenn Sie das Beispiel lokal hosten möchten, rufen Sie den neuen Ordner auf und führen Sie den folgenden Python-Befehl aus, um einen Webserver zu starten:

python3 -m http.server 8000

http.server ist nur in Python 3.x verfügbar. Sie können auch einen anderen Webserver verwenden, z. B. den Apache HTTP-Server oder Node.js.

Öffnen Sie einen Webbrowser und rufen Sie localhost:8000 auf, um einen Videoplayer zu sehen. Dein Browser muss die HLS.js-Bibliothek unterstützen.

Wenn alles richtig funktioniert, wird durch Klicken auf die Schaltfläche Wiedergabe im Videoplayer der Kurzfilm „Tears of Steel“ gestartet. Dabei werden alle 30 Sekunden Werbeunterbrechungen eingeblendet.

VOD-Stream anfordern

Wenn du den Beispielstream durch deinen VOD-Stream mit Anzeigen ersetzen möchtest, verwende die Klasse VideoStitcherVodStreamRequest, um automatisch eine Anzeigensitzung mit Google Ad Manager zu erstellen. Auf der Google Ad Manager-Benutzeroberfläche können Sie die generierten dynamischen Anzeigenbereitstellungssitzungen zum Überwachen und Beheben von Fehlern finden.

Im vorhandenen Beispiel gibt es Funktionen zum Anfordern eines VOD-Streams oder eines Livestreams. Damit die Funktion mit der Google Cloud Video Stitcher API funktioniert, müssen Sie eine neue Funktion hinzufügen, um ein VideoStitcherVodStreamRequest-Objekt zurückzugeben.

Beispiel:

// StreamManager which will be used to request DAI streams.
let streamManager;
...

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.LOADED,
      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);

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

  videoElement.addEventListener('pause', () => {
    playButton.style.display = "block";
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVodVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
  streamRequest.vodConfigId = 'VOD_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';

  streamManager.requestStream(streamRequest);
}

Lade die Seite neu. Anschließend kannst du den benutzerdefinierten VOD-Stream anfordern und abspielen.

(Optional) Optionen für die Streamingsitzung hinzufügen

Du kannst deine Streamanfrage anpassen, indem du Sitzungsoptionen hinzufügst, um die Standardkonfiguration der Cloud Video Stitcher API mit VideoStitcherVodStreamRequest.videoStitcherSessionOptions zu überschreiben. Wenn du eine nicht erkannte Option angibst, antwortet die Cloud Video Stitcher API mit einem HTTP-Fehler 400. Weitere Informationen finden Sie in der Anleitung zur Fehlerbehebung.

Du kannst die Manifestoptionen beispielsweise mit dem folgenden Code-Snippet überschreiben. Dabei werden zwei Streammanifeste mit Darstellungen angefordert, die nach der niedrigsten Bitrate sortiert sind.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "includeRenditions": [
      {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
      {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
    ],
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

Bereinigen

Nachdem du einen VOD-Stream mit der Google Cloud Video Stitcher API gehostet und über das IMA DAI SDK für HTML5 angefordert hast, solltest du alle Bereitstellungsressourcen bereinigen.

Folge der Anleitung unter VOD-Bereinigung, um alle nicht benötigten Ressourcen und Assets zu entfernen.

Verwenden Sie abschließend im Terminalfenster, in dem Sie den Python 3-Webserver gestartet haben, den Befehl ctrl+C, um den lokalen Server zu beenden.