Eseguire la migrazione dell'app Android Sender dall'SDK Cast v2 a Cast Application Framework (CAF)

La seguente procedura ti consente di convertire la tua app mittente per Android dall'SDK Cast v2 all'SDK CAF Sender, che si basa sul singleton CastContext.

Avviso: se stai creando un'app mittente CAF o eseguendo la migrazione a CAF, devi utilizzare CastContext e non GoogleAPIClient per accedere all'API Cast. È opportuno utilizzare GoogleAPIClient per accedere ad altre API di Google Play Services.

L'SDK CAF Sender di Cast utilizza CastContext per gestire GoogleAPIClient per tuo conto. CastContext gestisce i cicli di vita, gli errori e i callback per te, semplificando notevolmente lo sviluppo di un'app Cast.

Introduzione

• CAF Sender è ancora distribuito nell'ambito di Google Play Services tramite SDK Manager di Android
• Sono stati aggiunti nuovi pacchetti che si assumono la responsabilità di rispettare l'elenco di controllo per la progettazione di Google Cast (com.google.android.gms.cast.framework.*)
• CAF Sender fornisce widget conformi ai requisiti UX di Cast; v2 non forniva componenti UI e richiedeva l'implementazione di questi widget.
• L'utilizzo di GoogleApiClient non è più necessario per utilizzare l'API Cast.
• Il sottotitolaggio codificato in CAF Sender è simile alla versione 2.

Dipendenze

V2 e CAF hanno le stesse dipendenze dalle librerie di supporto e da Google Play Services (9.2.0 o versioni successive), come descritto nella guida alle funzionalità della libreria di supporto.

La versione minima dell'SDK Android supportata da CAF è la 9 (Gingerbread).

Inizializzazione

In CAF, è necessario un passaggio di inizializzazione esplicito per il framework Cast. Ciò comporta l'inizializzazione del singleton CastContext, utilizzando un OptionsProvider appropriato per specificare l'ID applicazione del ricevitore web e qualsiasi altra opzione globale.

public class CastOptionsProvider implements OptionsProvider {

    @Override
    public CastOptions getCastOptions(Context context) {
        return new CastOptions.Builder()
                .setReceiverApplicationId(context.getString(R.string.app_id))
                .build();
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}

Dichiara OptionsProvider all'interno del tag "application" del file AndroidManifest.xml dell'app:

<application>
...
    <meta-data
        android:name=
            "com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.google.sample.cast.refplayer.CastOptionsProvider" />
</application>

Inizializza in modo lazy CastContext nel metodo onCreate di ogni attività:

private CastContext mCastContext;

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.video_browser);
    setupActionBar();

    mCastContext = CastContext.getSharedInstance(this);
}

Questi passaggi non erano necessari nella versione 2.

Rilevamento dispositivi

In CAF, il processo di rilevamento viene avviato e interrotto automaticamente dal framework quando l'app passa rispettivamente in primo piano e in background. MediaRouteSelector e MediaRouter.Callback non devono essere utilizzati.

Pulsante Trasmetti e finestra di dialogo Trasmetti

Come nella versione 2, questi componenti sono forniti dalla libreria di supporto MediaRouter.

Il pulsante Trasmetti è ancora implementato da MediaRouteButton e può essere aggiunto alla tua attività (utilizzando un ActionBar o un Toolbar), come voce di menu nel tuo menu.

<item
    android:id="@+id/media_route_menu_item"
    android:title="@string/media_route_menu_title"
    app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always"/>

Esegui l'override del metodo onCreateOptionMenu() di ogni attività utilizzando CastButtonFactory per collegare MediaRouteButton al framework Cast:

private MenuItem mediaRouteMenuItem;

public boolean onCreateOptionsMenu(Menu menu) {
    super.onCreateOptionsMenu(menu);
    getMenuInflater().inflate(R.menu.browse, menu);
    mediaRouteMenuItem =
        CastButtonFactory.setUpMediaRouteButton(getApplicationContext(),
                                                menu,
                                                R.id.media_route_menu_item);
    return true;
}

