Utilizza un'integrazione personalizzata

Prima di iniziare

Questa guida illustra solo le istruzioni di riproduzione, in assenza del SDK IMA DAI.

Assicurati di aver già completato i passaggi descritti in Integrare Google Ad Manager (GAM) con i live streaming in precedenza.

Se l'SDK IMA non è disponibile per la piattaforma scelta, la tua applicazione dovrà chiamare le API richieste e attivare le impressioni degli annunci.

A questo scopo, avrai bisogno delle seguenti informazioni:

Località La Regione Google Cloud dove è stata creata la configurazione live:
LOCATION
Numero progetto Il numero del progetto Google Cloud che utilizza l'API Video Stitcher:
PROJECT_NUMBER
Token OAuth Il token OAuth a breve durata di un account di servizio con il ruolo utente Video Stitcher: 
OAUTH_TOKEN
Scopri di più sulla creazione di token OAuth a vita breve.
Codice di rete Il codice di rete Ad Manager per richiedere annunci:
NETWORK_CODE
ID configurazione dal vivo L'ID configurazione live specificato durante la creazione dell'evento in live streaming:
LIVE_CONFIG_ID
Chiave asset personalizzata La chiave asset personalizzata di Ad Manager generata durante il processo di creare una configurazione per un evento in live streaming con l'API Video Stitcher:
CUSTOM_ASSET_KEY

Inviare una richiesta di registrazione dello stream ad Ad Manager

Invia una richiesta POST all'endpoint di registrazione dello stream. In cambio, ricevi una risposta JSON contenente l'ID stream da inviare all'API Video stitching.

endpoint API

POST: /ssai/pods/api/v1/network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream
Host: dai.google.com
Content-Type: application/x-www-form-urlencoded

Parametri del percorso

NETWORK_CODE Il tuo codice di rete Google Ad Manager 360:
NETWORK_CODE
CUSTOM_ASSET_KEY L'identificatore personalizzato associato a questo evento in Google Ad Manager:
CUSTOM_ASSET_KEY

Parametri del corpo codificati in base al modulo

Un insieme facoltativo di codifica nel modulo parametri di targeting .

JSON della risposta

media_verification_url L'URL di base per eseguire il ping degli eventi di monitoraggio della riproduzione. Un URL completo per la verifica dei contenuti media viene formato aggiungendo un ID evento annuncio a questo URL di base.
MEDIA_VERIFICATION_URL
metadata_url L'URL per richiedere i metadati dei pod di annunci.
METADATA_URL
polling_frequency la frequenza consigliata in millisecondi per eseguire il polling di "metadata_url".
POLLING_FREQUENCY
stream_id La stringa utilizzata per identificare la sessione di streaming corrente.
STREAM_ID
valid_for Il tempo rimanente fino alla scadenza della sessione di streaming corrente, in formato dhms (giorni, ore, minuti, secondi). Ad esempio, 2h0m0.000s rappresenta una durata di 2 ore.
valid_until L'ora in cui scade la sessione di streaming corrente, indicata come ISO 8601 stringa data/ora in yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm formato.

Richiesta di esempio (cURL)

curl -X POST \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "cust_params=\"section%3Dsports%26page%3Dgolf%2Ctennis\"" \
  https://dai.google.com/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Esempio di risposta

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

In caso di errori, vengono restituiti codici di errore HTTP standard senza risposta JSON del testo.

Analizza la risposta JSON e memorizza i valori pertinenti.

Generare l'URI di riproduzione della sessione

Invia una richiesta POST all'endpoint /livesessions dell'API Video Stitcher per creare una nuova sessione dal vivo. In cambio, ricevi una risposta in formato JSON contenente il manifest dello stream da caricare nel video player.

endpoint API

POST: /v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions
Host: videostitcher.googleapis.com
Authorization: Bearer OAUTH_TOKEN
Content-Type: application/json

Parametri del percorso

PROJECT_NUMBER Il numero del progetto Google Cloud che utilizza l'API Video Stitcher:
PROJECT_NUMBER
LOCATION La Regione Google Cloud dove è stata creata la configurazione live:
LOCATION

Parametro dell'intestazione di autorizzazione

OAUTH_TOKEN Token OAuth di breve durata di un account di servizio con l'utente dello stitching video ruolo: 
OAUTH_TOKEN

Parametri del corpo con codifica JSON

liveConfig Una stringa contenente il numero di progetto. location e l'ID configurazione live seguente formato:
projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID
adTracking Imposta "CLIENT" per attivare il monitoraggio lato client.
gamSettings Un oggetto contenente l'ID stream con i seguenti elementi formato:
{"streamId":"STREAM_ID"}

JSON risposta

name Il nome della sessione live, contenente l'ID sessione.
playUri L'URI del manifest dello stream cucito da caricare nel video player per la riproduzione.
PLAY_URI
liveConfig La stessa stringa liveConfig inviata all'API nella richiesta del testo.
gamSettings Lo stesso oggetto gamSettings inviato all'API nella tua richiesta del testo.

