Videoplayer-App des Clients für VOD-Streams

Mit der Google DAI Pod Serving API können Sie serverseitige Anzeigenbereitstellung von Google Ads erstellt und gleichzeitig die Kontrolle über das Stitching von Videos behalten.

Wichtiger Hinweis: Bevor Sie sich für diese API entscheiden, sollten Sie überprüfen, ob bereits ein IMA DAI SDK für die Plattform Ihrer Wahl. Das IMA DAI SDK wird für Plattformen empfohlen, wo es verfügbar ist. Die Pod Serving API ist nur für die Verwendung in Plattformen ohne IMA DAI SDK.

In diesem Leitfaden erfahren Sie, wie Sie mit der Pod Serving API interagieren und mit dem IMA DAI SDK vergleichbar ist. Bei spezifischen Fragen zu unterstützten Funktionen, wenden Sie sich an Ihren Google Account Manager.

Die Pod Serving API unterstützt Pod-Auslieferungs-Streams entweder in HLS oder MPEG-DASH Streaming-Protokolle. In diesem Leitfaden geht es um HLS-Streams und die wichtigsten Unterschiede zwischen HLS und MPEG-DASH in bestimmten Schritten.

Führen Sie die folgenden Schritte aus, um die Pod Serving API in Ihre Anwendung für VOD-Streams zu integrieren: folgenden Schritten:

Anfrage für eine Streamregistrierung an Ad Manager senden

Stellen Sie eine POST-Anfrage an den Endpunkt der Streamregistrierung. Sie erhalten der Reihe nach eine JSON-Antwort mit der Stream-ID, die an die Manifestbearbeitung gesendet werden soll Server und zugehörige Pod Serving API-Endpunkte.

API-Endpunkt

POST: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Pfadparameter

{network_code}

Ihr Google Ad Manager 360-Netzwerkcode

JSON-Textparameter

targeting_parameters

Ein JSON-Objekt, das die ID der Contentquelle (cmsid), die Video-ID (vid) und Anzeigen-ausrichtung Parameter. Erforderlich

Antwort (JSON)

media_verification_url	Die Basis-URL zum Pingen von Wiedergabe-Tracking-Ereignissen. Eine vollständige Medienüberprüfung URL wird gebildet, indem eine Anzeigenereignis-ID an diese Basis-URL angehängt wird.
metadata_url	Die URL zum Anfordern von Anzeigen-Pod-Metadaten.
stream_id	Der String, mit dem die aktuelle Streamsitzung identifiziert wird.
valid_for	Die verbleibende Zeit bis zum Ablauf der aktuellen Streamsitzung in dhms (Tage, Stunden, Minuten, Sekunden). Beispiel: 2h0m0.000s steht für eine Dauer von 2 Stunden.
valid_until	Der Zeitpunkt, zu dem die aktuelle Streamsitzung abläuft, angegeben gemäß ISO 8601. Datum/Uhrzeit-String in yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm Format.

