Migration de l'application émettrice Android du SDK Cast v2 vers le framework d'application Cast

La procédure suivante vous permet de convertir votre application émettrice Android du SDK Cast v2 en expéditeur CAF, qui est basé sur le Singleton CastContext.

Le SDK expéditeur CAF Cast utilise CastContext pour gérer le GoogleAPIClient en votre nom. CastContext gère automatiquement les cycles de vie, les erreurs et les rappels, ce qui simplifie considérablement le développement d'une application Cast.

Introduction

  • L'expéditeur CAF est toujours distribué dans le cadre des services Google Play à l'aide d'Android SDK Manager.
  • De nouveaux packages ont été ajoutés pour assurer le respect de la checklist de conception de Google Cast (com.google.android.gms.cast.framework.*).
  • CAF Sender fournit des widgets conformes aux exigences de l'expérience utilisateur Cast. La version 2 ne fournissait aucun composant d'interface utilisateur et vous obligeait à implémenter ces widgets.
  • L'utilisation de GoogleApiClient n'est plus nécessaire pour utiliser l'API Cast.
  • Le sous-titrage dans CAF Sender est semblable à celui de la version 2.

Dépendances

V2 et CAF ont les mêmes dépendances sur les bibliothèques Support et les services Google Play (version 9.2.0 ou ultérieure), comme décrit dans le guide sur les fonctionnalités de la bibliothèque Support.

La version minimale du SDK Android compatible avec CAF est la version 9 (Gingerbread).

Initialisation

Dans CAF, une étape d'initialisation explicite est requise pour le framework Cast. Cela implique l'initialisation du Singleton CastContext, l'utilisation d'un OptionsProvider approprié pour spécifier l'ID d'application Web du récepteur et toute autre option 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;
    }
}

Déclarez OptionsProvider dans la balise "application" du fichier AndroidManifest.xml de l'application:

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

Initialisez CastContext de manière différée dans la méthode onCreate de chaque activité:

private CastContext mCastContext;

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

    mCastContext = CastContext.getSharedInstance(this);
}

Ces étapes n'étaient pas nécessaires dans la version 2.

Détection d'appareils

Dans CAF, le processus de découverte est démarré et arrêté automatiquement par le framework lorsque l'application passe au premier plan et passe en arrière-plan, respectivement. MediaRouteSelector et MediaRouter.Callback ne doivent pas être utilisés.

Icône Cast et boîte de dialogue Cast

Comme dans la version 2, ces composants sont fournis par la bibliothèque d'aide MediaRouter.

L'icône Cast est toujours implémentée par MediaRouteButton et peut être ajoutée à votre activité (à l'aide d'un ActionBar ou d'un Toolbar) en tant qu'élément de 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"/>

Remplacez la méthode onCreateOptionMenu() de chaque activité en utilisant CastButtonFactory pour connecter MediaRouteButton au 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;
}

Lorsqu'un utilisateur appuie sur le bouton, la boîte de dialogue "Caster" s'affiche automatiquement.

Contrôle des appareils

Dans CAF, le contrôle des appareils est en grande partie géré par le framework. L'application émettrice n'a pas besoin de gérer (et ne doit pas essayer de gérer) la connexion à l'appareil ni de lancer l'application Web Receiver à l'aide de GoogleApiClient. L'interaction entre l'expéditeur et le destinataire Web est désormais représentée sous la forme d'une "session". La classe SessionManager gère le cycle de vie de la session, et démarre et arrête automatiquement les sessions en réponse aux gestes de l'utilisateur: une session démarre lorsque l'utilisateur sélectionne un appareil Cast dans la boîte de dialogue Cast et se termine lorsqu'il appuie sur le bouton "Arrêter la diffusion" dans la boîte de dialogue ou lorsque l'application émettrice se termine. L'application émettrice peut être informée des événements de cycle de vie de la session en enregistrant un SessionManagerListener avec le SessionManager. Les rappels SessionManagerListener définissent des méthodes de rappel pour tous les événements de cycle de vie d'une session.

La classe CastSession représente une session avec un appareil Cast. La classe comporte des méthodes permettant de contrôler le volume de l'appareil et les états de son coupé, ce qui a été précédemment effectué dans la version 2 à l'aide de méthodes sur Cast.CastApi.

Dans la version 2, les rappels Cast.Listener fournissaient des notifications concernant les changements d'état de l'appareil, y compris le volume, l'état du son, de la mise en veille, etc.

Dans CAF, les notifications de changement d'état du volume ou du son sont toujours transmises via des méthodes de rappel dans Cast.Listener. Ces écouteurs sont enregistrés avec CastSession. Toutes les autres notifications d'état de l'appareil sont transmises via des rappels CastStateListener. Ces écouteurs sont enregistrés auprès de CastSession. Veillez à toujours désenregistrer les écouteurs lorsque les fragments, les activités ou les applications associés passent en arrière-plan.

Logique de reconnexion

Comme dans la version 2, CAF tente de rétablir les connexions réseau perdues en raison d'une perte temporaire de signal Wi-Fi ou d'autres erreurs réseau. Cette opération s'effectue désormais au niveau de la session. Une session peut passer à l'état "suspendue" lorsque la connexion est perdue, puis redevenir "connectée" lorsque la connectivité est restaurée. Le framework se charge de la reconnexion à l'application Web Receiver et de la reconnexion des canaux Cast au cours de ce processus.

