Aggiungi il supporto dell'API Ad Breaks a un ricevitore web

1. Panoramica

Questo codelab illustra come creare un'app di ricezione web personalizzata che utilizza l'API Cast Ad Breaks.

Che cos'è Google Cast?

Google Cast consente agli utenti di trasmettere contenuti da un dispositivo mobile a una TV. Gli utenti potranno quindi utilizzare il proprio dispositivo mobile come telecomando per riprodurre contenuti multimediali sulla TV.

L'SDK Google Cast ti consente di estendere la tua app per controllare una TV o un impianto audio. L'SDK Cast ti consente di aggiungere i componenti dell'interfaccia utente necessari in base all'elenco di controllo per la progettazione di Google Cast.

L'elenco di controllo per il design di Google Cast viene fornito per standardizzare le implementazioni di Google Cast in modo da rendere l'esperienza utente intuitiva su tutte le piattaforme supportate.

Cosa realizzeremo?

Una volta completato questo codelab, avrai creato un ricevitore di trasmissione che sfrutta l'API Break.

Obiettivi didattici

• Come includere interruzioni VMAP e VAST nei contenuti per Cast
• Come saltare i clip delle interruzioni
• Come personalizzare il comportamento di interruzione predefinito durante la ricerca

Che cosa ti serve

• Versione più recente del browser Google Chrome.
• Servizio di hosting HTTPS come Firebase Hosting o ngrok.
• Un dispositivo Google Cast, ad esempio Chromecast o Android TV, configurato con accesso a internet.
• Una TV o un monitor con ingresso HDMI oppure Google Home Hub

Esperienza

Assicurati di avere la seguente esperienza prima di continuare questo codelab.

• Conoscenze generali sullo sviluppo web.
• Creazione di applicazioni per ricevitore web Cast in corso...

2. recupera il codice campione

Scarica tutto il codice campione sul tuo computer...

file_downloadScarica il codice sorgente

e decomprimi il file ZIP scaricato.

3. Esegui il deployment del ricevitore in locale

Per poter utilizzare il ricevitore web con un dispositivo di trasmissione, il ricevitore deve essere ospitato in un luogo dove il dispositivo di trasmissione può raggiungerlo. Se è già disponibile un server che supporta https, ignora le seguenti istruzioni e prendi nota dell'URL, che ti servirà nella sezione successiva.

Se non disponi di un server disponibile per l'uso, puoi utilizzare Firebase Hosting o ngrok.

Esegui il server

Dopo aver configurato il servizio che preferisci, accedi a app-start e avvia il server.

Prendi nota dell'URL del ricevitore ospitato. Lo utilizzerai nella prossima sezione.

4. Registrare un'applicazione in Cast Console per gli sviluppatori

Devi registrare la tua applicazione per poter eseguire un ricevitore personalizzato, come integrato in questo codelab, sui dispositivi Chromecast. Dopo aver registrato l'applicazione, viene generato un ID applicazione che indica che l'applicazione mittente deve essere configurata per avviare l'applicazione Web ricevitore.

Fai clic su "Aggiungi nuova applicazione"

Seleziona "Ricevitore personalizzato": ecco cosa stiamo creando.

Inserisci i dettagli del nuovo destinatario. Assicurati di utilizzare l'URL che rimanda al punto in cui intendi ospitare l'applicazione di ricezione web. Prendi nota dell'ID applicazione generato dalla console dopo aver registrato l'applicazione. L'applicazione del mittente verrà configurata per utilizzare questo identificatore in una sezione successiva.

Devi anche registrare un dispositivo Google Cast in modo che possa accedere all'applicazione ricevitore prima di pubblicarla. Una volta pubblicata, l'applicazione ricevitore sarà disponibile per tutti i dispositivi Google Cast. Ai fini di questo codelab, è consigliabile lavorare con un'applicazione di ricezione non pubblicata.

Fai clic su "Aggiungi nuovo dispositivo"

Inserisci il numero di serie stampato sul retro del dispositivo di trasmissione e assegna un nome descrittivo. Puoi trovare il numero di serie anche trasmettendo lo schermo in Chrome quando accedi alla Console per gli sviluppatori dell'SDK Google Cast

Occorrono 5-15 minuti prima che il ricevitore e il dispositivo siano pronti per il test. Dopo aver atteso 5-15 minuti, devi riavviare il dispositivo di trasmissione.

5. Prepara l'inizio del progetto

Prima di iniziare questo codelab, potrebbe essere utile consultare la guida per gli sviluppatori di annunci, che fornisce una panoramica delle API per le interruzioni pubblicitarie.

