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

1. Panoramica

Logo di Google Cast

Questo codelab descrive come creare un'app Custom Web Receiver 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 possono quindi utilizzare il proprio dispositivo mobile come telecomando per la riproduzione dei contenuti multimediali sulla TV.

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

L'elenco di controllo per la progettazione di Google Cast viene fornito per standardizzare le implementazioni di Cast e rendere intuitive le esperienze degli utenti su tutte le piattaforme supportate.

Cosa realizzeremo

Al termine di questo codelab, avrai creato un ricevitore Cast che sfrutta l'API Break.

Obiettivi didattici

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

Che cosa ti serve

Esperienza

Prima di continuare con questo codelab, assicurati di avere la seguente esperienza.

  • Conoscenze generali di sviluppo web.
  • Creazione di applicazioni Cast Web Receiver.

Come utilizzerai questo tutorial?

Leggilo e basta Leggilo e completa gli esercizi

Come valuti la tua esperienza di creazione di app web?

Principiante Intermedio Avanzato

2. recupera il codice campione

Scarica tutto il codice campione sul computer…

ed estrai il file ZIP scaricato.

3. Esegui il deployment del ricevitore in locale

Per poter utilizzare il ricevitore web con un dispositivo Cast, è necessario ospitarlo in un luogo in cui il dispositivo Cast possa raggiungerlo. Se hai già a disposizione un server che supporta HTTPS, salta le istruzioni seguenti e prendi nota dell'URL, perché ti servirà nella sezione successiva.

Se non hai un server disponibile, puoi utilizzare Firebase Hosting o ngrok.

Esegui il server

Una volta configurato il servizio che preferisci, vai a app-start e avvia il server.

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

4. Registrare un'applicazione in Cast Developer Console

Devi registrare la tua applicazione per poter eseguire un ricevitore personalizzato, come quello integrato in questo codelab, sui dispositivi Chromecast. Dopo aver registrato l'applicazione, verrà generato un ID applicazione che deve essere configurato nell'applicazione mittente per avviare l'applicazione Web Receiver.

Immagine di Google Cast SDK Developer Console con il pulsante "Aggiungi nuova applicazione" evidenziato

Fai clic su "Aggiungi nuova applicazione".

Immagine della schermata "Nuova applicazione ricevitore" con l'opzione "Ricevitore personalizzato" evidenziata

Seleziona "Ricevitore personalizzato", ovvero ciò che stiamo creando.

Immagine della schermata "Nuovo ricevitore personalizzato" che mostra un URL che qualcuno sta digitando nel campo "URL applicazione ricevitore"

Inserisci i dettagli del nuovo destinatario. Assicurati di utilizzare l'URL che indirizza alla posizione in cui prevedi di ospitare l'applicazione Web Receiver. Prendi nota dell'ID applicazione generato dalla console dopo la registrazione dell'applicazione. L'applicazione 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, ti consigliamo di lavorare con un'applicazione ricevitore non pubblicata.

Immagine di Google Cast SDK Developer Console con il pulsante "Aggiungi nuovo dispositivo" evidenziato

Fai clic su "Aggiungi nuovo dispositivo".

Immagine della finestra di dialogo "Aggiungi dispositivo ricevitore di trasmissione"

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 a Google Cast SDK Developer Console.

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 Cast.

5. Prepara il progetto iniziale

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.

Il supporto di Google Cast deve essere aggiunto all'app di avvio che hai scaricato. Di seguito sono riportati alcuni termini di Google Cast utilizzati in questo codelab:

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

Ora puoi creare il progetto iniziale utilizzando il tuo editor di testo preferito:

  1. Seleziona la directory icona cartellaapp-start dal download del codice campione.
  2. Apri js/receiver.js e index.html

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

Progettazione di app

Come accennato, il codelab utilizza un'applicazione mittente per avviare una sessione Cast e un'applicazione ricevitore che verrà modificata per utilizzare le API per le interruzioni pubblicitarie.

In questo codelab, lo strumento di trasmissione e comando fungerà da mittente web per avviare l'app ricevitore. Per iniziare, apri lo strumento in un browser Chrome. Inserisci l'ID app ricevitore che ti è stato fornito in Cast SDK Developer Console e fai clic su Imposta per configurare l'app mittente per i test.

Nota: se l'icona Trasmetti non viene visualizzata, assicurati che il Web Receiver e i dispositivi di trasmissione siano registrati correttamente nella console per gli sviluppatori Cast. Se non l'hai ancora fatto, riavvia tutti i dispositivi di trasmissione appena registrati.

L'app ricevitore è l'obiettivo principale di questo codelab ed è costituita da una visualizzazione principale definita in index.html e da un file JavaScript denominato js/receiver.js. Questi sono descritti più nel dettaglio di seguito.

index.html

Questo file HTML contiene la UI per la nostra app ricevitore fornita dall'elemento cast-media-player. Carica anche le librerie CAF SDK e Cast Debug Logger.

receiver.js

Questo script gestisce tutta la logica della nostra app ricevitore. Al momento contiene un ricevitore CAF di base per inizializzare il contesto di trasmissione e caricare un asset video all'inizializzazione. Sono state aggiunte anche alcune funzionalità di registrazione di debug per fornire la registrazione allo strumento Cast and Command.

