Videoplayer-App des Clients für VOD-Streams

(SSAI) für VOD-Streams mit der Google DAI Pod Serving API.

Mit der Google DAI Pod Serving API können Sie die serverseitige Anzeigenbereitstellung mit Google Ads durchführen und gleichzeitig die Kontrolle über Ihr eigenes Video-Stitching behalten.

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

Die Pod Serving API unterstützt Streams für die Pod-Auslieferung in den Streamingprotokollen HLS oder MPEG-DASH. In diesem Leitfaden geht es um HLS-Streams. Außerdem werden in bestimmten Schritten die wichtigsten Unterschiede zwischen HLS und MPEG-DASH hervorgehoben.

So binden Sie die Pod Serving API in Ihre App für VOD-Streams ein:

Streamregistrierungsanfrage an Ad Manager senden

Stellen Sie eine POST-Anfrage an den Endpunkt für die Streamregistrierung. Sie erhalten eine JSON-Antwort mit der Stream-ID, die Sie an Ihren Server zur Manifestbearbeitung und die zugehörigen Pod Serving API-Endpunkte senden müssen.

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 mit den Parametern für die Ausrichtung von Anzeigen. Erforderlich

Antwort (JSON)

media_verification_url Die Basis-URL zum Pingen von Wiedergabe-Tracking-Ereignissen. Eine vollständige Media-Bestätigungs-URL wird gebildet, indem dieser Basis-URL eine Ad Event ID angehängt wird.
metadata_url Die URL zum Anfordern von Metadaten für Ad-Pods.
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). Beispiel: 2h0m0.000s steht für eine Dauer von 2 Stunden.
valid_until Die Uhrzeit, zu der die aktuelle Streamsitzung abläuft, als ISO 8601-Datetime-String im Format yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Beispielanfrage (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -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"
}

Im Falle von Fehlern werden standardmäßige HTTP-Fehlercodes ohne JSON-Antworttext zurückgegeben.

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

Streammanifest vom Manifestbearbeitungstool anfordern

Jeder Manifest-Manipulator hat unterschiedliche Anfrage- und Antwortformate. Wenden Sie sich an Ihren Manipulatoranbieter, um mehr über seine spezifischen Anforderungen zu erfahren. Wenn Sie einen eigenen Manifest-Manipulator implementieren, lesen Sie die Anleitung für Manifest-Manipulatoren, um die Anforderungen an diese Komponente zu verstehen.

Im Allgemeinen müssen Sie die Stream-ID, die vom Registrierungsendpunkt oben zurückgegeben wurde, an Ihren Manifest-Manipulator übergeben, damit dieser sitzungsspezifische Manifeste erstellen kann. Sofern Ihr Manifest-Manipulator nicht ausdrücklich etwas anderes angibt, 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 abspielen

Laden Sie das Manifest, das Sie vom Manifestbearbeitungsserver erhalten haben, in einen Videoplayer und starten Sie die Wiedergabe.

Metadaten für Anzeigen-Pods 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 Ihrem Manifest-Manipulator erhalten haben. Im Gegenzug erhalten Sie ein JSON-Objekt mit den folgenden Parametern:

tags Eine Reihe von Schlüssel/Wert-Paaren, die alle Werbeereignisse enthalten, die im Stream angezeigt werden. Die Schlüssel sind entweder die ersten 17 Zeichen einer Werbeereignis-ID, die in den Zeitmetadaten des Streams enthalten ist, oder im Fall von Ereignissen des Typs progress die vollständige Werbeereignis-ID.

Jeder Wert ist ein Objekt mit den folgenden Parametern:

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-Objekt übereinstimmt.
type Der Typ des Anzeigenereignisses. Anzeigenereignistypen:
start Wird zu Beginn 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 während der gesamten Anzeige regelmäßig ausgelöst, um die App darüber zu informieren, dass eine Werbeunterbrechung wiedergegeben wird.
ads Eine Reihe von Schlüssel/Wert-Paaren, die alle im Stream angezeigten Anzeigen beschreiben. Die Schlüssel sind Anzeigen-IDs, die mit den Werten im oben aufgeführten tags-Objekt übereinstimmen. Jeder Wert ist ein Objekt mit den folgenden Parametern:
ad_break_id Die ID einer Werbeunterbrechung, die mit einem Schlüssel im ad_breaks-Objekt übereinstimmt.
position Die Position, an der diese Anzeige innerhalb der Anzeigen in der Werbeunterbrechung ausgeliefert wird, in Gleitkommazahlen.
duration Die Länge der Anzeige in Sekunden als Gleitkommazahl.
clickthrough_url Die URL, die geöffnet werden soll, wenn ein Nutzer mit dieser Anzeige interagiert, sofern dies unterstützt wird.
ad_breaks Eine Reihe von Schlüssel/Wert-Paaren, die alle Werbeunterbrechungen im Stream beschreiben. Die Schlüssel sind Pausen-IDs, die mit den Werten in den oben aufgeführten Objekten tags und ads übereinstimmen. Jeder Wert ist ein Objekt mit den folgenden Parametern:
type Der Typ der Werbeunterbrechung. Die Arten von Werbeunterbrechungen sind pre (Pre-Roll), mid (Mid-Roll) und post (Post-Roll).
duration Die Länge der Werbeunterbrechung in Gleitkomma-Sekunden.
ads Die Anzahl der Anzeigen in dieser Werbeunterbrechung.

Speichere diese Werte, um sie mit Zeitmetadatenereignissen in deinem 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

Timed Metadata über ausgelöste Anzeigenereignisse im Audio-/Videostream Ihres Videoplayers abrufen.

Bei MPEG-TS-Streams werden die Metadaten als In-Band-ID3-Tags der Version 2.3 angezeigt. Jedes Metadatentag hat die ID TXXX und der Wert beginnt mit dem String google_, gefolgt von einer Reihe von Zeichen. Dieser Wert ist die Werbeereignis-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-Tags der Version 2.3 emulieren. Jede relevante emsg-Box 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 Werbeereignis-ID.

Beispiel für eine emsg-Box

Die Datenstruktur kann je nach Mediathek des Media-Players 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",
  ...
}

In einigen Media Player-Bibliotheken werden emsg-Ereignisse, die ID3-Tags emulieren, automatisch als native ID3-Tags dargestellt. In diesem Fall enthalten 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. Prüfen Sie das tags-Objekt auf einen 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 vom Typ progress sein.

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

  2. Aktualisieren Sie die Benutzeroberfläche Ihres Players mit diesen abgerufenen Informationen. Wenn Sie beispielsweise ein start- oder das erste progress-Ereignis erhalten, blenden Sie die Suchsteuerelemente des Players aus und zeigen Sie ein Overlay an, in dem die Position der aktuellen Anzeige im Werbeblock beschrieben wird, z. B. „Anzeige 1 von 3“.

Beispiel-IDs für Anzeigenereignisse

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

Beispiel für ein „tags“-Objekt

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

Media-Bestätigungs-Pings senden

Jedes Mal, wenn ein Anzeigenereignis mit einem anderen Typ als progress empfangen wird, muss ein Media-Bestätigungs-Ping an Ad Manager gesendet werden.

Wenn Sie die vollständige Media-Bestätigungs-URL eines Anzeigenereignisses generieren möchten, hängen Sie die vollständige Anzeigenereignis-ID an den media_verification_url-Wert aus der Antwort der 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 erhalten Sie den HTTP-Fehlercode 404.

Beispielanfrage (cURL)

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

Beispiel für eine erfolgreiche Antwort

HTTP/1.1 202 Accepted

Zusätzliche Ressourcen