App client di video player per i live streaming

L'API DAI Pod Serving di Google ti consente di eseguire l'inserimento di annunci lato server da Google Ads mantenendo il controllo dell'unione dei video.

Questa guida mostra come interagire con l'API Pod Serving e ottenere una funzionalità simile con l'SDK IMA DAI. Per domande specifiche su funzionalità supportata, contatta il tuo account manager Google.

L'API Pod Serving supporta gli stream di pod in HLS o MPEG-DASH protocolli di streaming. Questa guida si concentra sugli stream HLS ed evidenzia i principali differenze tra HLS e MPEG-DASH in passaggi specifici.

Per integrare l'API Pod Serving nella tua app per gli stream VOD, completa la seguenti passaggi:

Effettuare una richiesta di registrazione dello streaming all'API DAI Pod Serving

Effettua una richiesta POST all'endpoint di registrazione dello streaming. Ricevi a sua volta Risposta JSON contenente l'ID stream da inviare alla manipolazione del manifest e gli endpoint associati dell'API Pod Serving.

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 all'evento in Google Ad Manager.

Parametri del corpo con codifica con modulo

Un insieme facoltativo di codifica nel modulo parametri di targeting .

JSON risposta

media_verification_url L'URL di base per inviare un ping agli eventi di monitoraggio della riproduzione. Una verifica dei contenuti multimediali completa L'URL viene creato aggiungendo un ID evento dell'annuncio a questo URL di base.
metadata_url L'URL per richiedere i metadati dei pod di annunci.
stream_id La stringa utilizzata per identificare la sessione di streaming corrente.
valid_for La quantità di tempo restante prima della scadenza della sessione di streaming corrente, tra Formato dhms (giorni, ore, minuti, secondi). Ad esempio: 2h0m0.000s rappresenta una durata di 2 ore.
valid_until L'ora in cui scade la sessione di streaming corrente, indicata come ISO 8601 stringa data/ora in yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm formato.

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/ssai/pods/api/v1/network/51636543/custom_asset/ext-doc-ps-redirect-hls/stream

Esempio di risposta

{
  "stream_id":"9fe8fe4f-f12e-4fed-b509-0ca269bb1668:TUL",
  "media_verification_url":"https://dai.google.com/.../media/",
  "metadata_url":"https://dai.google.com/.../metadata",
  "session_update_url":"https://dai.google.com/.../session",
  "polling_frequency":10
}

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

Analizza la risposta JSON e archivia i valori pertinenti.

Richiedere il manifest dello stream dal manipolatore del manifest

Ogni manipolatore del manifest ha formati di richiesta e risposta diversi. Contatto il tuo fornitore di manipolatori per comprenderne i requisiti specifici. Se se implementi il tuo manipolatore del manifest, leggi il per comprendere requisiti per questo componente.

In generale, devi passare l'ID stream restituito di registrazione dell'endpoint precedente al manipolatore del manifest per creare specifici della sessione. Se non diversamente indicato dal file manifest manipolatore, la risposta alla richiesta del file manifest è uno stream video contenente sia di contenuti che di 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

Riprodurre lo stream

Carica il manifest ricevuto dal server di manipolazione del manifest in un video player e avvia la riproduzione.

Sondaggio per i nuovi metadati dell'interruzione pubblicitaria

L'applicazione è responsabile del recupero dei metadati per ogni interruzione pubblicitaria, quindi individua le impressioni da attivare. A questo scopo, imposterai una timer per eseguire regolarmente il polling delle API DAI metadata_url per il nuovo annuncio informazioni. L'intervallo per il polling è specificato nel criterio polling_frequency nella risposta della registrazione dello stream.

Riceverai in cambio un oggetto JSON contenente i seguenti parametri:

tags Un insieme di coppie chiave-valore contenenti tutti gli eventi annuncio che compaiono nella flusso di dati. Le chiavi sono i primi 17 caratteri di un evento dell'annuncio ID che compare nei metadati sincronizzati dello stream o, nel caso di eventi, di tipo progress, l'ID evento annuncio completo.

Ogni valore è un oggetto contenente i seguenti parametri:

