API per l'inserimento di annunci dinamici Linear

L'API di inserimento di annunci dinamici ti consente di richiedere e monitorare gli stream lineari (LIVE) DAI.

Servizio: dai.google.com

Tutti gli URI sono relativi a https://dai.google.com

Metodo: stream

Metodi
stream	POST /linear/v1/hls/event/{assetKey}/stream Crea uno stream DAI per l'ID evento specificato.

Richiesta HTTP

POST https://dai.google.com/linear/v1/hls/event/{assetKey}/stream

Intestazione della richiesta

Parametri
api‑key	string La chiave API, fornita durante la creazione di uno stream, deve essere valida per la rete del publisher. Anziché fornirla nel corpo della richiesta, la chiave API può essere passata nell'intestazione di autorizzazione HTTP con il seguente formato: Authorization: DCLKDAI key="<api-key>"

Parametri del percorso

Parametri
assetKey	string L'ID evento dello stream. Nota: la chiave asset stream è un identificatore che può essere trovato anche nell' interfaccia utente di Ad Manager.

Corpo della richiesta

Il corpo della richiesta è di tipo application/x-www-form-urlencoded e contiene i seguenti parametri:

Parametri
dai-ssb	Facoltativo	Imposta su true per creare uno stream di beaconing lato server. Il valore predefinito è false. Il monitoraggio dello stream predefinito viene avviato dal client e inviato tramite ping lato server.
Parametri di targeting DFP	Facoltativo	Parametri di targeting aggiuntivi.
Override Stream Parameters	Facoltativo	Esegui l'override dei valori predefiniti di un parametro di creazione dello stream.
Autenticazione HMAC	Facoltativo	Autenticati utilizzando un token basato su HMAC.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un nuovo Stream. Per gli stream di beaconing lato server, questo Stream contiene solo i campi stream_id e stream_manifest.

Open Measurement

L'API DAI contiene informazioni per la verifica Open Measurement nel campo Verifications. Questo campo contiene uno o più elementi Verification che elencano le risorse e i metadati necessari per eseguire il codice di misurazione di terze parti al fine di verificare la riproduzione delle creatività. È supportato solo JavaScriptResource. Per saperne di più, consulta la specifica di IAB Tech Lab e la specifica VAST 4.1.

Metodo: verifica dei media

Dopo aver rilevato un identificatore di contenuti multimediali dell'annuncio durante la riproduzione, invia immediatamente una richiesta utilizzando l'media_verification_url ottenuta dall'endpoint stream. Queste richieste non sono necessarie per gli stream di beaconing lato server, in cui il server avvia la verifica dei contenuti multimediali.

Le richieste all'endpoint media verification sono idempotenti.

Metodi
media verification	GET /{media_verification_url}/{ad_media_id} Notifica all'API un evento di verifica dei contenuti multimediali.

Nota: gli eventi ID3 avanzamento non devono essere sottoposti a ping su questo endpoint. Sono per i publisher per differenziare la riproduzione all'interno e all'esterno di un'interruzione pubblicitaria e non servono ad altri scopi di monitoraggio degli annunci. Gli editori possono identificare gli eventi di avanzamento cercando l'identificatore multimediale nel file JSON dei metadati e verificando che il campo type sia impostato su progress.

Richiesta HTTP

GET https://{media-verification-url}/{ad-media-id}

Corpo della risposta

media verification restituisce le seguenti risposte:

• HTTP/1.1 204 No Content se la verifica dei contenuti multimediali ha esito positivo e vengono inviati tutti i ping.
• HTTP/1.1 404 Not Found se la richiesta non riesce a verificare i contenuti multimediali a causa di una formattazione errata dell'URL o della scadenza.
• HTTP/1.1 404 Not Found se una precedente richiesta di verifica per questo documento d'identità è andata a buon fine.
• HTTP/1.1 409 Conflict se un'altra richiesta sta già inviando ping in questo momento.

ID elemento multimediale annuncio (HLS)

