API VOD per l'inserimento di annunci dinamici

L'API di inserimento di annunci dinamici ti consente di richiedere e monitorare gli streaming video on demand (VOD) con DAI. Gli stream HLS e DASH sono supportati.

Servizio: dai.google.com

Il percorso del metodo stream è relativo a https://dai.google.com

Metodo: stream

Metodi
stream	POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream Crea uno stream DAI HLS per l'origine di contenuti e l'ID video specificati. POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream Crea uno stream DAI DASH per l'origine di contenuti 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 del publisher. Anziché fornirla nel corpo della richiesta, la chiave API può essere passata nell'intestazione HTTP Authorization 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	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 sottoposto a ping lato server.
Parametri di targeting DFP	Facoltativo	Parametri di targeting aggiuntivi.
Eseguire l'override dei parametri per la riproduzione in streaming	Facoltativo	Sostituisci i valori predefiniti di un parametro di creazione dello stream.
Autenticazione HMAC	Facoltativo	Effettua 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 di beaconing lato server, questo Stream contiene solo i campi stream_id e stream_manifest.

Open Measurement

Il campo Verifications contiene informazioni per la verifica di Open Measurement per gli stream non beacon lato server. Verifications contiene uno o più elementi Verification che elencano le risorse e i metadati necessari per verificare la riproduzione delle creatività con il codice di misurazione di terze parti. È supportato solo JavaScriptResource. Per ulteriori informazioni, consulta IAB Tech Lab e la specifica VAST 4.1.

Metodo: verifica dei contenuti multimediali

Quando durante la riproduzione viene rilevato un identificatore dei contenuti multimediali dell'annuncio, invia 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 con beacon lato server, in cui è il server ad avviare 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 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 va a buon fine e tutti i ping vengono inviati.
• HTTP/1.1 404 Not Found se la richiesta non riesce a verificare i contenuti multimediali a causa di una formattazione o di una scadenza dell'URL errata.
• HTTP/1.1 404 Not Found se una richiesta di verifica precedente per questo documento è andata a buon fine.
• HTTP/1.1 409 Conflict se in questo momento è già in corso l'invio di ping da un'altra richiesta.

ID elementi multimediali dell'annuncio (HLS)

Gli identificatori dei contenuti multimediali degli annunci verranno codificati nei metadati a tempo HLS utilizzando la chiave TXXX, riservata per i frame "Informazioni di testo definite dall'utente". I contenuti dell'inquadratura non saranno criptati e inizieranno sempre con il testo "google_".

L'intero contenuto di testo del frame deve essere aggiunto a media_verification_url per ogni richiesta di verifica dell'annuncio.

ID elementi multimediali dell'annuncio (DASH)

Gli identificatori dei contenuti multimediali degli annunci verranno inseriti nel manifest tramite l'elemento EventStream di DASH.

Ogni EventStream avrà un URI ID schema di urn:google:dai:2018. Conteranno gli eventi con l'attributo messageData contenente un ID media dell'annuncio che inizia con “google_”. L'intero contenuto dell'attributo messageData deve essere aggiunto a media_verification_url per ogni richiesta di verifica dell'annuncio.

Dati di risposta

Stream

Stream viene utilizzato per visualizzare un elenco di tutte le risorse per un stream 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, in 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 all'MPD in DASH. Questo è l'unico campo oltre a "stream_id" 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 Apple TV. 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 degli annunci in-page.

AdBreak

AdBreak 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 mid, pre e post.
start	number Posizione in cui inizia l'interruzione nello stream, in secondi.
duration	number Durata dell'interruzione pubblicitaria, in secondi.
ads	[object(Ad)] Un elenco di annunci. Omesso se vuoto.

Annuncio

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), "skip_metadata": object(SkipMetadata), "extensions": [], }

