L'API di inserimento di annunci dinamici consente di richiedere e monitorare gli stream di video on demand (VOD) DAI. Sono supportati gli stream HLS e DASH.
Servizio: dai.google.com
Il percorso del metodo stream
è relativo a https://dai.google.com
Metodo: streaming
Metodi | |
---|---|
stream |
POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
Crea uno stream DAI HLS per l'origine di contenuto e l'ID video specificati.
Crea uno stream DAI DASH per l'origine di contenuto e l'ID video specificati. |
Richiesta HTTP
POST https://dai.google.com/ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream
POST https://dai.google.com/ondemand/v1/dash/content/{content-source}/vid/{video-id}/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 trasmessa nell'intestazione di autorizzazione HTTP con il seguente formato: Authorization: DCLKDAI key="<api-key>" |
Parametri del percorso
Parametri | |
---|---|
content-source |
string L'ID CMS dello stream. |
video-id |
string L'ID video 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
Il campo Verifications
contiene informazioni per la verifica di Open Measurement per gli stream con beaconing non lato server.
Verifications
contiene uno o più elementi Verification
che elencano le risorse
e i metadati necessari per verificare la riproduzione della creatività con il codice di misurazione di terze parti.
È supportato soltanto l'elemento JavaScriptResource
. Per ulteriori informazioni, consulta il IAB Tech Lab e la specifica VAST 4.1.
Metodo: verifica dei contenuti multimediali
Dopo aver riscontrato un identificatore dei contenuti multimediali degli annunci durante la riproduzione, effettua immediatamente una richiesta utilizzando media_verification_url
dall'endpoint stream
. media_verification_url
è un percorso assoluto.
Le richieste di verifica dei contenuti multimediali non sono necessarie per gli stream in 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 {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 degli elementi multimediali degli annunci verranno codificati nei metadati a tempo HLS utilizzando la chiave TXXX
,
riservati 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 a media_verification_url per ogni richiesta di verifica degli annunci.
ID elementi multimediali degli annunci (DASH)
Gli identificatori degli elementi multimediali degli annunci verranno inseriti nel manifest tramite l'utilizzo dell'elemento EventStream
di DASH.
Ogni EventStream
avrà un URI dell'ID schema pari a urn:google:dai:2018
.
Contengono eventi con l'attributo messageData
con un ID media annuncio che inizia con “google_”
. Tutti i contenuti dell'attributo messageData
devono essere aggiunti a media_verification_url per ogni richiesta di
verifica degli annunci.
Dati delle risposte
Trasmettere in live streaming
Il flusso viene utilizzato per eseguire il rendering di un elenco di tutte le risorse per un flusso appena creato in formato JSON .Rappresentazione JSON |
---|
{ "stream_id": string, "total_duration": number, "content_duration": number, "valid_for": string, "valid_until": string, "subtitles": [object(Subtitle)], "hls_master_playlist": string, "stream_manifest": string, "media_verification_url": string, "apple_tv": object(AppleTV), "ad_breaks": [object(AdBreak)], } |
Campi | |
---|---|
stream_id |
string Identificatore stream. |
total_duration |
number Durata dello stream in secondi. |
content_duration |
number Durata dei contenuti, senza annunci, in secondi. |
valid_for |
string Lo stream della durata è valido per il formato "00h00m00s". |
valid_until |
string Data di validità dello stream, in formato RFC 3339. |
subtitles |
[object(Subtitle)] Un elenco di sottotitoli. Omesso se vuoto. Solo HLS. |
hls_master_playlist |
string (OBSOLETO) URL della playlist principale HLS. Utilizza stream_manifest. Solo HLS. |
stream_manifest |
string Il file manifest dello stream. Corrisponde alla playlist principale in HLS e al file MPD in DASH. Questo è l'unico campo oltre a "stream_id" che è presente nella risposta quando si crea uno stream di beaconing lato server. |
media_verification_url |
string URL di verifica dei contenuti multimediali. |
apple_tv |
object(AppleTV) Informazioni facoltative specifiche per i dispositivi AppleTV. Solo HLS. |
ad_breaks |
[object(AdBreak)] Un elenco di interruzioni pubblicitarie. Omesso se vuoto. |
AppleTV
AppleTV contiene informazioni specifiche per i dispositivi Apple TV.Rappresentazione JSON |
---|
{ "interstitials_url": string, } |
Campi | |
---|---|
interstitials_url |
string URL interstitial. |
AdBreak
Interruzione pubblicitaria descrive una singola interruzione pubblicitaria nello stream. Contiene una posizione, una durata, un tipo (mid/pre/post) e un elenco di annunci.Rappresentazione JSON |
---|
{ "type": string, "start": number, "duration": number, "ads": [object(Ad)], } |
Campi | |
---|---|
type |
string I tipi di interruzione validi sono: intermedio, pre e post. |
start |
number Posizione in secondi del punto in cui inizia l'interruzione nello stream. |
duration |
number Durata dell'interruzione pubblicitaria, in secondi. |
ads |
[object(Ad)] Un elenco di annunci. Omesso se vuoto. |
Annuncio
L'annuncio descrive un annuncio nello stream. Contiene la posizione dell'annuncio nell'interruzione, la durata dell'annuncio e alcuni metadati facoltativi.Rappresentazione JSON |
---|
{ "seq": number, "start": 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, "icons": [object(Icon)], "wrappers": [object(Wrapper)], "events": [object(Event)], "verifications": [object(Verification)], "universal_ad_id": object(UniversalAdID), "companions": [object(Companion)], "interactive_file": object(InteractiveFile), } |
Campi | |
---|---|
seq |
number Posizione dell'annuncio nell'interruzione. |
start |
number Posizione in secondi nello stream in cui inizia l'annuncio. |
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. |
icons |
[object(Icon)] Un elenco di icone, omesse se vuoto. |
wrappers |
[object(Wrapper)] Un elenco di wrapper. Omesso se vuoto. |
events |
[object(Event)] Un elenco degli eventi nell'annuncio. |
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à. |
universal_ad_id |
object(UniversalAdID) ID annuncio universale facoltativo. |
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. |
Evento
L'evento contiene un tipo di evento e l'orario di presentazione di un evento.Rappresentazione JSON |
---|
{ "time": number, "type": string, } |
Campi | |
---|---|
time |
number Ora della presentazione di questo evento. |
type |
string Tipo di questo evento. |
Sottotitolo
Il sottotitolo descrive una traccia di sottotitoli collaterale per il video stream. Archivia due formati di sottotitoli: TTML e WebVTT. L'attributo TTMLPath contiene l'URL del file collaterale TTML, mentre l'attributo WebVTTPath contiene un URL al file collaterale WebVTT.Rappresentazione JSON |
---|
{ "language": string, "language_name": string, "ttml": string, "webvtt": string, } |
Campi | |
---|---|
language |
string Un codice lingua, ad esempio "en" o "de". |
language_name |
string Nome descrittivo della lingua. differenzia l'insieme specifico di sottotitoli se esistono più serie per la stessa lingua. |
ttml |
string URL facoltativo al file collaterale TTML. |
webvtt |
string URL facoltativo al file collaterale WebVTT. |
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. |