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 manipolatore di manifest.

Prerequisiti

Prima di continuare, devi disporre di quanto segue:

Effettua una richiesta di stream

Quando l'utente seleziona uno stream, procedi nel seguente modo:

  1. Invia una richiesta POST al metodo del servizio di live streaming. Per maggiori dettagli, consulta 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 stream:

    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'esito è positivo, 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 dello stream e memorizza altri dati per i passaggi successivi.

Metadati degli annunci con sondaggio

Per eseguire il polling dei metadati degli annunci, segui questi passaggi:

  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. Questo processo consente al server di restituire i metadati completi per la registrazione DVR (Digital Video Recorder) dello stream. La registrazione DVR contiene il periodo 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 della risposta più recente.

  4. Nella richiesta successiva, invia questo valore come parametro di query delta_token. Il server restituisce solo i metadati modificati dalla generazione del token. Invia sempre l'ultimo token ricevuto. Non tentare di analizzare, modificare o creare il token. Per maggiori dettagli, consulta 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;
    }
    

    Se l'operazione ha esito positivo, ricevi 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 sono obsolete, 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 il parametro obsolete_ad_break_ids è presente, 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 passare l'ID sessione, consulta la documentazione del manipolatore del manifest. Se sviluppi un manipolatore del manifest, consulta Manipolatore del manifest per il live streaming.

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 player è pronto, avvia la riproduzione.

Ascolta gli eventi degli annunci

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

  • Gli stream HLS con container Transport Stream (TS) utilizzano tag ID3 temporizzati per trasportare i metadati temporizzati. Per maggiori dettagli, consulta Informazioni su Common Media Application Format con HTTP Live Streaming (HLS).

  • Gli stream DASH utilizzano gli elementi EventStream per specificare gli eventi nel manifest.

  • Gli stream DASH utilizzano elementi InbandEventStream quando i segmenti contengono caselle Event Message (emsg) per i dati del payload, 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 i dettagli, consulta la guida alla gestione dei metadati temporizzati.

Per recuperare l'ID evento 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.

    L'esempio seguente 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 degli annunci

Per trovare l'oggetto TagSegment, segui questi passaggi:

  1. Recupera l'oggetto dei metadati dell'annuncio tags da Esegui il polling dei metadati dell'annuncio. L'oggetto tags è un array di oggetti TagSegment.

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

  3. Utilizza i primi 17 caratteri dell'ID evento dell'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 quello in cui i metadati associati diventano 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 sondaggio dei metadati successivo. Mantieni il tag nella coda fino al termine dell'elaborazione.

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

    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.

Invia ping di verifica contenuti multimediali

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

Per generare l'URL di verifica dei media completo di un evento annuncio, segui questi passaggi:

  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 lo strumento Monitoraggio attività di streaming (SAM) per esaminare un log cronologico di tutti gli eventi degli annunci. Per maggiori dettagli, consulta la sezione Monitora e risolvi i problemi di un live streaming.