API VOD per l'inserimento di annunci dinamici

L'API di inserimento di annunci dinamici ti consente di richiedere e monitorare gli stream 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: stream

Metodi
stream POST /ondemand/v1/hls/content/{content-source}/vid/{video-id}/stream

Crea uno stream HLS DAI per l'origine di contenuto e l'ID video specificati.

POST /ondemand/v1/dash/content/{content-source}/vid/{video-id}/stream

Crea uno stream DASH DAI 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 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
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 inviato tramite ping sul lato server.
Parametri di targeting DFP Facoltativo Parametri di targeting aggiuntivi.
Eseguire l'override dei parametri per la riproduzione in streaming 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

Il campo Verifications contiene informazioni per la verifica di Open Measurement per gli stream non server-side-beaconing. 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 saperne di più, consulta IAB Tech Lab e la specifica VAST 4.1.

Metodo: verifica dei contenuti multimediali

Dopo aver rilevato un identificatore di contenuti pubblicitari durante la riproduzione, 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 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.

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 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 elementi multimediali 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 non saranno criptati e inizieranno sempre con il testo "google_".

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

ID elementi multimediali dell'annuncio (DASH)

Gli identificatori dei contenuti multimediali dell'annuncio verranno inseriti nel manifest tramite l'utilizzo dell'elemento EventStream di DASH.

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

Dati della risposta

Stream

Stream viene utilizzato per eseguire il rendering di un elenco di tutte le risorse per un nuovo stream 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 dello stream.
total_duration number

Durata dello stream in secondi.
content_duration number

Durata dei contenuti, senza annunci, in secondi.
valid_for string

Durata per cui il flusso è valido, nel formato "00h00m00s".
valid_until string

Data fino alla quale lo stream è valido, nel 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 manifest dello stream. Corrisponde alla playlist principale in HLS e al file MPD in DASH. Questo è l'unico campo, oltre a "stream_id", presente nella risposta quando viene creato 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 degli interstitial.

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 nel flusso in cui inizia la pausa, in secondi.
duration number

Durata dell'interruzione pubblicitaria, in secondi.
ads [object(Ad)]

Un elenco di annunci. Omesso se vuoto.
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 nello stream in cui inizia l'annuncio, in secondi.
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.
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)]

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à.
universal_ad_id object(UniversalAdID)

ID annuncio universale facoltativo.
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.
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 per l'opzione Salta 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 orario di presentazione.
Rappresentazione JSON
{
  "time": number,
  "type": string,
}
Campi
time number

L'ora della presentazione di questo evento.
type string

Il tipo di evento.

Sottotitolo

Il sottotitolo descrive una traccia dei sottotitoli sidecar per lo stream video. Memorizza due formati di sottotitoli: TTML e WebVTT. L'attributo TTMLPath contiene l'URL del file TTML sidecar, mentre l'attributo WebVTTPath contiene un URL del file WebVTT sidecar.
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. che distingue il set specifico di sottotitoli se ne esistono più di uno per la stessa lingua
ttml string

URL facoltativo del file collaterale TTML.
webvtt string

URL facoltativo del file collaterale WebVTT.

SkipMetadata

SkipMetadata fornisce le informazioni necessarie ai client per gestire gli eventi di salto per gli annunci ignorabili.
Rappresentazione JSON
{
  "offset": number,
  "tracking_url": string,
}
Campi
offset number

L'offset indica la quantità di tempo in secondi che il player deve attendere prima di eseguire il rendering del pulsante Salta. Omesso se non fornito in VAST.
tracking_url string

TrackingURL contiene un URL per cui deve essere inviato un ping in caso di 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 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 un annuncio 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 questa creatività può richiedere l'estensione della durata.
ad_parameters string

Il valore del nodo <AdParameters> in VAST.