Lineare API für die dynamische Anzeigenbereitstellung

Mit der API für die dynamische Anzeigenbereitstellung können Sie lineare DAI-Streams (LIVE) anfordern und verfolgen.

Dienst: dai.google.com

Alle URIs beziehen sich auf https://dai.google.com

Methode: stream

Methoden
stream POST /linear/v1/hls/event/{assetKey}/stream

Erstellt einen DAI-Stream für die angegebene Event-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 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
assetKey string

Die Ereignis-ID des Streams.
Hinweis: Der Stream-Asset-Schlüssel ist eine Kennung, die auch auf der Ad Manager-Benutzeroberfläche zu finden ist.

Anfragetext

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

Parameter
dai-ssb Optional

Legen Sie true fest, um einen Stream für serverseitige Beacons zu erstellen. Die Standardeinstellung ist false. Das Tracking des Standardstreams wird vom Client initiiert und serverseitig angepingt.
DFP-Ausrichtungsparameter 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

Die DAI API enthält Informationen zur Open Measurement-Überprüfung im Feld Verifications. Dieses Feld enthält ein oder mehrere Verification-Elemente, in denen die Ressourcen und Metadaten aufgeführt sind, die zum Ausführen von Drittanbieter-Messcode zur Überprüfung der Creative-Wiedergabe erforderlich sind. Nur JavaScriptResource wird unterstützt. Weitere Informationen finden Sie auf der IAB Tech Lab-Website und in der VAST 4.1-Spezifikation.

Methode: Media-Überprüfung

Wenn während der Wiedergabe eine Media-ID für Anzeigen gefunden wird, senden Sie sofort eine Anfrage über die media_verification_url, die Sie vom stream-Endpunkt erhalten haben. Diese Anfragen sind für Streams mit serverseitigem Beaconing nicht erforderlich, da die Media-Ü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 Media-Bestätigungsereignis.

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 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 vor jeder Anfrage zur Anzeigenüberprüfung an die URL zur Anzeigenüberprüfung angehängt werden.

Methode: Metadaten

Der Metadaten-Endpunkt unter metadata_url gibt Informationen zurück, die zum Erstellen einer Benutzeroberfläche für Anzeigen verwendet werden. Der Metadatenendpunkt ist nicht für Streams mit serverseitigem Beaconing verfügbar, bei denen der Server für die Initiierung der Überprüfung von Werbemedien verantwortlich ist.

Methoden
metadata GET /{metadata_url}/{ad-media-id}

GET /{metadata_url}

Ruft Metadateninformationen zur Anzeige ab.

HTTP-Anfrage

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

GET https://{metadata_url}

Suchparameter

Parameter
delta_token optional string

Ein intransparentes Token, das den aktuellen Synchronisierungsstatus des Clients darstellt. Falls angegeben, gibt der Server nur die Metadaten zurück, die sich seit der Generierung des Tokens geändert haben, sowie ein neues next_delta_token in der Antwort. Falls nicht angegeben, gibt der Server die vollständigen Metadaten für das gesamte DVR-Zeitfenster zurück.

Antworttext

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

Mit Metadaten arbeiten

Metadaten haben drei separate Abschnitte: tags, ads und breaks. Der Einstiegspunkt in die Daten ist der Bereich tags. Durchlaufen Sie die Tags und suchen Sie nach dem ersten Eintrag, dessen Name ein Präfix für die Media-ID der Anzeige im Videostream ist. Beispiel:

google_1234567890

Anschließend finden Sie ein Tag-Objekt mit dem Namen google_12345. In diesem Fall entspricht sie Ihrer Media-ID für Anzeigen. Sobald Sie das richtige Präfixobjekt für Anzeigenmedien gefunden haben, können Sie nach Anzeigen-IDs, Werbeunterbrechungs-IDs und dem Ereignistyp suchen. Anzeigen-IDs werden dann zum Indexieren der ads-Objekte und Werbeunterbrechungs-IDs zum Indexieren der breaks-Objekte verwendet.

Antwortdaten

