Client-Videoplayer-App für Livestreams

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 die Streamregistrierung an die DAI Pod Serving API 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: /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 wurde.

Formularcodierte Textparameter

Optionaler Satz formularcodierter <ph type="x-smartling-placeholder"></ph> Targeting-Parameter

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 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Beispielantwort

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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.

Neue Werbeunterbrechungen-Metadaten abfragen

Die Anwendung ist für den Abruf der Metadaten für jede Werbeunterbrechung zuständig, weiß, welche Impressionen ausgelöst werden müssen. Um dies zu erreichen, legen Sie Timer für die regelmäßige Abfrage neuer Anzeigen von den APIs für die dynamische Anzeigenbereitstellung metadata_url Informationen. Das Intervall für die Abfrage wird in polling_frequency angegeben in der Antwort auf die Streamregistrierung.

Im Gegenzug erhalten Sie ein JSON-Objekt mit den folgenden Parametern:

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.

Speichern Sie diese Werte nach jeder Abfrage, um zeitlich begrenzte Metadatenereignisse in Ihren Videostream.

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 steuert und zeigt ein Overlay mit einer Beschreibung der aktuellen Anzeigenposition in der Anzeige an. Pause, z. B. „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

Zusätzliche Ressourcen