App video player client per gli stream VOD

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:

Inviare una richiesta di registrazione dello stream ad Ad Manager

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: /ondemand/pods/api/v1/network/{network_code}/stream_registration
Host: dai.google.com
Content-Type: application/json

Parametri del percorso

Parametri corpo JSON

JSON risposta

Richiesta di esempio (cURL)

curl -X POST \
     -d '{"targeting_parameters":{"cmsid":"12345","vid":"sample-video"}}' \
     -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 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.

Richiedere i metadati dei pod di annunci da Ad Manager

Invia una richiesta GET al metadata_url che hai ricevuto nel primo passaggio. Questo deve avvenire dopo aver ricevuto il file manifest unito dal file manifest manipolatore. In cambio, ricevi un oggetto JSON contenente quanto segue: parametri:

Archivia questi valori da associare agli eventi di metadati a tempo all'interno del video flusso di dati.

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 un'interruzione pubblicitaria, 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

• Documentazione sull'SDK IMA
• Tipi di implementazione del player DAI Confronto