Quando un utente tocca il pulsante, viene visualizzata automaticamente la finestra di dialogo di trasmissione.

Controllo dei dispositivi

In CAF, il controllo dei dispositivi è gestito in gran parte dal framework. L'applicazione mittente non deve gestire (e non deve tentare di gestire) la connessione al dispositivo e l'avvio dell'applicazione Web Receiver utilizzando GoogleApiClient. L'interazione tra mittente e ricevitore web è ora rappresentata come una "sessione". La classe SessionManager gestisce il ciclo di vita della sessione e avvia e interrompe automaticamente le sessioni in risposta alle attivazioni dall'utente: una sessione viene avviata quando l'utente seleziona un dispositivo di trasmissione nella finestra di dialogo di trasmissione e viene terminata quando l'utente tocca il pulsante "Interrompi trasmissione" nella finestra di dialogo di trasmissione o quando l'app mittente stessa termina. L'applicazione mittente può ricevere notifiche degli eventi del ciclo di vita della sessione registrando un SessionManagerListener con SessionManager. I callback SessionManagerListener definiscono i metodi di callback per tutti gli eventi del ciclo di vita della sessione.

La classe CastSession rappresenta una sessione con un dispositivo Cast. La classe dispone di metodi per controllare il volume e gli stati di disattivazione dell'audio del dispositivo, che in precedenza venivano eseguiti nella versione 2 utilizzando i metodi su Cast.CastApi.

Nella versione 2, i callback Cast.Listener fornivano notifiche delle modifiche allo stato del dispositivo, tra cui volume, stato di disattivazione dell'audio, stato di standby e così via.

In CAF, le notifiche di modifica dello stato di volume/disattivazione dell'audio vengono comunque inviate tramite metodi di callback in Cast.Listener; questi listener sono registrati con CastSession. Tutte le notifiche relative allo stato del dispositivo rimanenti vengono inviate tramite callback CastStateListener; questi listener sono registrati con CastSession. Assicurati di annullare comunque la registrazione dei listener quando i frammenti, le attività o le app associati passano in background.

Logica di riconnessione

Come per la versione 2, CAF tenta di ristabilire le connessioni di rete perse a causa di una perdita temporanea del segnale Wi-Fi o di altri errori di rete. Ora questa operazione viene eseguita a livello di sessione. Una sessione può entrare in uno stato "sospeso" quando la connessione viene interrotta e tornare allo stato "connesso" quando la connettività viene ripristinata. Il framework si occupa di riconnettersi all'applicazione Web Receiver e di riconnettere eventuali canali di trasmissione nell'ambito di questo processo.

