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 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 genere, effettui chiamate all'API Framework più semplice e di livello superiore, che vengono poi elaborate dall'API Base di livello inferiore.

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

Il framework del mittente utilizza una progettazione di callback asincrona per informare l'app del mittente degli eventi e per passare da un stato all'altro del ciclo di vita dell'app Cast.

Caricare la libreria

Affinché la tua app implementi le funzionalità di Google Cast, deve conoscere la posizione dell'SDK Web Sender di Google Cast, come mostrato di seguito. Aggiungi il parametro di query URL loadCastFramework per caricare anche l'API Framework del mittente web. Tutte le pagine dell'app devono fare riferimento alla libreria 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 è composto dai seguenti componenti principali:

  • The CastContext è un oggetto singleton che fornisce informazioni sullo stato attuale di Cast e attiva eventi per le modifiche dello stato di Cast e dello stato della sessione Cast.
  • L'CastSession oggetto 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 del pulsante Trasmetti, che è un semplice elemento HTML personalizzato che estende il pulsante HTML. Se il pulsante Trasmetti fornito non è sufficiente, puoi utilizzare lo stato di Cast per implementare un pulsante Trasmetti.
  • The RemotePlayerController fornisce l'associazione di dati per semplificare l'implementazione del player remoto.

Per una descrizione completa dello spazio dei nomi, consulta il riferimento API dell'SDK Web Sender di Google Cast.

Pulsante Trasmetti

Il componente del pulsante Trasmetti nella tua app viene 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 a livello di programmazione:

document.createElement("google-cast-launcher");

Se necessario, puoi applicare qualsiasi stile aggiuntivo, ad esempio dimensioni o posizionamento, all'elemento. 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. Assicurati che l'app imposti questo gestore nella window prima di caricare la libreria del mittente.

All'interno di questo gestore, inizializza l'interazione di Cast chiamando il setOptions(options) metodo 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' CastContext oggetto fornita dal framework. Poi utilizza setOptions(options) con un oggetto CastOptions per impostare applicationID.

Se utilizzi il ricevitore multimediale predefinito, che non richiede la registrazione, utilizza 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'oggetto corrente CastSession in qualsiasi momento utilizzando getCurrentSession().

var castSession = cast.framework.CastContext.getInstance().getCurrentSession();

È possibile utilizzare CastSession per caricare contenuti multimediali sul dispositivo Cast connesso utilizzando loadMedia(loadRequest). Innanzitutto, crea un MediaInfo, utilizzando contentId e contentType, nonché qualsiasi altra informazione relativa ai contenuti. Poi crea un oggetto LoadRequest da questo, impostando tutte le informazioni pertinenti per la richiesta. Infine, chiama loadMedia(loadRequest) su 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 Promise che può essere utilizzata per eseguire le operazioni necessarie per un risultato positivo. Se la Promise 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 RemotePlayer, inclusi i callback e i comandi degli eventi multimediali, vengono gestite con il RemotePlayerController.

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

RemotePlayerController offre all'app il controllo completo dei contenuti multimediali di RIPRODUCI, PAUSA, ARRESTA e CERCA per i contenuti multimediali caricati.

  • RIPRODUCI/PAUSA: playerController.playOrPause();
  • ARRESTA: playerController.stop();
  • CERCA: playerController.seek();

È possibile utilizzare RemotePlayer e RemotePlayerController con i framework di associazione di dati, come Polymer o Angular, per implementare un player remoto.

Di seguito è riportato 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 i listener per vari cast.framework.RemotePlayerEventType eventi sull' RemotePlayerControlleroggetto.

Per ottenere le informazioni sullo stato dei contenuti multimediali, utilizza l' cast.framework.RemotePlayerEventType.MEDIA_INFO_CHANGED evento, che viene attivato quando la riproduzione cambia e quando 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;
  });

Quando si verificano eventi come pausa, riproduzione, ripresa o ricerca, l'app dovrà agire su di essi e sincronizzarsi con l'app Web Receiver sul dispositivo Cast. Per ulteriori informazioni, consulta Aggiornamenti di stato.

Come funziona la gestione delle sessioni

L'SDK Cast introduce il concetto di sessione Cast, la cui creazione combina i passaggi di connessione a un dispositivo, avvio (o partecipazione) di un'app Web Receiver, connessione a quell'app e inizializzazione di un canale di controllo dei contenuti multimediali. Per saperne di più sulle sessioni Cast e sul ciclo di vita di Web Receiver, consulta la guida al ciclo di vita dell'applicazione Web Receiver .

Le sessioni vengono gestite dalla classe 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 Cast. La tua app può accedere alla sessione Cast attualmente attiva tramite CastContext.getCurrentSession().

Per monitorare lo stato della sessione, aggiungi un listener a CastContext per il CastContextEventType.SESSION_STATE_CHANGED tipo di evento.

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" da finestra di dialogo Trasmetti, puoi aggiungere un listener per il RemotePlayerEventType.IS_CONNECTED_CHANGED tipo di evento nel listener. Nel listener, controlla se RemotePlayer è disconnesso. In caso affermativo, aggiorna lo stato del player locale in base alle 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 Trasmetti del framework, il mittente stesso può interrompere la trasmissione utilizzando l'oggetto corrente CastSession.

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 è 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 si interrompe su un dispositivo (l'origine) 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 Receiver.

Indietro
Configurazione
Avanti
Aggiungi funzionalità avanzate