Dynamische Anzeigenbereitstellung – Live-API für die Pod-Auslieferung

Mit der Dynamic Ad Anzeigenauftrag API können Sie Livestreams für die dynamische Anzeigenbereitstellung anfordern und erfassen.

Dienst: dai.google.com

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

Methode: stream

Methoden
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Registriert eine Livestream-Sitzung der Pod-Auslieferung für die dynamische Anzeigenbereitstellung mit der dynamischen Anzeigenbereitstellung.

HTTP-Anfrage

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Pfadparameter

Parameter
network_code string

Der Google Ad Manager-Netzwerkcode des Publishers.

custom_asset_key string

Die benutzerdefinierte Kennung, die diesem Ereignis in Google Ad Manager zugewiesen wurde.

Anfragetext

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

Parameter
DFP-Targeting-Parameter Optional Zusätzliche Targeting-Parameter
Stream-Parameter überschreiben Optional Standardwerte eines Parameters zur 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-Objekt.

Open Measurement

Die DAI API enthält Informationen zur Open Measurement-Überprüfung in der Verifications-Feld. Dieses Feld enthält mindestens einen Verification-Elemente, die die für die Ausführung erforderlichen Ressourcen und Metadaten auflisten Drittanbieter-Messcode verwenden, um die Creative-Wiedergabe zu überprüfen. Nur JavaScriptResource wird unterstützt. Weitere Informationen finden Sie in der IAB Tech Lab und die VAST 4.1-Spezifikation.

Methode: Pod-Segment

Methoden
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Erstellt einen Stream für die dynamische Anzeigenbereitstellung für die angegebene Ereignis-ID.

HTTP-Anfrage

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Pfadparameter

Parameter
network_code string

Der Google Ad Manager-Netzwerkcode des Publishers.

custom_asset_key string

Die benutzerdefinierte Kennung, die diesem Ereignis in Google Ad Manager zugewiesen wurde.

pod_id integer

Die numerische Kennung der aktuellen Werbeunterbrechung. Anzeigen-Pod-IDs sind werden jedem Ereignis schrittweise zugewiesen, beginnend mit 1.
profile_name string

Die Name der angeforderten Codierungsprofil für die dynamische Anzeigenbereitstellung in Google Ad Manager. Das Codierungsprofil muss eines der konfigurierten Codierungsprofile für das ausgewählte Ereignis.

segment_number integer

Der Index des angeforderten Segments im aktuellen Anzeigen-Pod, beginnend mit bei null liegen.
segment_format string

Die Dateiendung, die dem angeforderten Segmentformat zugeordnet ist. Zulässige Erweiterungen: ts, mp4, vtt, aac, ac3 oder eac3

Abfrageparameter

Parameter
stream_id required string

Die Stream-ID für die Sitzung des aktuellen Nutzers. Dieser Wert wird von Eine erfolgreiche Anfrage an den Endpunkt stream.
sd required1 integer

Die Dauer des angeforderten Segments in Millisekunden.
so optional

Der Versatz des angeforderten Segments innerhalb des Anzeigen-Pods in Millisekunden. Wenn Sie den Parameter so weglassen, wird er so berechnet: Multiplizieren Sie die Segmentdauer mit der Segmentnummer.
pd erforderlich2 integer

Die Dauer des Anzeigen-Pods in Millisekunden.
auth-token required string

Eine signierte, URL-codierte HMAC-Token für den aktuellen Anzeigen-Pod.
last optional boolean

Hiermit wird das letzte Segment in der Werbeunterbrechung angegeben. Diesen Parameter für alle weglassen anderen Segmenten.
scte35 optional string

Base64-codiertes SCTE-35-Signal für diese Werbeunterbrechung.
cust_params optional string

Eine Reihe von Schlüssel/Wert-Paaren, die für das Targeting einer Ad Manager-Kampagne verwendet werden. Diese -Paare müssen als URL-codierter Abfragestring dargestellt werden.

Beispiel:
Parameter
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Fußnoten

  1. sd ist für Initialisierungssegmente nicht erforderlich. ↩
  2. pd ist für Ereignisse mit Anzeigen ohne Dauer nicht erforderlich Pausen aktiviert. ↩

Antworttext

Wenn der Vorgang erfolgreich ist, ist der Antworttext ein abspielbares Stream-Segment, das mit und die in der Anfrage angegebenen Parameter.

Methode: DASH-Pod-Zeitraumvorlage

