API live per la pubblicazione di pod di inserimento di annunci dinamici

L'API di inserimento di annunci dinamici consente di richiedere e monitorare i live streaming con inserimento di annunci dinamici.

Servizio: dai.google.com

Tutti gli URI sono relativi a https://dai.google.com.

Metodo: flusso

Metodi
stream POST /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Registra un pod DAI con DAI che pubblica una sessione in live streaming.

Richiesta HTTP

POST https://dai.google.com/ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset_key}/stream

Parametri del percorso

Parametri
network_code string

Il codice di rete Google Ad Manager del publisher.

custom_asset_key string

L'identificatore personalizzato associato all'evento in Google Ad Manager.

Corpo della richiesta

Il corpo della richiesta è di tipo application/x-www-form-urlencoded e contiene il parametro seguenti parametri:

Parametri
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 oggetto Stream.

Open Measurement

L'API DAI contiene informazioni per la verifica Open Measurement nel Verifications. Questo campo contiene uno o più Verification elemento che elenca le risorse e i metadati richiesti per l'esecuzione codice di misurazione di terze parti al fine di verificare la riproduzione della creatività. Solo JavaScriptResource è supportato. Per ulteriori informazioni, consulta IAB Tech Lab e il Specifiche VAST 4.1.

Metodo: segmento pod

Metodi
pod segment GET /linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Crea uno stream DAI per l'ID evento specificato.

Richiesta HTTP

GET https://dai.google.com//linear/pods/v1/seg/network/{network_code}/custom_asset/{custom_asset_key}/pod/{pod_id}/profile/{profile_name}/{segment_number}.{segment_format}

Parametri del percorso

Parametri
network_code string

Il codice di rete Google Ad Manager del publisher.

custom_asset_key string

L'identificatore personalizzato associato all'evento in Google Ad Manager.

pod_id integer

L'identificatore numerico dell'interruzione pubblicitaria corrente. Gli ID pod di annunci sono assegnati in modo incrementale a ogni evento, a partire da 1.
profile_name string

La nome delle richieste Profilo di codifica DAI di Google Ad Manager. Il profilo di codifica deve essere uno dei profili di codifica configurati per l'evento selezionato.

segment_number integer

L'indice del segmento richiesto all'interno del pod di annunci corrente, a partire da a zero.
segment_format string

L'estensione del file associata al formato del segmento richiesto. Le estensioni accettate sono: ts, mp4, vtt, aac, ac3 oppure eac3,

Parametri di query

Parametri
stream_id obbligatorio string

L'ID stream per la sessione dell'utente corrente. Questo valore viene restituito da una richiesta all'endpoint stream riuscita.
sd required1 integer

Durata del segmento richiesto, in millisecondi.
so facoltativo

L'offset del segmento richiesto all'interno del pod di annunci, in millisecondi. Se ometti il parametro so, questo verrà calcolato moltiplicando la durata del segmento per il numero del segmento.
pd obbligatoria2 integer

La durata del pod di annunci in millisecondi.
auth-token obbligatorio string

Un token firmato con codifica URL Token HMAC per il pod di annunci corrente.
last facoltativo boolean

Indica l'ultimo segmento nell'interruzione pubblicitaria. Ometti questo parametro per tutti altri segmenti.
scte35 facoltativo string

Segnale SCTE-35 con codifica Base64 per questa interruzione pubblicitaria.
cust_params facoltativo string

Un insieme di coppie chiave-valore, utilizzate per il targeting di una campagna Ad Manager. Questi devono essere rappresentate come una stringa di query con codifica nell'URL.

Esempio:
Parametri
  • section = sports
  • page = golf,tennis
Request URL ...&cust_params=section%3Dsports%26page%3Dgolf%2Ctennis...

Note a piè di pagina

  1. sd non è obbligatorio per i segmenti di inizializzazione. ↩
  2. pd non è obbligatorio per gli eventi con annuncio senza durata. siano attivate. ↩

Corpo della risposta

In caso di esito positivo, il corpo della risposta sarà un segmento dello stream riproducibile che corrisponde alla e i parametri specificati nella richiesta.

Metodo: modello periodo pod DASH

Metodi
pods GET /linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Consente di richiedere un modello di periodo DASH da Google Ad Manager. Questo modello contiene macro che devi completare con i parametri di streaming. Una volta queste macro vengono compilate, il modello diventa il periodo di interruzione pubblicitaria e possono essere unite al manifest DASH.

Richiesta HTTP

GET https://dai.google.com/linear/pods/v1/dash/network/{network_code}/custom_asset/{custom_asset_key}/pods.json

Parametri del percorso

Parametri
network_code string

Il codice di rete Google Ad Manager del publisher.

custom_asset_key string

L'identificatore personalizzato associato all'evento in Google Ad Manager.

Parametri di query

Parametri
stream_id obbligatorio string

L'ID stream per la sessione dell'utente corrente. Questo valore viene restituito da una richiesta all'endpoint stream riuscita.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un nuovo PodTemplateResponse.

Metodo: verifica dei media

