Gestire i live streaming DAI

L'API Google DAI ti consente di implementare stream abilitati per Google DAI in ambienti in cui l'implementazione dell'SDK IMA non è supportata. Ti consigliamo di utilizzare comunque IMA sulle piattaforme in cui è supportato l'SDK IMA.

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

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

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

Implementare l'API DAI per i live streaming

L'API DAI supporta gli stream lineari (LIVE) utilizzando 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 i seguenti passaggi:

1. Richiedere uno stream

Per richiedere un live streaming dall'API DAI, invia una chiamata POST all'endpoint stream. La risposta JSON contiene il manifest dello stream, nonché gli endpoint e i valori dell'API DAI associati.

Esempio di corpo della richiesta

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

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

Esempio di corpo della risposta

{
"stream_id":"c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"stream_manifest":"https://dai.google.com/linear/dash/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/manifest.mpd",
"media_verification_url":"https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/",
"metadata_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata",
"session_update_url":"https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session",
"polling_frequency":10
}

Risposta di errore

In caso di errori, vengono restituiti i codici di errore HTTP standard senza corpo della risposta JSON.

Analizza la risposta JSON e memorizza i seguenti valori:

stream_id
Questo valore può essere utilizzato per identificare lo stream restituito.
stream_manifest
Questo URL viene passato al tuo 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 eseguire il polling delle informazioni periodiche sugli eventi di streaming imminenti.
session_update_url
Questo URL viene utilizzato per aggiornare i parametri della richiesta di stream inviati durante la richiesta di stream iniziale. Tieni presente che i parametri di questa richiesta sostituiscono tutti i parametri impostati per lo stream precedente.
polling_frequency
La frequenza, in secondi, con cui richiedere i metadati aggiornati dell'interruzione pubblicitaria all'API DAI.

2. Esegui il polling per nuovi metadati di interruzione pubblicitaria

Imposta un timer per eseguire il polling dei nuovi metadati delle interruzioni pubblicitarie alla frequenza di polling, utilizzando l'URL dei metadati. Se non specificato nella risposta dello stream, l'intervallo consigliato predefinito è di 10 secondi.

Per ottimizzare la larghezza di banda:

  1. Invia una richiesta GET iniziale all'endpoint metadata_url.
    • Ometti il parametro di query delta_token. Questa procedura consente al server di restituire i metadati completi per la finestra del videoregistratore digitale (DVR) dello stream. La finestra del DVR contiene l'intervallo di tempo della trasmissione disponibile per la riproduzione e il riavvolgimento da parte di uno spettatore. La risposta include un campo oggetto next_delta_token.
  2. Archivia i metadati lato client.
  3. Effettua le chiamate successive utilizzando il valore next_delta_token restituito dalla risposta più recente. Ogni risposta contiene un valore next_delta_token. Invia sempre l'ultimo valore che ricevi.
  4. Aggiorna i metadati archiviati per unire le modifiche e rimuovere le interruzioni pubblicitarie obsolete.

Non tentare di analizzare, costruire o modificare il token delta. Il formato del token può cambiare. Memorizza il token così come è stato ricevuto e restituiscilo invariato nella richiesta successiva.

Esempio di richiesta iniziale

La richiesta iniziale non accetta parametri di query e restituisce i metadati completi:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata

Esempio di richiesta successiva

Ogni richiesta successiva passa il valore next_delta_token della risposta precedente come parametro delta_token. La risposta contiene quanto segue:

  • Annunci
  • Interruzioni pubblicitarie
  • Tag aggiunti o aggiornati dal server dopo l'emissione del token.
  • Un elenco obsolete_ad_break_ids di interruzioni pubblicitarie da rimuovere dai metadati memorizzati

Il server omette le interruzioni pubblicitarie che non sono state modificate. L'esempio seguente mostra un sondaggio successivo che utilizza il token delta per recuperare solo queste modifiche recenti:

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/metadata?delta_token=eyJyYW5nZXMiOlt7InMiOjEsImUiOjJ9XX0

