L'API Google DAI consente di implementare gli stream abilitati per l'inserimento di annunci dinamici di Google in ambienti in cui l'implementazione dell'SDK IMA non è supportata. Ti consigliamo di continuare a utilizzare IMA su piattaforme che supportano l'SDK IMA.
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 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) tramite 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 questi passaggi:
1. Richiedere uno stream
Per richiedere un live streaming dall'API DAI, effettua una chiamata POST all'endpoint stream. La risposta JSON contiene il manifest del flusso, 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":"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 corpo della risposta JSON.
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 tuo media player per la riproduzione dello streaming.
- media_verification_url
- Questo URL è l'endpoint di base per il monitoraggio degli eventi di riproduzione.
- metadata_url
- Questo URL viene utilizzato per raccogliere informazioni periodiche sui prossimi eventi di streaming.
- session_update_url
- Questo URL viene utilizzato per aggiornare i parametri della richiesta di streaming inviati durante la richiesta di streaming iniziale. Tieni presente che i parametri di questa richiesta sostituiscono tutti i parametri impostati per lo stream precedente.
- polling_frequency
- La frequenza, in secondi, per la richiesta di metadati di interruzione pubblicitaria aggiornati dall'API DAI.
2. Sondaggio per nuovi metadati di interruzione pubblicitaria
Imposta un timer per eseguire il polling dei nuovi metadati di interruzione pubblicitaria alla frequenza di polling, utilizzando l'URL dei metadati. Se non specificato nella risposta del flusso, l'intervallo consigliato predefinito è 10 secondi.
Esempio di corpo della richiesta
https://dai.google.com/linear/v1/pa/event/0ndl1dJcRmKDUPxTRjvdog/stream/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/metadata
Esempio di corpo della risposta
{
"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 traccia gli eventi di riproduzione
Per verificare che in uno stream video si siano verificati eventi specifici, segui questi passaggi per gestire gli eventi ID3:
- Archivia gli eventi multimediali in una coda, salvando ogni ID multimediale insieme al relativo timestamp (se visualizzato dal player).
- A ogni aggiornamento dal player o a una frequenza impostata (consigliato 500 ms), controlla la coda degli eventi multimediali per verificare la presenza di eventi riprodotti di recente confrontando i timestamp degli eventi con la testina di riproduzione.
- Per gli eventi multimediali di cui confermi che sono stati riprodotti, controlla il tipo cercando l'ID multimediale nei tag di interruzione pubblicitaria archiviati. Tieni presente che i tag archiviati contengono solo un prefisso dell'ID elemento multimediale, quindi non è possibile una corrispondenza esatta.
- Utilizza gli eventi "avanzamento" per tenere traccia dell'eventuale presenza di un utente all'interno di un'interruzione pubblicitaria. Non inviare questi eventi all'endpoint di verifica dei contenuti multimediali. Per altri tipi di eventi, aggiungi l'ID elemento multimediale all'endpoint di verifica dei contenuti multimediali ed effettua una richiesta GET per monitorare la riproduzione.
- Rimuovi l'evento multimediale dalla coda.
Esempio di corpo della richiesta
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 Monitoraggio attività di streaming.
4. Aggiorna i parametri della sessione per il live streaming
Potresti voler modificare i parametri di sessione dopo la creazione di 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/c6bbee18-0d20-4c55-b071-efdf3a81da33:ATL/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 relative al targeting:
- UserAgent: il parametro dello user agent viene trasmesso come valore specifico del browser anziché della piattaforma sottostante.
rdid,idtype,is_lat: l'ID dispositivo non è stato 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. Questo è progettato per impedire l'utilizzo dell'endpoint di metadati per il ping immediato a tutti i nodi di verifica.