Gli identificatori dei contenuti multimediali dell'annuncio verranno codificati nei metadati temporizzati HLS utilizzando la chiave TXXX, riservata ai frame "informazioni di testo definite dall'utente". I contenuti del frame verranno decriptati e inizieranno sempre con il testo "google_".

L'intero contenuto di testo del frame deve essere aggiunto all'URL di verifica dell'annuncio prima di effettuare ogni richiesta di verifica dell'annuncio.

Metodo: metadati

L'endpoint dei metadati all'indirizzo metadata_url restituisce le informazioni utilizzate per creare un'interfaccia utente dell'annuncio. L'endpoint dei metadati non è disponibile per gli stream di beaconing lato server, in cui il server è responsabile dell'avvio della verifica dei contenuti multimediali degli annunci.

Metodi
metadata	GET /{metadata_url}/{ad-media-id} GET /{metadata_url} Recupera le informazioni sui metadati dell'annuncio.

Nota: ti consigliamo di fornire l'ID media annuncio all'endpoint. In caso contrario, utilizza polling_frequency per determinare la frequenza di connessione a questo endpoint.

Richiesta HTTP

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

GET https://{metadata_url}

Parametri di query

Parametri
delta_token	facoltativo	string Un token opaco che rappresenta lo stato di sincronizzazione attuale del client. Se fornito, il server restituisce solo i metadati modificati dalla generazione del token, insieme a un nuovo next_delta_token nella risposta. Se omesso, il server restituisce i metadati completi per l'intera registrazione DVR.

Corpo della risposta

In caso di esito positivo, la risposta restituisce un'istanza di PodMetadata.

Utilizzo dei metadati

I metadati sono suddivisi in tre sezioni distinte: tags, ads e breaks. Il punto di accesso ai dati è la sezione tags. Da qui, scorri i tag e trova la prima voce il cui nome è un prefisso per l'ID media annuncio trovato nel flusso video. Ad esempio, potresti avere un ID media annuncio simile a questo:

google_1234567890

Poi trovi un oggetto tag denominato google_12345. In questo caso, corrisponde all'ID del media dell'annuncio. Una volta trovato l'oggetto prefisso multimediale annuncio corretto, puoi cercare gli ID annuncio, gli ID interruzione pubblicitaria e il tipo di evento. Gli ID annuncio vengono poi utilizzati per indicizzare gli oggetti ads e gli ID interruzione pubblicitaria vengono utilizzati per indicizzare gli oggetti breaks.

Dati della risposta

Stream

Stream viene utilizzato per eseguire il rendering di un elenco di risorse per un flusso appena creato in formato JSON.

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

Campi
stream_id	string L'identificatore dello stream GAM.
stream_manifest	string L'URL del manifest dello stream, utilizzato per recuperare la playlist multivariante in HLS o l'MPD in DASH.
hls_master_playlist	string (OBSOLETO) URL della playlist multivariante HLS. Utilizza "stream_manifest".
media_verification_url	string L'URL di verifica dei contenuti multimediali utilizzato come endpoint di base per il monitoraggio degli eventi di riproduzione.
metadata_url	string URL dei metadati utilizzato per eseguire il polling delle informazioni periodiche sugli eventi pubblicitari in streaming imminenti.
session_update_url	string L'URL di aggiornamento della sessione utilizzato per aggiornare i parametri di targeting per questo stream. I valori originali dei parametri di targeting vengono acquisiti durante la richiesta iniziale di creazione dello stream.
polling_frequency	number La frequenza di polling, in secondi, quando si richiede metadata_url o heartbeat_url.

PodMetadata

PodMetadata contiene informazioni sui metadati di annunci, interruzioni pubblicitarie e tag ID media.

Rappresentazione JSON
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], "next_delta_token": string, "obsolete_ad_break_ids": [], }

