VOD API für die dynamische Anzeigenbereitstellung

Mit der Dynamic Ad Inserting API können Sie VOD-Streams (Video-on-Demand) anfordern und erfassen. HLS- und DASH-Streams werden unterstützt.

Dienst: dai.google.com

Der Pfad der Methode stream ist relativ zu https://dai.google.com

Methode: Stream

Methoden
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Hiermit wird ein Stream für die HLS-dynamische Anzeigenbereitstellung für die angegebene Contentquelle und Video-ID erstellt.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Hiermit wird ein DASH-Stream für die dynamische Anzeigenbereitstellung für die angegebene Contentquelle und Video-ID erstellt.

HTTP-Anfrage

POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Anfrageheader

Parameter
api‑key string

Der API-Schlüssel, der beim Erstellen eines Streams bereitgestellt wird, muss für das Netzwerk des Publishers gültig sein.

Anstatt ihn im Anfragetext anzugeben, kann der API-Schlüssel im folgenden Format im HTTP-Autorisierungsheader übergeben werden:

Authorization: DCLKDAI key="<api-key>"

Pfadparameter

Parameter
content-source string

Die CMS-ID des Streams.

video-id string

Die Video-ID des Streams.

Anfragetext

Der Anfragetext ist vom Typ application/x-www-form-urlencoded und enthält die folgenden Parameter:

Parameter
dai-ssb Optional

Legen Sie true fest, um einen serverseitigen Beaconing-Stream zu erstellen. Die Standardeinstellung ist false. Das Tracking des Standardstreams wird vom Client initiiert und serverseitig angepingt.

Targeting-Parameter in DFP Optional Zusätzliche Targeting-Parameter.
Streamparameter überschreiben Optional Standardwerte eines Parameters zur Streamerstellung überschreiben.
HMAC-Authentifizierung Optional Mit einem HMAC-basierten Token authentifizieren.

Antworttext

Wenn der Vorgang erfolgreich ist, enthält der Antworttext einen neuen Stream. Bei serverseitigen Beaconing-Streams enthält Stream nur die Felder stream_id und stream_manifest.

Offene Messung

Das Feld Verifications enthält Informationen für die Open Measurement-Überprüfung für Streams ohne serverseitiges Beaconing. Verifications enthält ein oder mehrere Verification-Elemente mit den Ressourcen und Metadaten, die Sie benötigen, um die Creative-Wiedergabe mit dem Messcode eines Drittanbieters zu prüfen. Es wird nur JavaScriptResource unterstützt. Weitere Informationen finden Sie im IAB Tech Lab und in den VAST 4.1-Spezifikationen.

Methode: Medienüberprüfung

Wenn Sie bei der Wiedergabe auf eine Anzeigenmedien-ID stoßen, senden Sie sofort eine Anfrage mit media_verification_url vom Endpunkt stream. media_verification_url ist ein absoluter Pfad. Medienüberprüfungsanfragen sind für serverseitige Beaconing-Streams, bei denen der Server die Medienüberprüfung initiiert, nicht erforderlich.

Anfragen an den Endpunkt media verification sind idempotent.

Methoden
media verification GET {media_verification_url}/{ad_media_id}

Benachrichtigt die API über ein Medienüberprüfungsereignis.

HTTP-Anfrage

GET {media-verification-url}/{ad-media-id}

Antworttext

media verification gibt die folgenden Antworten zurück:

  • HTTP/1.1 204 No Content, wenn die Medienüberprüfung erfolgreich ist und alle Pings gesendet werden.
  • HTTP/1.1 404 Not Found, wenn die Medien aufgrund einer falschen URL-Formatierung oder eines falschen Ablaufdatums nicht in der Anfrage verifiziert werden können.
  • HTTP/1.1 404 Not Found, wenn eine vorherige Überprüfungsanfrage für diese ID erfolgreich war.
  • HTTP/1.1 409 Conflict, wenn zu diesem Zeitpunkt bereits eine andere Anfrage Pings sendet.

Media-IDs von Anzeigen (HLS)

