Benutzerdefinierte Integration verwenden

Hinweise

Dieser Leitfaden enthält nur die Wiedergabeanleitung für den Fall, dass das IMA DAI SDK nicht verwendet wird.

Du musst die Schritte unter Google Ad Manager (GAM) in Livestreams einbinden bereits ausgeführt haben.

Wenn das IMA SDK für Ihre gewünschte Plattform nicht verfügbar ist, müssen Sie in Ihrer Anwendung die erforderlichen APIs aufrufen und die Anzeigenimpressionen selbst auslösen.

Dazu benötigen Sie die folgenden Informationen:

Standort Die Google Cloud-Region , in der Ihre Livekonfiguration erstellt wurde:
LOCATION
Projektnummer Die Projektnummer des Google Cloud-Projekts, in dem die Video Stitcher API verwendet wird:
PROJECT_NUMBER
OAuth-Token Das kurzlebige OAuth-Token eines Dienstkontos mit der Rolle „Video Stitcher“: 
OAUTH_TOKEN
Weitere Informationen zum Erstellen kurzlebiger OAuth-Tokens
Netzwerkcode Der Ad Manager-Netzwerkcode zum Anfordern von Anzeigen:
NETWORK_CODE
Live-Konfigurations-ID Die Live-Konfigurations-ID, die du beim Erstellen des Livestream-Ereignisses angegeben hast:
LIVE_CONFIG_ID
Benutzerdefinierter Asset-Schlüssel Der benutzerdefinierte Ad Manager-Asset-Schlüssel, der beim Erstellen einer Konfiguration für ein Livestream-Ereignis mit der Video Stitcher API generiert wurde:
CUSTOM_ASSET_KEY

Streamregistrierungsanfrage an Ad Manager senden

Stelle eine POST-Anfrage an den Endpunkt zur Streamregistrierung. Als Antwort erhältst du eine JSON-Antwort mit der Stream-ID, die an die Video-Stitching API gesendet werden soll.

API-Endpunkt

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Pfadparameter

NETWORK_CODE Ihr Google Ad Manager 360-Netzwerkcode:
NETWORK_CODE
CUSTOM_ASSET_KEY Die benutzerdefinierte Kennung, die diesem Ereignis in Google Ad Manager zugewiesen ist:
CUSTOM_ASSET_KEY

Formularcodierte Textparameter

Optionale Reihe von formularcodierten Targeting-Parametern .

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.
MEDIA_VERIFICATION_URL
metadata_url Die URL, unter der Metadaten für Anzeigen-Pods angefordert werden.
METADATA_URL
polling_frequency die empfohlene Häufigkeit in Millisekunden, mit der die „metadata_url“ abgefragt werden soll.
POLLING_FREQUENCY
stream_id Der String, mit dem die aktuelle Stream-Sitzung identifiziert wird.
STREAM_ID
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 \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Beispielantwort

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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

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

URI für die Wiedergabe der Sitzung generieren

Stelle eine POST-Anfrage an den Endpunkt /livesessions der Video Stitcher API, um eine neue Live-Sitzung zu erstellen. Als Antwort erhältst du eine JSON-Antwort mit dem Stream-Manifest, das in deinen Videoplayer geladen werden soll.

API-Endpunkt

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Pfadparameter

PROJECT_NUMBER Die Projektnummer des Google Cloud-Projekts, in dem die Video Stitcher API verwendet wird:
PROJECT_NUMBER
LOCATION Die Google Cloud-Region , in der Ihre Livekonfiguration erstellt wurde:
LOCATION

Autorisierungsheader-Parameter

OAUTH_TOKEN Das kurzlebige OAuth-Token eines Dienstkontos mit der Rolle „Video Stitcher“: 
OAUTH_TOKEN

JSON-codierte Textparameter

liveConfig Ein String mit Ihrer Projektnummer, Ihrem Standort und der Live-Konfigurations-ID im folgenden Format:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
adTracking Setzen Sie den Wert auf "CLIENT", um das clientseitige Tracking zu aktivieren.
gamSettings Ein Objekt mit der Stream-ID im folgenden Format:
{"streamId":"STREAM_ID"}

