Lineare API für die dynamische Anzeigenbereitstellung

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.
Hinweis: Der Schlüssel für das Stream-Asset 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 serverseitigen Beaconing-Stream zu erstellen. Die Standardeinstellung ist false. Das Tracking des Standardstreams wird vom Client initiiert und serverseitig angepingt.
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
„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.