Utilizza un'integrazione personalizzata

Prima di iniziare

Questa guida illustra solo le istruzioni di riproduzione in assenza dell'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.

Per farlo, ti serviranno le seguenti informazioni:

OAUTH_TOKEN

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 di stitching video.

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

Parametri del corpo codificati in base al modulo

Un insieme facoltativo di parametri di targeting codificati in forma .

JSON della risposta

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

Risposta di esempio

{
  "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 testo della risposta JSON.

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 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

Parametro dell'intestazione di autorizzazione

OAUTH_TOKEN

Parametri del corpo con codifica JSON

JSON della risposta

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"
  }
}

Risposta di esempio

{
  "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
  }
}

Una volta ricevuta la risposta, puoi riprodurre il live streaming con annunci uniti facendo riferimento all'URI di riproduzione della sessione nel campo playUri dell'oggetto risposta.

L'API Video Stitcher genera un ID sessione univoco per ogni richiesta, che può essere recuperato dall'ultima sezione del campo name dell'oggetto di 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.

Effettuare una ricerca di nuovi metadati relativi all'interruzione pubblicitaria

L'applicazione è responsabile del recupero dei metadati per ogni interruzione pubblicitaria, pertanto conosce 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 campo polling_frequency nella risposta di registrazione dello stream.

In cambio, ricevi un oggetto JSON contenente i seguenti parametri:

Memorizza questi valori dopo ogni sondaggio per associare gli eventi dei metadati con temporizzazione all'interno del 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. Memorizza gli eventi multimediali in una coda, salvando ogni ID media insieme al relativo timestamp, se visualizzato dal player.
2. A ogni aggiornamento della data e dell'ora dal player o a una frequenza impostata (consigliata 500 ms), controlla la coda di eventi multimediali per gli eventi riprodotti di recente confrontando i timestamp degli eventi con il cursore 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. Tieni presente che l'oggetto tag interruzione annunci contiene solo una versione troncata dell'ID media, limitata alle prime 10 cifre dopo il prefisso google_, pertanto non esiste una corrispondenza diretta tra le chiavi e gli ID di verifica dei contenuti multimediali ID3 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 completo di verifica dei contenuti multimediali di un evento annuncio, aggiungere l'ID evento annuncio completo al valore media_verification_url della risposta alla creazione dello stream.
4. Utilizza gli eventi "progress" per monitorare se un utente si trova all'interno di 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 media all'URL media verification e invia una richiesta GET per monitorare la riproduzione.
5. Rimuovi l'evento multimediale dalla coda.

endpoint API

GET: MEDIA_VERIFICATION_URLAD_MEDIA_ID
Host: dai.google.com

Parametri del percorso

Valori di rendimento previsti

Richiesta di esempio (cURL)

curl MEDIA_VERIFICATION_URLAD_MEDIA_ID

Risposta di esempio

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 passato come valore specifico del browser anziché della piattaforma di base.
• rdid, idtype, is_lat: l'ID dispositivo non viene passato correttamente, il che limita la funzionalità delle seguenti funzionalità:
  • Quota limite
  • Rotazione sequenziale degli annunci
  • Segmentazione e targeting per pubblico