Questa pagina è stata tradotta dall'API Cloud Translation.

Early ad break notification

Usare l'API Early Ad Break Notification

Nota: questa API è ancora in versione beta. Rivolgiti al tuo account manager se vuoi richiedere l'accesso al programma EABN.

L'API Early Ad Break Notification (EABN) ti consente di notificare a Google Ad Manager l'imminente interruzione pubblicitaria con i relativi metadati prima del suo inizio. Puoi inviare una richiesta di notifica fino a un'ora prima dell'interruzione pubblicitaria. Questa guida spiega come abilitare e utilizzare l'API EABN e gli esempi di richieste e risposte.

Attenzione: le richieste EABN sono immutabili, quindi una volta creata un'interruzione, non è possibile modificarla. Le richieste successive per creare interruzioni pubblicitarie per lo stesso evento vengono rifiutate fino a quando l'interruzione non viene visualizzata nel manifest dell'evento.

Le chiamate effettuate all'API EABN devono includere le seguenti informazioni:

L'identificatore del live streaming corrispondente a cui viene creata l'interruzione pubblicitaria. L'identificatore può essere uno dei seguenti:
La "chiave risorsa" del live streaming.
La "chiave asset personalizzata" del live streaming, che ti consente di gestire il tuo spazio per le chiavi specificando una stringa identificatore personalizzata.
"Content Source ID" (ID origine contenuti) e "Content ID" del live streaming.

Nota: per utilizzare questo tipo di identificatore devi essere abilitato. Per ulteriori informazioni, contatta il tuo account manager.

La durata prevista della prossima interruzione pubblicitaria. La durata deve essere il più vicina possibile alla durata effettiva dell'interruzione pubblicitaria.

Oltre a questi campi obbligatori, puoi anche inviare parametri di targeting personalizzato, il nome di un modello di pod di annunci da applicare o dati di esclusione SCTE35, se disponibili.

Prerequisiti

Per utilizzare l'API EABN, devi creare un account di servizio e aggiungerlo alla tua rete Google Ad Manager.

Creazione di un account di servizio

Per creare un account di servizio per chiamare l'API EABN, completa i seguenti passaggi: - Se hai un account Google Cloud, usa il modulo IAM per creare un account di servizio. Per ulteriori informazioni, consulta la sezione Creare e gestire account di servizio. - Se non hai un account Google Cloud, completa i seguenti passaggi per crearne uno dalla console API di Google:

Crea un nuovo progetto o selezionane uno esistente.
Nella pagina Credenziali, fai clic su Gestisci account di servizio.
Nella pagina Account di servizio, fai clic su CREA ACCOUNT DI SERVIZIO.
Nella pagina Crea account di servizio, inserisci i dettagli dell'account. Poi, fai clic su CREA.

Dopo aver creato un account di servizio, copia la chiave JSON dell'account utilizzata per l'autenticazione.

Aggiunta dell'account di servizio alla rete Google Ad Manager

Per aggiungere l'account di servizio alla rete, completa i passaggi descritti in Aggiungere un utente con account di servizio per l'accesso API.

Attivazione dell'API

Una volta creato l'account di servizio, fornisci le seguenti informazioni al tuo account manager per abilitare l'API per il tuo account:

L'indirizzo email del tuo account Google Cloud
Il tuo account di servizio
Il codice di rete della tua rete Google Ad Manager.

Una volta che l'API è stata abilitata dall'account manager, completa i seguenti passaggi per abilitarla:

Nella libreria API di Google, cerca "API Google Ad Manager Video".
Fai clic su ABILITA.

Nota: se l'API non viene visualizzata nei risultati di ricerca, contatta il tuo account manager per verificare che l'account sia stato abilitato per l'API DAI.

Utilizzo dell'API

Puoi chiamare l'API EABN utilizzando richieste JSON/REST.

Autorizzazione

Per effettuare chiamate autorizzate all'API EABN, devi generare le credenziali dell'account di servizio OAuth2 utilizzando la chiave JSON del tuo account di servizio e dell'ambito https://www.googleapis.com/auth/video-ads. Per ulteriori informazioni, vedi Utilizzo di OAuth 2.0 per applicazioni server-server.

Devi includere il token di autorizzazione risultante come intestazione Auth per ogni chiamata all'API EABN.

Invio di una notifica di interruzione pubblicitaria anticipata