Se l'operazione va a buon fine, viene visualizzato un output simile al seguente:

{
   "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
   "obsolete_ad_break_ids": ["0003069407"],
   "tags":{
      "google_1022389921":{
         "ad":"0003069408_ad1",
         "ad_break_id":"0003069408",
         "type":"start"
      },
      ...
   },
   "ads":{
      "0003069408_ad1":{
         "ad_break_id":"0003069408",
         "position":1,
         "duration":10.01,
         "title":"External - Pod Midroll 1",
         ...
      }
   },
   "ad_breaks":{
      "0003069408":{
         "type":"mid",
         "duration":30,
         "expected_duration":30,
         "ads":3
      }
   }
}

3. Ascoltare gli eventi ID3 e monitorare gli eventi di riproduzione

Per verificare che si siano verificati 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 multimediale insieme al relativo timestamp (se visualizzato dal player).
  2. A ogni aggiornamento dell'ora da parte del player o a una frequenza impostata (consigliata 500 ms), controlla la coda degli eventi multimediali per gli 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 delle interruzioni pubblicitarie memorizzati. Tieni presente che i tag memorizzati contengono solo un prefisso dell'ID media, pertanto non è possibile una corrispondenza esatta.
  4. Poiché l'app video player esegue il polling dell'URL dei metadati periodicamente, potrebbe verificarsi un ritardo tra il momento in cui il video player rileva un tag ID3 nello stream e il momento in cui i metadati associati sono disponibili. Se non viene trovato un tag ID3 nei tag archiviati, mantieni il tag in una coda ed elaboralo di nuovo dopo il successivo polling dei metadati. Mantieni l'evento in coda fino al termine dell'elaborazione.
  5. Dopo aver trovato il tag nei metadati, confronta il campo type del tag con i tipi di eventi dell'annuncio elencati nella sezione seguente. Per tenere traccia se il video player sta riproducendo un'interruzione pubblicitaria, utilizza gli eventi con il valore progress del campo type. Non inviare questi eventi all'endpoint di verifica dei contenuti multimediali. Per tutti gli altri tipi di eventi, aggiungi l'ID media all'endpoint di verifica dei media ed effettua una richiesta GET per monitorare la riproduzione.
  6. Rimuovi l'evento multimediale dalla coda.

Tipi di eventi dell'annuncio

Ogni tag nell'oggetto tags dei metadati ha uno dei seguenti tipi di eventi:

Tipo di evento Descrizione
start Viene eseguito all'inizio dell'annuncio.
firstquartile Viene eseguito alla fine del primo quartile dell'annuncio.
midpoint Viene riprodotto a metà dell'annuncio.
thirdquartile Viene eseguito alla fine del terzo quartile dell'annuncio.
complete Viene eseguito alla fine dell'annuncio.
progress Viene eseguito periodicamente durante un'interruzione pubblicitaria per segnalare che è in corso la riproduzione di un'interruzione pubblicitaria. Non inviare questi eventi all'endpoint di verifica dei contenuti multimediali.

Esempio di richiesta

https://dai.google.com/view/p/service/linear/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/loc/ATL/network/51636543/event/0ndl1dJcRmKDUPxTRjvdog/media/google_1022389921

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 nel Monitoraggio attività di streaming.

4. Aggiornare i parametri di sessione del live streaming

Potresti voler modificare i parametri della sessione dopo aver creato uno stream. Per farlo, invia una richiesta all'URL di aggiornamento della sessione.

Esempio di corpo della richiesta

https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS/session

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

Esempio di corpo della risposta

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 al targeting:

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

Best practice

Tieni presente che l'endpoint dei metadati per gli indici dei live streaming si basa sul prefisso del tag ID3 corrispondente. Questa operazione è stata progettata per impedire l'utilizzo dell'endpoint dei metadati per il ping immediato di tutti i nodi di verifica.

Risorse aggiuntive