Mit der Google DAI Pod Serving API können Sie die serverseitige Anzeigenbereitstellung über Google Ads vornehmen und dabei Ihr eigenes Video-Stitching steuern.
In diesem Leitfaden erfahren Sie, wie Sie mit der Pod Serving API interagieren und ähnliche Funktionen mit dem IMA DAI SDK erzielen. Bei konkreten Fragen zu unterstützten Funktionen wenden Sie sich an Ihren Google Account Manager.
Die Pod Serving API unterstützt Pod-Bereitstellungsstreams entweder in HLS- oder MPEG-DASH-Streamingprotokollen. Dieser Leitfaden konzentriert sich auf HLS-Streams und hebt die wichtigsten Unterschiede zwischen HLS und MPEG-DASH in bestimmten Schritten hervor.
Mit den folgenden Schritten binden Sie die Pod Serving API für VOD-Streams in Ihre Anwendung ein:
Anfrage zur Streamregistrierung an Ad Manager senden
Stellen Sie eine POST-Anfrage an den Endpunkt der Streamregistrierung. Sie erhalten wiederum eine JSON-Antwort mit der Stream-ID, die an Ihren Manifestbearbeitungsserver und die zugehörigen Pod Serving API-Endpunkte gesendet werden soll.
API-Endpunkt
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded
Pfadparameter
{network_code} |
Ihr Google Ad Manager 360-Netzwerkcode |
{custom_asset} |
Die benutzerdefinierte Kennung, die diesem Ereignis in Google Ad Manager zugewiesen wird. |
Formularcodierte Textparameter
Ein optionaler Satz von formularcodierten Targeting-Parametern .
Antwort (JSON)
media_verification_url |
Basis-URL für Ping-Wiedergabe-Tracking-Ereignisse. Eine vollständige Medienüberprüfungs-URL wird gebildet, indem eine Anzeigenereignis-ID an diese Basis-URL angehängt wird. |
metadata_url |
Die URL zum Anfordern der 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 im Format dhms (Tage, Stunden, Minuten, Sekunden). Beispielsweise steht 2h0m0.000s für eine Dauer von 2 Stunden.
|
valid_until |
Der Zeitpunkt, zu dem die aktuelle Streamsitzung abläuft, als Datums-/Uhrzeitstring nach ISO 8601 im Format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
Beispielanfrage (cURL)
curl -X POST \
-H "Content-Type: application/x-www-form-urlencoded"
-d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\""
https://dai.google.com/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
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"
}
Im Falle von Fehlern werden Standard-HTTP-Fehlercodes ohne JSON-Antworttext zurückgegeben.
Parsen Sie die JSON-Antwort und speichern Sie die relevanten Werte.
Stream-Manifest von der Manifestbearbeitung anfordern
Jede Manifestbearbeitung hat ein anderes Anfrage- und Antwortformat. Wenden Sie sich an den Anbieter Ihrer Manipulation, um mehr über deren spezifische Anforderungen zu erfahren. Wenn Sie Ihre eigene Manifestbearbeitung implementieren, lesen Sie die Anleitung zur Manifestbearbeitung, um sich mit den Anforderungen für diese Komponente vertraut zu machen.
Im Allgemeinen musst du die Stream-ID, die vom obigen Registrierungsendpunkt zurückgegeben wurde, an deine Manifestbearbeitung übergeben, damit dieser sitzungsspezifische Manifeste erstellen kann. Sofern in der Manifestbearbeitung nicht anders angegeben, ist die Antwort auf Ihre Manifestanfrage ein Videostream, der sowohl Inhalte als auch Anzeigen enthält.
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 Manifestbearbeitungsserver erhalten haben, in einen Videoplayer und starten Sie die Wiedergabe.
Metadaten für Anzeigen-Pod von Ad Manager anfordern
Stellen Sie eine GET
-Anfrage an die metadata_url
, die Sie in Schritt 1 erhalten haben. Dieser Schritt muss erfolgen, nachdem Sie das zusammengefügte Manifest von der Manifestbearbeitung erhalten haben. Daraufhin erhalten Sie ein JSON-Objekt, das die folgenden Parameter enthält:
tags |
Eine Reihe von Schlüssel/Wert-Paaren, die alle Anzeigenereignisse enthalten, die im Stream erscheinen. Die Schlüssel sind entweder die ersten 17 Zeichen einer Anzeigenereignis-ID, die in den zeitgesteuerten Metadaten des Streams erscheint, oder bei Ereignissen vom Typ progress die vollständige Anzeigenereignis-ID.
Jeder Wert ist ein Objekt, das die folgenden Parameter enthält:
|
||||||||||||||||||
ads |
Eine Reihe von Schlüssel/Wert-Paaren, die alle Anzeigen beschreiben, die im Stream ausgeliefert werden. Die Schlüssel sind Anzeigen-IDs, die mit den Werten im oben aufgeführten tags -Objekt übereinstimmen. 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 von Werbeunterbrechungen, die mit den Werten in den oben aufgeführten tags - und ads -Objekten übereinstimmen. Jeder Wert ist ein Objekt, das die folgenden Parameter enthält:
|
Speichern Sie diese Werte, um sie mit zeitgesteuerten Metadatenereignissen in Ihrem Videostream 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
Im Audio-/Videostream Ihres Videoplayers werden zeitgesteuerte Metadaten durch ausgelöste Anzeigenereignisse erfasst.
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, die für "benutzerdefinierten Text" reserviert ist.
Beispiel für ein ID3-Tag
TXXXgoogle_1234567890123456789
Bei MP4-Streams werden diese als In-Band-Emsg-Ereignisse gesendet, die ID3 v2.3-Tags emulieren. 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 einen message_data
-Wert, der mit ID3TXXXgoogle_
beginnt. Dieser message_data
-Wert ohne das Präfix ID3TXXX
ist die Anzeigenereignis-ID.
Beispiel für ein E-Mail-Feld
Die Datenstruktur kann je nach Mediaplayer-Bibliothek variieren.
Wenn die Anzeigenereignis-ID google_1234567890123456789
ist, sieht die Antwort so aus:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Einige Mediaplayer-Bibliotheken stellen automatisch Emsg-Ereignisse dar, die ID3-Tags als native ID3-Tags emulieren. In diesem Fall haben MP4-Streams identische ID3-Tags wie 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 Objekt
tags
nach einem Schlüssel, der mit der vollständigen Anzeigenereignis-ID übereinstimmt. Wenn eine Übereinstimmung gefunden wird, rufen Sie den Ereignistyp und die zugehörigenad
- undad_break
-Objekte ab. Diese Ereignisse sollten den Typprogress
haben.Wenn für die vollständige Anzeigenereignis-ID keine Übereinstimmung gefunden wird, suchen Sie im
tags
-Objekt nach einem Schlüssel, der mit den ersten 17 Zeichen der Anzeigenereignis-ID übereinstimmt. Rufen Sie den Ereignistyp und die zugehörigenad
- undad_break
-Objekte ab. Dadurch sollten alle Ereignisse mit einem anderen Typ alsprogress
abgerufen werden.Verwende diese abgerufenen Informationen, um die Benutzeroberfläche deines Players zu aktualisieren. Wenn du beispielsweise ein
start
- oder das ersteprogress
-Ereignis erhältst, blende die Suchsteuerung des Players aus und blende ein Overlay ein, das die Position der aktuellen Anzeige in der Werbeunterbrechung beschreibt, zum Beispiel „Anzeige 1 von 3“.
Beispiele für Anzeigenereignis-IDs
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Beispielobjekt für Tags
{
"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
Jedes Mal, wenn ein Anzeigenereignis mit einem anderen Typ als progress
empfangen wird, muss ein Medienüberprüfungs-Ping an Ad Manager gesendet werden.
Um die vollständige Medienüberprüfungs-URL eines Anzeigenereignisses zu generieren, hängen Sie die vollständige Anzeigenereignis-ID an den Wert media_verification_url
aus der Antwort zur Streamregistrierung an.
Stellen Sie eine GET-Anfrage mit der vollständigen URL. Wenn die Bestätigungsanfrage erfolgreich ist, erhalten Sie eine HTTP-Antwort mit dem Statuscode 202
.
Andernfalls wird der HTTP-Fehlercode 404
angezeigt.
Beispielanfrage (cURL)
curl https://{...}/media/google_5555555555123456789
Beispiel für eine erfolgreiche Antwort
HTTP/1.1 202 Accepted