All'app di avvio scaricata è necessario aggiungere il supporto per Google Cast. Ecco la terminologia di Google Cast utilizzata in questo codelab:

• un'app di mittente viene eseguita su un dispositivo mobile o un laptop
• sul dispositivo Google Cast viene eseguita un'app di ricevitore.

Ora è tutto pronto per basarti sul progetto di partenza utilizzando il tuo editor di testo preferito:

1. Seleziona la directory app-start dal download del codice di esempio.
2. Apri js/receiver.js e index.html

Tieni presente che, mentre lavori a questo codelab, la soluzione di hosting web che hai scelto dovrebbe essere aggiornata con le modifiche apportate. Assicurati di eseguire il push delle modifiche al sito host quando continui a convalidarle e testarle.

Design dell'app

Come già detto, il codelab utilizza un'applicazione mittente per avviare una sessione di trasmissione e un'applicazione ricevente che verrà modificata in modo da utilizzare le API di interruzione pubblicitaria.

In questo codelab, lo strumento Cast e comando agirà da mittente web per avviare l'app di destinazione. Per iniziare, apri lo strumento in un browser Chrome. Inserisci l'ID app destinatario che hai ricevuto nella Console per gli sviluppatori dell'SDK Cast e fai clic su Imposta per configurare l'app del mittente per i test.

Nota: se l'icona Trasmetti non viene visualizzata, assicurati che il ricevitore web e i dispositivi di trasmissione siano registrati correttamente in Cast Developer Console. Se non l'hai ancora fatto, spegni e riaccendi tutti i dispositivi di trasmissione appena registrati.

L'app ricevente è l'elemento principale di questo codelab ed è composta da una vista principale definita in index.html e da un file JavaScript chiamato js/receiver.js. Questi aspetti sono descritti in maggiore dettaglio di seguito.

index.html

Questo file HTML contiene l'interfaccia utente dell'app ricevitore fornita dall'elemento cast-media-player. Carica anche le librerie CAF SDK e Cast Debug Logger.

receiver.js

Questo script gestisce tutte le logiche dell'app ricevitore. Al momento contiene un ricevitore CAF di base per inizializzare il contesto di trasmissione e caricare un asset video al momento dell'inizializzazione. Sono state aggiunte anche alcune funzionalità del logger di debug per fornire nuovamente i log allo strumento di trasmissione e comando.

6. Aggiungi VMAP ai tuoi contenuti

L'SDK Cast WebRicevir supporta gli annunci specificati tramite le Playlist di annunci video digitali multipli, note anche come VMAP. La struttura XML specifica le interruzioni pubblicitarie di un contenuto multimediale e i metadati del clip di interruzione associati. Per inserire questi annunci, l'SDK fornisce la proprietà vmapAdsRequest nell'oggetto MediaInformation.

Nel file js/receiver.js, crea un oggetto VastAdsRequest. Individua la funzione LOAD request intercettatore e sostituiscila con il codice riportato di seguito. Contiene un URL di tag VMAP di esempio di DoubleClick e fornisce un valore correlator casuale per garantire che le richieste successive allo stesso URL generino un modello XML con interruzioni pubblicitarie che non sono state ancora controllate.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      const vmapUrl =
          'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
          Math.floor(Math.random() * Math.pow(10, 10));
      let vmapRequest = new cast.framework.messages.VastAdsRequest();
      vmapRequest.adTagUrl = vmapUrl;
      loadRequestData.media.vmapAdsRequest = vmapRequest;

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Salva le modifiche apportate a js/receiver.js e carica il file sul server web. Avvia una sessione di trasmissione nello strumento di trasmissione e comando facendo clic sull'icona Trasmetti. Dovrebbero essere riprodotti gli annunci VMAP, seguiti dai contenuti principali.

7. Aggiungi VAST ai tuoi contenuti

Come accennato in precedenza, l'SDK Web receiver supporta molti tipi di annunci. Questa sezione illustra le API disponibili per integrare gli annunci Digital Video Ad Serving Template, noti anche come VAST. Se hai implementato il codice VMAP della sezione precedente, commentalo.

Copia quanto segue nel file js/receiver.js dopo l'intercettatore della richiesta di carico. Contiene sei clip di interruzione VAST di DoubleClick e un valore correlator casuale. Questi clip di interruzione sono assegnati a cinque interruzioni. Il valore position di ogni interruzione è impostato su un tempo in secondi relativo ai contenuti principali, incluse le interruzioni pre-roll (position impostato su 0) e post-roll (position impostato su -1).

