VOD API für die dynamische Anzeigenbereitstellung

Mit der Dynamic Ad Insertion API kannst du Video-on-Demand-Streams (VOD) mit dynamischer Anzeigenbereitstellung anfordern und erfassen. HLS- und DASH-Streams werden unterstützt.

Dienst: dai.google.com

Der Pfad der stream-Methode 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 ihn im Anfragetext anzugeben, kann der API-Schlüssel 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 serverseitigen Beaconing-Stream zu erstellen. Die Standardeinstellung ist false. Das Tracking des Standardstreams wird clientseitig initiiert und auf Serverseite gepingt.
DFP-Targeting-Parameter Optional Zusätzliche Targeting-Parameter
Streamparameter überschreiben Optional Standardwerte eines Parameters für die Streamerstellung überschreiben.
HMAC-Authentifizierung Optional Mit einem HMAC-basierten Token authentifizieren.

Antworttext

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

Open Measurement

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

Methode: Medienüberprüfung

Wenn du während der Wiedergabe eine Anzeigenmedien-ID siehst, sende sofort eine Anfrage mit der media_verification_url vom Endpunkt stream. media_verification_url ist ein absoluter Pfad. Anfragen zur Medienüberprüfung sind für serverseitige Beaconing-Streams nicht erforderlich, da die Medienüberprüfung vom Server initiiert wird.

Anfragen an den media verification-Endpunkt sind idempotent.

Methoden
media verification GET {media_verification_url}/{ad_media_id}

Benachrichtigt die API über ein Ereignis der Medienüberprüfung.

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 war und alle Pings gesendet wurden.
  • HTTP/1.1 404 Not Found, wenn die Medien aufgrund einer falschen URL-Formatierung oder eines Ablaufdatums nicht bestätigt werden können.
  • HTTP/1.1 404 Not Found, wenn eine vorherige Bestätigungsanfrage für diesen Ausweis erfolgreich war.
  • HTTP/1.1 409 Conflict, wenn zu diesem Zeitpunkt bereits Pings für eine andere Anfrage gesendet werden.

Anzeigen-Media-IDs (HLS)

Anzeigenmedien-IDs werden in HLS-zeitbasierten Metadaten 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 muss für jede Anfrage zur Anzeigenüberprüfung an media_verification_url angehängt werden.

Anzeigenmedien-IDs (DASH)

Anzeigenmedien-IDs werden über das DASH-Element EventStream 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 Anzeigenmedien-ID enthält, die mit “google_” beginnt. Der gesamte Inhalt des Attributs messageData muss für jede Anfrage zur Anzeigenüberprüfung an media_verification_url 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-ID
total_duration number

Streamdauer in Sekunden.
content_duration number

Dauer der Inhalte ohne Anzeigen in Sekunden.
valid_for string

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

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

Eine Liste mit Untertiteln. Wird weggelassen, wenn es leer ist. Nur HLS.
hls_master_playlist string

(VERSCHUSSELT) URL der HLS-Masterplaylist. Verwende „stream_manifest“. Nur HLS.
stream_manifest string

Das Manifest des Streams. Entspricht der Masterplaylist in HLS und der MPD in DASH. Dieses Feld ist neben „stream_id“ das einzige Feld, das in der Antwort enthalten ist, wenn ein serverseitiger Beaconing-Stream erstellt wird.
media_verification_url string

URL für die Medienüberprüfung
apple_tv object(AppleTV)

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

Eine Liste von Werbeunterbrechungen. Wird weggelassen, wenn es leer ist.

AppleTV

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

URL des Interstitials

AdBreak

„AdBreak“ beschreibt eine einzelne Werbeunterbrechung im Stream. Sie enthält eine Position, eine Dauer, einen Typ (Mid-/Pre-/Post-Roll) und eine Liste mit 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, an der die Werbeunterbrechung beginnt, in Sekunden.
duration number

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