Per inviare una notifica di interruzione pubblicitaria anticipata, invia una richiesta POST a uno dei tre URL EABN validi, a seconda di come preferisci specificare il live streaming. Le seguenti sezioni spiegano le differenze tra gli URL e forniscono esempi di richieste e risposte.

URL

Esistono tre URL validi per la notifica di interruzione pubblicitaria anticipata. Puoi utilizzare tutti e tre i tipi per creare un'interruzione pubblicitaria (POST) o visualizzare l'elenco delle interruzioni pubblicitarie assegnate (GET).

Per utilizzare la chiave asset di un live streaming, usa:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/assets/{asset_key}/adBreaks

Per usare la chiave asset personalizzata di un live streaming, usa:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/customAssets/{custom_asset_key}/adBreaks

Per utilizzare Content Source ID e Content ID, utilizza quanto segue:

POST admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

GET admanagervideo.googleapis.com/v1/networks/{network_code}/sources/{content_source_id}/content/{content_id}/adBreaks

Per tutti i parametri:

network_code rappresenta il codice di rete della tua rete Google Ad Manager.
asset_key rappresenta la chiave asset mostrata nella pagina dei dettagli del live streaming.
custom_asset_key rappresenta la chiave asset personalizzata del tuo live streaming.
content_source_id rappresenta l'ID di un'origine di contenuto in Google Ad Manager.
content_id rappresenta l'ID di un contenuto in Google Ad Manager.

Nota: la coppia content_source_id/content_id specificata deve essere associata a un live streaming in Google Ad Manager.

Corpo della richiesta, utilizzato solo per creare un'interruzione pubblicitaria (POST)

Oggetto
`expectedDuration`	Obbligatorio	La durata di questa interruzione pubblicitaria, utilizzando il formato di durata standard di Google (xx.xxxs dove xx.xxx è il numero di secondi)
`customParams`	Facoltativo	Le coppie chiave-valore da includere nelle richieste di annunci per questa interruzione per il targeting dei criteri personalizzati in AM360, separate da `=` e si è aggiunto `&` . Esempio: `key=value&key2=value2,value3` Per ulteriori informazioni sul targeting, consulta l'articolo Fornire parametri di targeting per lo stream.
`podTemplateName`	Facoltativo	Il nome del modello del pod di annunci
`scte35CueOut`	Facoltativo	Dati con codifica Base64 dal cue-out di scte35. Può includere il parametro `splice_insert()` o `time_signal()` utilizzando il comando gcloud. Esempi: time_signal(): `/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==` splice_insert(): `/DAvAAAAAAAA///wFAVIAACPf+/+c2nALv4AUsz1AAAAAAAKAAhDVUVJAAABNWLbowo=`

Richieste di esempio

Crea un'interruzione pubblicitaria

POST admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …
{
    "expectedDuration": "30s",
    "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
    "customParams": "param1=value1&param2=value2",
    "podTemplateName": "podtemplate"
}

Corpo della risposta

Il corpo della risposta contiene tutti i parametri inviati nell'oggetto adBreak, oltre a un campo name aggiuntivo, che contiene l'ID standard a livello Google dell'interruzione pubblicitaria creata. Questo campo viene restituito nel seguente formato:

networks/{network_code}/assets/{asset_key}/adBreaks/{ad_break_id}

Esempio di risposta

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "scte35CueOut": "/DA0AAAAAAAA///wBQb+cr0AUAAeAhxDVUVJSAAAjn/PAAGlmbAICAAAAAAsoKGKNAIAmsnRfg==",
  "customParams": "param1=value1&param2=value2",
  "podTemplateName": "podtemplate"
}

Elenca le interruzioni pubblicitarie assegnate

GET admanagervideo.googleapis.com/v1/networks/.../sources/.../content/.../adBreaks
Content-Type: application/json
Authorization: Bearer …

Corpo della risposta

Il corpo della risposta contiene le interruzioni pubblicitarie con un campo breakState aggiuntivo per ogni interruzione pubblicitaria assegnata allo stream. Il campo breakState supporta i seguenti valori:

 // Ad break decisioning has started.
BREAK_STATE_DECISIONED

// Break has started to be delivered to end users.
BREAK_STATE_COMPLETE

Esempio di risposta

HTTP/1.1 200 OK
{
  "name": "networks/.../assets/.../adBreaks/1",
  "expectedDuration": "30s",
  "breakState": "BREAK_STATE_COMPLETE"
}