const addVASTBreaksToMedia = (mediaInformation) => {
  mediaInformation.breakClips = [
    {
      id: 'bc1',
      title: 'bc1 (Pre-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('preroll')
      }
    },
    {
      id: 'bc2',
      title: 'bc2 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc3',
      title: 'bc3 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc4',
      title: 'bc4 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc5',
      title: 'bc5 (Mid-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('midroll')
      }
    },
    {
      id: 'bc6',
      title: 'bc6 (Post-roll)',
      vastAdsRequest: {
        adTagUrl: generateVastUrl('postroll')
      }
    }
  ];

  mediaInformation.breaks = [
    {id: 'b1', breakClipIds: ['bc1'], position: 0},
    {id: 'b2', breakClipIds: ['bc2'], position: 15},
    {id: 'b3', breakClipIds: ['bc3', 'bc4'], position: 60},
    {id: 'b4', breakClipIds: ['bc5'], position: 100},
    {id: 'b5', breakClipIds: ['bc6'], position: -1}
  ];
};

Nota: la proprietà breakClipIds di un'interruzione è un array, nel senso che è possibile assegnare più clip di interruzione a ogni interruzione.

In js/receiver.js file, individua l'intercettatore di messaggi LOAD e sostituiscilo con il seguente codice. Tieni presente che il lavoro di VMAP viene commentato per mostrare gli annunci di tipo VAST.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD, (loadRequestData) => {
      castDebugLogger.info('MyAPP.LOG', 'Intercepting LOAD request');

      // Create the VMAP Ads request data and append it to the MediaInformation.
      // const vmapUrl =
      //     'https://pubads.g.doubleclick.net/gampad/ads?sz=640x480&iu=/124319096/external/ad_rule_samples&ciu_szs=300x250&ad_rule=1&impl=s&gdfp_req=1&env=vp&output=vmap&unviewed_position_start=1&cust_params=deployment%3Ddevsite%26sample_ar%3Dpremidpost&cmsid=496&vid=short_onecue&correlator=' +
      //     Math.floor(Math.random() * Math.pow(10, 10));
      // let vmapRequest = new cast.framework.messages.VastAdsRequest();
      // vmapRequest.adTagUrl = vmapUrl;
      // loadRequestData.media.vmapAdsRequest = vmapRequest;

      // Append VAST ad breaks to the MediaInformation.
      addVASTBreaksToMedia(loadRequestData.media);

      castDebugLogger.warn(
          'MyAPP.LOG', 'Playable URL: ' + loadRequestData.media.contentId);

      return loadRequestData;
    });

Salva le modifiche apportate a js/receiver.js e carica il file sul server web. Avvia una sessione di trasmissione nello strumento di trasmissione e comando facendo clic sull'icona Trasmetti. Dovrebbero essere riprodotti gli annunci VAST, seguiti dai contenuti principali.

8. Passaggio dell'interruzione pubblicitaria

Il CAF ha una classe chiamata BreakManager che ti aiuta a implementare regole aziendali personalizzate per il comportamento degli annunci. Una di queste funzionalità consente alle applicazioni di saltare le interruzioni e interrompere i clip in modo programmatico in base a determinate condizioni. Questo esempio mostra come saltare un'interruzione pubblicitaria la cui posizione rientra nei primi 30 secondi del contenuto, ma non le interruzioni post-roll. Quando utilizzi gli annunci VAST configurati nella sezione precedente, sono definite cinque interruzioni: un'interruzione pre-roll, tre interruzioni mid-roll (a 15, 60 e 100 secondi) e, infine, un'interruzione post-roll. Dopo aver completato i passaggi, vengono ignorati solo i contenuti pre-roll e mid-roll con una posizione a 15 secondi.

A questo scopo, l'applicazione deve chiamare le API disponibili tramite BreakManager per impostare un intercettatore per il caricamento delle interruzioni. Copia la seguente riga nel file js/receiver.js, dopo le righe contenenti le variabili context e playerManager per ottenere un riferimento all'istanza.

const breakManager = playerManager.getBreakManager();

L'applicazione deve impostare un intercettore con una regola per ignorare le interruzioni pubblicitarie che si verificano prima di 30 secondi, tenendo presenti le interruzioni post-roll (poiché i loro valori position sono -1). Funziona come l'intercettatore LOAD su PlayerManager, ad eccezione del fatto che è specifico per il caricamento di clip di interruzione. Imposta questo parametro dopo l'intercettatore della richiesta LOAD e prima della dichiarazione della funzione addVASTBreaksToMedia.

Copia quanto segue nel file js/receiver.js.

