Livestreams mit dynamischer Anzeigenbereitstellung verwalten

Mit der Google DAI API können Sie Google DAI-fähige Streams in Umgebungen implementieren, in denen die Implementierung des IMA SDK nicht unterstützt wird. Wir empfehlen, IMA weiterhin auf Plattformen zu verwenden, auf denen das IMA SDK unterstützt wird.

Wir empfehlen die Verwendung der DAI API auf den folgenden Plattformen:

  • Samsung Smart TV (Tizen)
  • LG TV
  • HbbTV
  • Xbox (JavaScript-Apps)
  • KaiOS

Die API unterstützt die grundlegenden Funktionen des IMA DAI SDK. Wenn Sie spezielle Fragen zur Kompatibilität oder zu unterstützten Funktionen haben, wenden Sie sich an Ihren Google Account Manager.

DAI API für Livestreams implementieren

Die DAI API unterstützt lineare (LIVE-)Streams mit HLS- und DASH-Protokollen. Die in diesem Leitfaden beschriebenen Schritte gelten für beide Protokolle.

So binden Sie die API in Ihre App für Livestreams ein:

1. Stream anfordern

Wenn Sie einen Livestream über die DAI API anfordern möchten, stellen Sie einen POST-Aufruf an den Stream-Endpunkt. Die JSON-Antwort enthält das Streammanifest sowie zugehörige DAI API-Endpunkte und -Werte.

Beispiel für einen Anfragetext

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  "key1" : "value1",
  "stream_parameter1" : "value2"
}

Beispiel für einen Antworttext

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Fehlerantwort

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

Parsen Sie die JSON-Antwort und speichern Sie die folgenden Werte:

stream_id
Mit diesem Wert kann der zurückgegebene Stream identifiziert werden.
stream_manifest
Diese URL wird zur Streamwiedergabe an Ihren Media-Player übergeben.
media_verification_url
Diese URL ist der Basisendpunkt für das Tracking von Wiedergabeereignissen.
metadata_url
Diese URL wird verwendet, um regelmäßig Informationen zu anstehenden Stream-Events abzurufen.
session_update_url
Mit dieser URL werden Streamanfrageparameter aktualisiert, die bei der ursprünglichen Streamanfrage gesendet wurden. Die Parameter dieser Anfrage ersetzen alle Parameter, die für den vorherigen Stream festgelegt wurden.
polling_frequency
Die Häufigkeit in Sekunden, mit der aktualisierte AdBreak-Metadaten von der DAI API angefordert werden.

2. Neue AdBreak-Metadaten abrufen

Legen Sie einen Timer fest, um in der Abfragehäufigkeit mithilfe der Metadaten-URL nach neuen AdBreak-Metadaten zu suchen. Wenn im Stream keine Angabe erfolgt, beträgt das empfohlene Standardintervall 10 Sekunden.

So optimieren Sie die Bandbreite:

  1. Senden Sie eine erste GET-Anfrage an den metadata_url-Endpunkt.
    • Lassen Sie den Abfrageparameter delta_token weg. So kann der Server die vollständigen Metadaten für das DVR-Fenster (Digital Video Recorder) des Streams zurückgeben. Das DVR-Fenster enthält den Zeitraum der Übertragung, der für Zuschauer zum Zurückspulen und Abspielen verfügbar ist. Die Antwort enthält ein next_delta_token-Objektfeld.
  2. Metadaten clientseitig speichern.
  3. Führen Sie nachfolgende Aufrufe mit dem next_delta_token-Wert aus, der in der letzten Antwort zurückgegeben wurde. Jede Antwort enthält einen next_delta_token-Wert. Senden Sie immer den letzten empfangenen Wert.
  4. Aktualisieren Sie die gespeicherten Metadaten, um Änderungen zusammenzuführen und veraltete Werbeunterbrechungen zu entfernen.

Versuchen Sie nicht, das Delta-Token zu parsen, zu erstellen oder zu ändern. Das Format des Tokens kann sich ändern. Speichern Sie das Token so, wie es empfangen wurde, und geben Sie es in der nächsten Anfrage unverändert zurück.

Beispiel für eine erste Anfrage

Die ursprüngliche Anfrage enthält keine Suchparameter und gibt die vollständigen Metadaten zurück:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Beispiel für eine nachfolgende Anfrage

Bei jeder nachfolgenden Anfrage wird der Wert next_delta_token aus der vorherigen Antwort als Parameter delta_token übergeben. Die Antwort enthält Folgendes:

  • Anzeigen
  • Werbeunterbrechungen
  • Tags, die vom Server hinzugefügt oder aktualisiert wurden, seit das Token ausgestellt wurde.
  • Eine obsolete_ad_break_ids-Liste mit Werbeunterbrechungen, die aus Ihren gespeicherten Metadaten entfernt werden sollen

