VOD API für die dynamische Anzeigenbereitstellung

Mit der Dynamic Ad Insertion API können Sie VOD-Streams (Video-on-Demand) für die dynamische Anzeigenbereitstellung anfordern und nachverfolgen. 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

Erstellt einen HLS-DAI-Stream für die angegebene Contentquelle und Video-ID.

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

Erstellt einen DASH-DAI-Stream für die angegebene Contentquelle und Video-ID.

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 angegeben wird, muss für das Netzwerk des Publishers gültig sein.

Anstatt den API-Schlüssel im Anfragetext anzugeben, kann er im HTTP-Autorisierungsheader mit dem folgenden Format ü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 hat den Typ application/x-www-form-urlencoded und enthält die folgenden Parameter:

Parameter
dai-ssb Optional

Legen Sie den Wert auf true fest, um einen Stream für serverseitige Beacons zu erstellen. Die Standardeinstellung ist false. Das Tracking des Standardstreams wird vom Client initiiert und auf dem Server gepingt.
DFP-Targeting-Parameter Optional Zusätzliche Targeting-Parameter.
Streamparameter überschreiben Optional Standardwerte eines Parameters zur Streamerstellung überschreiben.
HMAC-Authentifizierung Optional Mit einem HMAC-basierten Token authentifizieren.

Antworttext

Bei Erfolg enthält der Antworttext eine neue Stream. Bei Streams mit serverseitigem Beaconing enthält Stream nur die Felder stream_id und stream_manifest.

Offene Messung

Das Feld Verifications enthält Informationen zur Open Measurement-Überprüfung für Streams ohne serverseitige Beacons. Verifications enthält ein oder mehrere Verification-Elemente, in denen die Ressourcen und Metadaten aufgeführt sind, die Sie zum Überprüfen der Creative-Wiedergabe mit Drittanbieter-Messcode benötigen. Es wird nur JavaScriptResource unterstützt. Weitere Informationen finden Sie auf der IAB Tech Lab-Website und in der VAST 4.1-Spezifikation.

Methode: Media-Bestätigung

Wenn Sie während der Wiedergabe auf eine Media-ID für Anzeigen stoßen, senden Sie sofort eine Anfrage mit der media_verification_url vom Endpunkt stream. media_verification_url ist ein absoluter Pfad. Für Streams mit serverseitigem Beaconing, bei denen der Server die Media-Bestätigung initiiert, sind keine Media-Bestätigungsanfragen erforderlich.

Anfragen an den media verification-Endpunkt sind idempotent.

Methoden
media verification GET {media_verification_url}/{ad_media_id}

Benachrichtigt die API über ein Media-Bestätigungsereignis.

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 Media-Überprüfung erfolgreich ist und alle Pings gesendet werden.
  • HTTP/1.1 404 Not Found, wenn die Media aufgrund einer falschen URL-Formatierung oder eines Ablaufs nicht überprüft werden können.
  • HTTP/1.1 404 Not Found, wenn eine frühere Bestätigungsanfrage für diese ID erfolgreich war.
  • HTTP/1.1 409 Conflict, wenn zu diesem Zeitpunkt bereits eine andere Anfrage Pings sendet.

Media-IDs für Anzeigen (HLS)

Anzeigen-Media-IDs werden in HLS Timed Metadata mit dem Schlüssel TXXX codiert, der für Frames mit „nutzerdefinierten Textinformationen“ reserviert ist. Der Inhalt des Frames ist unverschlüsselt und beginnt immer mit dem Text "google_".

Der gesamte Textinhalt des Frames sollte an die media_verification_url für jede Anfrage zur Anzeigenüberprüfung angehängt werden.

Media-IDs für Anzeigen (DASH)

Anzeigen-Media-IDs werden mithilfe des EventStream-Elements von DASH in das Manifest eingefügt.

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

Antwortdaten

Stream

Mit „Stream“ wird eine Liste aller Ressourcen für einen neu erstellten Stream im JSON-Format gerendert .
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-Kennung.
total_duration number

Streamdauer in Sekunden.
content_duration number

Dauer der Inhalte ohne Anzeigen in Sekunden.
valid_for string

Gültigkeitsdauer des Streams im Format „00h00m00s“.
valid_until string

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

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

(VERALTET) URL der HLS-Master-Playlist. Verwenden Sie stream_manifest. Nur HLS.
stream_manifest string

Das Manifest des Streams. Entspricht der Master-Playlist in HLS und dem MPD in DASH. Dies ist das einzige Feld neben „stream_id“, das in der Antwort beim Erstellen eines Streams mit serverseitigem Beaconing vorhanden ist.
media_verification_url string

Bestätigungs-URL für Medien.
apple_tv object(AppleTV)

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

Eine Liste von Ad-Breaks. Wird ausgelassen, wenn leer.

AppleTV

AppleTV enthält Informationen speziell für Apple TV-Geräte.
JSON-Darstellung
{
  "interstitials_url": string,
}
Felder
interstitials_url string

URL für Interstitials:

AdBreak

„AdBreak“ beschreibt eine einzelne Werbeunterbrechung im Stream. Sie 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 Unterbrechungstypen sind: „mid“, „pre“ und „post“.
start number

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

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

Eine Liste mit Anzeigen. Wird ausgelassen, wenn leer.
„Anzeige“ beschreibt eine Anzeige im Stream. Sie enthält die Position der Anzeige im Break, 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),
  "skip_metadata": object(SkipMetadata),
  "extensions": [],
}
Felder
seq number

Position der Anzeige in der Unterbrechung.
start number

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

Dauer der Anzeige in Sekunden.
title string

