Client-Videoplayer-App für Livestreams

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/json

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/an-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. Sie erhalten wiederum 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:

ad Die ID einer Anzeige, die einem Schlüssel im ads-Objekt entspricht.
ad_break_id Die ID einer Werbeunterbrechung, die mit einem Schlüssel im ad_breaks-Objekt übereinstimmt.
type Der Typ des Anzeigenereignisses. Folgende Anzeigenereignistypen sind verfügbar:
start Wird am Anfang der Anzeige ausgelöst
firstquartile Wird am Ende des ersten Quartils ausgelöst.
midpoint Wird in der Mitte der Anzeige ausgelöst
thirdquartile Wird am Ende des dritten Quartils ausgelöst.
complete Wird am Ende der Anzeige ausgelöst
progress Wird in regelmäßigen Abständen während der Anzeige ausgelöst, um die App darüber zu informieren, dass eine Werbeunterbrechung wiedergegeben wird.
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_break_id Die ID einer Werbeunterbrechung, die mit einem Schlüssel im ad_breaks-Objekt übereinstimmt.
position Die Position, an der die Anzeige innerhalb der Gruppe von Anzeigen in der Werbeunterbrechung erscheint, in Fließkommasekunden.
duration Die Länge der Anzeige in Gleitkommasekunden.
clickthrough_url Die URL, die geöffnet werden soll, wenn ein Nutzer mit dieser Anzeige interagiert, sofern unterstützt.
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:
type Die Art der Werbeunterbrechung. Die Arten der Werbeunterbrechung sind pre (Pre-Roll), mid (Mid-Roll) und post (Post-Roll).
duration Die Länge der Werbeunterbrechung in Gleitkommasekunden.
ads Die Anzahl der Anzeigen in dieser Werbeunterbrechung.

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:

  1. 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örigen ad- und ad_break-Objekte ab. Diese Ereignisse sollten den Typ progress 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örigen ad- und ad_break-Objekte ab. Dadurch sollten alle Ereignisse mit einem anderen Typ als progress abgerufen werden.

  2. Verwende diese abgerufenen Informationen, um die Benutzeroberfläche deines Players zu aktualisieren. Wenn du beispielsweise ein start- oder das erste progress-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 wiederum 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

Weitere Ressourcen