Richiesta di esempio (cURL)

curl -X POST \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer OAUTH_TOKEN" \
     -d '@request.json' \
  https://videostitcher.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/liveSessions

request.json

{
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID",
  "adTracking": "CLIENT",
  "gamSettings": {
    "streamId": "STREAM_ID"
  }
}

Esempio di risposta

{
  "name": "projects/PROJECT_NUMBER/locations/LOCATION/liveSessions/SESSION_ID",
  "playUri": PLAY_URI,
  "liveConfig": "projects/PROJECT_NUMBER/locations/LOCATION/liveConfigs/LIVE_CONFIG_ID"
  "gamSettings": {
    "streamId": STREAM_ID
  }
}

Dopo aver ricevuto la risposta, puoi riprodurre il live streaming con lo stitching di annunci fa riferimento all'URI di riproduzione della sessione dal campo playUri della .

L'API Video Stitcher genera un ID sessione univoco per per ogni richiesta, che può essere recuperata dall'ultima sezione del campo name dell'oggetto risposta.

Una sessione inattiva scade dopo 5 minuti. Una sessione è considerata inattiva se non sono stati eseguiti recuperi del manifest in un determinato periodo di tempo.

Sondaggio per i nuovi metadati dell'interruzione pubblicitaria

L'applicazione è responsabile del recupero dei metadati per ogni interruzione pubblicitaria, quindi individua le impressioni da attivare. Per farlo, imposta un timer per eseguire regolarmente il polling delle API DAI metadata_url per rilevare nuove informazioni sugli annunci. L'intervallo per il polling è specificato nel criterio polling_frequency nella risposta della registrazione dello stream.

Riceverai in cambio un oggetto JSON contenente i seguenti parametri:

tags Una serie di coppie chiave/valore che descrivono gli eventi multimediali degli annunci che si verificano. all'interno dello stream. Ogni chiave è costituita dai primi 17 caratteri di un ID elemento multimediale dell'annuncio che verrà visualizzato nei metadati ID3 dello stream o, nel caso degli eventi "progress", dall'intero ID elemento multimediale dell'annuncio. Ogni valore è un oggetto con le seguenti proprietà:
  • ad: l'ID dell'annuncio contenente l'evento relativo ai media dell'annuncio.
  • ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'evento media dell'annuncio.
  • type: il tipo di evento relativo ai media dell'annuncio. I valori sono uno dei seguenti:
    • start: l'annuncio è iniziato
    • firstquartile: l'annuncio è completato per il 25%.
    • midpoint: l'annuncio è completato al 50%.
    • thirdquartile: l'annuncio è completo al 75%.
    • complete: l'annuncio è terminato.
    • progress: attivato ogni secondo durante la riproduzione di un annuncio.
ads Un insieme di coppie chiave-valore che descrivono gli annunci da mostrare all'interno dello stream. Ogni chiave è un ID annuncio. Ogni valore è un oggetto con le seguenti caratteristiche proprietà:
  • ad_break_id: l'ID dell'interruzione pubblicitaria contenente l'evento media dell'annuncio.
  • position: la posizione dell'annuncio all'interno dell'interruzione pubblicitaria. Tieni presente che il primo annuncio in un'interruzione ha la posizione 1.
  • duration: la durata dell'annuncio in virgola mobile secondi.
  • title: il titolo dell'annuncio, come definito nel modello VAST.
  • description: la descrizione dell'annuncio, come definita nella il modello VAST.
  • ad_system: il sistema pubblicitario, come definito nel VAST.
  • ad_system: l'ID annuncio, come definito in VAST.
  • ad_system: l'ID creatività, come definito nel file VAST.
  • clickthrough_url: l'URL da aprire quando un utente interagisce con l'annuncio.
  • universal_ad_id: un oggetto che rappresenta l'universale come definito in VAST.
ad_breaks Una serie di coppie chiave-valore che descrivono le interruzioni pubblicitarie che si verificheranno. all'interno dello stream. Ogni chiave è un ID interruzione pubblicitaria. Ogni valore è un oggetto con le seguenti proprietà:
  • type: il tipo di interruzione pubblicitaria. I valori possono essere uno dei seguenti:
    • pre: rappresenta un annuncio pre-roll.
    • mid: rappresenta un annuncio mid-roll.
    • post: rappresenta un annuncio post-roll.
  • duration: la durata dell'interruzione pubblicitaria in secondi con virgola mobile.
  • expected_duration: la durata prevista dell'interruzione pubblicitaria in secondi in virgola mobile.
  • ads: il numero di annunci contenuti nell'interruzione pubblicitaria.

Archivia questi valori dopo ogni sondaggio per associare eventi di metadati a tempo all'interno di nel tuo stream video.

Richiesta di esempio (cURL)

curl https://dai.google.com/.../metadata/

