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 Mittente web utilizzando l'SDK Cast.

Terminologia

Il dispositivo mobile o il browser è il mittente, che controlla la riproduzione; il dispositivo Google Cast è il destinatario, 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 Base (chrome.cast) In generale, fai chiamate sull'API Framework più semplice e di livello superiore, che vengono poi elaborate dall'API di livello inferiore.

Il framework mittente si riferisce all'API Framework, al modulo e alle risorse associate che forniscono un wrapper attorno alla funzionalità di livello inferiore. L'app mittente o l'app Google Cast Chrome si riferisce a un'app web (HTML/JavaScript) in esecuzione all'interno di un browser Chrome su un dispositivo mittente. Un'app Ricevitore 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 Cast.

Carica la raccolta

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 ricerca dell'URL loadCastFramework per caricare anche l'API Web Sender Framework. Tutte le pagine della tua 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 da questi componenti principali:

  • CastContext è un oggetto singleton che fornisce informazioni sullo stato di trasmissione corrente e attiva gli eventi relativi alle modifiche dello stato di trasmissione e della sessione di trasmissione.
  • L'oggetto CastSession gestisce la sessione, fornisce informazioni sullo stato e attiva eventi, come modifiche al volume del dispositivo, alla disattivazione dell'audio e ai 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 di trasmissione per implementare un pulsante Trasmetti.
  • 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 nella tua app è gestito interamente dal framework. inclusa 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 uno stile aggiuntivo, ad esempio dimensioni o posizionamento. Utilizza l'attributo --connected-color per scegliere il colore per lo stato del ricevitore web collegato e --disconnected-color per lo stato disconnesso.

Inizializzazione

Dopo aver caricato l'API del framework, l'app chiama 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 Cast, chiamando il metodo setOptions(options) di CastContext.

Ad esempio:

<script>
window['__onGCastApiAvailable'] = function(isAvailable) {
  if (isAvailable) {
    initializeCastApi();
  }
};
</script>

Quindi, 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. Quindi utilizza setOptions(options) con un oggetto CastOptions per impostare il 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

Dopo aver inizializzato CastContext, l'app può recuperare la CastSession corrente 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 usando loadMedia(loadRequest). Innanzitutto, crea una MediaInfo, utilizzando contentId e contentType, nonché qualsiasi altra informazione relativa ai contenuti. Da qui puoi creare un elemento LoadRequest, impostando tutte le informazioni pertinenti per la richiesta. Infine, chiama il numero loadMedia(loadRequest) al numero 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à un promessa che può essere utilizzato per eseguire le operazioni necessarie per un risultato corretto. Se la promessa viene rifiutata, l'argomento della funzione sarà chrome.cast.ErrorCode.

Puoi accedere alle variabili dello stato del player in RemotePlayer. Tutte le interazioni con RemotePlayer, inclusi i callback e gli comandi dei contenuti multimediali, vengono gestite con RemotePlayerController.

var player = new cast.framework.RemotePlayer();
var playerController = new cast.framework.RemotePlayerController(player);

L'RemotePlayerController fornisce all'app il controllo completo dei contenuti multimediali in modalità di riproduzione, pausa, arresto e ricerca.

  • 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 dei contenuti multimediali si verificano vari eventi che possono essere acquisiti impostando gli ascoltatori per vari cast.framework.RemotePlayerEventType eventi nell'oggetto RemotePlayerController.

Per ottenere le informazioni sullo stato dei contenuti multimediali, usa 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 compiere azioni su di essi e sincronizzarsi con l'app Ricevitore web sul dispositivo di trasmissione. Per ulteriori informazioni, consulta la sezione Aggiornamenti di stato.

Come funziona la gestione delle sessioni

L'SDK Cast introduce il concetto di sessione di trasmissione, la cui combinazione combina i passaggi per connettersi a un dispositivo, lanciare (o partecipare) a un'app web Ricevitore, connettersi a quell'app e inizializzare un canale di controllo multimediale. Consulta la Guida al ciclo di vita dell'applicazione per il ricevitore web per ulteriori informazioni sulle sessioni di trasmissione e sul ciclo di vita 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 dalle 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 alla 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" dalla 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 tal caso, aggiorna lo stato del player locale a seconda delle 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
    }
  });

Mentre l'utente può controllare direttamente la terminazione di Cast 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

Conservare lo stato della sessione è la base del trasferimento dello stream, in cui gli utenti possono spostare stream audio e video esistenti su più 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). Tutti i dispositivi di trasmissione con il firmware più recente possono essere utilizzati come origini o destinazioni in un trasferimento di streaming.

Per ricevere 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 la pagina Trasferimento dello streaming sul ricevitore web.