Beispielanfrage (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

Beispielantwort

{
  "media_verification_url": "https://dai.google.com/.../media/",
  "metadata_url": "https://dai.google.com/.../metadata",
  "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
  "valid_for": "8h0m0s",
  "valid_until": "2023-03-24T08:30:26.839717986-07:00"
}

Bei Fehlern werden Standard-HTTP-Fehlercodes ohne JSON-Antwort zurückgegeben Textkörper.

Parsen Sie die JSON-Antwort und speichern Sie die relevanten Werte.

Tipp :Die in der API-Antwort angegebenen URLs können ohne vorherige Änderungen . Verwenden Sie daher die URLs aus der API-Antwort selbst bei der Konstruktion. So können Sie sicherstellen, dass Ihr Code weiterhin funktioniert. wenn sich die URLs ändern.

Streammanifest über die Manifestbearbeitung anfordern

Jede Manifestbearbeitung hat ein anderes Anforderungs- und Antwortformat. Kontakt erfahren Sie vom Anbieter der Manipulatoren, welche spezifischen Anforderungen Sie erfüllen müssen. Wenn Sie Implementieren Sie Ihre eigene Manifest-Manipulator-App, lesen Sie die Manifest-Manipulator-App , um zu verstehen, Anforderungen für diese Komponente.

Im Allgemeinen müssen Sie die Stream-ID übergeben, die vom Registrierungsendpunkt oben an deine Manifest-Manipulator-App übergeben, damit sie sitzungsspezifischen Manifesten. Sofern in Ihrem Manifest nicht ausdrücklich anders angegeben erhalten Sie als Antwort auf Ihre Manifest-Anfrage einen Videostream mit sowohl auf Content als auch auf Anzeigen.

Beispielanfrage (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Beispielantwort (HLS)

#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_     subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8

Stream wiedergeben

Laden Sie das Manifest, das Sie vom Server für die Manifestbearbeitung erhalten haben, in ein Videoplayer und starte die Wiedergabe.

Metadaten des Anzeigen-Pods von Ad Manager anfordern

Stellen Sie eine GET-Anfrage an die metadata_url, die Sie in Schritt 1 erhalten haben. Dieses Schritt muss erfolgen, nachdem Sie das zusammengesetzte Manifest aus Ihrem Manifest erhalten haben und Manipulator. Im Gegenzug erhalten Sie ein JSON-Objekt, das Folgendes enthält: Parameter:

tags	Eine Reihe von Schlüssel/Wert-Paaren, die alle Anzeigenereignisse enthalten, die in der . Die Schlüssel sind entweder die ersten 17 Zeichen eines Anzeigenereignisses. ID, die in den zeitgesteuerten Metadaten des Streams oder im Fall von Ereignissen angezeigt wird vom Typ progress, der vollständigen Anzeigenereignis-ID. Jeder Wert ist ein Objekt, das die folgenden Parameter enthält: ad Die ID einer Anzeige, die mit einem Schlüssel im ads-Objekt übereinstimmt. ad_break_id Die ID einer Werbeunterbrechung, die mit einem Schlüssel im ad_breaks übereinstimmt -Objekt enthält. type Die Art des Anzeigenereignisses. Zu den Anzeigenereignistypen gehören: start Wird zu Beginn der Anzeige ausgelöst firstquartile Wird am Ende des ersten Quartils ausgelöst. midpoint Wird beim Mittelpunkt der Anzeige ausgelöst thirdquartile Wird am Ende des dritten Quartils ausgelöst. complete Wird am Ende der Anzeige ausgelöst progress Wird regelmäßig während der gesamten Anzeige ausgelöst, um die App darüber zu informieren wird die Pause gerade gespielt.
ads	Eine Reihe von Schlüssel/Wert-Paaren, die alle im Stream erscheinenden Anzeigen beschreiben. Die Schlüssel sind Anzeigen-IDs, die mit den Werten im tags-Objekt übereinstimmen oben aufgeführt. Jeder Wert ist ein Objekt, das die folgenden Parameter enthält: ad_break_id Die ID einer Werbeunterbrechung, die mit einem Schlüssel im ad_breaks übereinstimmt -Objekt enthält. position Die Position, an der diese Anzeige innerhalb der Gruppe von Anzeigen erscheint. in Gleitkommasekunden. duration Die Länge der Anzeige in Gleitkommasekunden. clickthrough_url Die URL, die geöffnet werden soll, wenn ein Nutzer mit dieser Anzeige interagiert (falls unterstützt).
ad_breaks	Eine Reihe von Schlüssel/Wert-Paaren, die alle Werbeunterbrechungen im Stream beschreiben. Die Schlüssel sind IDs für Werbeunterbrechungen, die mit Werten im tags übereinstimmen. und ads. Jeder Wert ist ein Objekt mit den folgenden Parametern: type Der Typ der Werbeunterbrechung Werbeunterbrechungstypen sind pre (Pre-Roll), mid (Mid-Roll) und post (Post-Roll). duration Das ist die Länge der Werbeunterbrechung in Gleitkommasekunden. ads Die Anzahl der Anzeigen in dieser Werbeunterbrechung.

Speichere diese Werte, um sie mit zeitlich festgelegten Metadatenereignissen in deinem Video zu verknüpfen .

Beispielanfrage (cURL)

curl https://dai.google.com/.../metadata

Beispielantwort

{
  "tags":{
    "google_5555555555":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"firstquartile"
    },
    "google_1234567890123456789":{
      "ad":"0000229834_ad1",
      "ad_break_id":"0000229834",
      "type":"progress"
    },
    ...
  },
  "ads":{
    "0000229834_ad1":{
      "ad_break_id":"0000229834",
      "position":1,
      "duration":15,
      "clickthrough_url":"https://.../",
      ...
    },
          ...
  },
  "ad_breaks":{
    "0000229834":{
      "type":"mid",
      "duration":15,
      "ads":1
    },
    ...
  }
}

Auf Anzeigenereignisse warten

Über ausgelöste Anzeigenereignisse im Audio-/Videostream auf zeitlich begrenzte Metadaten warten Ihres Videoplayers.

Bei MPEG-TS-Streams werden die Metadaten als In-Band-ID3 v2.3-Tags angezeigt. Jedes Metadaten-Tag hat die ID TXXX und der Wert beginnt mit dem String google_ gefolgt von einer Reihe von Zeichen. Dieser Wert ist die Anzeigenereignis-ID.

XXX in TXXX ist kein Platzhalter. Der String TXXX ist die ID3-Tag-ID. für „Benutzerdefinierten Text“ reserviert.

Beispiel für ein ID3-Tag

TXXXgoogle_1234567890123456789

Bei MP4-Streams werden diese als In-Band-Emsg-Ereignisse gesendet, die ID3 v2.3 emulieren. Tags. Jedes relevante E-Mail-Feld hat einen scheme_id_uri-Wert von entweder https://aomedia.org/emsg/ID3 oder https://developer.apple.com/streaming/emsg-id3 und ein message_data-Wert beginnend mit ID3TXXXgoogle_. Dieser message_data-Wert ohne den Wert ID3TXXX, ist die Anzeigenereignis-ID.

Beispiel für ein Nachrichtenfeld

Die Datenstruktur kann je nach Mediaplayer-Bibliothek variieren.

Wenn die Anzeigenereignis-ID google_1234567890123456789 lautet, sieht die Antwort so aus: dies:

{
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1234567890123456789",
  ...
}

Einige Mediaplayer-Bibliotheken zeigen automatisch E-Mail-Ereignisse an, die ID3 emulieren Tags als native ID3-Tags. In diesem Fall weisen MP4-Streams identische ID3-Tags auf. als MPEG_TS.

Benutzeroberfläche der Client-Videoplayer-App aktualisieren

Jede Anzeigenereignis-ID kann einem Schlüssel im tags-Objekt aus Schritt 4 zugeordnet werden. Der Abgleich dieser Werte erfolgt in zwei Schritten:

1. Suchen Sie im tags-Objekt nach einem Schlüssel, der mit der vollständigen Anzeigenereignis-ID übereinstimmt. Wenn eine Übereinstimmung gefunden wurde, rufen Sie den Ereignistyp und die zugehörigen ad ab und ad_break-Objekte. Diese Ereignisse sollten den Typ progress haben.

   Wenn für die vollständige Anzeigenereignis-ID keine Übereinstimmung gefunden wird, sieh in der tags nach -Objekt für einen Schlüssel, der mit den ersten 17 Zeichen der Anzeigenereignis-ID übereinstimmt. Rufen Sie den Ereignistyp und die zugehörigen ad- und ad_break-Objekte ab. Damit sollten alle Ereignisse mit anderen Typen als progress abgerufen werden.

2. Verwende diese Informationen, um die Benutzeroberfläche deines Players zu aktualisieren. Wenn beispielsweise du ein start- oder das erste progress-Ereignis erhältst, blende die Suche des Spielers aus und zeigen ein Overlay an, das die Position der aktuellen Anzeige Werbeunterbrechung, zum Beispiel: „Anzeige 1 von 3“.

Beispiele für Anzeigenereignis-IDs

google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID

Beispiel-Tags-Objekt

{
  "google_5555555555":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"firstquartile"
  },
  "google_1234567890123456789":{
    "ad":"0000229834_ad1",
    "ad_break_id":"0000229834",
    "type":"progress"
  },
  ...
}