Methoden
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Hiermit wird eine DASH-Zeitraumvorlage von Google Ad Manager angefordert. Diese Vorlage enthält Makros, die Sie mit Ihren Streamparametern füllen müssen. Einmal werden diese Makros ausgefüllt, die Vorlage wird zu Ihrem Zeitraum für die Werbeunterbrechung kann in dein DASH-Manifest eingefügt werden.

HTTP-Anfrage

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Pfadparameter

Parameter
network_code string

Der Google Ad Manager-Netzwerkcode des Publishers.

custom_asset_key string

Die benutzerdefinierte Kennung, die diesem Ereignis in Google Ad Manager zugewiesen wurde.

Abfrageparameter

Parameter
stream_id required string

Die Stream-ID für die Sitzung des aktuellen Nutzers. Dieser Wert wird von Eine erfolgreiche Anfrage an den Endpunkt stream.

Antworttext

Wenn der Vorgang erfolgreich ist, enthält der Antworttext ein neues PodTemplateResponse-Objekt.

Methode: Medienüberprüfung

Wenn bei der Wiedergabe eine Medien-ID für die Anzeige erkannt wird, Anfrage mit der media_verification_url aus dem stream Endpunkt oben. Für das serverseitige Beaconing sind diese Anfragen nicht erforderlich. Streams, bei denen der Server die Medienüberprüfung initiiert.

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 folgende Antworten zurück:

  • HTTP/1.1 204 No Content, wenn die Medienbestätigung erfolgreich ist und alle Pings dies sind gesendet.
  • HTTP/1.1 404 Not Found, wenn das Medium aus folgendem Grund nicht bestätigt werden kann: inkorrekte Formatierung oder Ablauf von URLs
  • HTTP/1.1 404 Not Found, wenn bereits eine Bestätigungsanfrage für diese ID gestellt wurde erfolgreich war.
  • HTTP/1.1 409 Conflict, wenn an dieser Stelle bereits Pings von einer anderen Anfrage gesendet werden .

Media-IDs für Anzeigen

Die Media-IDs für Anzeigen werden in einem separaten Metadaten-Track codiert – zeitlich festgelegt. Metadaten für HLS-Transport-Stream oder emsg für MP4-Dateien. Media-IDs für Anzeigen beginnt immer mit dem String google_.

Der gesamte Textinhalt des Metadateneintrags muss an die Anzeige angehängt werden. Bestätigungs-URL eingeben.

Methode: metadata

Der Metadaten-Endpunkt metadata_url gibt Informationen zurück, die zum Erstellen einer Anzeige verwendet werden. UI. Der Metadatenendpunkt ist nicht für serverseitige Beaconing-Streams verfügbar, Der Server ist hier für die Initiierung der Überprüfung der Anzeigenmedien zuständig.

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

Bei Erfolg gibt die Antwort eine Instanz von PodMetadata

Metadaten parsen

Metadaten haben drei separate Abschnitte: tags, ads und Anzeige breaks. Der Eintrag Punkt in die Daten ist der Abschnitt tags. Anschließend können Sie die Tags und suchen Sie den ersten Eintrag, dessen Name ein Präfix für die Die Media-ID der Anzeige wurde im Videostream gefunden. Zum Beispiel haben Sie könnte eine Anzeigenmedien-ID haben, die so aussieht:

google_1234567890

Nun finden Sie ein Tag-Objekt mit dem Namen google_12345. In diesem Fall entspricht er Media-ID der Anzeige. Sobald Sie das richtige Anzeigenmedienpräfix-Objekt gefunden haben, können Sie Anzeigen-IDs, Werbeunterbrechungen-IDs und den Ereignistyp. Die Anzeigen-IDs werden dann zur Indexierung der ads-Objekte und Werbeunterbrechungs-IDs werden verwendet, um die breaks-Objekte zu indexieren.

Antwortdaten

Stream

Mit „Stream“ wird eine Liste von Ressourcen für einen neu erstellten Stream in JSON-Format.
JSON-Darstellung
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Felder
stream_id string

Die GAM-Stream-ID
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 Stream-Anzeigenereignissen abgerufen 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.
heartbeat_url string

Die Heartbeat-URL, mit der der serverseitige Beaconing-Stream aktiv bleibt, Er muss alle {PollingFrequency} Sekunden gepingt werden. Wird für serverseitige Beaconing-Streams ausgefüllt.
polling_frequency number

Die Abfragehäufigkeit in Sekunden bei Anfragen von metadata_url oder heartbeat_url.
pod_manifest_url string

