Esegui la migrazione al ricevitore web

Questa guida spiega come eseguire la migrazione di un'app Cast Receiver alla versione web più recente.

Il nuovo SDK Cast Application Framework (CAF), noto anche come Web Receiver v3, è un importante upgrade dell'SDK Receiver v2. L'SDK del ricevitore web fornisce un SDK semplice ed essenziale per lo sviluppo di applicazioni multimediali del ricevitore web.

Il destinatario web fornisce un'API più coerente con le nuove API del mittente CAF. Consente l'integrazione completa di un player (MPL e Shaka) e l'implementazione completa e il supporto dei comandi vocali di Google Cast Media e dell'Assistente Google. L'SDK CAF fornisce inoltre un'UI predefinita che può essere facilmente ottimizzata utilizzando CSS e un servizio di associazione di dati per semplificare l'implementazione dell'interfaccia utente.

Perché eseguire la migrazione?

Con la migrazione di un'applicazione Receiver v2 a Web Receiver, una grande quantità di codice che gestisce il player può essere eliminata, in modo che tu possa concentrarti sulla scrittura della logica di business specifica dell'applicazione.

CAF integra perfettamente i lettori MPL e Shaka per supportare una gamma più ampia di tipi di contenuti, tra cui HTTP Live Streaming (TS e CMAF), MPEG-DASH, Fluida e tipi supportati dalla proprietà sorgente dell'elemento Media (MP3, MP4, Icecast e così via). Per un elenco completo, consulta l'articolo Contenuti multimediali supportati per Google Cast. Attualmente il CAF non supporta un player fornito dall'utente.

Con la migrazione a CAF verrà aggiunto il supporto per il controllo vocale con l'Assistente Google. Qualsiasi nuovo comando vocale dell'Assistente Google sarà supportato automaticamente quando utilizzi CAF.

Oltre a supportare nuovi comandi multimediali, come "cambia tracce in base alla lingua" e "cambia la velocità di riproduzione", CAF offre anche una migliore coda, supporto integrato degli annunci e un migliore supporto in tempo reale.

Che cosa è cambiato?

L'API Web Receiver tenta di seguire le convenzioni introdotte dai mittenti CAF per Android e iOS ed è abbastanza diversa dalla v2.

Il destinatario web utilizza un nuovo spazio dei nomi cast.framework anziché cast.receiver per tutte le API esposte. Molti degli oggetti dati utilizzati da v2 sono gli stessi in CAF e sono esposti sotto lo spazio dei nomi cast.framework.messages (erano principalmente in cast.receiver.media).

I seguenti servizi v2 sono sostituiti dai servizi CAF corrispondenti:

  • La classe CastReceiverManager viene sostituita da CastReceiverContext, che è un singleton che gestisce la sessione di trasmissione, i mittenti, l'invio di messaggi personalizzati e gli eventi di sistema globali. CastReceiverOptions può essere utilizzato per fornire al contesto opzioni globali dell'applicazione (come coda, versione del ricevitore, configurazione di riproduzione e così via).
  • La classe MediaManager viene sostituita da PlayerManager, che è una proprietà del singleton CastReceiverContext, e gestisce la sessione multimediale, le richieste multimediali, le richieste vocali dell'Assistente Google (CommandAndControlManager nella versione 2) e attiva gli eventi multimediali. La configurazione per i player (cast.player.api.Host in MPL) viene fornita da PlaybackConfig, che può essere fornita a livello globale o per richiesta di caricamento.

PlayerManager espone inoltre le nuove classi di amministratore secondario:

const context = cast.framework.CastReceiverContext.getInstance();
const playerManager = context.getPlayerManager();

// Set global options.
const options = new cast.framework.CastReceiverOptions();
options.versionCode = DEVELOPERS_APP_VERSION;

context.start(options);

Logica aziendale del destinatario

