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

1. Panoramica

Logo di Google Cast

Questo codelab illustra come creare un'app ricevitore web personalizzata che utilizzi 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 di contenuti multimediali sulla TV.

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

Viene fornito un elenco di controllo per la progettazione di Google Cast per standardizzare le implementazioni di Google Cast e rendere l'esperienza utente intuitiva su tutte le piattaforme supportate.

Cosa realizzeremo

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

Obiettivi didattici

  • Come includere interruzioni VMAP e VAST nei contenuti per la trasmissione
  • Come saltare i clip delle interruzioni
  • Come personalizzare il comportamento predefinito delle interruzioni nella ricerca

Che cosa ti serve

  • La 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

Prima di continuare con questo codelab, assicurati di disporre della seguente esperienza.

  • Conoscenza generale dello sviluppo web.
  • Creazione di applicazioni Cast Web ricevir.

Come userai questo tutorial?

Leggi solo tutto Leggi e completa gli esercizi

Come valuteresti la tua esperienza con lo sviluppo di app web?

Principiante Intermedio Esperto

2. Recupera il codice campione

Scarica tutto il codice campione sul computer...

e decomprimere il file ZIP scaricato.

3. Esegui il deployment del destinatario in locale

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

Se non disponi di un server da utilizzare, puoi usare Firebase Hosting o ngrok.

Esegui il server

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

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

4. Registrare un'applicazione nella Console per gli sviluppatori di Google Cast

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 deve essere configurato per poter avviare l'applicazione ricevitore web.

Immagine della Developer Console dell'SDK Google Cast 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". È quello che stiamo realizzando.

Immagine della schermata "Nuovo ricevitore personalizzato" che mostra l'URL che qualcuno sta digitando nel campo "URL applicazione del destinatario"

Inserisci i dettagli del nuovo ricevitore. Assicurati di utilizzare l'URL che rimandi al luogo in cui prevedi di ospitare l'applicazione ricevitore web. Prendi nota dell'ID applicazione generato dalla console dopo aver registrato l'applicazione. L'applicazione del mittente verrà configurata per utilizzare l'identificatore in una sezione successiva.

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

Immagine della Console per gli sviluppatori dell'SDK Google Cast 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 assegnagli 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.

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

5. Prepara il progetto iniziale

Prima di iniziare questo codelab, potrebbe essere utile consultare la guida per gli sviluppatori di annunci, che offre una panoramica delle API di interruzione pubblicitaria.

Il supporto di Google Cast deve essere aggiunto all'app iniziale che hai scaricato. Ecco alcuni termini di Google Cast utilizzati in questo codelab:

  • Un'app del mittente viene eseguita su un dispositivo mobile o un laptop,
  • Sul dispositivo Google Cast è in esecuzione un'app per ricevitore.

Ora puoi iniziare a creare sulla base del progetto di partenza 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, man mano che utilizzi questo codelab, la soluzione di hosting web che hai scelto dovrebbe essere aggiornata con le modifiche apportate. Assicurati di applicare le modifiche al sito host quando continui a convalidarle e testarle.

Progettazione dell'app

Come accennato in precedenza, il codelab utilizza un'applicazione del mittente per avviare una sessione di trasmissione e un'applicazione del destinatario che verrà modificata per utilizzare le API di interruzione pubblicitaria.

In questo codelab, lo strumento di trasmissione e comando fungerà da web Sender per avviare l'app del destinatario. Per iniziare, apri lo strumento in un browser Chrome. Inserisci l'ID app ricevitore che ti è stato fornito nella Developer Console dell'SDK di 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 nella Console per gli sviluppatori di Google Cast. Se non l'hai ancora fatto, spegni e riaccendi i dispositivi di trasmissione appena registrati.

L'app destinatario è l'argomento 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 più in dettaglio di seguito.

index.html

Questo file HTML contiene l'interfaccia utente della nostra app destinatario 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 al momento dell'inizializzazione. Sono state aggiunte anche alcune funzionalità di log di debug per fornire il log di accesso allo strumento Cast e Command.

6. Aggiungi VMAP ai tuoi contenuti

