Questa guida per gli sviluppatori descrive come aggiungere il supporto di Google Cast alla tua 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 ricevente, che mostra i contenuti sullo schermo per la riproduzione.
L'SDK Web Sender è costituito da due parti: l'API Framework (cast.framework) e l'API di base (chrome.cast) In genere, effettui chiamate all'API Framework, più semplice e di livello superiore, che vengono poi elaborate dall'API di base di livello inferiore.
Il framework mittente si riferisce all'API, al modulo e alle risorse associate del framework che forniscono un wrapper per le 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 di ricezione web si riferisce a 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 passare da uno stato all'altro del ciclo di vita dell'app di trasmissione.
Carica la libreria
Affinché la tua app possa implementare le funzionalità di Google Cast, 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 come segue:
<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 invocano 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 corrente di Cast e attiva eventi per le modifiche dello stato di Cast e della sessione di Cast.- L'oggetto
CastSession
gestisce la sessione: fornisce informazioni sullo stato e attiva eventi, ad esempio modifiche al volume del dispositivo, allo stato di disattivazione dell'audio e ai metadati dell'app. - L'elemento pulsante Trasmetti, che è un semplice elemento HTML personalizzato che estende il pulsante HTML. Se il pulsante di trasmissione fornito non è sufficiente, puoi utilizzare lo stato di trasmissione per implementare un pulsante di trasmissione.
RemotePlayerController
fornisce il binding dei 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 del pulsante Trasmetti nella tua app viene gestito interamente dal framework. Sono incluse la gestione della visibilità e la gestione 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 allo stile eventuali stili aggiuntivi, 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 del framework, l'app chiamerà l'handlerwindow.__onGCastApiAvailable
. Devi assicurarti che l'app imposti questo gestore su window
prima di caricare la libreria del mittente.
In questo gestore, puoi inizializzare l'interazione di trasmissione chiamando il metodo
setOptions(options)
di
CastContext
.
Ad esempio:
<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
if (isAvailable) {
initializeCastApi();
}
};
</script>
Poi, inizializza l'API come segue:
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
fornito dal framework. Poi utilizza
setOptions(options)
con un
oggetto
CastOptions
per impostare applicationID
.
Se utilizzi il ricevitore multimediale predefinito, che non richiede registrazione,
invece di applicationID
, utilizza una costante predefinita dall'SDK Web Sender, come mostrato di seguito:
cast.framework.CastContext.getInstance().setOptions({
receiverApplicationId: chrome.cast.media.DEFAULT_MEDIA_RECEIVER_APP_ID
});
Controllo dei contenuti multimediali
Una volta inizializzato CastContext
, l'app può recuperare il valore corrente di
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 collegato utilizzando
loadMedia(loadRequest)
.
Innanzitutto, crea un
MediaInfo
,
utilizzando contentId
e contentType
, nonché qualsiasi altra informazione
relativa ai contenuti. Quindi, crea un
LoadRequest
da essa 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 le operazioni necessarie per ottenere un risultato positivo.
Se la promessa viene rifiutata, l'argomento della funzione sarà un
chrome.cast.ErrorCode
.
Puoi accedere alle variabili dello stato del player in
RemotePlayer
.
Tutte le interazioni con RemotePlayer
, inclusi i comandi e i callback degli eventi multimediali, vengono gestite con RemotePlayerController
.
var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);
RemotePlayerController
consente all'app di controllare completamente i contenuti multimediali con i comandi RIProduci, Metti in pausa, Interrompi e Avanti/Indietro per i contenuti multimediali caricati.
- PLAY/PAUSA:
playerController.playOrPause();
- STOP:
playerController.stop();
- SEEK:
playerController.seek();
RemotePlayer
e RemotePlayerController
possono essere utilizzati con framework di binding dei 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 dei contenuti multimediali si verificano vari eventi che possono essere acquisiti impostando gli 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 cambia la riproduzione e quando cambia il valore di
CastSession.getMediaSession().media
.
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;
});
Quando si verificano eventi come messa in pausa, riproduzione, ripresa o ricerca, l'app dovrà intervenire su di essi e sincronizzarsi con l'app Web Receiver sul dispositivo di trasmissione. Per ulteriori informazioni, consulta Aggiornamenti sullo stato.
Come funziona la gestione delle sessioni
L'SDK Cast introduce il concetto di sessione di trasmissione, la cui impostazione combina i passaggi di connessione a un dispositivo, di lancio (o adesione) a un'app Web Receiver, di connessione a quell'app e di inizializzazione di un canale di controllo dei contenuti multimediali. Per ulteriori informazioni sulle sessioni di trasmissione e sul ciclo di vita del ricevitore web, consulta la guida al ciclo di vita dell'applicazione del ricevitore web.
Le sessioni sono gestite dal corso
CastContext
,
che la tua app può recuperare tramite
cast.framework.CastContext.getInstance()
.
Le singole sessioni sono rappresentate da sottoclassi della classe
Session
. Ad esempio,
CastSession
rappresenta le sessioni con i dispositivi di trasmissione. L'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 Trasmissione, puoi aggiungere un listener per il tipo di evento RemotePlayerEventType
.IS_CONNECTED_CHANGED
nel tuo listener. Nell'ascoltatore, controlla se
RemotePlayer
è
scollegato. In questo caso, aggiorna lo stato del player locale, se necessario. 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 l'interruzione della trasmissione tramite il pulsante Trasmetti del framework, il mittente stesso 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
La conservazione dello stato della sessione è alla base del trasferimento dello streaming, che consente agli utenti di 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 si interrompe su un dispositivo (la sorgente) e continua su un altro (la destinazione). Qualsiasi dispositivo di trasmissione con il firmware più recente può essere utilizzato come sorgente o destinazione in un trasferimento in streaming.
Per ottenere il nuovo dispositivo di destinazione durante il trasferimento dello stream, chiama
CastSession#getCastDevice()
quando viene chiamato l'evento
cast.framework.SessionState
.SESSION_RESUMED
.
Per ulteriori informazioni, consulta Trasferimento di stream su Web Receiver.