Gestori di eventi esposti v2 del destinatario (come CastReceiverManager.onReady o MediaManager.onLoad) per aggiungere la logica di business. In CAF i gestori di eventi vengono sostituiti dai listener di eventi (CastReceiverContext.addEventListener) e dai intercettatori di messaggi (PlayerManager.setMessageInterceptor). Il destinatario web può avere più listener di eventi per un evento (il listener non influisce sull'evento) e un intercettore per messaggio. L'intercettatore può aggiornare la richiesta o gestirla (restituire una richiesta modificata, un messaggio di operazione riuscita o un messaggio di errore) e può essere un gestore asincrono che restituisce una promessa.

L'intercettatore della richiesta di carico è il punto più comune per aggiungere una logica specifica dell'applicazione. Per le richieste di carico inviate da un mittente, l'intercettatore del carico può convertire l'ID contenuto in URL di contenuti. L'intercettatore del carico viene chiamato anche per le richieste di precaricamento e precache, se non è stato fornito alcun intercettore esplicito per il precaricamento.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.LOAD,
    request => {
      // Resolve entity to content id
      if (request.media.entity && !request.media.contentId) {
        return getMediaByEntity(request.media.entity).then(
            media => {
              request.media.contentId = media.url;
              return request;
            });
      }
      return request;
    });

Anche il gestore di stato dei contenuti multimediali personalizzato v2 viene sostituito da un intercettatore di messaggi per il messaggio di stato dei contenuti multimediali. Le app web Receiver che non vogliono esporre l'URL dell'elemento multimediale nello stato dell'elemento multimediale possono fornire un resolver URL (PlayerManager.setMediaUrlResolver), che fornisce l'URL dell'elemento multimediale per una richiesta di caricamento. Questo URL è utilizzato internamente dal CAF e non è fornito nello stato multimediale.

playerManager.setMessageInterceptor(
    cast.framework.messages.MessageType.MEDIA_STATUS,
    status => {
      // Disable seek.
      status.supportedMediaCommands &=
          ~cast.framework.messages.Command.SEEK
      return status;
    });

Eventi

Il ricevitore web offre una vasta gamma di eventi sia da CastReceiverContext che da PlayerManager. Le app di ricezione web possono avere più ascoltatori in qualsiasi evento e possono anche fornire un listener a più eventi. Per alcuni gruppi di eventi, vedi cast.framework.events.category.

Gli eventi riguardano qualsiasi richiesta dell'utente, avanzamento della riproduzione, elaborazione del player e qualsiasi evento dell'elemento multimediale di basso livello (CAF non espone l'elemento multimediale stesso).

L'app Web Receiver può aggiungere ascoltatori di eventi per agire (ad esempio, aggiungere la definizione di tracce di testo al termine del caricamento) o per l'analisi.

// Log all media commands
playerManager.addEventListener(
    cast.framework.events.category.REQUEST,
    event => logEvent(event.type));

Bus di messaggi personalizzato

CAF non espone il bus di messaggi nell'API, ma fornisce CastReceiverContext.addCustomMessageListener per aggiungere un listener di messaggi per uno spazio dei nomi specifico (solo uno per spazio dei nomi) e CastReceiverContext.sendCustomMessage per inviare un messaggio in uno spazio dei nomi. Tutti gli spazi dei nomi devono essere dichiarati prima di avviare il destinatario web (ovvero prima di chiamare CastReceiverContext.start). Per gli spazi dei nomi è possibile dichiararli aggiungendo un listener di messaggi oppure possono essere forniti come opzione di avvio in CastReceiverOptions.customNamespaces.

const options = new cast.framework.CastReceiverOptions();
options.customNamespaces = {
    CUSTOM_NS: cast.framework.system.MessageType.JSON
};
context.start(options);

context.sendCustomMessage(CUSTOM_NS, {
  type: 'status'
  message: 'Playing'
});

UI predefinita

CAF fornisce un'interfaccia utente predefinita del ricevitore web che mostra una barra di avanzamento della riproduzione e i metadati multimediali necessari. L'UI predefinita viene fornita come elemento personalizzato (<cast-media-player>) che può avere uno stile di stile CSS.

<style>
   cast-media-player { --splash-image: url("splash.png"); }
</style>
<cast-media-player></cast-media-player>

Per una maggiore personalizzazione, un'app Ricevitore web può implementare la propria UI. Il Ricevitore web fornisce la classe cast.framework.ui.PlayerDataBinder per associare un oggetto UI allo stato di riproduzione del Ricevitore web.