Stream

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

Die GAM-Stream-ID.
stream_manifest string

Die Manifest-URL des Streams, die zum Abrufen der Playlist mit mehreren Varianten in HLS oder des MPD in DASH verwendet wird.
hls_master_playlist string

(DEPRECATED) HLS-Playlist-URL mit mehreren Varianten. Verwenden Sie stattdessen „stream_manifest“.
media_verification_url string

Die Bestätigungs-URL für Medien, die als Basisendpunkt für das Tracking von Wiedergabeereignissen verwendet wird.
metadata_url string

Metadaten-URL, die zum Abrufen von regelmäßigen Informationen zu anstehenden Stream-Werbeereignissen verwendet wird.
session_update_url string

Die Aktualisierungs-URL der Sitzung, die zum Aktualisieren der Ausrichtungsparameter für diesen Stream verwendet wird. Die ursprünglichen Werte für die Targeting-Parameter werden bei der ersten Anfrage zur Streamerstellung erfasst.
polling_frequency number

Die Abfragehäufigkeit in Sekunden beim Anfordern von metadata_url oder heartbeat_url.

PodMetadata

PodMetadata enthält Metadaten 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)],
  "next_delta_token": string,
  "obsolete_ad_break_ids": [],
}
Felder
tags map[string, object(TagSegment)]

Karte der Tag-Segmente, die nach Tag-Präfix indexiert sind.
ads map[string, object(Ad)]

Karte der nach Anzeigen-ID indexierten Anzeigen.
ad_breaks map[string, object(AdBreak)]

Karte der Werbeunterbrechungen, indexiert nach der ID der Werbeunterbrechung.
next_delta_token string

Ein verschlüsseltes Token, das der Client beim nächsten Poll verwenden soll.
obsolete_ad_break_ids string

Eine Liste mit Anzeigenunterbrechungs-IDs, die nicht mehr aktuell sind und aus dem Cache des Clients entfernt werden sollten.

TagSegment

„TagSegment“ enthält einen Verweis auf eine Anzeige, die zugehörige Werbeunterbrechung und den Ereignistyp. TagSegment mit type="progress" sollte nicht an den Endpunkt für die Überprüfung von Anzeigenmedien gesendet werden.
JSON-Darstellung
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Felder
ad string

Die ID der Anzeige dieses Tags.
ad_break_id string

Die ID der Werbeunterbrechung dieses Tags.
type string

Der Ereignistyp dieses Tags.

AdBreak

„AdBreak“ beschreibt eine einzelne Werbeunterbrechung im Stream. Sie enthält eine Dauer, einen Typ (Mid/Pre/Post) und die Anzahl der Anzeigen.
JSON-Darstellung
{
  "type": string,
  "duration": number,
  "expected_duration": number,
  "ads": number,
}
Felder
type string

Gültige Pausentypen sind: „pre“, „mid“ und „post“.
duration number

Gesamtdauer der Anzeigen für diese Werbeunterbrechung in Sekunden.
expected_duration number

Erwartete Dauer der Werbeunterbrechung (in Sekunden), einschließlich aller Anzeigen und aller Slates.
ads number

Anzahl der Anzeigen in der Werbeunterbrechung.
„Anzeige“ beschreibt eine Anzeige 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 mit 1.
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.
click_tracking_urls string

Optionale Klick-Tracking-URLs
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.
slate boolean

Optionaler boolescher Wert, der angibt, ob der aktuelle Eintrag ein Slate ist.
icons [object(Icon)]

Eine Liste von Symbolen, die ausgelassen wird, wenn sie leer ist.
wrappers [object(Wrapper)]

Eine Liste von Wrappern, die ausgelassen wird, wenn sie leer ist.
universal_ad_id object(UniversalAdID)

Optionale universelle Anzeigen-ID.
extensions string

Optionale Liste aller <Extension>-Knoten im VAST.
companions [object(Companion)]

Optionale Begleit-Creatives, 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.

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, 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.

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 nicht transparenter 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 Companions. 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.