Optionaler Titel der Anzeige.
description string

Optionale Beschreibung der Anzeige.
advertiser string

Optionale Werbe-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 ausgelassen wird, wenn sie leer ist.
wrappers [object(Wrapper)]

Eine Liste von Wrappern. Wird 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, in denen die Ressourcen und Metadaten aufgeführt sind, die zum Ausführen von Drittanbieter-Messcode zur Überprüfung der Creative-Wiedergabe erforderlich sind.
universal_ad_id object(UniversalAdID)

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

Optionale Companion-Anzeigen, 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.
skip_metadata object(SkipMetadata)

Optionale Metadaten für überspringbare Anzeigen. Wenn dieser Wert festgelegt ist, gibt er an, dass die Anzeige überspringbar ist. Außerdem enthält er eine Anleitung dazu, wie die Benutzeroberfläche zum Überspringen und das Tracking-Ereignis zu verarbeiten sind.
extensions string

Optionale Liste aller <Extension>-Knoten im VAST.

Ereignis

Ein Ereignis enthält einen Ereignistyp und eine Präsentationszeit.
JSON-Darstellung
{
  "time": number,
  "type": string,
}
Felder
time number

Die Präsentationszeit dieses Ereignisses.
type string

Der Typ dieses Ereignisses.

Untertitel

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

Ein Sprachcode, z. B. „en“ oder „de“.
language_name string

Aussagekräftiger Name der Sprache. Damit wird zwischen den einzelnen Untertiteln unterschieden, wenn mehrere Untertitel für dieselbe Sprache vorhanden sind.
ttml string

Optionale URL zur TTML-Sidecar-Datei.
webvtt string

Optionale URL zur WebVTT-Sidecar-Datei.

SkipMetadata

SkipMetadata enthält Informationen, die Clients benötigen, um Skip-Ereignisse für überspringbare Anzeigen zu verarbeiten.
JSON-Darstellung
{
  "offset": number,
  "tracking_url": string,
}
Felder
offset number

Der Offset gibt an, wie viele Sekunden nach Beginn der Anzeige der Player warten soll, bevor er die Schaltfläche „Überspringen“ rendert. Wird ausgelassen, wenn sie im VAST nicht angegeben ist.
tracking_url string

TrackingURL enthält eine URL, die beim Überspringen angepingt werden soll.

Symbol

„Icon“ 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 Symbol-Clickthrough.
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, ist sie nicht enthalten.
JSON-Darstellung
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Felder
system string

Kennung des Anzeigensystems.
ad_id string

Anzeigen-ID, die für die Wrapper-Anzeige verwendet wird.
creative_id string

Creative-ID für die Wrapper-Anzeige.
creative_ad_id string

Creative-Anzeigen-ID, die für die Wrapper-Anzeige verwendet wird.
deal_id string

Optionale Deal-ID für die Wrapper-Anzeige.

Bestätigung

„Verification“ enthält Informationen für Open Measurement, die die Sichtbarkeits- und Verifizierungsmessung durch Drittanbieter erleichtern. Derzeit werden nur JavaScript-Ressourcen unterstützt. Weitere Informationen finden Sie unter 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 Verifikationsanbieter.
java_script_resources [object(JavaScriptResource)]

Liste der JavaScript-Ressourcen für die Überprüfung.
tracking_events [object(TrackingEvent)]

Liste der Tracking-Ereignisse für die Bestätigung.
parameters string

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

JavaScriptResource

JavaScriptResource enthält Informationen zur Überprüfung über 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 Videoframeworks, das den Bestätigungscode verwendet.
browser_optional boolean

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

TrackingEvent

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

Der Typ des Tracking-Ereignisses.
uri string

Das Tracking-Ereignis, das angepingt werden soll.

UniversalAdID

Mit UniversalAdID wird eine eindeutige Creative-Kennung bereitgestellt, die in allen Anzeigensystemen beibehalten wird.
JSON-Darstellung
{
  "id_value": string,
  "id_registry": string,
}
Felder
id_value string

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

Ein String zur Identifizierung der URL für die 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 ausgeliefert werden können.
JSON-Darstellung
{
  "click_data": object(ClickData),
  "creative_type": string,
  "height": int32,
  "width": int32,
  "resource": string,
  "type": string,
  "ad_slot_id": string,
  "api_framework": string,
  "tracking_events": [object(TrackingEvent)],
}
Felder
click_data object(ClickData)

Die Klickdaten für diesen Companion.
creative_type string

Das CreativeType-Attribut für den <StaticResource>-Knoten im VAST, wenn es sich um einen Companion vom Typ „static“ handelt.
height int32

Die Höhe dieses Companion in Pixeln.
width int32

Die Breite dieses Companion-Banners in Pixeln.
resource string

Bei statischen und iFrame-Begleit-Creatives ist dies die URL, die geladen und angezeigt werden soll. Bei HTML-Companion-Anzeigen ist das das HTML-Snippet, das als Companion-Anzeige angezeigt werden soll.
type string

Typ dieses Companion. Sie kann statisch, als iFrame oder als HTML-Datei vorliegen.
ad_slot_id string

Die Slot-ID für diesen Companion.
api_framework string

Das API-Framework für diesen Companion.
tracking_events [object(TrackingEvent)]

Liste der Tracking-Ereignisse für diesen Companion.

InteractiveFile

„InteractiveFile“ enthält Informationen für interaktive 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

Die URL zum interaktiven Creative.
type string

Der MIME-Typ der als Ressource bereitgestellten Datei.
variable_duration boolean

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

Der Wert des Knotens <AdParameters> im VAST.