Campi
tags	map[string, object(TagSegment)] Mappa dei segmenti di tag indicizzati in base al prefisso del tag.
ads	map[string, object(Ad)] Mappa degli annunci indicizzati per ID annuncio.
ad_breaks	map[string, object(AdBreak)] Mappa delle interruzioni pubblicitarie indicizzate per ID interruzione pubblicitaria.
next_delta_token	string Un token opaco che il client deve utilizzare nel sondaggio successivo.
obsolete_ad_break_ids	string Un elenco di ID interruzione pubblicitaria obsoleti e da rimuovere dalla cache del client.

TagSegment

TagSegment contiene un riferimento a un annuncio, alla relativa interruzione pubblicitaria e al tipo di evento. TagSegment con type="progress" non deve essere sottoposto a ping all'endpoint di verifica dei contenuti multimediali dell'annuncio.

Rappresentazione JSON
{ "ad": string, "ad_break_id": string, "type": string, }

Campi
ad	string L'ID dell'annuncio di questo tag.
ad_break_id	string L'ID dell'interruzione pubblicitaria di questo tag.
type	string Il tipo di evento di questo tag.

AdBreak

AdBreak descrive una singola interruzione pubblicitaria nello stream. Contiene una durata, un tipo (mid/pre/post) e il numero di annunci.

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

Campi
type	string I tipi di interruzione validi sono: pre, mid e post.
duration	number Durata totale dell'annuncio per questa interruzione pubblicitaria, in secondi.
expected_duration	number Durata prevista dell'interruzione pubblicitaria (in secondi), inclusi tutti gli annunci e qualsiasi slate.
ads	number Numero di annunci nell'interruzione pubblicitaria.

Annuncio

Annuncio descrive un annuncio nello stream.

Rappresentazione JSON