Inoltre, CAF aggiunge anche il ripristino automatico della sessione, che è attivato per impostazione predefinita (e può essere disattivato tramite CastOptions. Se l'applicazione mittente viene inviata in background o viene terminata (tramite scorrimento o a causa di un arresto anomalo) mentre è in corso una sessione di trasmissione, il framework tenterà di riprendere la sessione quando l'applicazione mittente torna in primo piano o viene riavviata; questa operazione viene gestita automaticamente da SessionManager, che emetterà i callback appropriati su tutte le istanze SessionManagerListener registrate.

Registrazione del canale personalizzato

Nella versione 2, i canali personalizzati (implementati utilizzando Cast.MessageReceivedCallback) vengono registrati con Cast.CastApi. In CAF, i canali personalizzati vengono invece registrati con l'istanza CastSession. La registrazione può essere eseguita nel metodo di callback SessionManagerListener.onSessionStarted. Per le applicazioni multimediali, non è più necessario registrare esplicitamente il canale di controllo multimediale tramite Cast.CastApi.setMessageReceivedCallbacks; per ulteriori dettagli, consulta la sezione seguente.

Controllo dei contenuti multimediali

La classe v2 RemoteMediaPlayer è stata ritirata e non deve essere utilizzata. In CAF, è sostituita dalla nuova classe RemoteMediaClient, che fornisce funzionalità equivalenti in un'API più comoda. Non è necessario inizializzare o registrare esplicitamente questo oggetto. Il framework creerà automaticamente un'istanza dell'oggetto e registrerà il canale multimediale sottostante all'ora di inizio della sessione se l'applicazione Web Receiver a cui viene effettuata la connessione supporta lo spazio dei nomi multimediale.

Puoi accedere a RemoteMediaClient come metodo getRemoteMediaClient dell'oggetto CastSession.

Nella versione 2, tutte le richieste di contenuti multimediali inviate su RemoteMediaPlayer restituivano un RemoteMediaPlayer.MediaChannelResult tramite un callback PendingResult.

In CAF, tutte le richieste di contenuti multimediali inviate su RemoteMediaClient restituiscono un RemoteMediaClient.MediaChannelResult tramite un PendingResult callback che può essere utilizzato per monitorare l'avanzamento e l'eventuale risultato della richiesta.

La versione 2 di RemoteMediaPlayer inviava notifiche relative alle modifiche dello stato del media player sul Web Receiver tramite RemoteMediaPlayer.OnStatusUpdatedListener.

In CAF, RemoteMediaClient fornisce callback equivalenti tramite la sua interfaccia RemoteMediaClient.Listener. È possibile registrare un numero qualsiasi di listener con RemoteMediaClient, il che consente a più componenti mittente di condividere la singola istanza di RemoteMediaClient associata alla sessione.

Nella versione 2, l'applicazione mittente doveva occuparsi di mantenere l'interfaccia utente sincronizzata con lo stato del media player sul ricevitore web.

In CAF, la classe UIMediaController si assume la maggior parte di questa responsabilità.

Overlay introduttivo

La versione 2 non fornisce un'interfaccia utente di overlay introduttiva.

CAF fornisce una visualizzazione personalizzata IntroductoryOverlay per evidenziare il pulsante Trasmetti quando viene mostrato per la prima volta agli utenti.

Mini controller

Nella versione 2, devi implementare un mini controller da zero nell'app mittente.

In CAF, l'SDK fornisce una visualizzazione personalizzata, MiniControllerFragment, che puoi aggiungere al file di layout dell'app delle attività in cui vuoi mostrare il mini controller.

Notifica e schermata di blocco

Nella versione 2, i controller per le notifiche e la schermata di blocco non sono forniti dall'SDK. Per questo SDK, devi integrare queste funzionalità nella tua app mittente utilizzando le API del framework Android.

In CAF, l'SDK fornisce un NotificationsOptions.Builder per aiutarti a creare controlli multimediali per la notifica e la schermata di blocco nell'app mittente. I controlli della notifica e della schermata di blocco possono essere attivati con CastOptions durante l'inizializzazione di CastContext.

public CastOptions getCastOptions(Context context) {
    NotificationOptions notificationOptions = new NotificationOptions.Builder()
            .setTargetActivityClassName(VideoBrowserActivity.class.getName())
            .build();
    CastMediaOptions mediaOptions = new CastMediaOptions.Builder()
            .setNotificationOptions(notificationOptions)
            .build();

    return new CastOptions.Builder()
            .setReceiverApplicationId(context.getString(R.string.app_id))
            .setCastMediaOptions(mediaOptions)
            .build();
}

Controller espanso

Nella versione 2, devi implementare un controller espanso da zero nell'app mittente.

CAF fornisce una classe helper UIMediaController che ti consente di creare facilmente il tuo controller espanso.

CAF aggiunge un widget controller espanso predefinito ExpandedControllerActivity che puoi semplicemente aggiungere alla tua app. Non è più necessario implementare un controller espanso personalizzato utilizzando UIMediaController.

Focus audio

Nella versione 2, devi utilizzare MediaSessionCompat per gestire l'audio focus.

In CAF, la priorità audio viene gestita automaticamente.

Logging di debug

In CAF non sono disponibili opzioni di logging.

App di esempio

Abbiamo tutorial di codelab e app di esempio che utilizzano CAF.

Avviso: se hai eseguito la migrazione della tua app a CAF e questa utilizza ancora GoogleAPIClient per accedere all'API Cast, devi rimuovere GoogleAPIClient e seguire la procedura di inizializzazione per utilizzare CastContext.