Die URL-Vorlage des Pod-Manifests wird verwendet, um die URL zum Abrufen des Pod-Manifests eines Streams zu generieren. entspricht der URL der Playlist mit mehreren Varianten in HLS oder der MPD-Datei in DASH. Wird für Livestream-Ereignisse des Typs „POD_SERVING_MANIFEST“ der dynamischen Anzeigenbereitstellung ausgefüllt. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

„Manifestformat“ ist das Format des Manifests, das von „pod_manifest_url“ abgerufen wurde. Bindestrich oder hl.

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)]

Zuordnung von Tag-Segmenten, die nach Tag-Präfix indexiert sind.
ads map[string, object(Ad)]

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

Zuordnung der Werbeunterbrechungen, die nach der 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" sollten nicht an die Anzeigenmedien gepingt werden. den Endpunkt der Überprüfung.
JSON-Darstellung
{
  "ad": string,
  "ad_break_id": string,
  "type": string,
}
Felder
ad string

Die ID der Anzeige dieses Tags
ad_break_id string

Das ist die ID der Werbeunterbrechung dieses Tags.
type string

Der Ereignistyp dieses Tags.

AdBreak

Eine Werbeunterbrechung beschreibt eine einzelne Werbeunterbrechung im Stream. Es enthält die 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 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

Das ist die ID der Werbeunterbrechung dieser Anzeige.
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-Überprüfungseinträge, in denen die Ressourcen aufgelistet sind und Metadaten, die erforderlich sind, um Drittanbieter-Messcode auszuführen, Creative-Wiedergabe zu präsentieren.
slate boolean

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

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

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

Optionale universelle Anzeigen-ID.
extensions string

Optionale Liste aller <Extension>-Tags in der VAST-Antwort.
companions [object(Companion)]

Optionale Companions, die zusammen mit dieser Anzeige angezeigt werden können.
interactive_file object(InteractiveFile)

Optionales interaktives Creative (SIMID), das während der Anzeigenwiedergabe eingeblendet werden soll.

PodTemplateResponse

PodTemplateResponse stellt die JSON-Nutzlast dar, die für das Pod-Stitching an ein VTP zurückgegeben wird.
JSON-Darstellung
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Felder
dash_period_template string

DashPeriodTemplate ist die XML-Vorlage für den Zeitraum, der vor dem Zusammenfügen mit den entsprechenden Daten gefüllt werden soll.
segment_duration_ms int64

SegmentDurationMS ist die Dauer der Zeitraumsegmente in Millisekunden.

Symbol

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. Es enthält kein Deal-ID, falls nicht vorhanden
JSON-Darstellung
{
  "system": string,
  "ad_id": string,
  "creative_id": string,
  "creative_ad_id": string,
  "deal_id": string,
}
Felder
system string

System-ID des Anzeigenkontos.
ad_id string

Die für die Wrapper-Anzeige verwendete Anzeigen-ID.
creative_id string

Creative-ID, die für die Wrapper-Anzeige verwendet wird
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 Sichtbarkeits- und Verifizierungsmessung durch Drittanbieter. 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 Anbieter der Überprüfung
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, Bestätigungscode.
browser_optional boolean

Ob das Script außerhalb eines Browser.

TrackingEvent

TrackingEvent enthält URLs, die vom Client in bestimmten Situationen.
JSON-Darstellung
{
  "event": string,
  "uri": string,
}
Felder
event string

Die Art des Tracking-Ereignisses.
uri string

Das Tracking-Ereignis, das gepingt werden soll.

UniversalAdID

UniversalAdID verwendet wird, um eine eindeutige Creative-ID bereitzustellen, die über alle Anzeigensysteme hinweg verwaltet werden.
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 der Registry-Website, auf der die wird die universelle Anzeigen-ID des ausgewählten Creatives katalogisiert.

Companion

Companion enthält Informationen zu Companion-Anzeigen, die angezeigt werden können. zusammen mit der Anzeige.
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 CreativeType-Attribut in <StaticResource> Knoten im VAST, wenn Dies ist ein Companion vom Typ „static“.
height int32

Die Höhe dieses Companion in Pixeln.
width int32

Die Breite dieses Companion in Pixeln.
resource string

Für statische und iFrame-Companions ist dies die zu ladende URL. angezeigt. Für HTML-Companions ist dies das HTML-Snippet, das als Companion angezeigt werden.
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 diese Companion-Anzeige.

InteractiveFile

InteractiveFile enthält Informationen für interaktive Creatives (z. B. SIMID). der während der Wiedergabe angezeigt werden sollte.
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 von <AdParameters> Knoten im VAST.