Preparare il cliente al reindirizzamento della pubblicazione del pod

Questa guida illustra lo sviluppo di un'applicazione client per caricare un live streaming HLS o DASH con l'API Pod Serving e il tuo manipolatore di manifest.

Prerequisiti

Prima di continuare, devi avere:

Effettuare una richiesta di stream

Quando l'utente seleziona uno stream:

  1. Invia una richiesta POST al metodo del servizio di live streaming. Per maggiori dettagli, vedi Metodo: stream.

  2. Trasmetti i parametri di targeting degli annunci nei formati application/x-www-form-urlencoded o application/json. Questa richiesta registra una sessione di streaming con Google DAI.

    L'esempio seguente effettua una richiesta di flusso:

    Codifica del modulo

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const params = new URLSearchParams({
        cust_params: 'section=sports&page=golf,tennis'
}).toString();

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded'
        },
        body: params
});

console.log(await response.json());

    Codifica JSON

    const url = `https://dai.google.com/ssai/pods/api/v1/` +
      `network/NETWORK_CODE/custom_asset/CUSTOM_ASSET_KEY/stream`;

const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({
          cust_params: {
            section: 'sports',
            page: 'golf,tennis'
          }
        })
});

console.log(await response.json());

    Se l'operazione va a buon fine, viene visualizzato un output simile al seguente:

    {
"stream_id": "c4a5dad5-aaa8-4550-8acb-7cda3cdb21bb:DLS",
"media_verification_url": "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/",
"metadata_url": "https://dai.google.com/linear/pods/hls/.../metadata",
"session_update_url": "https://dai.google.com/linear/.../session",
"polling_frequency": 10
}

  3. Nella risposta JSON, individua l'ID sessione stream e archivia gli altri dati per i passaggi successivi.

Metadati dell'annuncio sondaggio

Per eseguire il polling dei metadati dell'annuncio:

  1. Leggi il valore metadata_url dalla risposta di registrazione dello stream.

  2. Invia una richiesta GET iniziale all'endpoint metadata_url.

    • Ometti il parametro di query delta_token. Questa procedura consente al server di restituire i metadati completi per la finestra del Digital Video Recorder (DVR) dello stream. La finestra del DVR contiene l'intervallo di tempo della trasmissione disponibile per la riproduzione e il riavvolgimento da parte di uno spettatore. La risposta include un campo next_delta_token.

  3. Per ottimizzare la larghezza di banda, memorizza il valore next_delta_token dell'ultima risposta.

  4. Nella richiesta successiva, invia questo valore come parametro di query delta_token. Il server restituisce solo i metadati modificati da quando è stato generato il token. Invia sempre il token più recente che hai ricevuto. Non tentare di analizzare, modificare o costruire il token. Per i dettagli, vedi Metodo: metadati.

    L'esempio seguente recupera i metadati dell'annuncio:

    // Initial request (returns full metadata and next_delta_token)
let response = await fetch(metadata_url);
let metadata = await response.json();
let deltaToken = metadata.next_delta_token;

// Subsequent request (returns only changes since deltaToken)
if (deltaToken) {
  const url = new URL(metadata_url);
  url.searchParams.append('delta_token', deltaToken);
  response = await fetch(url.toString());
  const deltaMetadata = await response.json();
  // Merge deltaMetadata into your local cache
  mergeMetadata(metadata, deltaMetadata);
  deltaToken = deltaMetadata.next_delta_token;
}

    In caso di esito positivo, riceverai la risposta PodMetadata. Se fornisci il parametro delta_token, la risposta contiene solo gli annunci, le interruzioni pubblicitarie e i tag che il server ha aggiunto o aggiornato da quando ha generato il token. La risposta contiene anche un nuovo valore next_delta_token. Se alcune interruzioni pubblicitarie non sono aggiornate, la risposta include anche un elenco obsolete_ad_break_ids delle interruzioni pubblicitarie da rimuovere dalla cache.

    {
  "next_delta_token": "eyJyYW5nZXMiOlt7InMiOjEsImUiOjN9XX0",
  "obsolete_ad_break_ids": ["0003069407"],
  "tags":{
    "google_1022389921":{
      "ad":"0003069408_ad1",
      "ad_break_id":"0003069408",
      "type":"start"
    },
    ...
  },
  "ads":{
    "0003069408_ad1":{
      "ad_break_id":"0003069408",
      "position":1,
      "duration":10.01,
      "title":"External - Pod Midroll 1",
      "clickthrough_url":"https://.../",
      ...
    },
    ...
  },
  "ad_breaks":{
    "0003069408":{
      "type":"mid",
      "duration":30,
      "ads":3
    },
    ...
  }
}

  5. Salva l'oggetto tags e unisci gli aggiornamenti nella cache locale. Se è presente il parametro obsolete_ad_break_ids, rimuovi le interruzioni pubblicitarie e gli annunci e i tag associati dalla cache.

  6. Imposta un timer utilizzando il valore polling_frequency per richiedere regolarmente i metadati. In ogni sondaggio, invia il valore next_delta_token restituito nella risposta dei metadati più recente come parametro di query delta_token.

