Videoplayer-App des Clients für VOD-Streams

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

In diesem Leitfaden erfahren Sie, wie Sie mit der Pod Serving API interagieren und ähnliche Funktionen mit dem IMA DAI SDK erzielen. Bei spezifischen 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 entweder mit 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.

So bindest du die Pod Serving API in deine App für VOD-Streams ein:

Streamregistrierungsanfrage an Ad Manager senden

Stelle eine POST-Anfrage an den Endpunkt zur Streamregistrierung. Du erhältst eine JSON-Antwort mit der Stream-ID, die an deinen Manifest-Manipulationsserver und die zugehörigen Pod Serving API-Endpunkte gesendet werden soll.

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 Targeting-Parametern der Anzeige. Erforderlich

Antwort (JSON)

media_verification_url Die Basis-URL, an die Wiedergabe-Tracking-Ereignisse gesendet werden. Eine vollständige URL für die Medienüberprüfung wird gebildet, indem an diese Basis-URL eine Anzeigenereignis-ID angehängt wird.
metadata_url Die URL, unter der Metadaten für Anzeigen-Pods angefordert werden.
stream_id Der String, mit dem die aktuelle Stream-Sitzung identifiziert wird.
valid_for Die verbleibende Zeit bis zum Ablauf der aktuellen Stream-Sitzung im Format dhms (Tage, Stunden, Minuten, Sekunden). So steht zum Beispiel 2h0m0.000s für eine Dauer von 2 Stunden.
valid_until Die Zeit, zu der die aktuelle Stream-Sitzung abläuft, als ISO 8601-Datum/Uhrzeit-String im yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm-Format.

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"
}

Bei Fehlern werden Standard-HTTP-Fehlercodes ohne JSON-Antworttext zurückgegeben.

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

Streammanifest von der Manifestbearbeitung anfordern

Für jeden Manifest-Manipulator gelten unterschiedliche Anfrage- und Antwortformate. Wenden Sie sich an Ihren Manipulatoranbieter, um die spezifischen Anforderungen zu erfahren. Wenn Sie Ihren eigenen Manifest-Manipulator implementieren, lesen Sie den Leitfaden für Manifest-Manipulatoren, um die Anforderungen an diese Komponente zu erfahren.

Im Allgemeinen musst du die Stream-ID, die vom Registrierungsendpunkt oben zurückgegeben wurde, an deinen Manifest-Manipulator übergeben, damit er sitzungsspezifische Manifeste erstellen kann. Sofern nicht ausdrücklich vom Manifest-Manipulator angegeben, ist die Antwort auf deine 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

Lade das Manifest, das du vom Server zur Manipulation von Manifesten erhalten hast, in einen Videoplayer und starte 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 du das zusammengeführte Manifest von deinem Manifest-Manipulator erhalten hast. Als Antwort erhältst du ein JSON-Objekt mit den folgenden Parametern:

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 zeitbezogenen Metadaten des Streams enthalten sind, oder bei Ereignissen vom Typ progress die vollständige Anzeigenereignis-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 Anzeigenereignistyp. Anzeigenereignistypen:
start Wird zu Beginn der Anzeige ausgelöst.
firstquartile Wird am Ende des ersten Quartils ausgelöst.
midpoint Wird nach der Hälfte 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 Anzeigen beschreiben, die im Stream erscheinen. 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 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, sofern unterstützt.
ad_breaks Eine Reihe von Schlüssel/Wert-Paaren, die alle Werbeunterbrechungen beschreiben, die im Stream erscheinen. Die Schlüssel sind Werbeunterbrechungs-IDs, die mit Werten in den oben aufgeführten tags- und ads-Objekten ü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 Dauer der Werbeunterbrechung in Gleitkommasekunden.
ads Die Anzahl der Anzeigen in dieser Werbeunterbrechung.

Speichere diese Werte, um sie mit zeitbasierten Metadatenereignissen 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

Über ausgelöste Anzeigenereignisse im Audio-/Videostream deines Videoplayers nach zeitbasierten Metadaten suchen

Bei MPEG-TS-Streams werden die Metadaten als In-Band-ID3v2.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 sie als In-Band-EMSG-Ereignisse gesendet, die ID3-v2.3-Tags 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 Anzeigenereignis-ID.

Beispiel für ein E-Mail-Feld

Die Datenstruktur kann je nach Mediaplayer-Mediathek 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 emulieren, als native ID3-Tags. In diesem Fall enthalten MP4-Streams dieselben 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. Das Abgleichen dieser Werte erfolgt in zwei Schritten:

  1. Prüfen Sie das tags-Objekt auf einen Schlüssel, der mit der vollständigen ID des Anzeigenereignisses ü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 keine Übereinstimmung für die vollständige Anzeigenereignis-ID 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 anderen Typen 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, kannst du die Suchfunktionen des Players ausblenden und ein Overlay anzeigen, in dem die Position der aktuellen Anzeige in der Werbeunterbrechung beschrieben wird, z. B. „Anzeige 1 von 3“.

Beispiel für Anzeigenereignis-IDs

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"
  },
  ...
}

Pings zur Medienbestätigung senden

Jedes Mal, wenn ein Anzeigenereignis mit einem anderen Typ als progress empfangen wird, muss ein Ping zur Medienüberprüfung an Ad Manager gesendet werden.

Wenn du die vollständige URL für die Medienüberprüfung eines Anzeigenereignisses generieren möchtest, füge dem Wert „media_verification_url“ aus der Antwort der Streamregistrierung die vollständige Anzeigenereignis-ID an.

Stellen Sie eine GET-Anfrage mit der vollständigen URL. Wenn die Bestätigungsanfrage erfolgreich war, 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