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.
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 |
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. |
Werbeunterbrechung
„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 |