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

JSON-Textparameter

Antwort (JSON)

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:

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

• IMA SDK-Dokumentation
• Gegenüberstellung der Implementierungstypen von Playern für die dynamische Anzeigenbereitstellung