Utilizzare l'SDK IMA DAI con un client HTML5

Riproduci gli stream VOD registrati con l'API Google Cloud Video Stitcher

Questa guida mostra come utilizzare l'SDK IMA DAI per HTML5 per richiedere e riprodurre una sessione di streaming VOD di Google Cloud.

Questa guida amplia l'esempio di base riportato nella guida introduttiva per l'IMA DAI.

Per informazioni sull'integrazione con altre piattaforme o sull'utilizzo degli SDK lato client IMA, consulta SDK Interactive Media Ads.

Per visualizzare o seguire un'integrazione di esempio completata, scarica l'esempio di strumentazione di stitching video di Cloud per HLS o DASH.

Configura un progetto Google Cloud

Inserisci le seguenti variabili da utilizzare nell'SDK IMA:

Località
La regione Google Cloud in cui è stata creata la configurazione VOD: LOCATION
Numero progetto
Il numero del progetto Google Cloud che utilizza l'API Video Stitcher: PROJECT_NUMBER
Token OAuth

Il token OAuth a breve termine di un account di servizio con il ruolo utente Video Stitcher:

OAUTH_TOKEN

Scopri di più sulla creazione di token OAuth di breve durata. Il token OAuth può essere riutilizzato in più richieste, a condizione che non sia scaduto.

Codice di rete

Il codice di rete Ad Manager per la richiesta di annunci: NETWORK_CODE

ID configurazione VOD

L'ID configurazione VOD per lo stream VOD: VOD_CONFIG_ID

Scopri di più sulla creazione dell'ID di configurazione VOD nella guida alla creazione di una configurazione VOD per l'unione in cloud.

Configurare un ambiente di sviluppo

Le app di esempio IMA mostrano solo le richieste di stream HLS. Puoi comunque utilizzare gli stream DASH per la costruzione della classe VideoStitcherVodStreamRequest. Quando configuri il player compatibile con DASH, devi configurare un ascoltatore per gli eventi di avanzamento del video player che possa fornire i metadati del video a StreamManager.processMetadata(). Questa funzione accetta tre parametri:

  1. type: una stringa che deve essere impostata su 'ID3' per gli stream HLS e su 'urn:google:dai:2018' per gli stream DASH.

  2. data: per i messaggi di eventi DASH, si tratta della stringa di dati del messaggio.

  3. timestamp: un numero che corrisponde all'ora di inizio del messaggio dell'evento per gli stream DASH.

Invia i metadati il prima possibile e con la massima frequenza consentita dagli eventi del player. Se i metadati mancano o non sono corretti, l'SDK IMA DAI potrebbe non attivare gli eventi correlati agli annunci, con conseguente generazione di eventi correlati agli annunci non corretti.

Scarica gli esempi IMA DAI per HTML5 ed estrai il hls_js/simple file ZIP di esempio in una nuova cartella. Questo esempio è un'app web che puoi ospitare localmente a scopo di test.

Per ospitare l'esempio localmente, vai alla nuova cartella ed esegui il seguente comando Python per avviare un server web:

python3 -m http.server 8000

http.server è disponibile solo in Python 3.x. Puoi utilizzare qualsiasi altro server web, come Apache HTTP Server o Node JS.

Apri un browser web e vai alla pagina localhost:8000 per visualizzare un video player. Il browser deve supportare la libreria HLS.js.

Se tutto funziona correttamente, facendo clic sul pulsante Riproduci sul video player viene avviato lo short film "Lacrime d'acciaio", con interruzioni pubblicitarie ogni 30 secondi.

Richiedere uno stream VOD

Per sostituire lo stream di esempio con lo stream VOD con annunci uniti, utilizza la classe VideoStitcherVodStreamRequest per creare automaticamente una sessione di annunci con Google Ad Manager. Puoi utilizzare l'interfaccia utente di Google Ad Manager per individuare le sessioni DAI generate per il monitoraggio e il debug.

