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.
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.
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:
|
||||||||||||||||||
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_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:
|
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:
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örigenad
ab undad_break
-Objekte. Diese Ereignisse sollten den Typprogress
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örigenad
- undad_break
-Objekte ab. Damit sollten alle Ereignisse mit anderen Typen alsprogress
abgerufen werden.Verwende diese Informationen, um die Benutzeroberfläche deines Players zu aktualisieren. Wenn beispielsweise du ein
start
- oder das ersteprogress
-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.
Beispielanfrage (cURL)
curl https://{...}/media/google_5555555555123456789
Beispiel für eine erfolgreiche Antwort
HTTP/1.1 202 Accepted