Pings zur Medienüberprüfung senden

Bei jedem Anzeigenereignis muss ein Media-Bestätigungs-Ping an Ad Manager gesendet werden. mit einem anderen Typ als progress empfangen wird.

Um die vollständige Medienüberprüfungs-URL eines Anzeigenereignisses zu generieren, hängen Sie die vollständige Anzeigenereignis-ID in den Wert „media_verification_url“ aus der Streamregistrierung Antwort.

Stellen Sie eine GET-Anfrage mit der vollständigen URL. Wenn die Überprüfungsanfrage erfolgreich war, erhalten Sie eine HTTP-Antwort mit dem Statuscode 202. Andernfalls wird der HTTP-Fehlercode 404 zurückgegeben.

Tipp :Anzeigenereignisse vom Typ progress sollten nicht an Ad Manager gesendet werden. Diese So soll der Videoplayer-App des Kunden darüber informiert werden, dass eine Werbeunterbrechung die in Situationen wiedergegeben werden, in denen das Startereignis nicht empfangen wurde. z. B. wenn der Nutzer zu einer bestimmten Position sucht oder die Wiedergabe an einer bestimmten Stelle startet. der sich in der Mitte der Anzeige befindet, erhält er kein Startereignis. An Ad Manager gesendete Fortschrittsereignisse werden verworfen, was sich negativ auf der App-Leistung.

Beispielanfrage (cURL)

curl https://{...}/media/google_5555555555123456789

Beispiel für eine erfolgreiche Antwort

HTTP/1.1 202 Accepted

Zusätzliche Ressourcen

• IMA SDK-Dokumentation
• Implementierungstypen von Playern für die dynamische Anzeigenbereitstellung Vergleich