L'SDK Cast Web ricevir supporta gli annunci specificati tramite le playlist di annunci multipli di video digitali, anche note come VMAP. La struttura XML specifica le interruzioni pubblicitarie di un contenuto multimediale e i metadati delle 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 CARICA intercettatore richiesta e sostituiscila con il codice seguente. 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 non ancora osservate.

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 Trasmetti 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 fetchr supporta molti tipi di annunci. Questa sezione evidenzia le API disponibili per l'integrazione degli 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 caricamento. Contiene sei clip di interruzione VAST di DoubleClick e un valore correlator casuale. Questi clip di interruzione sono assegnati a 5 interruzioni. Il valore position di ogni interruzione è impostato su una durata in secondi relativa 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 e ciò significa che è possibile assegnare più clip di interruzione a ciascuna interruzione.

Nel tuo js/receiver.js file, individua l'intercettatore dei messaggi LOAD e sostituiscilo con il codice seguente. Tieni presente che il lavoro VMAP è stato 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 Trasmetti e comando facendo clic sull'icona Trasmetti. Dovrebbero essere riprodotti gli annunci VAST, seguiti dai contenuti principali.

8. Interruzione pubblicitaria saltata

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 in modo programmatico le interruzioni e interrompere i clip in base a una determinata condizione. Questo esempio mostra come saltare un'interruzione pubblicitaria la cui posizione rientra nei primi 30 secondi del contenuto, ma non nelle 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 file pre-roll e mid-roll la cui posizione è impostata a 15 secondi.

A questo scopo, l'applicazione deve chiamare le API disponibili tramite BreakManager per impostare un intercettore per il caricamento di interruzione. 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 prima dei 30 secondi, tenendo presente eventuali interruzioni post-roll (poiché i loro valori position sono -1). Questo intercettore funziona come l'intercettore LOAD su PlayerManager, tranne per il fatto che questa è specifica per il caricamento dei clip delle interruzioni. Impostalo 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: se ripristini null qui, il BreakClip non verrà elaborato. Se per un elemento Break non sono definiti clip di interruzione, l'interruzione viene saltata.

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

9. Personalizza il comportamento di ricerca dell'interruzione

Quando cerchi interruzioni passate, l'implementazione predefinita riceve 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 il video Break il cui position è 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 avvia la riproduzione delle relative clip di interruzione. Una volta guardata l'interruzione, la riproduzione dei contenuti principali riprende dalla posizione seekTo. In assenza di tale interruzione, non viene riprodotta alcuna interruzione e la riproduzione dei contenuti principali riprende nella posizione seekTo.

Per personalizzare la riproduzione delle interruzioni durante una ricerca, l'SDK Cast fornisce l'API setBreakSeekInterceptor in BreakManager. Quando un'applicazione fornisce la propria logica personalizzata tramite quell'API, l'SDK la chiama ogni volta che un'operazione di ricerca viene eseguita in 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 il BreakSeekData.

Per mostrarne l'utilizzo, l'esempio seguente sostituisce il comportamento predefinito, completando tutte le interruzioni cercate e riproducendo solo la prima visualizzata nella sequenza temporale.

Copia quanto segue nel file js/receiver.js con 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 Trasmetti e comando facendo clic sull'icona Trasmetti. Gli annunci VAST dovrebbero essere elaborati. Tieni presente che gli annunci pre-roll e mid-roll (il cui position dura 15 secondi) non vengono riprodotti.

Attendi che il tempo di riproduzione raggiunga i 30 secondi per superare tutte le interruzioni saltate dall'intercettatore di caricamento del clip di interruzione. Una volta raggiunto questo obiettivo, invia un comando di ricerca andando alla scheda Controllo contenuti multimediali. Completa l'input Seek Into Media con 300 secondi, quindi fai clic sul pulsante TO. Prendi nota dei log stampati nell'intercettore di ricerca dell'interruzione. Ora viene eseguito l'override del comportamento predefinito per riprodurre l'interruzione più vicino all'ora seekFrom.

10. Congratulazioni

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

Per maggiori dettagli, consulta la guida per gli sviluppatori sulle interruzioni pubblicitarie.