Lineare API für die dynamische Anzeigenbereitstellung

Mit der Dynamic Ad Inserting API können Sie lineare (Live-)Streams für die dynamische Anzeigenbereitstellung anfordern und erfassen.

Dienst: dai.google.com

Alle unten angegebenen URIs verweisen auf https://dai.google.com

Methode: Stream

Methoden
stream	POST /linear/v1/hls/event/{assetKey}/stream Erstellt einen Stream für die dynamische Anzeigenbereitstellung für die angegebene Ereignis-ID.

HTTP-Anfrage

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/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
assetKey	string Die Ereignis-ID des Streams. Hinweis: Der Stream-Asset-Schlüssel ist eine Kennung, die auch auf der Ad Manager-UI zu finden ist.

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

Die DAI API enthält im Feld Verifications Informationen für die Open Measurement-Überprüfung. Dieses Feld enthält ein oder mehrere Verification-Elemente, die die Ressourcen und Metadaten auflisten, die zum Ausführen des Drittanbieter-Messcodes erforderlich sind, um die Creative-Wiedergabe zu prüfen. Nur JavaScriptResource wird unterstützt. Weitere Informationen finden Sie im IAB Tech Lab und in den Spezifikationen für VAST 4.1.

Methode: Medienüberprüfung

Wenn bei der Wiedergabe eine Werbe-Media-ID erkannt wird, senden Sie sofort eine Anfrage mit der media_verification_url, die Sie oben vom stream-Endpunkt erhalten haben. Für serverseitige Beaconing-Streams, bei denen der Server die Medienüberprüfung initiiert, sind diese Anfragen 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.

Hinweis: ID3-Ereignisse für den Fortschritt sollten nicht an diesen Endpunkt gesendet werden. Sie dienen Publishern dazu, die Wiedergabe innerhalb und außerhalb einer Werbeunterbrechung zu unterscheiden, und dienen keinem anderen Anzeigen-Tracking-Zweck. Verlage und Webpublisher können Fortschrittsereignisse identifizieren, indem sie in der JSON-Metadatendatei nach der Medien-ID suchen und prüfen, ob das Feld type auf progress gesetzt ist.

HTTP-Anfrage

GET https://{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)

Werbemedien-IDs werden mit dem Schlüssel TXXX in HLS-zeitgesteuerten Metadaten codiert. Dieser Schlüssel ist für Frames mit benutzerdefinierten Textinformationen reserviert. Der Inhalt des Frames ist unverschlüsselt und beginnt immer mit dem Text "google_".

Vor jeder Anzeigenüberprüfungsanfrage sollte der gesamte Textinhalt des Frames an die Anzeigenüberprüfungs-URL angehängt werden.

Methode: metadata

Der Metadatenendpunkt unter metadata_url gibt Informationen zurück, die zum Erstellen einer Anzeigen-UI verwendet werden. Der Metadatenendpunkt ist nicht für serverseitige Beaconing-Streams verfügbar, bei denen der Server für die Initiierung der Anzeigenmedienüberprüfung verantwortlich ist.

Methoden
metadata	GET /{metadata_url}/{ad-media-id} GET /{metadata_url} Ruft Informationen zu Anzeigenmetadaten ab.

Hinweis :Es wird empfohlen, dem Endpunkt die Anzeigenmedien-ID bereitzustellen. Andernfalls können Sie mit polling_frequency bestimmen, wie oft eine Verbindung zu diesem Endpunkt hergestellt werden soll.

HTTP-Anfrage

GET https://{metadata_url}/{ad-media-id}

GET https://{metadata_url}

Antworttext

Bei Erfolg gibt die Antwort eine Instanz von PodMetadata zurück.

Mit Metadaten arbeiten

Metadaten bestehen aus drei separaten Abschnitten: tags, ads und Anzeige breaks. Der Einstiegspunkt in die Daten ist der Abschnitt tags. Gehen Sie dort die Tags durch und suchen Sie den ersten Eintrag, dessen Name ein Präfix für die Anzeigen-Media-ID im Videostream ist. Ihre Anzeigenmedien-ID könnte zum Beispiel so aussehen:

google_1234567890

