Dynamic Ad Insertion API für Livestreams

Mit der Google DAI API können Sie Streams implementieren, die für die dynamische Anzeigenbereitstellung von Google in Umgebungen aktiviert sind, 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 DAI API auf den folgenden Plattformen zu verwenden:

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

Die API unterstützt die grundlegenden Funktionen, die vom IMA DAI SDK bereitgestellt werden. Bei konkreten Fragen zur Kompatibilität oder den unterstützten Funktionen wenden Sie sich bitte 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.

Führe die folgenden Schritte aus, um die API in deine App für Livestreams zu integrieren:

1. Stream anfordern

Wenn Sie einen Livestream von der DAI API anfordern möchten, senden Sie einen POST-Aufruf an den Streamendpunkt. Die JSON-Antwort enthält das Streammanifest sowie zugehörige Endpunkte und Werte für die dynamische Anzeigenbereitstellung.

Beispiel für den Anfragetext

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

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

Beispiel für Antworttext

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Fehlerantwort

Im Falle von Fehlern werden Standard-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 für die Streamwiedergabe an Ihren Mediaplayer übergeben.
media_verification_url
Diese URL ist der Basisendpunkt für das Tracking von Wiedergabeereignissen.
metadata_url
Über diese URL werden regelmäßig Informationen zu anstehenden Streamereignissen abgerufen.
session_update_url
Mit dieser URL werden die Parameter der Streamanfrage aktualisiert, die bei der ersten 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 Metadaten für Werbeunterbrechungen abrufen

Stellen Sie einen Timer ein, um neue Metadaten für Werbeunterbrechungen mit der Abfragehäufigkeit abzurufen. Verwenden Sie dazu die Metadaten-URL. Wenn nicht in der Streamantwort angegeben, beträgt das empfohlene standardmäßig 10 Sekunden.

Beispiel für den Anfragetext

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

Beispiel für Antworttext

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },......
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },....
   }
}

3. ID3-Ereignisse und Wiedergabeereignisse im Blick behalten

Wenn Sie prüfen möchten, ob bestimmte Ereignisse in einem Videostream aufgetreten sind, gehen Sie so vor, um ID3-Ereignisse zu verarbeiten:

  1. Speichern Sie die Medienereignisse in einer Warteschlange. Speichern Sie dabei jede Medien-ID zusammen mit ihrem Zeitstempel (sofern sie vom Player angezeigt wird).
  2. Prüfen Sie bei jeder Aktualisierung über den Player oder mit einer festgelegten Häufigkeit (empfohlen: 500 ms) die Warteschlange der Medienereignisse auf kürzlich wiedergegebene Ereignisse, indem Sie die Ereigniszeitstempel mit dem Abspielkopf vergleichen.
  3. Prüfen Sie bei Medienereignissen, die wiedergegeben wurden, den Typ, indem Sie die Media-ID in den gespeicherten Tags für Werbeunterbrechungen suchen. Die gespeicherten Tags enthalten nur ein Präfix der Media-ID, sodass keine genaue Übereinstimmung möglich ist.
  4. Mit Fortschrittsereignissen lässt sich nachverfolgen, ob sich ein Nutzer innerhalb einer Werbeunterbrechung befindet. Senden Sie diese Ereignisse nicht an den Endpunkt der Medienüberprüfung. Bei anderen Ereignistypen hängen Sie die Medien-ID an den Endpunkt der Medienüberprüfung an und stellen eine GET-Anfrage, um die Wiedergabe zu verfolgen.
  5. Entfernen Sie das Medienereignis aus der Warteschlange.

Beispiel für den Anfragetext

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

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 Überwachung der Streamingaktivitäten überprüfen.

4. Livestream-Sitzungsparameter aktualisieren

Möglicherweise möchten Sie Ihre Sitzungsparameter nach dem Erstellen eines Streams anpassen. Stellen Sie dazu eine Anfrage an die Sitzungsaktualisierungs-URL.

Beispiel für den Anfragetext

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

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

Beispiel für Antworttext

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

Beschränkungen

Wenn Sie die API in WebViews verwenden, gelten für das Targeting die folgenden Einschränkungen:

  • UserAgent: Der User-Agent-Parameter wird als browserspezifischer Wert und nicht als die zugrunde liegende Plattform übergeben.
  • rdid, idtype, is_lat: Die Geräte-ID wird nicht korrekt übergeben, wodurch die Möglichkeiten der folgenden Funktionen eingeschränkt werden:
    • Frequency Capping
    • Sequenzielle Anzeigenrotation
    • Zielgruppensegmentierung und Ausrichtung

Best Practices

Beachten Sie, dass der Metadatenendpunkt für Livestream-Indexe auf dem Präfix des entsprechenden ID3-Tags basiert. Dies soll die Verwendung des Metadatenendpunkts für sofortige Pings aller Bestätigungsknoten verhindern.

Zusätzliche Ressourcen