{ "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), }

Campi
ad_break_id	string L'ID dell'interruzione pubblicitaria di questo annuncio.
position	number Posizione di questo annuncio nell'interruzione pubblicitaria, a partire da 1.
duration	number Durata dell'annuncio, in secondi.
title	string Titolo facoltativo dell'annuncio.
description	string Descrizione facoltativa dell'annuncio.
advertiser	string Identificatore inserzionista facoltativo.
ad_system	string Sistema pubblicitario facoltativo.
ad_id	string ID annuncio facoltativo.
creative_id	string ID creatività facoltativo.
creative_ad_id	string ID annuncio creatività facoltativo.
deal_id	string ID offerta facoltativo.
clickthrough_url	string (Facoltativo) URL di clickthrough.
click_tracking_urls	string (Facoltativo) URL di monitoraggio dei clic.
verifications	[object(Verification)] Voci di verifica Open Measurement facoltative che elencano le risorse e i metadati necessari per eseguire il codice di misurazione di terze parti per verificare la riproduzione delle creatività.
slate	boolean Valore booleano facoltativo che indica che la voce corrente è una proposta.
icons	[object(Icon)] Un elenco di icone, omesso se vuoto.
wrappers	[object(Wrapper)] Un elenco di wrapper, omesso se vuoto.
universal_ad_id	object(UniversalAdID) ID annuncio universale facoltativo.
extensions	string Elenco facoltativo di tutti i nodi <Extension> in VAST.
companions	[object(Companion)] Asset companion facoltativi che possono essere visualizzati insieme a questo annuncio.
interactive_file	object(InteractiveFile) Creatività interattiva facoltativa (SIMID) da visualizzare durante la riproduzione dell'annuncio.

Icona

L'icona contiene informazioni su un'icona VAST.

Rappresentazione JSON
{ "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, }

Campi
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 contiene informazioni su un clickthrough di un'icona.

Rappresentazione JSON
{ "url": string, }

Campi
url	string

FallbackImage

FallbackImage contiene informazioni su un'immagine di riserva VAST.

Rappresentazione JSON
{ "creative_type": string, "height": int32, "width": int32, "resource": string, "alt_text": string, }

Campi
creative_type	string
height	int32
width	int32
resource	string
alt_text	string

Wrapper

Il wrapper contiene informazioni su un annuncio wrapper. Non include un ID deal se non esiste.

Rappresentazione JSON
{ "system": string, "ad_id": string, "creative_id": string, "creative_ad_id": string, "deal_id": string, }

Campi
system	string Identificatore del sistema pubblicitario.
ad_id	string ID annuncio utilizzato per l'annuncio wrapper.
creative_id	string ID creatività utilizzato per l'annuncio wrapper.
creative_ad_id	string ID annuncio della creatività utilizzato per l'annuncio wrapper.
deal_id	string ID deal facoltativo per l'annuncio wrapper.

Verifica

La verifica contiene informazioni per Open Measurement, che facilita la misurazione della visibilità e della verifica di terze parti. Al momento sono supportate solo le risorse JavaScript. Visita la pagina https://iabtechlab.com/standards/open-measurement-sdk/

Rappresentazione JSON
{ "vendor": string, "java_script_resources": [object(JavaScriptResource)], "tracking_events": [object(TrackingEvent)], "parameters": string, }

Campi
vendor	string Il fornitore di soluzioni di verifica.
java_script_resources	[object(JavaScriptResource)] Elenco delle risorse JavaScript per la verifica.
tracking_events	[object(TrackingEvent)] Elenco degli eventi di monitoraggio per la verifica.
parameters	string Una stringa opaca passata al codice di verifica di bootstrap.

JavaScriptResource

JavaScriptResource contiene informazioni per la verifica tramite JavaScript.

Rappresentazione JSON
{ "script_url": string, "api_framework": string, "browser_optional": boolean, }

Campi
script_url	string URI del payload JavaScript.
api_framework	string APIFramework è il nome del framework video che esercita il codice di verifica.
browser_optional	boolean Indica se questo script può essere eseguito al di fuori di un browser.

TrackingEvent

TrackingEvent contiene URL che devono essere pingati dal client in determinate situazioni.

Rappresentazione JSON
{ "event": string, "uri": string, }

Campi
event	string Il tipo di evento di monitoraggio.
uri	string L'evento di monitoraggio da pingare.

UniversalAdID

UniversalAdID viene utilizzato per fornire un identificatore univoco della creatività mantenuto in tutti i sistemi pubblicitari.

Rappresentazione JSON
{ "id_value": string, "id_registry": string, }

Campi
id_value	string L'ID annuncio universale della creatività selezionata per l'annuncio.
id_registry	string Una stringa utilizzata per identificare l'URL del sito web del registro in cui è catalogato l'ID annuncio universale della creatività selezionata.

Complementare

Companion contiene informazioni sugli annunci companion che potrebbero essere visualizzati insieme all'annuncio.

Rappresentazione JSON
{ "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)], }

Campi
click_data	object(ClickData) I dati sui clic per questo companion.
creative_type	string L'attributo CreativeType nel nodo <StaticResource> del tag VAST se si tratta di una companion di tipo statico.
height	int32 L'altezza in pixel di questo annuncio companion.
width	int32 La larghezza in pixel di questo annuncio companion.
resource	string Per i companion statici e iframe, questo sarà l'URL da caricare e visualizzare. Per i companion HTML, questo sarà lo snippet HTML da mostrare come companion.
type	string Tipo di questa creatività companion. Può essere statico, iframe o HTML.
ad_slot_id	string L'ID slot per questo annuncio companion.
api_framework	string Il framework API per questo complemento.
tracking_events	[object(TrackingEvent)] Elenco degli eventi di monitoraggio per questo annuncio companion.

InteractiveFile

InteractiveFile contiene informazioni per la creatività interattiva (ad es. SIMID) che devono essere visualizzate durante la riproduzione dell'annuncio.

Rappresentazione JSON
{ "resource": string, "type": string, "variable_duration": boolean, "ad_parameters": string, }

Campi
resource	string L'URL della creatività interattiva.
type	string Il tipo MIME del file fornito come risorsa.
variable_duration	boolean Indica se è possibile richiedere l'estensione della durata di questa creatività.
ad_parameters	string Il valore del nodo <AdParameters> in VAST.