Mit der Dynamic Ad Inserting API können Sie lineare Livestreams (LIVE) 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 Verlags oder Webpublishers gültig sein. Anstatt den API-Schlüssel im Anfragetext anzugeben, kann er im HTTP-Autorisierungsheader im folgenden Format übergeben werden: Authorization: DCLKDAI key="<api-key>" |
Pfadparameter
Parameter | |
---|---|
assetKey |
string Die Ereignis-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 |
DFP-Targeting-Parameter | Optional | Zusätzliche Targeting-Parameter. |
Stream-Parameter überschreiben | Optional | Standardwerte eines Parameters für die Streamerstellung überschreiben. |
HMAC-Authentifizierung | Optional | Authentifizieren Sie sich mit einem HMAC-basierten Token. |
Antworttext
Wenn der Vorgang erfolgreich ist, enthält der Antworttext ein neues Stream
. Für serverseitige Beaconing-Streams enthält Stream
nur die Felder stream_id
und stream_manifest
.
Open Measurement
Die DAI API enthält im Feld Verifications
Informationen zur Open Measurement-Überprüfung. Dieses Feld enthält ein oder mehrere Verification
-Elemente mit den Ressourcen und Metadaten, die zum Ausführen von Drittanbieter-Messcode erforderlich sind, um die Creative-Wiedergabe zu prüfen. 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 bei der Wiedergabe auf eine Werbemedien-ID gestoßen ist, senden Sie sofort eine Anfrage mit der URL media_verification_url, die vom oben angegebenen stream-Endpunkt abgerufen wurde. Diese Anfragen 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 Medienüberprüfungsereignisse. |
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 das Medium aufgrund einer falschen URL-Formatierung oder eines falschen Ablaufs nicht überprüft werden kann.HTTP/1.1 404 Not Found
, wenn eine vorherige Bestätigungsanfrage für diese ID erfolgreich war.HTTP/1.1 409 Conflict
, wenn derzeit über eine andere Anfrage bereits Pings gesendet werden.
Media-IDs von Anzeigen (HLS)
Media-IDs von Anzeigen werden mit dem Schlüssel TXXX
in HLS Timed Metadata codiert. Dieser Schlüssel ist für Frames vom Typ „benutzerdefinierte Textinformationen“ reserviert. Der Inhalt des Frames wird entschlüsselt und beginnt immer mit dem Text "google_"
.
Der gesamte Textinhalt des Frames sollte vor jeder Anzeigenüberprüfungsanfrage an die Anzeigenüberprüfungs-URL angehängt werden.
Methode: metadata
Der Metadatenendpunkt bei 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 Überprüfung von Anzeigenmedien verantwortlich ist.
Methoden | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
Ruft Informationen zu Anzeigenmetadaten ab. |
HTTP-Anfrage
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
Antworttext
Wenn der Vorgang erfolgreich ist, wird eine Instanz von PodMetadata
zurückgegeben.
Mit Metadaten arbeiten
Metadaten haben drei separate Abschnitte: tags
, ads
und Anzeige breaks
. Der Einstiegspunkt für die Daten ist der Abschnitt tags
. Durchlaufen Sie dann die Tags und suchen Sie den ersten Eintrag, dessen Name ein Präfix für die Anzeigenmedien-ID im Videostream ist. Angenommen, Sie haben eine Anzeigenmedien-ID, die so aussieht:
google_1234567890
Nun finden Sie ein Tag-Objekt mit dem Namen google_12345
. In diesem Fall stimmt sie mit Ihrer Anzeigen-Media-ID überein. Sobald Sie das richtige Anzeigenmedienpräfixobjekt gefunden haben, können Sie die Anzeigen-IDs, Werbeunterbrechungen-IDs und den Ereignistyp abrufen. Anschließend werden die ads
-Objekte mit Anzeigen-IDs indexiert und die breaks
-Objekte mit den Werbeunterbrechungs-IDs.
Antwortdaten
Stream
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 Die GAM-Stream-ID |
stream_manifest |
string Die Manifest-URL des Streams, mit der die Playlist mit mehreren Varianten in HLS oder die MPD-Datei in DASH abgerufen wird. |
hls_master_playlist |
string (VERWORFEN) URL der HLS-Playlist mit mehreren Varianten. Verwenden Sie stattdessen „stream_manifest“. |
media_verification_url |
string Die Medienbestätigungs-URL, die als Basisendpunkt für das Tracking von Wiedergabeereignissen verwendet wird. |
metadata_url |
string Metadaten-URL, mit der regelmäßig Informationen zu anstehenden Streamanzeigenereignissen abgefragt werden |
session_update_url |
string Die Update-URL der Sitzung, die zum Aktualisieren der Targeting-Parameter für diesen Stream verwendet wird. Die ursprünglichen Werte für die Targeting-Parameter werden bei der ersten Anfrage zum Erstellen des Streams erfasst. |
polling_frequency |
number Die Abfragehäufigkeit in Sekunden, wenn „metadata_url“ von oder „fazbeat_url“ angefordert wird. |
PodMetadata
PodMetadata enthalten 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)], } |
Felder | |
---|---|
tags |
map[string, object(TagSegment)] Karte der Tag-Segmente, die nach Tag-Präfix indexiert sind. |
ads |
map[string, object(Ad)] Nach Anzeigen-ID indexierte Anzeigen |
ad_breaks |
map[string, object(AdBreak)] Zuordnung der Werbeunterbrechungen, die nach ID der Werbeunterbrechung indexiert sind |
TagSegment
TagSegment enthält einen Verweis auf eine Anzeige, die zugehörige Werbeunterbrechung und den Ereignistyp. TagSegment mit type="progress" sollte nicht an den Bestätigungsendpunkt für Anzeigenmedien 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 Die ID der Werbeunterbrechung dieses Tags |
type |
string Der Ereignistyp dieses Tags. |
AdBreak
Eine Werbeunterbrechung beschreibt eine einzelne Werbeunterbrechung im Stream. Sie enthält die Dauer, einen Typ (Mitte/Vorher/Nachher) 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 Gesamte Anzeigendauer für diese 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 |
Ad
„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 Werbeunterbrechung |
position |
number Position dieser Anzeige in der Werbeunterbrechung, beginnend bei 1 |
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 |
click_tracking_urls |
string Optionale Klick-Tracking-URLs |
verifications |
[object(Verification)] Optionale Open Measurement-Bestätigungseinträge, in denen die Ressourcen und Metadaten aufgeführt sind, die zum Ausführen des Drittanbieter-Messcodes erforderlich sind, um die Creative-Wiedergabe zu verifizieren |
slate |
boolean Optionaler boolescher Wert, der angibt, dass der aktuelle Eintrag ein Slate ist. |
icons |
[object(Icon)] Eine Liste von Symbolen wird weggelassen, wenn sie leer ist. |
wrappers |
[object(Wrapper)] Eine Liste der Wrapper, sofern leer. |
universal_ad_id |
object(UniversalAdID) Optionale universelle Anzeigen-ID |
extensions |
string Optionale Liste aller <Extension>-Knoten im VAST |
companions |
[object(Companion)] Optionale Companions, die mit dieser Anzeige eingeblendet werden können |
interactive_file |
object(InteractiveFile) Optionales interaktives Creative (SIMID), das während der Anzeigenwiedergabe eingeblendet 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 Click-through eines Symbols.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, wird sie nicht angegeben.JSON-Darstellung |
---|
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, } |
Felder | |
---|---|
system |
string System-ID des Anzeigensystems |
ad_id |
string Die für die Wrapper-Anzeige verwendete Anzeigen-ID |
creative_id |
string Die für die Wrapper-Anzeige verwendete Creative-ID |
creative_ad_id |
string Die für die Wrapper-Anzeige verwendete Creative-Anzeigen-ID |
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 Sichtbarkeitsmessung durch Drittanbieter und die Überprüfungsmessung 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 Überprüfung |
parameters |
string Ein intransparenter String, der an den Bootstrap-Bestätigungscode übergeben wird. |
JavaScriptResource
JavaScriptResource enthält Informationen zur Überprüfung mit 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 das 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. |
uri |
string Das Tracking-Ereignis, das gepingt werden soll |
UniversalAdID
Mit UniversalAdID wird eine eindeutige Creative-ID bereitgestellt, die von allen Anzeigensystemen verwaltet 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, mit dem die URL der Registry-Website identifiziert wird, auf der die universelle Anzeigen-ID des ausgewählten Creatives katalogisiert ist. |
Companion
Die Companion-Anzeige enthält Informationen zu Companion-Anzeigen, die zusammen mit der Anzeige angezeigt 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_type |
string Das Attribut „CreativeType“ auf dem <StaticResource>-Knoten im VAST, wenn es sich um einen Companion vom Typ „Statisch“ handelt. |
height |
int32 Die Höhe dieses Companion in Pixeln. |
width |
int32 Die Breite dieses Companion in Pixeln. |
resource |
string Bei statischen und iFrame-Companions ist dies die URL, die geladen und angezeigt werden soll. Bei HTML-Companions ist dies das HTML-Snippet, das als Companion angezeigt werden sollte. |
type |
string Der Typ dieses Companion. Er kann entweder statisch, iFrame oder HTML sein. |
ad_slot_id |
string Die Anzeigenflächen-ID für diese Companion-Anzeige. |
api_framework |
string Das API-Framework für diese Companion-Anzeige. |
tracking_events |
[object(TrackingEvent)] Liste der Tracking-Ereignisse für dieses Companion |
InteractiveFile
InteractiveFile enthält Informationen für ein interaktives Creative (z.B. SIMID), das während der Anzeigenwiedergabe eingeblendet werden soll.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 Datei, die als Ressource bereitgestellt wird. |
variable_duration |
boolean Gibt an, ob für dieses Creative eine Verlängerung der Dauer angefordert werden kann. |
ad_parameters |
string Der Wert des <AdParameters>-Knotens in VAST. |