L'API di inserimento di annunci dinamici consente di richiedere e monitorare gli stream lineari (DAL VIVO) DAI.
Servizio: dai.google.com
Tutti gli URI di seguito sono relativi a https://dai.google.com
Metodo: flusso
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 dell'editore. 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. |
Corpo della richiesta
Il corpo della richiesta è di tipo application/x-www-form-urlencoded
e contiene i seguenti parametri:
Parametri | ||
---|---|---|
dai-ssb |
Facoltativo | Impostalo su |
Parametri di targeting di DFP | Facoltativo | Parametri di targeting aggiuntivi. |
Sostituire i parametri dello stream | Facoltativo | Esegui l'override dei valori predefiniti di un parametro di creazione dello stream. |
Autenticazione HMAC | Facoltativo | Esegui l'autenticazione utilizzando un token basato su HMAC. |
Corpo della risposta
In caso di esito positivo, il corpo della risposta contiene un nuovo elemento Stream
. Per gli stream di beaconing lato server, l'elemento Stream
contiene solo i campi stream_id
e stream_manifest
.
Open Measurement
L'API DAI contiene informazioni per la verifica di 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 della creatività. È supportato solo JavaScriptResource
. Per ulteriori informazioni, consulta il Tech Lab di IAB e la specifica VAST 4.1.
Metodo: verifica dei media
Dopo aver trovato un identificatore di contenuti multimediali dell'annuncio durante la riproduzione, effettua immediatamente una richiesta utilizzando media_verification_url ottenuto dall'endpoint stream riportato sopra. Queste richieste non sono necessarie per i flussi di beaconing lato server, dove 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}
Invia una notifica all'API di un evento di verifica dei media. |
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 può verificare i contenuti multimediali a causa di una formattazione dell'URL o una scadenza non corrette.HTTP/1.1 404 Not Found
se una precedente richiesta di verifica per questo ID ha esito positivo.HTTP/1.1 409 Conflict
se un'altra richiesta sta già inviando ping in questo momento.
ID elementi multimediali annuncio (HLS)
Gli identificatori degli elementi multimediali dell'annuncio verranno codificati nei metadati a tempo HLS utilizzando la chiave TXXX
, riservata ai frame "informazioni di testo definite dall'utente". I
contenuti del frame non saranno criptati e inizieranno sempre con il testo
"google_"
.
L'intero contenuto testuale del frame deve essere aggiunto all'URL di verifica dell'annuncio prima di effettuare ogni richiesta di verifica dell'annuncio.
Metodo: metadati
L'endpoint di metadati in 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 degli elementi multimediali degli annunci.
Metodi | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
Recupera le informazioni sui metadati dell'annuncio. |
Richiesta HTTP
GET https://{metadata_url}/{ad-media-id}
GET https://{metadata_url}
Corpo della risposta
In caso di esito positivo, la risposta restituisce un'istanza di PodMetadata
.
Utilizzo dei metadati
I metadati includono tre sezioni distinte: tags
, ads
e breaks
annuncio. Il punto di accesso
ai dati è la sezione tags
. Da qui, ripeti i tag e trova la prima voce il cui nome è un prefisso per l'ID elemento multimediale annuncio trovato nello stream video. Ad esempio, potresti avere un ID elemento multimediale annuncio simile al seguente:
google_1234567890
Quindi, trovi un oggetto tag denominato google_12345
. In questo caso, corrisponde all'ID
dei contenuti multimediali dell'annuncio. Una volta trovato l'oggetto corretto per i prefissi multimediali degli annunci, puoi cercare gli ID annuncio, gli ID delle interruzioni pubblicitarie e il tipo di evento. Gli ID annuncio vengono quindi utilizzati per indicizzare
gli oggetti ads
e gli ID delle interruzioni pubblicitarie vengono utilizzati per indicizzare gli oggetti breaks
.
Dati di risposta
Stream
Il flusso 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 file 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. Al suo posto, usa "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 chiedere informazioni periodiche sui prossimi eventi relativi agli annunci in streaming. |
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 richiedono metadata_url from o heartbeat_url. |
PodMetadata
PodMetadata contiene informazioni sui metadati su annunci, interruzioni pubblicitarie e tag ID multimediale.Rappresentazione JSON |
---|
{ "tags": map[string, object(TagSegment)], "ads": map[string, object(Ad)], "ad_breaks": map[string, object(AdBreak)], } |
Campi | |
---|---|
tags |
map[string, object(TagSegment)] Mappa dei segmenti di tag indicizzati dal 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. |
TagSegment
TagSegment contiene un riferimento a un annuncio, alla relativa interruzione pubblicitaria e al tipo di evento. TagSegment con type="progress" non deve essere inviato all'endpoint di verifica degli elementi multimediali degli annunci.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 Tipo di evento di questo tag. |
AdBreak
L'interruzione pubblicitaria descrive una singola interruzione pubblicitaria nello stream. Contiene la durata, un tipo (metà/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: prima, media 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 slate. |
ads |
number Numero di annunci nell'interruzione pubblicitaria. |
Annuncio
L'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 dell'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 facoltativo dell'inserzionista. |
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 deal facoltativo. |
clickthrough_url |
string URL di clickthrough facoltativo. |
click_tracking_urls |
string URL di monitoraggio dei clic facoltativi. |
verifications |
[object(Verification)] Voci di verifica facoltative di Open Measurement che elencano le risorse e i metadati necessari per eseguire il codice di misurazione di terze parti al fine di verificare la riproduzione della creatività. |
slate |
boolean Bool facoltativo che indica che la voce corrente è in slate. |
icons |
[object(Icon)] Un elenco di icone, omesse 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 <Estensione> nel VAST. |
companions |
[object(Companion)] Annunci companion facoltativi che possono essere visualizzati insieme all'annuncio. |
interactive_file |
object(InteractiveFile) Creatività interattiva facoltativa (SIMID) che deve essere visualizzata 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 sul clickthrough di un'icona.Rappresentazione JSON |
---|
{ "url": string, } |
Campi | |
---|---|
url |
string |
FallbackImage
L'immagine di riserva 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 di annunci. |
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 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 di verifica e visibilità di terze parti. Al momento, sono supportate solo le risorse JavaScript. Vedi 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 servizi di verifica. |
java_script_resources |
[object(JavaScriptResource)] Elenco di 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 del 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 per il payload JavaScript. |
api_framework |
string APIFramework è il nome del framework video che utilizza il codice di verifica. |
browser_optional |
boolean Indica se questo script può essere eseguito al di fuori di un browser. |
TrackingEvent
Il valore TrackingEvent contiene URL che devono essere inviati 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 di cui inviare il ping. |
UniversalAdID
UniversalAdID viene utilizzato per fornire un identificatore creatività univoco gestito nei 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 registry in cui è catalogato l'ID annuncio universale della creatività selezionata. |
Companion
Questa creatività contiene informazioni relative ad annunci companion che possono 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 questa creatività companion. |
creative_type |
string L'attributo CreativeType sul nodo <StaticResource> in VAST se si tratta di un companion di tipo statico. |
height |
int32 L'altezza in pixel di questa creatività companion. |
width |
int32 La larghezza in pixel di questa creatività companion. |
resource |
string Per le creatività companion statiche e iframe, questo sarà l'URL da caricare e visualizzare. Per le creatività companion HTML, 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 questa creatività companion. |
api_framework |
string Il framework API per questa app companion. |
tracking_events |
[object(TrackingEvent)] Elenco di eventi di monitoraggio per questa creatività 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 la creatività può richiedere l'estensione della durata. |
ad_parameters |
string Il valore del nodo <AdParameters> nel modello VAST. |