Campi
seq	number Posizione dell'annuncio nell'interruzione.
start	number Posizione in cui inizia l'annuncio nello stream, in secondi.
duration	number Durata dell'annuncio in secondi.
title	string Titolo facoltativo dell'annuncio.
description	string Descrizione facoltativa dell'annuncio.
advertiser	string Identificatore dell'inserzionista facoltativo.
ad_system	string Sistema di annunci facoltativo.
ad_id	string ID annuncio facoltativo.
creative_id	string ID creatività facoltativo.
creative_ad_id	string ID annuncio della creatività facoltativo.
deal_id	string (Facoltativo) ID deal.
clickthrough_url	string URL di clickthrough facoltativo.
icons	[object(Icon)] Un elenco di icone, omesso se vuoto.
wrappers	[object(Wrapper)] Un elenco di wrapper. Omesso se vuoto.
events	[object(Event)] Un elenco degli eventi nell'annuncio.
verifications	[object(Verification)] Voce facoltativa di verifica Open Measurement che elenca le risorse e i metadati necessari per eseguire il codice di misurazione di terze parti per 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) da visualizzare durante la riproduzione dell'annuncio.
skip_metadata	object(SkipMetadata) Metadati facoltativi per gli annunci ignorabili. Se impostato, indica che l'annuncio è ignorabile e include istruzioni su come gestire l'interfaccia utente di salto e l'evento di monitoraggio.
extensions	string Elenco facoltativo di tutti i nodi <Extension> in VAST.

Evento

L'evento contiene un tipo di evento e un'ora di presentazione di un evento.

Rappresentazione JSON
{ "time": number, "type": string, }

Campi
time	number L'ora di presentazione di questo evento.
type	string Il tipo di questo evento.

Sottotitolo

Subtitle descrive una traccia di sottotitoli codificati aggiuntiva per lo stream video. Memorizza due formati di sottotitoli: TTML e WebVTT. L'attributo TTMLPath contiene l'URL al file sidecar TTML e l'attributo WebVTTPath contiene un URL al file sidecar 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. Consente di distinguere l'insieme specifico di sottotitoli se esistono più insiemi per la stessa lingua
ttml	string URL facoltativo del file TTML aggiuntivo.
webvtt	string URL facoltativo del file collaterale WebVTT.

SkipMetadata

SkipMetadata fornisce le informazioni necessarie ai clienti per gestire gli eventi di salto per gli annunci ignorabili.

Rappresentazione JSON
{ "offset": number, "tracking_url": string, }

Campi
offset	number L'offset indica il tempo in secondi che deve trascorrere dall'inizio dell'annuncio prima che il player possa visualizzare il pulsante Salta. Omesso se non specificato in VAST.
tracking_url	string TrackingURL contiene un URL per cui deve essere inviato un ping nell'evento di salto.

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 clic sull'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 offerta 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 in wrapper.
creative_id	string ID creatività utilizzato per l'annuncio con wrapper.
creative_ad_id	string ID annuncio della creatività utilizzato per l'annuncio con wrapper.
deal_id	string (Facoltativo) ID deal per l'annuncio wrapper.

Verifica

La verifica contiene informazioni per Open Measurement, che semplifica 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 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 esegue il codice di verifica.
browser_optional	boolean Indica se questo script può essere eseguito al di fuori di un browser.

TrackingEvent

TrackingEvent contiene gli URL a cui deve essere inviato un ping 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 a cui inviare il ping.

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 registry in cui è catalogato l'ID annuncio universale della creatività selezionata.

Companion

La sezione 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, "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> in VAST se si tratta di un companion di tipo statico.
height	int32 L'altezza in pixel di questo componente aggiuntivo.
width	int32 La larghezza in pixel di questo compagno.
resource	string Per i companion statici e iframe, questo sarà l'URL da caricare e mostrare. Per i companion HTML, si tratta dello snippet HTML che deve essere visualizzato come companion.
type	string Tipo di creatività companion. Può essere statico, iframe o HTML.
ad_slot_id	string L'ID dello slot per questo componente aggiuntivo.
api_framework	string Il framework API per questo companion.
tracking_events	[object(TrackingEvent)] Elenco di eventi di monitoraggio per questo componente aggiuntivo.

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 per questa creatività è possibile richiedere l'estensione della durata.
ad_parameters	string Il valore del nodo <AdParameters> in VAST.