Carica lo stream nel video player

Dopo aver ottenuto l'ID sessione dalla risposta di registrazione, passalo al manipolatore del manifest o crea un URL del manifest per caricare lo stream in un video player.

Per trasmettere l'ID sessione, consulta la documentazione del manipolatore del manifest. Se sviluppi un manipolatore di manifest, consulta Manipolatore di manifest per livestream.

L'esempio seguente assembla un URL del manifest:

https://<your_manifest_manipulator_url>/manifest.m3u8?DAI_stream_ID=SESSION_ID&network_code=NETWORK_CODE&DAI_custom_asset_key=CUSTOM_ASSET_KEY"

Quando il lettore è pronto, inizia la riproduzione.

Ascolta gli eventi degli annunci

Controlla il formato del contenitore dello stream per i metadati temporizzati:

  • Gli stream HLS con contenitori Transport Stream (TS) utilizzano tag ID3 temporizzati per trasportare metadati temporizzati. Per informazioni dettagliate, vedi Informazioni su Common Media Application Format con HTTP Live Streaming (HLS).

  • I flussi DASH utilizzano gli elementi EventStream per specificare gli eventi nel manifest.

  • Gli stream DASH utilizzano elementi InbandEventStream quando i segmenti contengono caselle di messaggi evento (emsg) per i dati utili, inclusi i tag ID3. Per i dettagli, consulta InbandEventStream.

  • Gli stream CMAF, inclusi DASH e HLS, utilizzano caselle emsg contenenti tag ID3.

Per recuperare i tag ID3 dal tuo stream, consulta la guida del tuo video player. Per maggiori dettagli, consulta la guida alla gestione dei metadati temporizzati.

Per recuperare l'ID evento dell'annuncio dai tag ID3:

  1. Filtra gli eventi per scheme_id_uri con urn:google:dai:2018 o https://aomedia.org/emsg/ID3.

  2. Estrai l'array di byte dal campo message_data.

    Il seguente esempio decodifica i dati emsg in JSON:

    {
  "scheme_id_uri": "https://developer.apple.com/streaming/emsg-id3",
  "presentation_time": 27554,
  "timescale": 1000,
  "message_data": "ID3TXXXgoogle_1022389921",
  ...
}

  3. Filtra i tag ID3 con il formato TXXXgoogle_{ad_event_ID}:

    TXXXgoogle_1022389921

Mostra i dati sugli eventi dell'annuncio

Per trovare l'oggetto TagSegment:

  1. Recupera l'oggetto tags dei metadati dell'annuncio da Poll ad metadata. L'oggetto tags è un array di oggetti TagSegment.

  2. Utilizza l'ID evento dell'annuncio completo per trovare un oggetto TagSegment con il tipo progress.

  3. Utilizza i primi 17 caratteri dell'ID evento annuncio per trovare un oggetto TagSegment di altri tipi.

    Poiché l'app client esegue periodicamente il polling dei metadati degli annunci, potrebbe verificarsi un ritardo tra il momento in cui il video player rileva un tag ID3 nello stream e il momento in cui i metadati associati sono disponibili. Se l'app client non trova un tag ID3 nei tag archiviati, mantieni il tag in una coda ed elaboralo di nuovo dopo il successivo polling dei metadati. Mantieni il tag in coda fino al termine dell'elaborazione.

  4. Dopo aver ottenuto TagSegment, utilizza la proprietà ad_break_id come chiave per trovare l'oggetto AdBreak nell'oggetto ad_breaks dei metadati dell'annuncio.

    L'esempio seguente trova un oggetto AdBreak:

    {
  "type":"mid",
  "duration":15,
  "ads":1
}

  5. Utilizza i dati TagSegment e AdBreak per mostrare informazioni sulla posizione dell'annuncio nell'interruzione pubblicitaria. Ad esempio: Ad 1 of 3.

Inviare ping di verifica dei contenuti multimediali

Per ogni evento dell'annuncio, ad eccezione del tipo progress, invia un ping di verifica dei contenuti multimediali. Google DAI scarta gli eventi progress e l'invio frequente di questi eventi potrebbe influire sulle prestazioni dell'app.

Per generare l'URL di verifica media completo di un evento dell'annuncio, procedi nel seguente modo:

  1. Dalla risposta dello stream, aggiungi l'ID evento annuncio completo al valore media_verification_url.

  2. Invia una richiesta GET con l'URL completo:

    // media_verification_url: "https://dai.google.com/view/.../event/c14aZDWtQg-ZwQaEGl6bYA/media/"
const completeUrl = `${media_verification_url}google_1022389921`;

const response = await fetch(completeUrl);

    In caso di esito positivo, ricevi una risposta con codice di stato 202. In caso contrario, riceverai un codice di errore 404.

Puoi utilizzare il Monitoraggio attività di streaming (Stream Activity Monitor, SAM) per esaminare un log cronologico di tutti gli eventi pubblicitari. Per maggiori dettagli, vedi Monitorare e risolvere i problemi di un live streaming.