En outre, CAF ajoute également la reprise de session automatique, qui est activée par défaut (et peut être désactivée via CastOptions). Si l'application émettrice est envoyée en arrière-plan ou arrêtée (en balayant l'écran ou en raison d'un plantage) alors qu'une session Cast est en cours, le framework tente de la reprendre lorsque l'application émettrice revient au premier plan ou est relancée. Cette opération est gérée automatiquement par SessionManager, qui émet les rappels appropriés sur toutes les instances SessionManagerListener enregistrées.

Enregistrement d'un critère personnalisé

Dans la version 2, les canaux personnalisés (implémentés à l'aide de Cast.MessageReceivedCallback) sont enregistrés auprès de Cast.CastApi. Dans CAF, les canaux personnalisés sont plutôt enregistrés auprès de l'instance CastSession. L'enregistrement peut être effectué dans la méthode de rappel SessionManagerListener.onSessionStarted. Pour les applications multimédias, il n'est plus nécessaire d'enregistrer explicitement le canal de commande multimédia via Cast.CastApi.setMessageReceivedCallbacks. Pour en savoir plus, consultez la section suivante.

Commande multimédia

La classe v2 RemoteMediaPlayer est obsolète et ne doit pas être utilisée. Dans CAF, elle est remplacée par la nouvelle classe RemoteMediaClient, qui fournit des fonctionnalités équivalentes dans une API plus pratique. Il n'est pas nécessaire d'initialiser ou d'enregistrer explicitement cet objet. Le framework instancie automatiquement l'objet et enregistre le canal multimédia sous-jacent au début de la session si l'application Web Receiver connectée prend en charge l'espace de noms multimédia.

RemoteMediaClient est accessible en tant que méthode getRemoteMediaClient de l'objet CastSession.

Dans la version 2, toutes les requêtes multimédias émises sur RemoteMediaPlayer renvoyaient un RemoteMediaPlayer.MediaChannelResult via un rappel PendingResult.

Dans CAF, toutes les requêtes médias émises sur le RemoteMediaClient renvoient RemoteMediaClient.MediaChannelResult via un rappel PendingResult, qui peut être utilisé pour suivre la progression et le résultat final de la requête.

La version 2 de RemoteMediaPlayer envoie des notifications sur les modifications de l'état du lecteur multimédia sur le récepteur Web via RemoteMediaPlayer.OnStatusUpdatedListener.

Dans CAF, RemoteMediaClient fournit des rappels équivalents via son interface RemoteMediaClient.Listener. Un nombre illimité d'écouteurs peut être enregistré avec RemoteMediaClient, ce qui permet à plusieurs composants expéditeurs de partager la même instance de RemoteMediaClient associée à la session.

Dans la version 2, l'application émettrice devait assurer la synchronisation de l'interface utilisateur avec l'état du lecteur multimédia sur le récepteur Web.

Dans CAF, la classe UIMediaController assume la plupart de ces responsabilités.

Message d'annonce en superposition

V2 ne fournit pas d'introduction en superposition pour l'interface utilisateur.

CAF fournit une vue personnalisée IntroductoryOverlay permettant de mettre en surbrillance l'icône Cast la première fois que les utilisateurs la voient.

Mini-télécommande

Avec la version 2, vous devez implémenter entièrement une mini-télécommande dans l'application émettrice.

Dans CAF, le SDK fournit une vue personnalisée, MiniControllerFragment, que vous pouvez ajouter au fichier de mise en page de l'application pour les activités dans lesquelles vous souhaitez afficher la mini-télécommande.

Notifications et écran de verrouillage

Dans la version 2, les manettes des notifications et de l'écran de verrouillage ne sont pas fournies par le SDK. Pour ce SDK, vous devez intégrer ces fonctionnalités dans votre application émettrice à l'aide des API du framework Android.

Dans CAF, le SDK fournit un NotificationsOptions.Builder pour vous aider à créer des commandes multimédias pour la notification et l'écran de verrouillage dans l'application de l'expéditeur. Les commandes de notification et d'écran de verrouillage peuvent être activées avec CastOptions lors de l'initialisation de 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();
}

Télécommande agrandie

Dans la version 2, vous devez implémenter entièrement un contrôleur étendu dans l'application émettrice.

CAF fournit une classe d'aide UIMediaController qui vous permet de créer facilement votre propre contrôleur étendu.

CAF ajoute un widget de contrôleur développé prédéfini ExpandedControllerActivity, que vous pouvez simplement ajouter à votre application. Vous n'avez plus besoin d'implémenter un contrôleur développé personnalisé à l'aide de UIMediaController.

Priorité audio

Dans la version 2, vous devez utiliser MediaSessionCompat pour gérer la priorité audio.

Dans CAF, la priorité audio est gérée automatiquement.

Consignation des données de débogage

Dans CAF, il n'existe aucune option de journalisation.

Exemples d'applications

Nous proposons des tutoriels d'atelier de programmation et des exemples d'applications qui utilisent CAF.