API Dynamic Ad Placement per live streaming

L'API DAI di Google ti consente di implementare gli stream abilitati per l'inserimento di annunci dinamici di Google negli ambienti in cui l'implementazione dell'SDK IMA non è supportata. Ti consigliamo di continuare a utilizzare IMA sulle piattaforme in cui è supportato l'SDK IMA.

Ti consigliamo di utilizzare l'API DAI sulle seguenti piattaforme:

  • Smart TV Samsung (Tizen)
  • TV LG
  • HbbTV
  • Xbox (app JavaScript)
  • KaiOS

L'API supporta le funzionalità di base fornite dall'SDK IMA DAI. Per per domande specifiche sulla compatibilità o sulle funzionalità supportate, contatta il tuo account manager Google.

Implementare l'API DAI per i LIVE streaming

L'API DAI supporta gli stream lineari (LIVE) che utilizzano entrambi i protocolli HLS e DASH. I passaggi descritti in questa guida si applicano a entrambi i protocolli.

Per integrare l'API nella tua app per i LIVE streaming, completa quanto segue passaggi:

1. Richiedi uno stream

Per richiedere un live streaming dall'API DAI, effettua una chiamata POST allo stream endpoint. La risposta JSON contiene il manifest dello stream e i dati associati Endpoint e valori dell'API DAI.

Corpo della richiesta di esempio

https://dai.google.com/linear/v1/dash/event/0ndl1dJcRmKDUPxTRjvdog/stream

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Corpo di risposta di esempio

{
"stream_id":"c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session",
"polling_frequency":10
}

Risposta di errore

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

Analizza la risposta JSON e archivia i seguenti valori:

stream_id
Questo valore può essere utilizzato per identificare lo stream restituito.
stream_manifest
Questo URL viene trasmesso al media player per la riproduzione dello stream.
media_verification_url
Questo URL è l'endpoint di base per il monitoraggio degli eventi di riproduzione.
metadata_url
Questo URL viene utilizzato per chiedere informazioni periodiche sul live streaming in programma eventi.
session_update_url
Questo URL viene utilizzato per aggiornare i parametri della richiesta di streaming inviati durante l'iniziale richiesta di streaming. Tieni presente che i parametri di questa richiesta sostituiscono tutti i parametri impostato per lo stream precedente.
polling_frequency
La frequenza, in secondi, durante la richiesta di metadati dell'interruzione pubblicitaria aggiornati dal API DAI.

2. Sondaggio per i nuovi metadati dell'interruzione pubblicitaria

Imposta un timer per eseguire il polling per i nuovi metadati dell'interruzione pubblicitaria alla frequenza di polling, utilizzando il metodo dell'URL dei metadati. Se non specificato nella risposta dinamica, viene consigliato il valore predefinito è di 10 secondi.

Corpo della richiesta di esempio

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata

Corpo di 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/pcs/click?xai=AKAO...\u0026adurl=http://google.com",
         "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
      },....
   }
}

3. Ascolta gli eventi ID3 e monitora gli eventi di riproduzione

Per verificare che eventi specifici si siano verificati in uno stream video: 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. A ogni aggiornamento dal player o con una frequenza prestabilita (consigliato 500 ms), controlla se nella coda degli eventi multimediali sono presenti eventi riprodotti di recente confrontando i timestamp degli eventi con la testina di riproduzione.
  3. Per gli eventi multimediali che confermi di aver riprodotto, controlla il tipo cercando l'ID elemento multimediale nei tag di interruzione pubblicitaria archiviati. Ricorda che i tag archiviati contengono solo un prefisso dell'ID elemento multimediale, pertanto non è possibile una corrispondenza esatta.
  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 un altro evento tipi, aggiungi l'ID multimediale all'endpoint di verifica dei contenuti multimediali ed effettua una richiesta GET richiesta di tenere traccia della riproduzione.
  5. Rimuovi l'evento multimediale dalla coda.

Corpo della richiesta di esempio

https://dai.google.com/view/p/service/linear/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/

Risposte di esempio

Accepted for asynchronous verification - HTTP/1.1 202 Accepted
Successful empty response - HTTP/1.1 204 No Content
Media verification not found - HTTP/1.1 404 Not Found
Media verification sent by someone else - HTTP/1.1 409 Conflict

Puoi verificare gli eventi di monitoraggio in Attività di streaming Monitora.

4. Aggiorna i parametri della sessione di live streaming

Può essere utile modificare i parametri di sessione dopo che lo stream è stato è stato creato. Per farlo, invia una richiesta all'URL di aggiornamento della sessione.

Corpo della richiesta di esempio

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/session

{
  key1 : "value1",
  stream_parameter1 : "value2"
}

Corpo di risposta di esempio

Successful response would be to look for - HTTP/1.1 200

Limitazioni

Se utilizzi l'API all'interno di WebView, si applicano le seguenti limitazioni in relazione a al targeting:

  • UserAgent: il parametro user agent viene passato come valore specifico del browser anziché dalla piattaforma sottostante.
  • rdid, idtype, is_lat: L'ID dispositivo non viene trasmesso correttamente, il che limita le capacità del componente le seguenti funzionalità:
    • Quota limite
    • Rotazione sequenziale degli annunci
    • Segmentazione e targeting del pubblico

Best practice

Tieni presente che l'endpoint dei metadati per gli indici dei live streaming si basa sul del tag ID3 corrispondente. Questa funzionalità è stata progettata per impedire l'uso per l'invio immediato di un ping a tutti i nodi di verifica.

Risorse aggiuntive