Dann finden Sie ein Tag-Objekt mit dem Namen google_12345. In diesem Fall stimmt sie mit Ihrer Anzeigen-Media-ID überein. Wenn Sie das richtige Anzeigenmedienpräfix-Objekt gefunden haben, können Sie die Anzeigen-IDs, Werbeunterbrechungen-IDs und den Ereignistyp nachschlagen. Anschließend werden die ads-Objekte mit Werbe-IDs und die breaks-Objekte mit IDs für Werbeunterbrechungen indexiert.

Antwortdaten

Streamen

Stream wird verwendet, um eine Liste von Ressourcen für einen neu erstellten Stream im JSON-Format zu rendern.

JSON-Darstellung
{ "stream_id": string, "stream_manifest": string, "hls_master_playlist": string, "media_verification_url": string, "metadata_url": string, "session_update_url": string, "polling_frequency": number, }

Felder
stream_id	string Stream-ID.
stream_manifest	string Das Manifest des Streams, das der Masterplaylist in HLS oder dem MPD in DASH entspricht. Neben „stream_id“ ist es das einzige Feld, das beim Erstellen eines serverseitigen Beacon-Streams in der Antwort vorhanden ist.
hls_master_playlist	string (EINGESTELLT) HLS-Masterplaylist-URL. Verwende stattdessen „stream_manifest“.
media_verification_url	string Medienüberprüfungs-URL
metadata_url	string Metadaten-URL der Anzeigenmedien
session_update_url	string Sitzungs-Update-URL.
polling_frequency	number Empfohlene Häufigkeit der Metadaten-URL-Abfrage in Sekunden

PodMetadata

PodMetadata enthalten Metadateninformationen zu Anzeigen, Werbeunterbrechungen und Media-ID-Tags.

JSON-Darstellung
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], }

Felder
tags	map[string, object(TagSegment)] Übersicht von Tag-Segmenten, die nach Tag-Präfix indexiert sind.
ads	map[string, object(Ad)] Nach Anzeigen-ID indexierte Übersicht
ad_breaks	map[string, object(AdBreak)] Übersicht der Werbeunterbrechungen, die nach Werbeunterbrechungen-ID indexiert wurden.

TagSegment

„TagSegment“ enthält einen Verweis auf eine Anzeige sowie deren Werbeunterbrechung und Ereignistyp. TagSegment mit type="progress" sollte nicht an den Endpunkt der Anzeigenmedienüberprüfung gepingt werden.

JSON-Darstellung
{ "ad": string, "ad_break_id": string, "type": string, }

Felder
ad	string Die ID der Anzeige dieses Tags.
ad_break_id	string ID der Werbeunterbrechung dieses Tags
type	string Ereignistyp dieses Tags

AdBreak

Eine Werbeunterbrechung beschreibt eine einzelne Werbeunterbrechung im Stream. Es enthält eine Dauer, einen Typ (Mid/Vorher/Nachher) und die Anzahl der Anzeigen.

JSON-Darstellung
{ "type": string, "duration": number, "expected_duration": number, "ads": number, }

Felder
type	string Gültige Werbeunterbrechungstypen sind: Pre, Mid und Post.
duration	number Gesamtdauer der Werbeunterbrechung in Sekunden
expected_duration	number Erwartete Dauer der Werbeunterbrechung (in Sekunden), einschließlich aller Anzeigen und Slates
ads	number Anzahl der Anzeigen in der Werbeunterbrechung.

Werbeunterbrechung

„Anzeige“ beschreibt eine Werbeanzeige im Stream.

JSON-Darstellung

{ "ad_break_id": string, "position": 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, "click_tracking_urls": [], "verifications": [object(Verification)], "slate": boolean, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "universal_ad_id": object(UniversalAdID), "extensions": [], "companions": [object(Companion)], "interactive_file": object(InteractiveFile), }

Felder
ad_break_id	string Die ID der Werbeunterbrechung dieser Anzeige.
position	number Position dieser Anzeige in der Werbeunterbrechung, beginnend bei 1
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
click_tracking_urls	string Optionale Klick-Tracking-URLs:
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.
slate	boolean Optionaler boolescher Wert, der angibt, dass der aktuelle Eintrag Slate ist.
icons	[object(Icon)] Eine Liste von Symbolen, die weggelassen werden, wenn das Feld leer ist.
wrappers	[object(Wrapper)] Eine Liste der Wrapper, ausgelassen, wenn das Feld leer ist.
universal_ad_id	object(UniversalAdID) Optionale universelle Anzeigen-ID
extensions	string Optionale Liste aller <Extension>-Knoten im VAST
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

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