Der Server lässt Werbeunterbrechungen aus, die sich nicht geändert haben. Im folgenden Beispiel wird gezeigt, wie Sie mit dem Delta-Token nur die letzten Änderungen abrufen:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Bei erfolgreicher Ausführung erhalten Sie eine Ausgabe ähnlich der folgenden:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. ID3-Ereignisse erfassen und Wiedergabeereignisse tracken

So prüfen Sie, ob bestimmte Ereignisse in einem Videostream aufgetreten sind, indem Sie ID3-Ereignisse verarbeiten:

  1. Speichern Sie die Media-Ereignisse in einer Warteschlange und speichern Sie jede Media-ID zusammen mit dem zugehörigen Zeitstempel (falls vom Player angezeigt).
  2. Prüfen Sie bei jeder Zeitaktualisierung durch den Player oder in einem festgelegten Intervall (empfohlen: 500 ms) die Warteschlange für Media-Ereignisse auf kürzlich wiedergegebene Ereignisse, indem Sie die Zeitstempel der Ereignisse mit dem Playhead vergleichen.
  3. Bei Media-Ereignissen, die nachweislich abgespielt wurden, können Sie den Typ ermitteln, indem Sie die Media-ID in den gespeicherten Werbeunterbrechungs-Tags nachschlagen. Die gespeicherten Tags enthalten nur ein Präfix der Media-ID, sodass kein exakter Abgleich möglich ist.
  4. Da Ihre Videoplayer-App die Metadaten-URL regelmäßig abruft, kann es zu einer Verzögerung zwischen dem Zeitpunkt, zu dem Ihr Videoplayer ein ID3-Tag im Stream erkennt, und dem Zeitpunkt, zu dem die zugehörigen Metadaten verfügbar sind, kommen. Wenn in den gespeicherten Tags kein ID3-Tag gefunden wird, behalte das Tag in einer Warteschlange und verarbeite es nach dem nächsten Metadaten-Polling noch einmal. Lassen Sie das Ereignis in der Warteschlange, bis die Verarbeitung abgeschlossen ist.
  5. Nachdem Sie das Tag in den Metadaten gefunden haben, vergleichen Sie das Feld type des Tags mit den Anzeigeneignistypen im folgenden Abschnitt. Wenn Sie nachvollziehen möchten, ob im Videoplayer eine Werbeunterbrechung wiedergegeben wird, verwenden Sie Ereignisse mit dem Wert progress aus dem Feld type. Senden Sie diese Ereignisse nicht an den Endpunkt für die Media-Überprüfung. Hängen Sie für alle anderen Ereignistypen die Media-ID an den Media-Bestätigungsendpunkt an und senden Sie eine GET-Anfrage, um die Wiedergabe zu erfassen.
  6. Entferne das Media-Ereignis aus der Warteschlange.

Anzeigenereignistypen

Jedes Tag im tags-Metadatenobjekt hat einen der folgenden Ereignistypen:

Ereignistyp Beschreibung
start Wird zu Beginn der Anzeige ausgeführt.
firstquartile Wird am Ende des ersten Quartils der Anzeige ausgeführt.
midpoint Wird in der Mitte der Anzeige ausgeführt.
thirdquartile Wird am Ende des dritten Quartils der Anzeige ausgeführt.
complete Wird am Ende der Anzeige ausgeführt.
progress Wird während einer Werbeunterbrechung regelmäßig ausgeführt, um zu signalisieren, dass eine Werbeunterbrechung wiedergegeben wird. Senden Sie diese Ereignisse nicht an den Endpunkt für die Media-Bestätigung.

Beispielanfrage

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

Beispielantworten

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Sie können Tracking-Ereignisse in der Überprüfung der Streamingaktivitäten überprüfen.

4. Livestream-Sitzungsparameter aktualisieren

Möglicherweise möchten Sie Ihre Sitzungsparameter anpassen, nachdem ein Stream erstellt wurde. Senden Sie dazu eine Anfrage an die URL für die Sitzungsaktualisierung.

Beispiel für einen Anfragetext

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Beispiel für einen Antworttext

Successful response would be to look for - HTTP/1.1 200

Beschränkungen

Wenn Sie die API in Webviews verwenden, gelten die folgenden Einschränkungen in Bezug auf das Targeting:

  • UserAgent: Der User-Agent-Parameter wird als browserspezifischer Wert anstelle der zugrunde liegenden Plattform übergeben.
  • rdid, idtype, is_lat: Die Geräte-ID wird nicht richtig übergeben, was die Möglichkeiten der folgenden Funktionen einschränkt:
    • Frequency Capping
    • Sequenzielle Anzeigenrotation
    • Zielgruppensegmentierung und ‑ausrichtung

Best Practices

Der Metadaten-Endpunkt für Livestream-Indizes basiert auf dem Präfix des entsprechenden ID3-Tags. Dies ist so vorgesehen, um zu verhindern, dass der Metadatenendpunkt verwendet wird, um sofort alle Überprüfungsknoten zu pingen.

Zusätzliche Ressourcen