Nel sample esistente sono presenti funzioni per richiedere uno stream VOD o un live streaming. Per farlo funzionare con l'API Google Cloud Video Stitcher, devi aggiungere una nuova funzione per restituire un oggetto VideoStitcherVodStreamRequest.

Ecco un esempio:

// StreamManager which will be used to request DAI streams.
let streamManager;
...

function initPlayer() {
  videoElement = document.getElementById('video');
  adUiElement = document.getElementById('adUi');
  streamManager = new google.ima.dai.api.StreamManager(
    videoElement,
    adUiElement
  );
  streamManager.addEventListener(
    [
      google.ima.dai.api.StreamEvent.Type.LOADED,
      google.ima.dai.api.StreamEvent.Type.ERROR,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_STARTED,
      google.ima.dai.api.StreamEvent.Type.AD_BREAK_ENDED
    ],
    onStreamEvent, false);

  hls.on(Hls.Events.FRAG_PARSING_METADATA, function(event, data) {
    if (streamManager && data) {
      // For each ID3 tag in our metadata, we pass in the type - ID3, the
      // tag data (a byte array), and the presentation timestamp (PTS).
      data.samples.forEach(function(sample) {
        streamManager.processMetadata('ID3', sample.data, sample.pts);
      });
    }
  });

  videoElement.addEventListener('pause', () => {
    playButton.style.display = "block";
  });

  playButton.addEventListener('click', initiatePlayback);
}

function initiatePlayback() {
  requestVodVideoStitcherStream();

  playButton.style.display = "none";
  playButton.removeEventListener('click', initiatePlayback);
  playButton.addEventListener('click', resumePlayback);
}
...
function requestVodVideoStitcherStream() {
  const streamRequest = new google.ima.dai.api.VideoStitcherVodStreamRequest();
  streamRequest.vodConfigId = 'VOD_CONFIG_ID';
  streamRequest.region = 'LOCATION';
  streamRequest.projectNumber = 'PROJECT_NUMBER';
  streamRequest.oAuthToken = 'OAUTH_TOKEN';
  streamRequest.networkCode = 'NETWORK_CODE';

  streamManager.requestStream(streamRequest);
}

Ricarica la pagina. Dopodiché, potrai richiedere e riprodurre lo stream VOD personalizzato.

(Facoltativo) Aggiungi opzioni per la sessione di streaming

Personalizza la richiesta di stream aggiungendo opzioni di sessione per eseguire l'override della configurazione predefinita dell'API Cloud Video Stitcher utilizzando VideoStitcherVodStreamRequest.videoStitcherSessionOptions. Se fornisci un'opzione non riconosciuta, l'API Cloud Video Stitcher risponderà con un errore HTTP 400. Per assistenza, consulta la guida alla risoluzione dei problemi.

Ad esempio, puoi sostituire le opzioni manifest con lo snippet di codice seguente, che richiede due manifest di stream con le rappresentazioni ordinate dalla maggiore alla minore velocità in bit.

...

// The following session options are examples. Use session options
// that are compatible with your video stream.
streamRequest.videoStitcherSessionOptions = {
  "manifestOptions": {
    "includeRenditions": [
      {"bitrateBps": 3000, "codecs": "hvc1.1.4.L126.B0, mp4a.40.2"},
      {"bitrateBps": 2000, "codecs": "avc1.64001f, mp4a.40.2"},
    ],
    "bitrateOrder": "ascending"
  }
};

streamManager.requestStream(streamRequest);

Esegui la pulizia

Ora che hai ospitato correttamente uno stream VOD utilizzando l'API Google Cloud Video Stitcher e lo hai richiesto utilizzando l'SDK IMA DAI per HTML5, è importante ripulire le risorse di pubblicazione.

Segui la guida alla pulizia dei contenuti VOD per rimuovere risorse e asset non necessari.

Infine, nella finestra del terminale in cui hai avviato il server web Python 3, utilizza il comando ctrl+C per terminare il server locale.