Integra l'SDK Cast nella tua app Web Sender

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 browser è il mittente, che controlla la riproduzione; il dispositivo Google Cast è il ricevitore, 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 generale, puoi effettuare chiamate sull'API Framework di livello superiore più semplice, che viene poi elaborata dall'API Base di livello inferiore.

Il framework mittente si riferisce all'API Framework, al modulo e alle risorse associate che forniscono un wrapper per le funzionalità di livello inferiore. Con l'app del mittente o l'app di Chrome di Google Cast si intende un'app web (HTML/JavaScript) in esecuzione in un browser Chrome su un dispositivo del mittente. Un'app Web Ricevir si riferisce a un'app HTML/JavaScript in esecuzione su Chromecast o un dispositivo Google Cast.

Il framework del mittente utilizza un design asincrono del callback per informare l'app del mittente degli eventi e per passare tra i vari stati del ciclo di vita dell'app Cast.

Carica la libreria

Affinché l'app possa implementare le funzioni 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 della tua 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 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 le modifiche dello stato della trasmissione e della sessione di trasmissione.
  • L'oggetto CastSession gestisce la sessione e fornisce informazioni sullo stato e attiva eventi come le modifiche al volume del dispositivo, lo stato dell'audio e i metadati delle app.
  • L'elemento pulsante Trasmetti, che è un semplice elemento HTML personalizzato che estende il pulsante HTML. Se il pulsante Trasmetti fornito non è sufficiente, puoi utilizzare lo stato Trasmetti per implementarlo.
  • L'elemento RemotePlayerController fornisce l'associazione di dati per semplificare l'implementazione del player remoto.

Consulta la pagina Riferimento 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 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 all'elemento eventuali stili aggiuntivi, come dimensione 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 del mittente.

All'interno di questo gestore, inizializza l'interazione con la trasmissione 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) mediante un oggetto CastOptions per impostare applicationID.

Se utilizzi il Ricevitore multimediale predefinito, che non richiede la registrazione, utilizzi una costante predefinita dall'SDK Web Sender, come mostrato di seguito, anziché applicationID:

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 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). Per prima cosa, crea un MediaInfo, utilizzando i campi contentId e contentType e qualsiasi altra informazione correlata ai contenuti. Poi crea un LoadRequest a partire da questo, 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 al fine di ottenere un risultato. Se Promise viene rifiutato, l'argomento della funzione sarà un chrome.cast.ErrorCode.

Puoi accedere alle variabili di 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 la riproduzione, la messa in pausa, l'interruzione e la ricerca dei contenuti multimediali caricati.

  • RIPRODUZIONE/PAUSA: playerController.playOrPause();
  • FERMATA: playerController.stop();
  • CERCA: playerController.seek();

RemotePlayer e RemotePlayerController possono essere utilizzati con framework di associazione 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 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 cambia la riproduzione e quando cambia 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 quali la messa in pausa, la riproduzione, la ripresa o la ricerca, l'app deve intervenire e sincronizzarsi tra se stessa e l'app Web Ricevir sul dispositivo di trasmissione. Per ulteriori informazioni, consulta Aggiornamenti dello stato.

Come funziona la gestione delle sessioni

L'SDK Cast introduce il concetto di sessione Cast, la cui creazione combina i passaggi per la connessione a un dispositivo, l'avvio (o l'unione) di un'app ricevitore web, la connessione a quell'app e l'inizializzazione di 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 del ricevitore web.

Le sessioni sono gestite dalla classe CastContext, che la tua app può recuperare tramite cast.framework.CastContext.getInstance(). Le sessioni individuali sono rappresentate da sottoclassi del corso 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 disconnettersi, 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 tuo listener, controlla se RemotePlayer è disconnesso. In questo caso, aggiorna lo stato del player locale in base alle tue esigenze. 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 di Cast tramite il pulsante Cast 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, grazie al quale 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 (la sorgente) e continua su un altro (la destinazione). Qualsiasi dispositivo di trasmissione con il firmware più recente può fungere da origine o destinazione in un trasferimento dello streaming.

Per ottenere 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, consulta Trasferimento dello streaming su Web ricevitore.