App video player client per gli stream VOD

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

Questa guida mostra 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 gli stream 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 gli stream VOD, completa i seguenti passaggi:

Inviare una richiesta di registrazione dello stream ad Ad Manager

Invia una richiesta POST all'endpoint di registrazione dello stream. A tua volta, ricevi 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: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parametri del percorso

{network_code} Il tuo codice di rete Google Ad Manager 360

Parametri del corpo JSON

targeting_parameters Un oggetto JSON contenente i parametri di targeting dell'annuncio. Obbligatorio

JSON della risposta

media_verification_url L'URL di base per eseguire il ping degli eventi di monitoraggio della riproduzione. Un URL di verifica dei contenuti multimediali completo viene formato aggiungendo un ID evento 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 Il tempo rimanente fino 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, come stringa data/ora ISO 8601 nel formato yyyy-MM-dd'T'hh:mm:ss.sssssssss[+|-]hh:mm.

Richiesta di esempio (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"url":"http://example.com"}}' \
     -H 'Content-Type: application/json' \
  https://dai.google.com/ondemand/pods/api/v1/network/21775744923/stream_registration

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, vengono restituiti codici di errore HTTP standard senza testo della risposta JSON.

Analizza la risposta JSON e memorizza i valori pertinenti.

Richiedi il manifest dello stream dal manipolatore del manifest

Ogni manipolatore di manifest ha formati di richiesta e risposta diversi. Contatta il fornitore del manipolatore per conoscere i suoi requisiti specifici. Se stai implementando il tuo manipolatore manifest, leggi la guida al manipolatore manifest per conoscere i requisiti di questo componente.

In generale, devi passare l'ID stream restituito dall'endpoint di registrazione riportato sopra al tuo manipolatore di manifest affinché possa creare manifest specifici per la sessione. A meno che non sia specificato esplicitamente dal manipolatore del manifest, la risposta alla richiesta del manifest è uno stream video contenente sia contenuti che annunci.

Richiesta di esempio (cURL)

curl https://{manifest_manipulator}/video/1331997/stream/6e69425c-0ac5-43ef-b070-c5143ba68541:CHS/vod_manifest.m3u8

Risposta di esempio (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 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

Invia una richiesta di GET all'indirizzo metadata_url che hai ricevuto nel passaggio 1. Questo passaggio deve avvenire dopo aver ricevuto il manifest unito dal tuo manipolatore di manifest. In cambio, ricevi un oggetto JSON contenente i seguenti parametri:

tags Un insieme di coppie chiave-valore contenente tutti gli eventi correlati agli annunci visualizzati nello stream. Le chiavi sono i primi 17 caratteri di un ID evento pubblicitario visualizzati nei metadati a tempo dello stream o, nel caso di eventi di tipo progress, l'ID evento pubblicitario 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 dell'annuncio che corrisponde 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 Viene attivato alla fine del primo quartile.
midpoint Attivato a metà dell'annuncio.
thirdquartile Viene attivato alla fine del terzo quartile.
complete Attivato alla fine dell'annuncio.
progress Viene attivato 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 corrispondenti ai valori trovati nell'oggetto tags elencato sopra. Ogni valore è un oggetto contenente i seguenti parametri:
ad_break_id L'ID di un'interruzione dell'annuncio che corrisponde a una chiave nell'oggetto ad_breaks.
position La posizione in cui viene visualizzato questo annuncio nell'insieme di annunci nell'interruzione pubblicitaria, in secondi con virgola mobile.
duration La durata dell'annuncio in secondi con virgola mobile.
clickthrough_url L'URL che deve essere aperto 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 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 interruzioni pubblicitarie sono pre (pre-roll), mid (mid-roll) e post (post-roll).
duration La durata dell'interruzione pubblicitaria in secondi con virgola mobile.
ads Il numero di annunci in questa interruzione pubblicitaria.

Memorizza questi valori da associare agli eventi dei metadati con temporizzazione 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 correlati agli annunci

Ascolta i metadati con temporizzazione tramite gli eventi correlati agli annunci attivati nello stream audio/video del tuo video player.

Per gli stream MPEG-TS, i metadati vengono visualizzati come tag ID3 v2.3 in banda. Ogni tag dei metadati ha l'ID TXXX e il valore inizia con la stringa google_ followed by a series of characters. Questo valore è l'ID evento 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 banda che simulano i tag ID3 v2.3. Ogni casella emsg 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 inizia con ID3TXXXgoogle_. Questo valore message_data, senza il prefisso ID3TXXX, è l'ID evento annuncio.

Esempio di casella di messaggio elettronico

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

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

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

Aggiornare l'interfaccia utente dell'app di riproduzione video del client

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

  1. Controlla se nell'oggetto tags è presente una chiave corrispondente all'ID evento annuncio completo. Se viene trovata una corrispondenza, recupera il tipo di evento e gli oggetti ad e ad_break associati. Questi eventi devono avere il tipo progress.

    Se non viene trovata una corrispondenza per l'ID evento annuncio completo, controlla se nell'oggetto tags è presente una chiave corrispondente ai primi 17 caratteri dell'ID evento annuncio. Recupera il tipo di evento e gli oggetti ad e ad_break associati. Dovresti recuperare tutti gli eventi con tipi diversi da progress.

  2. Utilizza le 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"
  },
  ...
}

Inviare ping di verifica dei contenuti multimediali

Un ping di verifica dei media deve essere inviato ad Ad Manager ogni volta che viene ricevuto un evento correlato all'annuncio con un tipo diverso da progress.

Per generare l'URL completo di verifica dei contenuti multimediali di un evento correlato agli annunci, aggiungi l'ID evento correlato agli annunci completo al valore media_verification_url della risposta alla registrazione dello stream.

Invia una richiesta GET con l'URL completo. Se la richiesta di verifica va a buon fine, ricevi 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 corretta

HTTP/1.1 202 Accepted

Risorse aggiuntive