Dopo aver trovato un identificatore multimediale dell'annuncio durante la riproduzione, crea immediatamente una la richiesta utilizzando il valore media_verification_url ottenuto dallo stream dell'endpoint, qui sopra. Queste richieste non sono necessarie per il 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}

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 tutti i ping vengono inviate.
  • HTTP/1.1 404 Not Found se la richiesta non può verificare i contenuti multimediali a causa di a causa della formattazione o della scadenza dell'URL.
  • HTTP/1.1 404 Not Found se una richiesta di verifica precedente per questo ID riuscito.
  • HTTP/1.1 409 Conflict se un'altra richiesta sta già inviando ping a questo nel tempo.

ID elementi multimediali dell'annuncio

Gli identificatori multimediali degli annunci verranno codificati in una traccia di metadati separata, a tempo metadati per il flusso di trasporto HLS o emsg per i file mp4. Identificatori degli elementi multimediali degli annunci inizierà sempre con la stringa google_.

L'intero contenuto testuale della voce di metadati deve essere aggiunto all'annuncio URL di verifica 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 annuncio nell'interfaccia utente. L'endpoint dei metadati non è disponibile per i flussi di beaconing lato server. in cui il server è responsabile di avviare la 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

Analisi dei metadati

I metadati includono tre sezioni distinte: tags, ads e breaks annuncio. Voce nei dati è la sezione tags. Da qui, ripeti i tag e trova la prima voce il cui nome è un prefisso per ID elemento multimediale annuncio trovato nello stream video. Ad esempio, potrebbe avere un ID elemento multimediale dell'annuncio simile a:

google_1234567890

Quindi, trovi un oggetto tag denominato google_12345. In questo caso, corrisponde ID elemento multimediale annuncio. Una volta trovato l'oggetto corretto per il prefisso degli elementi multimediali dell'annuncio, puoi cercare ID annunci, ID interruzioni pubblicitarie e tipo di evento. Gli ID annuncio vengono quindi utilizzati per indicizzare Per indicizzare gli oggetti breaks vengono utilizzati ads oggetti e ID di interruzioni pubblicitarie.

Dati di risposta

Stream

Lo stream viene utilizzato per eseguire il rendering di un elenco di risorse per un flusso appena creato in JSON.
Rappresentazione JSON
{
  "stream_id": string,
  "media_verification_url": string,
  "metadata_url": string,
  "session_update_url": string,
  "heartbeat_url": string,
  "polling_frequency": number,
  "pod_manifest_url": string,
  "manifest_format": string,
}
Campi
stream_id string

L'identificatore dello stream GAM.
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 il sondaggio di 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.
heartbeat_url string

L'URL heartbeat, utilizzato per mantenere attivo lo stream di beaconing lato server, deve essere inviato ogni {PollingFrequency} secondi. Compilato per i flussi di beaconing lato server.
polling_frequency number

La frequenza di polling, in secondi, quando si richiede metadata_url o heartbeat_url.
pod_manifest_url string

Il modello di URL del manifest dei pod viene utilizzato per generare l'URL e recuperare il manifest di un pod di uno stream. corrispondente all'URL della playlist multivariante in HLS o all'MPD in DASH. Compilato per gli eventi di live streaming di tipo di inserimento di annunci dinamici POD_SERVING_MANIFEST. https://developers.google.com/ad-manager/api/reference/v202305/LiveStreamEventService.DynamicAdInsertionType
manifest_format string

Il formato manifest è il formato del file manifest recuperato da pod_manifest_url, utilizzando trattini o hl.

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 di 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 agli elementi multimediali dell'annuncio endpoint di verifica.
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

Il tipo di evento di questo tag.

AdBreak

L'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: 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 qualsiasi slate.
ads number

Numero di annunci nell'interruzione pubblicitaria.
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 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 facoltativo della creatività.
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 metadati necessari per eseguire il codice di misurazione di terze parti al fine di verificare e la riproduzione delle creatività.
slate boolean

Bool facoltativo che indica che la voce corrente è uno slate.
icons [object(Icon)]

Un elenco di icone, omesso 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 file <Estensione> nodi in VAST.
companions [object(Companion)]

Annunci companion facoltativi che possono essere visualizzati insieme all'annuncio.
interactive_file object(InteractiveFile)

Creatività interattiva facoltativa (SIMID) da mostrare durante la riproduzione dell'annuncio.

PodTemplateResponse

PodTemplateResponse rappresenta il payload JSON restituito a una VTP per lo stitching dei pod.
Rappresentazione JSON
{
  "dash_period_template": string,
  "segment_duration_ms": int64,
}
Campi
dash_period_template string

DashPeriodTemplate è il modello XML per il periodo da compilare con i dati appropriati prima dello stitching.
segment_duration_ms int64

SegmentDurationMS è la durata dei segmenti del periodo in millisecondi.

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 facilitano misurazione di visibilità e verifica 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 codice di verifica.
browser_optional boolean

Indica se questo script può essere eseguito al di fuori di un o un browser.

TrackingEvent

Il valore TrackingEvent contiene URL per i quali il client deve inviare un ping in determinati in situazioni diverse.
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 che gestiti 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 l'ID annuncio universale della creatività selezionata è catalogato.

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 nella risorsa <StaticResource> in VAST 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 companion statici e iframe, questo sarà l'URL da caricare e visualizzati. Per le creatività companion HTML, sarà lo snippet HTML che deve verrà mostrato 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) da mostrare 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 parametro <AdParameters> del nodo VAST.