L'API Google DAI Pod Serving ti consente di eseguire l'inserimento di annunci lato server con tecnologia Google Ads, mantenendo al contempo il controllo dello stitching video.
Questa guida illustra come interagire con l'API Pod Serving e ottenere funzionalità simili con l'SDK IMA DAI. Per domande specifiche sulle funzionalità supportate, contatta il tuo account manager Google.
L'API Pod Serving supporta flussi di pubblicazione di pod nei protocolli di streaming HLS o MPEG-DASH. Questa guida si concentra sugli stream HLS ed evidenzia le principali differenze tra HLS e MPEG-DASH in passaggi specifici.
Per integrare l'API Pod Serving nella tua app per i flussi VOD, completa i seguenti passaggi:
Inviare una richiesta di registrazione dello stream ad Ad Manager
Effettua una richiesta POST all'endpoint di registrazione del flusso. Ricevi a sua volta una risposta JSON contenente l'ID stream da inviare al server di manipolazione del manifest e agli endpoint dell'API Pod Serving associati.
Endpoint API
POST: /ssai/pods/api/v1/network/{network_code}/custom_asset/{custom_asset}/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 |
{custom_asset} |
L'identificatore personalizzato associato a questo evento in Google Ad Manager. |
Parametri corporei con codifica modulo
Un set facoltativo di parametri di targeting codificati nel modulo.
JSON risposta
media_verification_url |
L'URL di base per inviare un ping agli eventi di monitoraggio della riproduzione. Per ottenere un URL completo di verifica dei contenuti multimediali, aggiungi un ID evento dell'annuncio a questo URL di base. |
metadata_url |
L'URL per richiedere i metadati del pod di annunci. |
stream_id |
La stringa utilizzata per identificare la sessione di streaming corrente. |
valid_for |
La quantità di tempo rimanente 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 di scadenza della sessione di streaming corrente, sotto forma di stringa di data/ora ISO 8601 in formato yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm .
|
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/linear/pods/api/v1/network/21775744923/custom_asset/a-public-test-asset/stream
Esempio di risposta
{
"media_verification_url": "https://dai.google.com/.../media/",
"metadata_url": "https://dai.google.com/.../metadata",
"stream_id": "6e69425c-0ac5-43ef-b070-c5143ba68541:CHS",
"valid_for": "8h0m0s",
"valid_until": "2023-03-24T08:30:26.839717986-07:00"
}
In caso di errori, i codici di errore HTTP standard vengono restituiti senza alcun corpo di risposta JSON.
Analizza la risposta JSON e archivia i valori pertinenti.
Richiedi il manifest del flusso al manipolatore del manifest
Ogni manipolatore del manifest ha formati di richiesta e risposta diversi. Contatta il fornitore del manipolatore per comprendere i suoi requisiti specifici. Se implementi un manipolatore del manifest personalizzato, leggi la guida del manipolatore del manifest per comprendere i requisiti per questo componente.
In generale, devi passare l'ID stream restituito dall'endpoint di registrazione in alto al manipolatore del manifest affinché possa creare manifest specifici della sessione. A meno che non sia esplicitamente indicato dal creatore del file manifest, la risposta a questa richiesta è un video stream che include sia contenuti sia annunci.
Richiesta di esempio (cURL)
curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8
Esempio di risposta (HLS)
#EXTM3U
#EXT-X-MEDIA:TYPE=SUBTITLES,GROUP-ID="subs0",LANGUAGE="en",NAME="English",AUTOSELECT=YES,DEFAULT=YES,URI="abcd1234_ subitles-en.vtt"
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080,CODECS="avc1.42e00a,mp4a.40.2"
abcd1234_video-1080p.m3u8
Riproduci lo stream
Carica il file manifest che hai ricevuto dal server di manipolazione del manifest in un video player e avvia la riproduzione.
Richiedere i metadati dei pod di annunci da Ad Manager
Effettua una richiesta GET
all'indirizzo metadata_url
che hai ricevuto nel passaggio 1. Questo passaggio deve avvenire dopo aver ricevuto il manifest creato dallo stitching dal manipolatore del manifest. In cambio, ricevi un oggetto JSON contenente i seguenti parametri:
tags |
Un insieme di coppie chiave-valore contenente tutti gli eventi annuncio visualizzati nel flusso. Le chiavi corrispondono ai primi 17 caratteri di un ID evento dell'annuncio visualizzati nei metadati temporali dello stream oppure, nel caso di eventi di tipo progress , all'ID evento completo dell'annuncio.
Ogni valore è un oggetto contenente i seguenti parametri:
|
||||||||||||||||||
ads |
Un insieme di coppie chiave-valore che descrivono tutti gli annunci visualizzati nello stream. Le chiavi sono ID annuncio che corrispondono ai valori presenti nell'oggetto tags sopra elencato. Ogni valore è un oggetto contenente i seguenti parametri:
|
||||||||||||||||||
ad_breaks |
Un insieme di coppie chiave-valore che descrivono tutte le interruzioni pubblicitarie visualizzate nello stream.
Le chiavi sono ID di interruzione pubblicitaria che corrispondono ai valori trovati negli oggetti tags e ads elencati sopra. Ogni valore è un oggetto contenente i seguenti parametri:
|
Archivia questi valori da associare agli eventi di metadati con timestamp all'interno dello stream video.
Richiesta di esempio (cURL)
curl https://dai.google.com/.../metadata
Esempio di risposta
{
"tags":{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
},
"ads":{
"0000229834_ad1":{
"ad_break_id":"0000229834",
"position":1,
"duration":15,
"clickthrough_url":"https://.../",
...
},
...
},
"ad_breaks":{
"0000229834":{
"type":"mid",
"duration":15,
"ads":1
},
...
}
}
Ascolta gli eventi relativi agli annunci
Ascolta i metadati temporali tramite eventi annuncio attivati nello stream audio/video del video player.
Per gli stream MPEG-TS, i metadati compaiono come tag ID3 v2.3 nella banda. Ogni tag di metadati ha l'ID TXXX
e il valore inizia con la stringa google_
seguita da una serie di caratteri. Questo valore è l'ID evento dell'annuncio.
XXX
in TXXX
non è un segnaposto. La stringa TXXX
è l'ID tag ID3
riservato per il "testo definito dall'utente".
Esempio di tag ID3
TXXXgoogle_1234567890123456789
Per gli stream MP4, vengono inviati come eventi emsg in-band che emulano tag ID3 v2.3. Ogni casella di emsg pertinente ha un valore scheme_id_uri
pari a
https://aomedia.org/emsg/ID3
o
https://developer.apple.com/streaming/emsg-id3
e un valore message_data
che inizia con ID3TXXXgoogle_
. Questo valore message_data
, senza il
prefisso ID3TXXX
, è l'ID evento dell'annuncio.
Casella emsg di esempio
La struttura dei dati può variare a seconda della libreria del lettore multimediale.
Se l'ID evento dell'annuncio è google_1234567890123456789
, la risposta sarà simile alla seguente:
{
"scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
"presentation_time": 27554,
"timescale": 1000,
"message_data": "ID3TXXXgoogle_1234567890123456789",
...
}
Alcune librerie di media player presentano automaticamente eventi di emsg che emulano tag ID3 come tag ID3 nativi. In questo caso, gli stream MP4 presentano tag ID3 identici a MPEG_TS.
Aggiorna l'interfaccia utente dell'app del video player del client
Ogni ID evento dell'annuncio può essere abbinato a una chiave nell'oggetto tags
del passaggio 4.
La corrispondenza di questi valori è un processo a due fasi:
Verifica se nell'oggetto
tags
è presente una chiave corrispondente all'ID evento completo dell'annuncio. Se viene trovata una corrispondenza, recupera il tipo di evento e gli oggettiad
ead_break
associati. Questi eventi devono essere di tipoprogress
.Se non viene trovata una corrispondenza per l'ID evento completo dell'annuncio, controlla se nell'oggetto
tags
è presente una chiave corrispondente ai primi 17 caratteri dell'ID evento dell'annuncio. Recupera il tipo di evento e gli oggettiad
ead_break
associati. Verranno recuperati tutti gli eventi di tipo diverso daprogress
.Usa queste informazioni recuperate per aggiornare l'interfaccia utente del player. Ad esempio, quando ricevi un evento
start
o il primo eventoprogress
, nascondi i controlli di ricerca del player e mostra un overlay che descrive la posizione dell'annuncio corrente nell'interruzione pubblicitaria, ad esempio "Annuncio 1 di 3".
Esempi di ID evento dell'annuncio
google_1234567890123456789 // Progress event ID
google_5555555555123456789 // First Quartile event ID
Oggetto tag di esempio
{
"google_5555555555":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"firstquartile"
},
"google_1234567890123456789":{
"ad":"0000229834_ad1",
"ad_break_id":"0000229834",
"type":"progress"
},
...
}
Invia ping di verifica dei contenuti multimediali
Un ping di verifica dei contenuti multimediali deve essere inviato ad Ad Manager ogni volta che viene ricevuto un evento dell'annuncio di tipo diverso da progress
.
Per generare l'URL completo di verifica dei contenuti multimediali di un evento annuncio, aggiungi l'ID evento dell'annuncio completo al valore media_verification_url
dalla risposta della registrazione dello streaming.
Effettua una richiesta GET con l'URL completo. Se la richiesta di verifica ha esito positivo, riceverai una risposta HTTP con il codice di stato 202
.
In caso contrario, verrà visualizzato il codice di errore HTTP 404
.
Richiesta di esempio (cURL)
curl https://{...}/media/google_5555555555123456789
Esempio di risposta riuscita
HTTP/1.1 202 Accepted