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 daCastReceiverContext
, 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 daPlayerManager
, che è una proprietà del singletonCastReceiverContext
, 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 daPlaybackConfig
, che può essere fornita a livello globale o per richiesta di caricamento.
PlayerManager
espone inoltre le nuove classi di amministratore secondario:
TextTracksManager
: gestisci tracce di testo dei contenuti multimediali.AudioTracksManager
: gestisci tracce audio.QueueManager
: gestisci la coda.BreakManager
: gestisci gli annunci.
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.