Risposta di esempio

{
   "tags":{
      "google_0492266569":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"firstquartile"
      },
      "google_1560331148":{
         "ad":"0000229836_ad1",
         "ad_break_id":"0000229836",
         "type":"thirdquartile"
      },
      "google_1877686714378797835":{
         "ad":"0000229836_slate",
         "ad_break_id":"0000229836",
         "type":"progress"
      },
      "google_1vRyQBYPw_7Gg3MrZ6S5EjmV9aLje-YpW8QHed1DSlU":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"progress"
      },
      "google_2032765498":{
         "ad":"0000229835_ad1",
         "ad_break_id":"0000229835",
         "type":"midpoint"
      },
      ...
      "google_5646900623":{
         "ad":"0000229837_ad1",
         "ad_break_id":"0000229837",
         "type":"complete"
      }
   },
   "ads":{
      "0000229834_ad1":{
         "ad_break_id":"0000229834",
         "position":1,
         "duration":15.01,
         "title":"truman-e2e-creativeset4",
         "description":"truman-e2e-creativeset4 ad",
         "ad_system":"GDFP",
         "ad_id":"39066884",
         "creative_id":"58092079124",
         "clickthrough_url":"https://pubads.g.doubleclick.net/...",
         "universal_ad_id":{
            "id_value":"58092079124",
            "id_registry":"GDFP"
         }
      },
      "0000229834_slate":{
         "ad_break_id":"0000229834",
         "position":-1,
         "duration":14.974977777,
         "slate":true
      },
      ...
   },
   "ad_breaks":{
      "0000229834":{
         "type":"mid",
         "duration":15.01,
         "expected_duration":29.984977776999997,
         "ads":1
      },
      ...
   }
}

Ascolta gli eventi ID3 e monitora gli eventi di riproduzione

Per verificare che siano avvenuti eventi specifici in uno stream video, segui questi passaggi per gestire gli eventi ID3:

  1. Archivia gli eventi multimediali in una coda, salvando ogni ID multimediale insieme al relativo , se mostrato dal player.
  2. Ad ogni aggiornamento dal player o con una frequenza impostata (500 ms l'opzione consigliata), controlla la coda degli eventi multimediali per verificare se sono presenti eventi riprodotti di recente confrontando i timestamp degli eventi con la testina di riproduzione.
  3. Per gli eventi multimediali di cui confermi la riproduzione, controlla il tipo cercando l'ID media nei tag di interruzione pubblicitaria archiviati. Ricorda che i tag di interruzione pubblicitaria contiene solo una versione troncata dell'ID elemento multimediale, limitata le prime 10 cifre dopo il prefisso google_, quindi non c'è una corrispondenza diretta. tra gli ID verifica contenuti multimediali ID3 e le chiavi nell'oggetto tag. Questo serve per impedire l'invio di ping di verifica degli eventi prima dell'arrivo dell'evento ID3. Per generare l'URL di verifica dei contenuti completo di un evento annuncio, aggiungere l'ID evento annuncio completo al valore media_verification_url della risposta alla creazione dello stream.
  4. Utilizzare "avanzamento" per tenere traccia della presenza di un utente durante un'interruzione pubblicitaria. Non inviare questi eventi all'endpoint di verifica dei contenuti multimediali per evitare un codice di errore HTTP. Per altri tipi di eventi, aggiungi l'ID elemento multimediale all'elemento multimediale l'URL di verifica ed effettua una richiesta GET per tracciare la riproduzione.
  5. Rimuovi l'evento multimediale dalla coda.

endpoint API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parametri del percorso

MEDIA_VERIFICATION_URL Il valore restituito dall'endpoint di registrazione dello stream, in Campo media_verification_url:
MEDIA_VERIFICATION_URL
AD_MEDIA_ID L'ID elemento multimediale dell'annuncio completo, come visualizzato nei metadati ID3 dello stream:
AD_MEDIA_ID

Valori di rendimento previsti

HTTP/1.1 204 No Content Risposta vuota riuscita.
HTTP/1.1 404 Not Found L'ID verifica dei contenuti multimediali non è stato riconosciuto.
HTTP/1.1 409 Conflict L'ID verifica dei contenuti multimediali è già stato inviato.

Richiesta di esempio (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Esempio di risposta

HTTP/1.1 204 No Content

Limitazioni

Se utilizzi l'API all'interno delle visualizzazioni web, si applicano le seguenti limitazioni per quanto riguarda il targeting:

  • UserAgent: il parametro user agent viene trasmesso come valore specifico del browser. anziché dalla piattaforma sottostante.
  • rdid, idtype, is_lat: l'ID dispositivo non viene passato correttamente, il che limita la funzionalità delle seguenti funzionalità:
    • Quota limite
    • Rotazione degli annunci sequenziale
    • Segmentazione e targeting per pubblico
Indietro
tvOS
Avanti
Esegui la pulizia