Eine Liste von Anzeigen. Wird weggelassen, wenn es leer ist.
„Anzeige“ beschreibt eine Anzeige im Stream. Sie enthält die Position der Anzeige in der Werbeunterbrechung, 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 Werbeunterbrechung.
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 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 bei leerem Wert weggelassen wird.
wrappers [object(Wrapper)]

Eine Liste der Wrapper. Wird weggelassen, wenn es leer ist.
events [object(Event)]

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

Optionale Open Measurement-Bestätigungseinträge, die die Ressourcen und Metadaten enthalten, die zum Ausführen des Messcodes von Drittanbietern zur Überprüfung der Creative-Wiedergabe erforderlich sind.
universal_ad_id object(UniversalAdID)

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

Optionale Companion-Creatives, die zusammen mit dieser Anzeige ausgeliefert werden können.
interactive_file object(InteractiveFile)

Optionales interaktives Creative (SIMID), das während der Anzeigenwiedergabe eingeblendet werden soll.
skip_metadata object(SkipMetadata)

Optionale Metadaten für überspringbare Anzeigen. Wenn diese Option festgelegt ist, gibt sie an, dass die Anzeige übersprungen werden kann. Außerdem enthält sie eine Anleitung zum Umgang mit der Benutzeroberfläche zum Überspringen und dem Tracking-Ereignis.
extensions string

Optionale Liste aller <Extension>-Knoten im VAST.

Ereignis

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

Die Präsentationszeit dieses Ereignisses.
type string

Der Typ dieses Ereignisses.

Untertitel

„Subtitle“ beschreibt einen Sidecar-Untertiteltrack 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 eine URL zur WebVTT-Sidecar-Datei.
JSON-Darstellung
{
  "language": string,
  "language_name": string,
  "ttml": string,
  "webvtt": string,
}
Felder
language string

Ein Sprachcode wie „en“ oder „de“.
language_name string

Beschreibender Name der Sprache. Er unterscheidet die einzelnen Untertitel, wenn für dieselbe Sprache mehrere 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 zum Bearbeiten von Überspringe-Ereignissen für überspringbare Anzeigen benötigen.
JSON-Darstellung
{
  "offset": number,
  "tracking_url": string,
}
Felder
offset number

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

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

Symbol

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 auf ein 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. Eine Deal-ID ist nicht enthalten, wenn keine vorhanden ist.
JSON-Darstellung
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Felder
system string

ID des Anzeigensystems.
ad_id string

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

Creative-ID, die für die Wrapper-Anzeige verwendet wird.
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.

Überprüfung

Die Bestätigung enthält Informationen für Open Measurement, die die Sichtbarkeits- und Überprüfungsmessung 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 Überprüfungsanbieter.
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 zum JavaScript-Nutzlast
api_framework string

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

Ob dieses Script außerhalb eines Browsers ausgeführt werden kann.

TrackingEvent

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

Der Typ des Tracking-Ereignisses.
uri string

Das Tracking-Ereignis, an das ein Ping gesendet werden soll.

UniversalAdID

Mit der UniversalAdID wird eine eindeutige Creative-ID bereitgestellt, die in allen Werbesystemen verwendet 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, der die URL für die Registrierungswebsite angibt, auf der die Universal-Anzeigen-ID des ausgewählten Creatives katalogisiert wird.

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 dieses Companion-Creative.
creative_type string

Das CreativeType-Attribut im <StaticResource>-Knoten im VAST-Tag, wenn es sich um ein Companion-Creative vom Typ „static“ handelt.
height int32

Die Höhe dieses Companion-Elements in Pixeln.
width int32

Die Breite dieses Companion-Elements in Pixeln.
resource string

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

Typ dieses Companion. Sie kann entweder statisch, iFrame oder HTML sein.
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 Wiedergabe der Anzeige 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

Ob für dieses Creative die Dauer verlängert werden kann.
ad_parameters string

Der Wert des Knotens <AdParameters> im VAST-Tag.