Wenn du die Video Stitcher API für dein Projekt aktivieren möchtest, wende dich bitte an deinen Account Manager oder den Vertrieb.

Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefinierte Integration verwenden

Hinweise

In diesem Dokument werden nur die Wiedergabeanleitungen ohne das IMA DAI SDK behandelt.

Du musst die Schritte unter Google Ad Manager (GAM) mit VOD-Assets verknüpfen 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 Überprüfungen der Anzeigenmedien 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 Wichtiger Hinweis:Das OAuth-Token kann für mehrere Anfragen wiederverwendet werden, solange es nicht abgelaufen ist.
Netzwerkcode	Der Ad Manager-Netzwerkcode zum Anfordern von Anzeigen: `NETWORK_CODE`
VOD-Konfigurations-ID	Die VOD-Konfigurations-ID, die du beim Erstellen des VOD-Streams angegeben hast: `VOD_CONFIG_ID`

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 deinen Server für die Manifestmanipulation 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-codierte Textparameter

targeting_parameters: Eine Reihe optionaler, JSON-codierter Targeting-Parameter.

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`
`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/json" \
     -d '@request.json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

request.json

{
  "targeting_parameters": {
    "cust_params": "sport%3Dfootball%26city%3Dnewyork"
  }
}

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.

Cloud Video Stitcher VOD-Sitzung generieren

Stelle eine POST-Anfrage an den Endpunkt zur Registrierung der VOD-Sitzung. Als Antwort erhältst du eine JSON-Antwort mit dem Manifest-URI des Streams und den Metadaten zu Werbeunterbrechungen, Anzeigen und Anzeigenereignissen.

API-Endpunkt

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

Pfadparameter

`PROJECT_NUMBER`	Ihre Google Cloud-Projektnummer.
`LOCATION`	Ihre Google Cloud-Region.
`NETWORK CODE`	Ihren Google Ad Manager 360-Netzwerkcode

JSON-codierte Textparameter

`vodConfig`	Ein String mit deiner Projektnummer, deinem Speicherort und der VOD-Konfigurations-ID im folgenden Format: `projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID`
`adTracking`	Setzen Sie den Wert auf `"CLIENT"`, um das clientseitige Tracking zu aktivieren.
`gamSettings`	Ein Objekt mit dem Netzwerkcode und der Stream-ID im folgenden Format: { "networkCode":"`NETWORK_CODE`", "streamId":"`STREAM_ID`" }

Antwort (JSON)

`name`	Der Name der VOD-Sitzung, der die Sitzungs-ID enthält.
`playUri`	Der URI des zusammengefügten Stream-Manifests, das zur Wiedergabe in deinen Videoplayer geladen werden soll. `SESSION_PLAYBACK_URI`
`adTracking`	Derselbe `adTracking`-Wert, der im Anfragetext an die API gesendet wurde.
`vodConfig`	Derselbe `vodConfig`-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/vodSessions/

request.json

{
  "vod_config": "projects/PROJECT_NUMBER/locations/LOCATION/vodConfigs/VOD_CONFIG_ID",
  "ad_tracking": "CLIENT",
  "gam_settings": {
    "network_code": "NETWORK_CODE",
    "stream_id": "STREAM_ID"
  }
}

Beispielantwort

{
  "name": "projects/.../vodSessions/4a703a1f-5f48-4147-9738-c7d4c7b70e7f",
  "playUri": "https://videostitcher.googleapis.com/.../manifest.m3u8",
  "sourceUri": "https://storage.googleapis.com/.../hls.m3u8",
  "adTagUri": "https://pubads.g.doubleclick.net/gampad/ads?...",
  "vodConfig": "projects/...",
  "assetId":   "63b94af2767e17e5c975f8d7d2b15c0d0b0320a17c3d7ac8a3f6d4e0c165b9e5",
  "adTracking": "CLIENT",
  "gam_settings": {
    "network_code": "21775744923",
    "stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS"
  }
}

Nachdem die Antwort empfangen wurde, kannst du den mit Anzeigen zusammengefügten Livestream abspielen, indem du auf den URI aus dem Feld playUri des Antwortobjekts verweist.

Metadaten für Anzeigen-Pods in Ad Manager anfordern

Sende eine GET-Anfrage an die metadata_url, die du bei der Registrierung deines Streams in Ad Manager erhalten hast. Dieser Schritt muss erfolgen, nachdem du das zusammengeführte Manifest über den Wiedergabe-URI erhalten hast.

Du erhältst ein JSON-Objekt, das die Werbeunterbrechungen, Anzeigen und Anzeigenereignisse des Streams beschreibt.

API-Endpunkt

GET: METADATA_URL
Host: dai.google.com

Antwort (JSON)

`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 im VAST-Dokument 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.

Beispielanfrage (cURL)

curl METADATA_URL

Beispiel für eine JSON-Antwort

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

Speichere diese Werte, um sie mit getakteten Metadatenereignissen in deinem Videostream zu verknüpfen.

ID3-Ereignisse erfassen und Wiedergabeereignisse protokollieren

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

Speichere die Medienereignisse in einer Warteschlange und speichere jede Medien-ID zusammen mit ihrem Zeitstempel, sofern sie vom Player angezeigt wird.
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.
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.
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-Aufruf, um die Wiedergabe zu erfassen.
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 -targeting

Weiter

Übersicht