Anzeigenmedien-IDs werden mit dem Schlüssel TXXX in HLS-zeitgesteuerten Metadaten codiert und für Frames vom Typ „benutzerdefinierte Textinformationen“ reserviert. Der Inhalt des Frames ist unverschlüsselt und beginnt immer mit dem Text "google_".

Der gesamte Textinhalt des Frames sollte bei jeder Anfrage zur Anzeigenüberprüfung an media_verification_url angehängt werden.

Media-IDs von Anzeigen (DASH)

Anzeigenmedien-IDs werden über das EventStream-Element von DASH in das Manifest eingefügt.

Jeder EventStream hat den URI der Schema-ID urn:google:dai:2018. Sie enthalten Ereignisse mit dem Attribut messageData, das eine Anzeigenmedia-ID enthält, die mit “google_” beginnt. Der gesamte Inhalt des Attributs messageData sollte für jede Anfrage zur Anzeigenüberprüfung an media_verification_url angehängt werden.

Antwortdaten

Streamen

Stream wird verwendet, um eine Liste aller Ressourcen für einen neu erstellten Stream im JSON-Format zu rendern .
JSON-Darstellung
{
  "stream_id": string,
  "total_duration": number,
  "content_duration": number,
  "valid_for": string,
  "valid_until": string,
  "subtitles": [object(Subtitle)],
  "hls_master_playlist": string,
  "stream_manifest": string,
  "media_verification_url": string,
  "apple_tv": object(AppleTV),
  "ad_breaks": [object(AdBreak)],
}
Felder
stream_id string

Stream-ID.
total_duration number

Streamdauer in Sekunden.
content_duration number

Die Dauer des Contents (ohne Anzeigen) in Sekunden.
valid_for string

Der Dauerstream ist im Format „00h00m00s“ gültig.
valid_until string

Datum, bis zu dem der Stream gültig ist, im RFC 3339-Format.
subtitles [object(Subtitle)]

Eine Liste der Untertitel. Ausgelassen, wenn leer. Nur HLS.
hls_master_playlist string

(EINGESTELLT) HLS-Masterplaylist-URL. Verwenden Sie stream_manifest. Nur HLS.
stream_manifest string

Das Manifest des Streams. Entspricht der Masterplaylist in HLS und der MPD-Datei in DASH. Neben „stream_id“ ist es das einzige Feld, das beim Erstellen eines serverseitigen Beacon-Streams in der Antwort vorhanden ist.
media_verification_url string

Medienüberprüfungs-URL
apple_tv object(AppleTV)

Optionale Informationen speziell für Apple TV-Geräte. Nur HLS.
ad_breaks [object(AdBreak)]

Eine Liste der Werbeunterbrechungen. Ausgelassen, wenn leer.

AppleTV

AppleTV enthält spezifische Informationen zu Apple TV-Geräten.
JSON-Darstellung
{
  "interstitials_url": string,
}
Felder
interstitials_url string

Interstitial-URL:

AdBreak

Eine Werbeunterbrechung beschreibt eine einzelne Werbeunterbrechung im Stream. Es enthält eine Position, eine Dauer, einen Typ (mid/pre/post) und eine Liste von Anzeigen.
JSON-Darstellung
{
  "type": string,
  "start": number,
  "duration": number,
  "ads": [object(Ad)],
}
Felder
type string

Gültige Werbeunterbrechungstypen sind: mid, pre und post.
start number

Position im Stream in Sekunden, an der die Pause beginnt.
duration number

Dauer der Werbeunterbrechung in Sekunden
ads [object(Ad)]

Eine Liste der Anzeigen. Ausgelassen, wenn leer.
„Anzeige“ beschreibt eine Werbeanzeige im Stream. Sie enthält die Position der Anzeige in der Pause, die Dauer der Anzeige und einige optionale Metadaten.
JSON-Darstellung
{
  "seq": number,
  "start": number,
  "duration": number,
  "title": string,
  "description": string,
  "advertiser": string,
  "ad_system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
  "clickthrough_url": string,
  "icons": [object(Icon)],
  "wrappers": [object(Wrapper)],
  "events": [object(Event)],
  "verifications": [object(Verification)],
  "universal_ad_id": object(UniversalAdID),
  "companions": [object(Companion)],
  "interactive_file": object(InteractiveFile),
}
Felder
seq number

