App client di video player per i live streaming

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

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/an-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. A sua volta, riceverai 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:

ad L'ID di un annuncio corrispondente a una chiave nell'oggetto ads.
ad_break_id L'ID di un'interruzione pubblicitaria corrispondente a una chiave nell'oggetto ad_breaks.
type Il tipo di evento dell'annuncio. I tipi di eventi dell'annuncio sono:
start Attivato all'inizio dell'annuncio.
firstquartile Attivato alla fine del primo quartile.
midpoint Attivata nel punto centrale dell'annuncio.
thirdquartile Attivato alla fine del terzo quartile.
complete Attivato alla fine dell'annuncio.
progress Attivati periodicamente durante l'annuncio per notificare all'app che è in corso un'interruzione pubblicitaria.
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_break_id L'ID di un'interruzione pubblicitaria corrispondente a una chiave nell'oggetto ad_breaks.
position La posizione in cui l'annuncio viene visualizzato all'interno dell'insieme di annunci nell'interruzione pubblicitaria, espressa in secondi in virgola mobile.
duration La durata dell'annuncio in secondi in virgola mobile.
clickthrough_url L'URL che dovrebbe aprirsi quando un utente interagisce con questo annuncio, se supportato.
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:
type Il tipo di interruzione pubblicitaria. I tipi di interruzione pubblicitaria sono pre (pre-roll), mid (mid-roll) e post (post-roll).
duration La durata dell'interruzione pubblicitaria in secondi in virgola mobile.
ads Il numero di annunci in questa interruzione pubblicitaria.

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:

  1. 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 oggetti ad e ad_break associati. Questi eventi devono essere di tipo progress.

    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 oggetti ad e ad_break associati. Verranno recuperati tutti gli eventi di tipo diverso da progress.

  2. Usa queste informazioni recuperate per aggiornare l'interfaccia utente del player. Ad esempio, quando ricevi un evento start o il primo evento progress, 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 a sua volta 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

Risorse aggiuntive