L'API di inserimento di annunci dinamici consente di richiedere e monitorare stream lineari (LIVE) con DAI.
Servizio: dai.google.com
Tutti gli URI di seguito sono relativi a https://dai.google.com
Metodo: streaming
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. Invece di 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. |
Override dei parametri 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
Stream
. Per gli stream con beaconing lato server, questo elemento Stream
contiene solo i campi stream_id
e stream_manifest
.
Apri 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 delle creatività. È supportato solo
JavaScriptResource
. Per ulteriori informazioni, consulta
IAB Tech Lab e la
specifica VAST 4.1.
Metodo: verifica dei contenuti multimediali
Dopo aver incontrato un identificatore dei media pubblicitari durante la riproduzione, effettua immediatamente una richiesta utilizzando il valore media_verification_url ottenuto dall'endpoint stream sopra indicato. Queste richieste non sono necessarie per i flussi 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}
Comunica all'API un evento di verifica dei contenuti multimediali. |
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 o scadenza dell'URL non corretta.HTTP/1.1 404 Not Found
se una precedente richiesta di verifica per questo documento di identità è andata a buon fine.HTTP/1.1 409 Conflict
se un'altra richiesta sta già inviando ping in questo momento.
ID elementi multimediali degli annunci (HLS)
Gli identificatori dei contenuti multimediali degli annunci 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 del 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 in metadata_url
restituisce le informazioni utilizzate per creare un'interfaccia utente
pubblicitaria. L'endpoint dei metadati non è disponibile per gli stream con beaconing lato server, in cui il server è responsabile dell'avvio della verifica degli annunci multimediali.
Metodi | |
---|---|
metadata |
GET /{metadata_url}/{ad-media-id} GET /{metadata_url}
Recupera le informazioni sui metadati degli annunci. |
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 hanno tre sezioni discrete: tags
, ads
e annuncio breaks
. Il punto di ingresso nei dati è la sezione tags
. Quindi, esegui l'iterazione dei tag
e individua la prima voce il cui nome corrisponde a un prefisso per l'
ID media dell'annuncio trovato nel video stream. Ad esempio, potresti avere un ID elemento multimediale dell'annuncio simile al seguente:
google_1234567890
Troverai quindi un oggetto tag denominato google_12345
. In questo caso, corrisponde
all'ID elemento multimediale dell'annuncio. Una volta trovato l'oggetto prefisso dei contenuti multimediali dell'annuncio corretto, 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
, mentre gli ID delle interruzioni pubblicitarie vengono utilizzati per indicizzare gli oggetti breaks
.
Dati delle risposte
Trasmettere in live streaming
Il flusso viene utilizzato per visualizzare un elenco di risorse in formato JSON per un flusso appena creato.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 Identificatore stream. |
stream_manifest |
string Il file manifest dello stream, corrispondente alla playlist principale in HLS o all'MPD in DASH. Questo è l'unico campo oltre a "stream_id" che è presente nella risposta quando si crea uno stream di beaconing lato server. |
hls_master_playlist |
string (OBSOLETO) URL della playlist principale HLS. Usa invece "stream_manifest". |
media_verification_url |
string URL di verifica dei contenuti multimediali. |
metadata_url |
string URL dei metadati dei contenuti multimediali dell'annuncio. |
session_update_url |
string URL di aggiornamento della sessione. |
polling_frequency |
number Frequenza di polling consigliata per gli URL dei metadati, in secondi. |
PodMetadata
PodMetadata contiene informazioni sui metadati relative ad annunci, interruzioni pubblicitarie e tag ID multimediali.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 di segmenti di tag indicizzati per prefisso 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 sua interruzione pubblicitaria e al tipo di evento. Non è possibile eseguire il ping di TagSegment con type="progress" sull'endpoint di verifica dei media pubblicitari.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
Interruzione pubblicitaria 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, intermedio 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
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 questa 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 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 facoltative di verifica di Open Measurement che elencano le risorse e i metadati richiesti per eseguire il codice di misurazione di terze parti al fine di verificare la riproduzione delle creatività. |
slate |
boolean Bool facoltativo che indica che la voce corrente è 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 <Extension> nel VAST. |
companions |
[object(Companion)] Companion facoltativi che possono essere visualizzati insieme a questo 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
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 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
Verification contiene informazioni per Open Measurement, che facilita la misurazione della visibilità e della verifica di terze parti. Attualmente sono supportate solo le risorse JavaScript. Consulta 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 di 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 al payload JavaScript. |
api_framework |
string APIFramework è il nome del framework video che utilizza il codice di verifica. |
browser_optional |
boolean Indica se lo script può essere eseguito al di fuori di un browser. |
TrackingEvent
TrackingEvent contiene URL a cui il client deve inviare un ping in determinate situazioni.Rappresentazione JSON |
---|
{ "event": string, "uri": string, } |
Campi | |
---|---|
event |
string Il tipo di evento di monitoraggio, attualmente l'unica opzione è "verificationNotExecuted", come specificato nella specifica VAST 4.1. |
uri |
string L'evento di monitoraggio di cui inviare un ping. |
UniversalAdID
UniversalAdID viene utilizzato per fornire un identificatore di creatività univoco da mantenere 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 registry in cui è catalogato l'ID annuncio universale della creatività selezionata. |
Companion
Companion contiene informazioni per gli 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, } |
Campi | |
---|---|
click_data |
object(ClickData) I dati sui clic per questo companion. |
creative_type |
string L'attributo CreativeType sul nodo <StaticResource> nel VAST se si tratta di un companion di tipo statico. |
height |
int32 L'altezza in pixel dell'annuncio companion. |
width |
int32 La larghezza in pixel dell'annuncio companion. |
resource |
string Per i companion statici e iframe, questo sarà l'URL da caricare e visualizzare. Per le creatività companion HTML, sarà lo snippet HTML che deve essere mostrato come companion. |
type |
string Tipo di companion. Può essere un formato statico, iframe o HTML. |
InteractiveFile
InteractiveFile contiene informazioni per la creatività interattiva (ad esempio SIMID) da visualizzare 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> nell'API VAST. |