Position der Anzeige in der Unterbrechung
start number

Angabe der Position im Stream in Sekunden, an der die Anzeige gestartet wird.
duration number

Die Dauer der Anzeige in Sekunden.
title string

Optionaler Anzeigentitel
description string

Optionale Beschreibung der Anzeige
advertiser string

Optionale Werbetreibenden-ID
ad_system string

Optionales Anzeigensystem
ad_id string

Optionale Anzeigen-ID
creative_id string

Optionale Creative-ID
creative_ad_id string

Optionale Creative-Anzeigen-ID
deal_id string

Optionale Deal-ID
clickthrough_url string

Optionale Klick-URL
icons [object(Icon)]

Eine Liste von Symbolen, die weggelassen werden, wenn das Feld leer ist.
wrappers [object(Wrapper)]

Eine Liste der Wrapper. Ausgelassen, wenn leer.
events [object(Event)]

Eine Liste der Ereignisse in der Anzeige.
verifications [object(Verification)]

Optionale Einträge für die Open Measurement-Überprüfung. Darin sind die Ressourcen und Metadaten aufgelistet, die erforderlich sind, um Drittanbieter-Messcode auszuführen, um die Creative-Wiedergabe zu prüfen.
universal_ad_id object(UniversalAdID)

Optionale universelle Anzeigen-ID
companions [object(Companion)]

Optionale Companions, die zusammen mit dieser Anzeige ausgeliefert werden können
interactive_file object(InteractiveFile)

Optionales interaktives Creative (SIMID), das während der Anzeigenwiedergabe angezeigt werden soll

Veranstaltung

Der Termin enthält einen Ereignistyp und eine Präsentationszeit eines Termins.
JSON-Darstellung
{
  "time": number,
  "type": string,
}
Felder
time number

Zeit für die Präsentation dieses Termins.
type string

Dieser Ereignistyp.

Untertitel

„Subtitle“ beschreibt einen Sidecar-Untertitel-Track für den Videostream. Es werden zwei Untertitelformate gespeichert: TTML und WebVTT. Das TTMLPath-Attribut enthält die URL zur TTML-Sidecar-Datei und das WebVTTPath-Attribut eine URL zur WebVTT-Sidecar-Datei.
JSON-Darstellung
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Felder
language string

Sprachcode wie „en“ oder „de“
language_name string

Beschreibender Name der Sprache. Es unterscheidet einen bestimmten Satz von Untertiteln, wenn mehrere Sätze für dieselbe Sprache vorhanden sind.
ttml string

Optionale URL zur TTML-Sidecar-Datei
webvtt string

Optionale URL zur WebVTT-Sidecar-Datei

Icon

Das Symbol enthält Informationen zu einem VAST-Symbol.
JSON-Darstellung
{
  "click_data": object(ClickData),
  "creative_type": string,
  "click_fallback_images": [object(FallbackImage)],
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "x_position": string,
  "y_position": string,
  "program": string,
  "alt_text": string,
}
Felder
click_data object(ClickData)

creative_type string

click_fallback_images [object(FallbackImage)]

height int32

width int32

resource string

type string

x_position string

y_position string

program string

alt_text string

ClickData

ClickData enthält Informationen zu einem Klick-Symbol.
JSON-Darstellung
{
  "url": string,
}
Felder
url string

FallbackImage

FallbackImage enthält Informationen zu einem VAST-Fallback-Bild.
JSON-Darstellung
{
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "alt_text": string,
}
Felder
creative_type string

height int32

width int32

resource string

alt_text string

Wrapper

Der Wrapper enthält Informationen zu einer Wrapper-Anzeige. Wenn keine Deal-ID vorhanden ist, enthält sie keine Deal-ID.
JSON-Darstellung
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Felder
system string

Die Werbesystem-ID.
ad_id string

Die für die Wrapper-Anzeige verwendete Anzeigen-ID.
creative_id string