Antwort (JSON)

name Der Name der Live-Sitzung, der die Sitzungs-ID enthält.
playUri Der URI des zusammengefügten Stream-Manifests, das zur Wiedergabe in deinen Videoplayer geladen werden soll.
PLAY_URI
liveConfig Derselbe liveConfig-String, der im Anfragetext an die API gesendet wurde.
gamSettings Das gamSettings-Objekt, das im Anfragetext an die API gesendet wurde.

Beispielanfrage (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

Beispielantwort

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

Nachdem die Antwort empfangen wurde, kannst du den mit Anzeigen zusammengefügten Livestream abspielen, indem du im Feld playUri des Antwortobjekts auf den URI für die Wiedergabe der Sitzung verweist.

Die Video Stitcher API generiert für jede Anfrage eine eindeutige Sitzungs-ID, die im letzten Abschnitt des Felds name des Antwortobjekts abgerufen werden kann.

Eine inaktive Sitzung läuft nach 5 Minuten ab. Eine Sitzung gilt als inaktiv, wenn innerhalb eines bestimmten Zeitraums keine Manifestabrufe erfolgt sind.

Neue AdBreak-Metadaten abfragen

Die Anwendung ist dafür verantwortlich, Metadaten für jede Werbeunterbrechung abzurufen, damit sie weiß, welche Impressionen ausgelöst werden müssen. Dazu legen Sie einen Timer fest, der die DAI-APIs metadata_url regelmäßig auf neue Anzeigeninformationen abfragt. Das Intervall für das Polling wird im Feld polling_frequency in der Antwort auf die Streamregistrierung angegeben.

Als Antwort erhalten Sie ein JSON-Objekt mit den folgenden Parametern:

tags Eine Reihe von Schlüssel/Wert-Paaren, die Ereignisse für Anzeigenmedien beschreiben, die im Stream auftreten. Jeder Schlüssel besteht entweder aus den ersten 17 Zeichen einer Anzeigenmedium-ID, die in den ID3-Metadaten des Streams enthalten ist, oder, im Fall von Fortschrittsereignissen, aus der gesamten Anzeigenmedium-ID. Jeder Wert ist ein Objekt mit den folgenden Properties:
  • ad: Die ID der Anzeige, die das Ereignis „Anzeigenmedien“ enthält.
  • ad_break_id: Die ID der Werbeunterbrechung, die das Anzeigen-Medienereignis enthält.
  • type: Der Typ des Anzeigen-Media-Ereignisses. Werte können einen der folgenden Werte haben:
    • start – Die Anzeige wurde gestartet
    • firstquartile – Die Anzeige ist zu 25% fertig.
    • midpoint – Die Anzeige ist zu 50% fertig.
    • thirdquartile – Die Anzeige ist zu 75% fertig.
    • complete – Die Anzeige ist beendet.
    • progress – wird jede Sekunde ausgelöst, während eine Anzeige wiedergegeben wird.
ads Eine Reihe von Schlüssel/Wert-Paaren, die Anzeigen beschreiben, die im Stream erscheinen. Jeder Schlüssel ist eine Anzeigen-ID. Jeder Wert ist ein Objekt mit den folgenden Properties:
  • ad_break_id: Die ID der Werbeunterbrechung, die das Anzeigen-Medienereignis enthält.
  • position: die Position der Anzeige innerhalb der Werbeunterbrechung. Die erste Anzeige in einer Werbeunterbrechung hat die Position 1.
  • duration: Die Dauer der Anzeige in Gleitkommasekunden.
  • title: Der Titel der Anzeige, wie im VAST-Dokument definiert.
  • description: die Beschreibung der Anzeige, wie im VAST-Dokument definiert.
  • ad_system: das Anzeigensystem, wie im VAST-Dokument definiert.
  • ad_system: die Anzeigen-ID, wie in der VAST-Datei definiert.
  • ad_system: Die Creative-ID, wie im VAST-Dokument definiert.
  • clickthrough_url: Die URL, die geöffnet wird, wenn ein Nutzer mit der Anzeige interagiert.
  • universal_ad_id: Ein Objekt, das die universelle Anzeigen-ID darstellt, wie in der VAST-Datei definiert.
ad_breaks Eine Reihe von Schlüssel/Wert-Paaren, die Werbeunterbrechungen beschreiben, die im Stream vorkommen. Jeder Schlüssel ist eine Werbeunterbrechungs-ID. Jeder Wert ist ein Objekt mit den folgenden Properties:
  • type: Der Typ der Werbeunterbrechung. Folgende Werte sind zulässig:
    • pre: Stellt eine Pre-Roll-Anzeige dar.
    • mid: Stellt eine Mid-Roll-Anzeige dar.
    • post: Stellt eine Post-Roll-Anzeige dar.
  • duration: Die Dauer der Werbeunterbrechung in Gleitkommasekunden.
  • expected_duration: Die erwartete Dauer der Werbeunterbrechung in Gleitkommasekunden.
  • ads: Die Anzahl der Anzeigen in der Werbeunterbrechung.

Speichere diese Werte nach jeder Umfrage, um getaktete Metadatenereignisse in deinem Videostream zu verknüpfen.

Beispielanfrage (cURL)

curl https://dai.google.com/.../metadata/

Beispielantwort

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

ID3-Ereignisse erfassen und Wiedergabeereignisse protokollieren

So prüfen Sie, ob bestimmte Ereignisse in einem Videostream aufgetreten sind:

  1. Speichere die Medienereignisse in einer Warteschlange und speichere jede Medien-ID zusammen mit ihrem Zeitstempel, sofern sie vom Player angezeigt wird.
  2. Prüfe bei jeder Aktualisierung durch den Player oder in einem festgelegten Intervall (500 ms empfohlen) die Warteschlange der Medienereignisse auf kürzlich wiedergegebene Ereignisse, indem du die Ereigniszeitstempel mit der Wiedergabeposition vergleichst.
  3. Prüfe den Typ der Media-Ereignisse, die du als wiedergegeben bestätigt hast, indem du die Media-ID in den gespeicherten Werbeunterbrechungs-Tags suchst. Das Objekt „Anzeigenunterbrechungs-Tags“ enthält nur eine gekürzte Version der Medien-ID, die auf die ersten zehn Ziffern nach dem Präfix „google_“ beschränkt ist. Daher gibt es keine direkte Übereinstimmung zwischen den ID3-Medienbestätigungs-IDs und den Schlüsseln im Tags-Objekt. So wird verhindert, dass Pings zur Ereignisbestätigung gesendet werden, bevor das ID3-Ereignis eintrifft. Wenn du die vollständige URL für die Mediaüberprüfung eines Anzeigenereignisses generieren möchtest, füge dem Wert „media_verification_url“ aus der Antwort auf die Streamerstellung die vollständige Anzeigenereignis-ID an.
  4. Mit „progress“-Ereignissen kannst du verfolgen, ob sich ein Nutzer in einer Werbeunterbrechung befindet. Sende diese Ereignisse nicht an den Endpunkt für die Medienüberprüfung, um einen HTTP-Fehlercode zu vermeiden. Fügen Sie bei anderen Ereignistypen die Medien-ID an die URL für die Medienüberprüfung an und senden Sie einen GET-Vorgang, um die Wiedergabe zu erfassen.
  5. Entfernen Sie das Medienereignis aus der Warteschlange.

API-Endpunkt

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Pfadparameter

MEDIA_VERIFICATION_URL Der vom Endpunkt zur Streamregistrierung zurückgegebene Wert im Feld media_verification_url:
MEDIA_VERIFICATION_URL
AD_MEDIA_ID Die vollständige ID des Anzeigenmediums, wie sie in den ID3-Metadaten des Streams angezeigt wird:
AD_MEDIA_ID

Erwartete Rückgabewerte

HTTP/1.1 204 No Content Erfolgreiche leere Antwort.
HTTP/1.1 404 Not Found Die Bestätigungs-ID für Medien wurde nicht erkannt.
HTTP/1.1 409 Conflict Die Bestätigungs-ID für Medien wurde bereits gesendet.

Beispielanfrage (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Beispielantwort

HTTP/1.1 204 No Content

Beschränkungen

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

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