Questa guida per gli sviluppatori descrive come aggiungere il supporto di Google Cast all'app Web Sender utilizzando l'SDK Cast.
Terminologia
Il dispositivo mobile o il browser è il mittente, che controlla la riproduzione; il dispositivo Google Cast è il ricevitore, che visualizza i contenuti sullo schermo per la riproduzione.
L'SDK Web Sender è composto da due parti: l'API Framework (cast.framework) e l'API Base (chrome.cast). In generale, si effettuano chiamate sull'API Framework di livello superiore, più semplice, che vengono poi elaborate dall'API Base di livello inferiore.
Il framework del mittente si riferisce all'API del framework, al modulo e alle risorse associate che forniscono un wrapper per la funzionalità di livello inferiore. L'app mittente o l'app Google Cast per Chrome si riferisce a un'app web (HTML/JavaScript) in esecuzione in un browser Chrome su un dispositivo mittente. Un'app Web receiver è un'app HTML/JavaScript in esecuzione su Chromecast o su un dispositivo Google Cast.
Il framework del mittente utilizza un design di callback asincrono per informare l'app del mittente degli eventi e per consentire la transizione tra i vari stati del ciclo di vita dell'app di trasmissione.
Carica la libreria
Per poter implementare le funzionalità di Google Cast, la tua app deve conoscere la posizione dell'SDK Google Cast Web Sender, come mostrato di seguito. Aggiungi il parametro di query dell'URL loadCastFramework per caricare anche l'API Web Sender Framework. Tutte le pagine dell'app devono fare riferimento alla raccolta nel seguente modo:
<script src="https://www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
Framework
L'SDK Web Sender utilizza lo spazio dei nomi cast.framework.*. Lo spazio dei nomi rappresenta quanto segue:
- Metodi o funzioni che richiamano operazioni sull'API
- Listener di eventi per le funzioni listener nell'API
Il framework è costituito dai seguenti componenti principali:
CastContext
è un oggetto singleton che fornisce informazioni sullo stato di trasmissione attuale e attiva eventi per lo stato di trasmissione e le modifiche dello stato della sessione di trasmissione.- L'oggetto
CastSession
gestisce la sessione. Fornisce informazioni sullo stato e attiva eventi, come modifiche al volume del dispositivo, stato di disattivazione dell'audio e metadati dell'app. - L'elemento pulsante Trasmetti, che è un semplice elemento personalizzato HTML che estende il pulsante HTML. Se il pulsante Trasmetti fornito non è sufficiente, puoi utilizzare lo stato Trasmetti per implementarlo.
RemotePlayerController
fornisce l'associazione di dati per semplificare l'implementazione del player remoto.
Consulta la documentazione di riferimento dell'API Google Cast Web Sender per una descrizione completa dello spazio dei nomi.
Pulsante Trasmetti
Il componente Pulsante Trasmetti nell'app è gestito interamente dal framework. Ciò include la gestione della visibilità e degli eventi di clic.
<google-cast-launcher></google-cast-launcher>
In alternativa, puoi creare il pulsante in modo programmatico:
document.createElement("google-cast-launcher");
Se necessario, puoi applicare all'elemento altri stili, come dimensioni o posizionamento. Utilizza l'attributo --connected-color
per
scegliere il colore per lo stato del ricevitore web connesso e
--disconnected-color
per lo stato disconnesso.
Inizializzazione
Dopo aver caricato l'API framework, l'app chiamerà il gestore window.__onGCastApiAvailable
. Devi assicurarti che l'app imposti questo gestore
su window
prima di caricare la libreria dei mittenti.
All'interno di questo gestore, inizializza l'interazione con Google Cast chiamando il metodo
setOptions(options)
di
CastContext
.
Ad esempio:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
Quindi, inizializza l'API nel seguente modo:
initializeCastApi = function() {
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: applicationId,
autoJoinPolicy: chrome.cast.AutoJoinPolicy.ORIGIN_SCOPED
});
};
Innanzitutto, l'app recupera l'istanza singleton dell'oggetto
CastContext
fornita dal framework. Quindi utilizza setOptions(options)
con un oggetto CastOptions
per impostare applicationID
.
Se usi il programma predefinito, che non richiede la registrazione,
usa una costante predefinita dell'SDK Web Sender, mostrata di seguito, anziché
applicationID
:
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
Controllo dei contenuti multimediali
Una volta inizializzata la CastContext
, l'app può recuperare l'attuale CastSession
in qualsiasi momento utilizzando getCurrentSession()
.
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
CastSession
può essere utilizzato per caricare contenuti multimediali sul dispositivo di trasmissione connesso tramite loadMedia(loadRequest)
.
Innanzitutto, crea una MediaInfo
utilizzando i contentId
e contentType
e qualsiasi altra informazione relativa ai contenuti. Quindi, crea un elemento LoadRequest
da lì, impostando tutte le informazioni pertinenti per la richiesta. Infine,
chiama loadMedia(loadRequest)
sul tuo CastSession
.
var mediaInfo = new chrome.cast.media.MediaInfo(currentMediaURL, contentType);
var request = new chrome.cast.media.LoadRequest(mediaInfo);
castSession.loadMedia(request).then(
function() { console.log('Load succeed'); },
function(errorCode) { console.log('Error code: ' + errorCode); });
Il metodo loadMedia
restituirà una
promessa
che può essere utilizzata per eseguire qualsiasi operazione necessaria per ottenere un risultato positivo.
Se la promessa viene rifiutata, l'argomento della funzione sarà un
chrome.cast.ErrorCode
.
Puoi accedere alle variabili di stato del player in RemotePlayer
.
Tutte le interazioni con l'RemotePlayer
, inclusi i comandi e i callback di eventi multimediali, vengono gestite con RemotePlayerController
.
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
L'RemotePlayerController
offre all'app il controllo completo dei contenuti multimediali
riproduzione, pausa, interruzione e ricerca dei contenuti multimediali caricati.
- RIPRODUCI/PAUSA:
playerController.playOrPause();
- INTERROMPI:
playerController.stop();
- CERCA:
playerController.seek();
RemotePlayer
e RemotePlayerController
possono essere utilizzati con framework di associazione di dati, come Polymer o Angular, per implementare un player remoto.
Ecco uno snippet di codice per Angular:
<button id="playPauseButton" class="playerButton" ng-disabled="!player.canPause" ng-click="controller.playOrPause()"> {{player.isPaused ? 'Play' : 'Pause'}} </button> <script> var player = new cast.framework.RemotePlayer(); var controller = new cast.framework.RemotePlayerController(player); // Listen to any player update, and trigger angular data binding update.controller.addEventListener( cast.framework.RemotePlayerEventType.ANY_CHANGE, function(event) { if (!$scope.$$phase) $scope.$apply(); }); </script>
Stato dei contenuti multimediali
Durante la riproduzione di contenuti multimediali, si verificano vari eventi che possono essere acquisiti impostando
ascoltatori per vari
eventi
cast.framework.RemotePlayerEventType
sull'oggetto
RemotePlayerController
.
Per ottenere le informazioni sullo stato dei contenuti multimediali, utilizza l'evento cast.framework.RemotePlayerEventType
.MEDIA_INFO_CHANGED
, che si attiva quando la riproduzione cambia e CastSession.getMediaSession().media
cambia.
playerController.addEventListener(
cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED, function() {
// Use the current session to get an up to date media status.
let session = cast.framework.CastContext.getInstance().getCurrentSession();
if (!session) {
return;
}
// Contains information about the playing media including currentTime.
let mediaStatus = session.getMediaSession();
if (!mediaStatus) {
return;
}
// mediaStatus also contains the mediaInfo containing metadata and other
// information about the in progress content.
let mediaInfo = mediaStatus.media;
});
In caso di eventi come pausa, riproduzione, ripresa o ricerca, l'app dovrà intervenire su questi eventi e sincronizzarsi tra stessa e l'app Ricevitore web sul dispositivo di trasmissione. Per ulteriori informazioni, consulta Aggiornamenti di stato.
Come funziona la gestione delle sessioni
L'SDK Cast introduce il concetto di una sessione di trasmissione, la cui stabilità combina i passaggi per connettersi a un dispositivo, avviare (o partecipare) a un'app ricevitore web, connettersi all'app e inizializzare un canale di controllo multimediale. Per ulteriori informazioni sulle sessioni di trasmissione e sul ciclo di vita del ricevitore web, consulta la Guida al ciclo di vita dell'applicazione di Web receiver.
Le sessioni sono gestite dalla classe CastContext
, che la tua app può recuperare tramite cast.framework.CastContext.getInstance()
.
Le singole sessioni sono rappresentate dalle sottoclassi della classe
Session
. Ad esempio, CastSession
rappresenta le sessioni con dispositivi di trasmissione. La tua app può accedere alla sessione di trasmissione attualmente attiva tramite CastContext.getCurrentSession()
.
Per monitorare lo stato della sessione, aggiungi un listener a CastContext
per il tipo di evento CastContextEventType
.SESSION_STATE_CHANGED
.
var context = cast.framework.CastContext.getInstance();
context.addEventListener(
cast.framework.CastContextEventType.SESSION_STATE_CHANGED,
function(event) {
switch (event.sessionState) {
case cast.framework.SessionState.SESSION_STARTED:
case cast.framework.SessionState.SESSION_RESUMED:
break;
case cast.framework.SessionState.SESSION_ENDED:
console.log('CastContext: CastSession disconnected');
// Update locally as necessary
break;
}
})
Per la disconnessione, ad esempio quando l'utente fa clic sul pulsante "Interrompi trasmissione" nella
finestra di dialogo Trasmetti, puoi aggiungere un listener per il tipo di evento
RemotePlayerEventType
.IS_CONNECTED_CHANGED
nel tuo listener. Nel listener, controlla se RemotePlayer
è disconnesso. Se necessario, aggiorna lo stato del player locale. Ad esempio:
playerController.addEventListener(
cast.framework.RemotePlayerEventType.IS_CONNECTED_CHANGED, function() {
if (!player.isConnected) {
console.log('RemotePlayerController: Player disconnected');
// Update local player to disconnected state
}
});
Sebbene l'utente possa controllare direttamente la terminazione della trasmissione tramite il pulsante Trasmetti
della struttura, il mittente può interrompere la trasmissione utilizzando l'oggetto
CastSession
corrente.
function stopCasting() {
var castSession = cast.framework.CastContext.getInstance().getCurrentSession();
// End the session and pass 'true' to indicate
// that Web Receiver app should be stopped.
castSession.endSession(true);
}
Trasferimento dello streaming
Conservare lo stato della sessione è la base del trasferimento dello streaming, in cui gli utenti possono spostare gli stream audio e video esistenti tra i dispositivi utilizzando i comandi vocali, l'app Google Home o gli smart display. La riproduzione dei contenuti multimediali viene interrotta su un dispositivo (l'origine) e continua su un altro (la destinazione). Qualsiasi dispositivo di trasmissione con il firmware più recente può fungere da sorgente o destinazione in un trasferimento dello streaming.
Per ricevere il nuovo dispositivo di destinazione durante il trasferimento dello streaming, chiama
CastSession#getCastDevice()
quando viene chiamato l'evento
cast.framework.SessionState
.SESSION_RESUMED
.
Per ulteriori informazioni, vedi Trasferimento dello streaming su WebRicevitore.