Für die Wrapper-Anzeige verwendete Creative-ID
creative_ad_id string

Die Anzeigen-ID des Creatives, die für die Wrapper-Anzeige verwendet wird.
deal_id string

Optionale Deal-ID für die Wrapper-Anzeige

Überprüfung

Die Überprüfung enthält Informationen für Open Measurement, die die Sichtbarkeits- und Verifizierungsmessung durch Drittanbieter erleichtern. Derzeit werden nur JavaScript-Ressourcen unterstützt. Siehe https://iabtechlab.com/standards/open-measurement-sdk/
JSON-Darstellung
{
  "vendor": string,
  "java_script_resources": [object(JavaScriptResource)],
  "tracking_events": [object(TrackingEvent)],
  "parameters": string,
}
Felder
vendor string

Der Überprüfungsanbieter.
java_script_resources [object(JavaScriptResource)]

Liste der JavaScript-Ressourcen für die Bestätigung.
tracking_events [object(TrackingEvent)]

Liste der Tracking-Ereignisse für die Überprüfung
parameters string

Ein intransparenter String, der an den Bootstrap-Bestätigungscode übergeben wird.

JavaScriptResource

JavaScriptResource enthält Informationen zur Überprüfung mittels JavaScript.
JSON-Darstellung
{
  "script_url": string,
  "api_framework": string,
  "browser_optional": boolean,
}
Felder
script_url string

URI zur JavaScript-Nutzlast.
api_framework string

APIFramework ist der Name des Video-Frameworks, das den Bestätigungscode ausführt.
browser_optional boolean

Gibt an, ob dieses Skript außerhalb eines Browsers ausgeführt werden kann.

TrackingEvent

TrackingEvent enthält URLs, die in bestimmten Situationen vom Client angepingt werden sollten.
JSON-Darstellung
{
  "event": string,
  "uri": string,
}
Felder
event string

Der Typ des Tracking-Ereignisses. Aktuell ist gemäß der VAST 4.1-Spezifikation die einzige Option „verificationNotExecuted“.
uri string

Das zu kontaktierende Tracking-Ereignis.

UniversalAdID

UniversalAdID wird verwendet, um eine eindeutige Creative-ID bereitzustellen, die über alle Werbesysteme hinweg verwaltet wird.
JSON-Darstellung
{
  "id_value": string,
  "id_registry": string,
}
Felder
id_value string

Die universelle Anzeigen-ID des für die Anzeige ausgewählten Creatives.
id_registry string

String zur Identifizierung der URL der Registry-Website, auf der die universelle Anzeigen-ID des ausgewählten Creatives katalogisiert ist

Companion

Companion enthält Informationen zu Companion-Anzeigen, die zusammen mit der Anzeige eingeblendet werden können.
JSON-Darstellung
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
}
Felder
click_data object(ClickData)

Die Klickdaten für dieses Companion.
creative_type string

Das CreativeType-Attribut im <StaticResource>-Knoten in der VAST-Antwort, wenn es sich um eine statische Companion-Anzeige handelt.
height int32

Die Höhe dieses Companions in Pixeln.
width int32

Die Breite dieses Companions in Pixeln.
resource string

Bei statischen und iFrame-Companions ist dies die URL, die geladen und angezeigt werden soll. Für HTML-Companions ist dies das HTML-Snippet, das als Companion angezeigt werden soll.
type string

Typ dieses Companions. Er kann entweder statisch, iFrame oder HTML sein.

InteractiveFile

InteractiveFile enthält Informationen zu interaktiven Creatives (z.B. SIMID), die während der Anzeigenwiedergabe angezeigt werden sollen.
JSON-Darstellung
{
  "resource": string,
  "type": string,
  "variable_duration": boolean,
  "ad_parameters": string,
}
Felder
resource string

URL zum interaktiven Creative
type string

Der MIME-Typ der Datei, die als Ressource bereitgestellt wird.
variable_duration boolean

Gibt an, ob für dieses Creative eine Verlängerung der Dauer angefordert wird.
ad_parameters string

Wert des <AdParameters>-Knotens im VAST