breakManager.setBreakClipLoadInterceptor((breakClip, breakContext) => {
  /**
   * The code will skip playback of break clips if the break position is within
   * the first 30 seconds.
   */
  let breakObj = breakContext.break;
  if (breakObj.position >= 0 && breakObj.position < 30) {
    castDebugLogger.debug(
        'MyAPP.LOG',
        'Break Clip Load Interceptor skipping break with ID: ' + breakObj.id);
    return null;
  } else {
    return breakClip;
  }
});

Nota: la restituzione di null qui salta l'elaborazione di BreakClip. Se per un elemento Break non sono stati definiti clip di interruzione, l'interruzione stessa viene saltata.

Salva le modifiche in js/receiver.js e carica il file sul server web. Avvia una sessione di trasmissione nello strumento di trasmissione e comando facendo clic sull'icona Trasmetti. Gli annunci VAST dovrebbero essere elaborati. Tieni presente che gli annunci pre-roll e il primo mid-roll (i cui position dura 15 secondi) non vengono riprodotti.

9. Personalizza il comportamento di ricerca dell'interruzione

Quando cerchi le interruzioni passate, l'implementazione predefinita ottiene tutti gli elementi Break la cui posizione è compresa tra i valori seekFrom e seekTo dell'operazione di ricerca. In questo elenco di interruzioni, l'SDK riproduce Break il cui position è il più vicino al valore seekTo e la cui proprietà isWatched è impostata su false. La proprietà isWatched dell'interruzione viene quindi impostata su true e il player inizia la riproduzione dei relativi clip delle interruzioni. Dopo aver guardato l'interruzione, la riproduzione del contenuto principale riprende dalla posizione seekTo. Se non esistono interruzioni di questo tipo, non vengono riprodotte interruzioni e la riproduzione dei contenuti principali riprende nella posizione seekTo.

Per personalizzare le interruzioni riprodotte in una ricerca, l'SDK Cast fornisce l'API setBreakSeekInterceptor in BreakManager. Quando un'applicazione fornisce la sua logica personalizzata tramite l'API, l'SDK la chiama ogni volta che un'operazione di ricerca viene eseguita su una o più interruzioni. La funzione di callback viene passata a un oggetto che contiene tutte le interruzioni tra la posizione seekFrom e la posizione seekTo. L'applicazione deve quindi modificare e restituire BreakSeekData.

Per mostrarne l'utilizzo, l'esempio seguente sostituisce il comportamento predefinito prendendo tutte le interruzioni ricercate e riproducendo solo la prima che appare nella sequenza temporale.

Copia quanto segue nel file js/receiver.js sotto la definizione nel file setBreakClipLoadInterceptor.

breakManager.setBreakSeekInterceptor((breakSeekData) => {
  /**
   * The code will play an unwatched break between the seekFrom and seekTo
   * position. Note: If the position of a break is less than 30 then it will be
   * skipped due to the setBreakClipLoadInterceptor code.
   */
  castDebugLogger.debug(
      'MyAPP.LOG',
      'Break Seek Interceptor processing break ids ' +
          JSON.stringify(breakSeekData.breaks.map(adBreak => adBreak.id)));

  // Remove all other breaks except for the first one.
  breakSeekData.breaks.splice(1,breakSeekData.breaks.length);
  return breakSeekData;
});

Nota: se la funzione non restituisce un valore o se restituisce null, non vengono riprodotte interruzioni.

Salva le modifiche apportate a js/receiver.js e carica il file sul server web. Avvia una sessione di trasmissione nello strumento di trasmissione e comando facendo clic sull'icona Trasmetti. Gli annunci VAST dovrebbero essere elaborati. Tieni presente che gli annunci pre-roll e il primo mid-roll (i cui position dura 15 secondi) non vengono riprodotti.

Attendi che il tempo di riproduzione raggiunga i 30 secondi per superare tutte le interruzioni ignorate dall'intercettatore di caricamento dei clip di interruzione. Una volta raggiunto il limite, invia un comando di ricerca passando alla scheda Media Control (Controllo multimediale). Compila l'input Seek Into Media con 300 secondi e fai clic sul pulsante A. Osserva i registri stampati in Break Seek Interceptor. Ora dovrebbe essere eseguito l'override del comportamento predefinito per riprodurre l'interruzione più vicino al momento di seekFrom.

10. Complimenti

Ora sai come aggiungere annunci all'applicazione ricevitore utilizzando l'SDK Cast ricevitore più recente.

Per ulteriori dettagli, consulta la Guida per gli sviluppatori relativa alle interruzioni pubblicitarie.