6. Aggiungere VMAP ai tuoi contenuti

L'SDK Cast Web Receiver fornisce il supporto per gli annunci specificati tramite Digital Video Multiple Ad Playlists, note anche come VMAP. La struttura XML specifica le interruzioni pubblicitarie di un media e i relativi metadati dei clip di interruzione. 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 interceptor e sostituiscila con il seguente codice. Contiene un URL del tag VMAP di esempio di DoubleClick e fornisce un valore correlatore casuale per garantire che le richieste successive allo stesso URL generino un modello XML con interruzioni pubblicitarie che non sono ancora state visualizzate.

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 tuo server web. Avvia una sessione di trasmissione sullo strumento di trasmissione e controllo facendo clic sull'icona Trasmetti. Gli annunci VMAP devono essere riprodotti, seguiti dai contenuti principali.

7. Aggiungere VAST ai tuoi contenuti

Come accennato in precedenza, l'SDK Web Receiver supporta molti tipi di annunci. Questa sezione mette in evidenza 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, inseriscilo come commento.

Copia quanto segue nel file js/receiver.js dopo l'intercettore della richiesta di caricamento. Contiene sei clip di interruzione VAST di DoubleClick e un valore correlatore casuale. Questi clip di interruzione sono assegnati a 5 interruzioni. Il position di ogni interruzione è impostato su un orario 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 una pausa è un array, il che significa che a ogni pausa possono essere assegnati più clip.

Nel tuo js/receiver.js file, individua l'intercettatore di messaggi LOAD e sostituiscilo con il codice seguente. Tieni presente che il lavoro VMAP è 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 tuo server web. Avvia una sessione di trasmissione sullo strumento di trasmissione e controllo facendo clic sull'icona Trasmetti. Gli annunci VAST devono essere riprodotti, seguiti dai contenuti principali.

8. Salto delle interruzioni pubblicitarie

CAF ha una classe denominata BreakManager che ti aiuta a implementare regole aziendali personalizzate per i comportamenti degli annunci. Una di queste funzionalità consente alle applicazioni di saltare in modo programmatico le interruzioni e i clip delle interruzioni in base a una determinata condizione. Questo esempio mostra come saltare un'interruzione pubblicitaria la cui posizione si trova entro i primi 30 secondi dei contenuti, ma non le interruzioni post-roll. Quando utilizzi gli annunci VAST configurati nella sezione precedente, sono definite 5 interruzioni: 1 interruzione pre-roll, 3 interruzioni mid-roll (a 15, 60 e 100 secondi) e, infine, 1 interruzione post-roll. Dopo aver completato i passaggi, vengono saltati solo gli annunci pre-roll e mid-roll la cui posizione è a 15 secondi.

A questo scopo, l'applicazione deve chiamare le API disponibili tramite BreakManager per impostare un intercettore per il caricamento delle interruzioni. Copia la riga seguente 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 configurare un intercettore con una regola per ignorare le interruzioni pubblicitarie che si verificano prima di 30 secondi, tenendo presente le interruzioni post-roll (poiché i relativi valori position sono -1). Questo intercettore funziona come l'intercettore LOAD su PlayerManager, tranne per il fatto che questo è specifico per il caricamento dei clip delle interruzioni. Imposta questo valore dopo l'intercettore di richieste LOAD e prima della dichiarazione di 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: il ritorno di null qui salta l'elaborazione di BreakClip. Se un Break non ha clip di interruzione definiti, l'interruzione stessa viene saltata.

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

9. Personalizzare il comportamento di ricerca delle interruzioni

Quando si cercano interruzioni passate, l'implementazione predefinita recupera tutti gli elementi Break la cui posizione è compresa tra i valori seekFrom e seekTo dell'operazione di ricerca. Da questo elenco di interruzioni, l'SDK riproduce l'interruzione Break il cui position è più vicino al valore seekTo e la cui proprietà isWatched è impostata su false. La proprietà isWatched della pausa viene quindi impostata su true e il player inizia a riprodurre i clip della pausa. Una volta guardata la pausa, la riproduzione dei contenuti principali riprende dalla posizione seekTo. Se non esiste una pausa di questo tipo, non viene riprodotta alcuna pausa e la riproduzione dei contenuti principali riprende dalla posizione seekTo.

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

Per mostrare il suo utilizzo, l'esempio riportato di seguito esegue l'override del comportamento predefinito prendendo in considerazione tutte le interruzioni che sono state cercate e riproducendo solo la prima che appare nella sequenza temporale.

Copia quanto segue nel file js/receiver.js sotto la definizione di 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 riprodotti intermezzi.

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

Attendi che il tempo di riproduzione raggiunga i 30 secondi per superare tutte le interruzioni ignorate dall'intercettore di caricamento dei clip pubblicitari. Una volta raggiunto, invia un comando di ricerca andando alla scheda Controllo contenuti multimediali. Inserisci 300 secondi nel campo di input Seek Into Media e fai clic sul pulsante TO. Prendi nota dei log stampati nell'intercettatore di ricerca interruzioni. Ora il comportamento predefinito dovrebbe essere sostituito per riprodurre la pausa più vicino all'ora seekFrom.

10. Complimenti

Ora sai come aggiungere annunci alla tua applicazione ricevitore utilizzando l'ultima versione dell'SDK Cast Receiver.

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