ad L'ID di un annuncio che corrisponde a una chiave nell'oggetto ads.
ad_break_id L'ID di un'interruzione pubblicitaria che corrisponde a una chiave in 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 Attivato nel punto centrale dell'annuncio.
thirdquartile Attivato alla fine del terzo quartile.
complete Attivato alla fine dell'annuncio.
progress Attivato periodicamente nel corso dell'annuncio per notificare all'app che un annuncio pausa.
ads Una serie di coppie chiave/valore che descrivono tutti gli annunci visualizzati nello stream. La Le chiavi sono ID annuncio corrispondenti ai valori presenti nell'oggetto tags elencati sopra. Ogni valore è un oggetto contenente i seguenti parametri:
ad_break_id L'ID di un'interruzione pubblicitaria che corrisponde a una chiave in ad_breaks .
position La posizione in cui l'annuncio viene visualizzato nell'insieme di annunci dell'annuncio in virgola mobile, in secondi.
duration Durata dell'annuncio in secondi con rappresentazione 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 delle interruzioni pubblicitarie che corrispondono ai valori presenti nella sezione tags e ads oggetti elencati sopra. Ogni valore è un oggetto che contengono 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 con rappresentazione in virgola mobile.
ads Il numero di annunci in questa interruzione pubblicitaria.

Archivia questi valori dopo ogni sondaggio per associare eventi di metadati a tempo all'interno di nel tuo 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
    },
    ...
  }
}

Monitora eventi relativi agli annunci

Ascolta i metadati a tempo tramite eventi annuncio attivati nello stream audio/video del video player.

Per gli stream MPEG-TS, i metadati vengono visualizzati come tag ID3 v2.3 in banda. Ciascuna Il tag di metadati ha l'ID TXXX e il valore inizia con la stringa google_ seguito 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 riservata al "testo definito dall'utente".

Tag ID3 di esempio

TXXXgoogle_1234567890123456789

Per gli stream MP4, vengono inviati come eventi di emsg in banda che emulano ID3 v2.3 i tag. Ogni casella di posta elettronica pertinente ha un valore scheme_id_uri di https://aomedia.org/emsg/ID3 o https://developer.apple.com/streaming/emsg-id3 e un valore message_data che iniziano con ID3TXXXgoogle_. Questo valore message_data, senza il valore ID3TXXX, è l'ID evento dell'annuncio.

Casella di messaggio di esempio

La struttura dei dati potrebbe variare a seconda della raccolta del media player.

Se l'ID evento dell'annuncio è google_1234567890123456789, la risposta sarà simile a questo:

{
  "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 emsg che emulano ID3 come tag ID3 nativi. In questo caso, gli stream MP4 presentano tag ID3 identici come MPEG_TS.

Aggiorna l'UI dell'app del video player client

Ogni ID evento dell'annuncio può essere abbinato a una chiave nell'oggetto tags nel passaggio 4. La corrispondenza di questi valori è un processo in due fasi:

  1. Cerca nell'oggetto tags una chiave corrispondente all'ID evento dell'annuncio completo. Se viene trovata una corrispondenza, recupera il tipo di evento e i relativi ad associati ad_break oggetti. Questi eventi devono essere di tipo progress.

    Se non viene trovata una corrispondenza per l'ID evento dell'annuncio completo, controlla la tags di 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. Dovrebbero essere recuperati tutti gli eventi di tipo diverso da progress.

  2. Usa le informazioni recuperate per aggiornare l'UI del player. Ad esempio, quando ricevi un evento start o il primo progress, nascondi la ricerca del giocatore e visualizza un overlay che descrive la posizione dell'annuncio corrente pausa, ad esempio: "Annuncio 1 di 3".

ID eventi annuncio di esempio

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 media deve essere inviato ad Ad Manager ogni volta che si verifica un evento dell'annuncio. di tipo diverso da progress.

Per generare l'URL di verifica dei media completo per un evento dell'annuncio, aggiungi l'URL completo l'ID evento dell'annuncio nel valore media_verification_url della registrazione dello stream. la risposta corretta.

Effettua una richiesta GET con l'URL completo. Se la richiesta di verifica è operazione completata, riceverai una risposta HTTP con il codice di stato 202. In caso contrario, viene 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