Cette page contient des extraits de code et une description des fonctionnalités disponibles pour personnaliser une application réceptrice Android TV.
Configurer des bibliothèques
Pour que les API Cast Connect soient disponibles dans votre application Android TV, procédez comme suit:
-
Ouvrez le fichier
build.gradle
dans le répertoire du module de votre application. -
Vérifiez que
google()
est inclus dans la listerepositories
.repositories { google() }
-
Selon le type d'appareil cible de votre application, ajoutez les dernières versions des bibliothèques à vos dépendances :
-
Pour l'application Android Receiver :
dependencies { implementation 'com.google.android.gms:play-services-cast-tv:21.1.0' implementation 'com.google.android.gms:play-services-cast:21.5.0' }
-
Pour l'application Android Sender :
dependencies { implementation 'com.google.android.gms:play-services-cast:21.1.0' implementation 'com.google.android.gms:play-services-cast-framework:21.5.0' }
-
Pour l'application Android Receiver :
-
Enregistrez les modifications et cliquez sur
Sync Project with Gradle Files
dans la barre d'outils.
-
Assurez-vous que
Podfile
ciblegoogle-cast-sdk
4.8.1 ou une version ultérieure -
Ciblez iOS 14 ou version ultérieure. Pour en savoir plus, consultez les notes de version.
platform: ios, '14' def target_pods pod 'google-cast-sdk', '~>4.8.1' end
- Nécessite le navigateur Chromium version M87 ou ultérieure.
-
Ajouter la bibliothèque de l'API Web Sender à votre projet
<script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>
Exigence AndroidX
Les nouvelles versions des services Google Play nécessitent la mise à jour d'une application afin d'utiliser l'espace de noms androidx
. Suivez les instructions pour effectuer la migration vers AndroidX.
Conditions préalables à l'utilisation de l'application Android TV
Pour utiliser Cast Connect dans votre application Android TV, vous devez créer et gérer des événements à partir d'une session multimédia. Les données fournies par votre session multimédia fournissent des informations de base (par exemple, la position et l'état de la lecture) concernant l'état du contenu multimédia. Votre session multimédia est également utilisée par la bibliothèque Cast Connect pour signaler qu'elle a reçu certains messages d'un expéditeur, par exemple pour la mettre en pause.
Pour en savoir plus sur les sessions multimédias et découvrir comment les initialiser, consultez le guide d'utilisation d'une session multimédia.
Cycle de vie d'une session multimédia
Votre application doit créer une session multimédia au début de la lecture et la publier lorsqu'elle ne peut plus être contrôlée. Par exemple, si votre application est une application vidéo, vous devez libérer la session lorsque l'utilisateur quitte l'activité de lecture, soit en sélectionnant "Retour" pour parcourir d'autres contenus, ou en mettant l'application en arrière-plan. Si votre application est une application musicale, vous devez la libérer lorsqu'elle ne lit plus aucun contenu multimédia.
Mise à jour de l'état de la session...
Vous devez tenir à jour les données de votre session multimédia en fonction de l'état de votre lecteur. Par exemple, lorsque la lecture est suspendue, vous devez mettre à jour l'état de la lecture ainsi que les actions compatibles. Les tableaux suivants répertorient les états que vous devez maintenir à jour.
MediaMetadataCompat
Champ de métadonnées | Description |
---|---|
METADATA_KEY_TITLE (obligatoire) | Titre du contenu multimédia. |
METADATA_KEY_DISPLAY_SUBTITLE | Le sous-titre. |
METADATA_KEY_DISPLAY_ICON_URI | URL de l'icône. |
METADATA_KEY_DURATION (obligatoire) | Durée du contenu multimédia. |
METADATA_KEY_MEDIA_URI | l'ID de contenu ; |
METADATA_KEY_ARTIST | L'artiste. |
METADATA_KEY_ALBUM | L'album. |
PlaybackStateCompat
Méthode obligatoire | Description |
---|---|
setActions() | Définit les commandes multimédias compatibles. |
setState() | Définissez l'état de lecture et la position actuelle. |
MediaSessionCompat
Méthode obligatoire | Description |
---|---|
setRepeatMode() | Définit le mode de répétition. |
setShuffleMode() | Définit le mode aléatoire. |
setMetadata() | Définit les métadonnées multimédias. |
setPlaybackState() | Définit l'état de lecture. |
private fun updateMediaSession() { val metadata = MediaMetadataCompat.Builder() .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI, mMovie.getCardImageUrl()) .build() val playbackState = PlaybackStateCompat.Builder() .setState( PlaybackStateCompat.STATE_PLAYING, player.getPosition(), player.getPlaybackSpeed(), System.currentTimeMillis() ) .build() mediaSession.setMetadata(metadata) mediaSession.setPlaybackState(playbackState) }
private void updateMediaSession() { MediaMetadataCompat metadata = new MediaMetadataCompat.Builder() .putString(MediaMetadataCompat.METADATA_KEY_TITLE, "title") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_SUBTITLE, "subtitle") .putString(MediaMetadataCompat.METADATA_KEY_DISPLAY_ICON_URI,mMovie.getCardImageUrl()) .build(); PlaybackStateCompat playbackState = new PlaybackStateCompat.Builder() .setState( PlaybackStateCompat.STATE_PLAYING, player.getPosition(), player.getPlaybackSpeed(), System.currentTimeMillis()) .build(); mediaSession.setMetadata(metadata); mediaSession.setPlaybackState(playbackState); }
Gérer le contrôle du transport
Votre application doit implémenter le rappel de commande de transport de session multimédia. Le tableau suivant présente les actions de contrôle du transport qu'il doit gérer:
MediaSessionCompat.Callback
Actions | Description |
---|---|
onPlay() | Reprendre |
onPause() | Pause |
onSeekTo() | Rechercher un lieu |
onStop() | Arrêter la lecture du contenu multimédia en cours |
class MyMediaSessionCallback : MediaSessionCompat.Callback() { override fun onPause() { // Pause the player and update the play state. ... } override fun onPlay() { // Resume the player and update the play state. ... } override fun onSeekTo (long pos) { // Seek and update the play state. ... } ... } mediaSession.setCallback( MyMediaSessionCallback() );
public MyMediaSessionCallback extends MediaSessionCompat.Callback { public void onPause() { // Pause the player and update the play state. ... } public void onPlay() { // Resume the player and update the play state. ... } public void onSeekTo (long pos) { // Seek and update the play state. ... } ... } mediaSession.setCallback(new MyMediaSessionCallback());
Configurer la compatibilité avec Cast
Lorsqu'une requête de lancement est envoyée par une application émettrice, un intent est créé avec un espace de noms d'application. Votre application se charge de la gérer et de créer une instance de l'objet CastReceiverContext
lorsque l'application TV est lancée. L'objet CastReceiverContext
est nécessaire pour interagir avec Cast pendant que l'application TV est en cours d'exécution. Cet objet permet à votre application TV d'accepter les messages multimédias Cast provenant de tous les expéditeurs connectés.
Configuration d'Android TV
Ajouter un filtre d'intent de lancement
Ajoutez un filtre d'intent à l'activité dont vous souhaitez gérer l'intent de lancement à partir de votre application émettrice:
<activity android:name="com.example.activity">
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LAUNCH" />
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
Spécifier le fournisseur d'options du récepteur
Vous devez implémenter un ReceiverOptionsProvider
pour fournir CastReceiverOptions
:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) .setStatusText("My App") .build() } }
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider { @Override public CastReceiverOptions getOptions(Context context) { return new CastReceiverOptions.Builder(context) .setStatusText("My App") .build(); } }
Spécifiez ensuite le fournisseur d'options dans AndroidManifest
:
<meta-data
android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
android:value="com.example.mysimpleatvapplication.MyReceiverOptionsProvider" />
ReceiverOptionsProvider
permet de fournir le CastReceiverOptions
lorsque CastReceiverContext
est initialisé.
Contexte du récepteur Cast
Initialisez CastReceiverContext
lors de la création de votre application:
override fun onCreate() { CastReceiverContext.initInstance(this) ... }
@Override public void onCreate() { CastReceiverContext.initInstance(this); ... }
Démarrez CastReceiverContext
lorsque votre application passe au premier plan:
CastReceiverContext.getInstance().start()
CastReceiverContext.getInstance().start();
Appelez stop()
sur le CastReceiverContext
après que l'application passe en arrière-plan pour les applications vidéo ou les applications qui ne sont pas compatibles avec la lecture en arrière-plan:
// Player has stopped. CastReceiverContext.getInstance().stop()
// Player has stopped. CastReceiverContext.getInstance().stop();
De plus, si votre application est compatible avec la lecture en arrière-plan, appelez stop()
sur CastReceiverContext
lorsqu'elle s'arrête en arrière-plan.
Nous vous recommandons vivement d'utiliser LifecycleObserver de la bibliothèque androidx.lifecycle
pour gérer les appels de CastReceiverContext.start()
et de CastReceiverContext.stop()
, en particulier si votre application native comporte plusieurs activités. Cela permet d'éviter les conditions de concurrence lorsque vous appelez start()
et stop()
à partir de différentes activités.
// Create a LifecycleObserver class. class MyLifecycleObserver : DefaultLifecycleObserver { override fun onStart(owner: LifecycleOwner) { // App prepares to enter foreground. CastReceiverContext.getInstance().start() } override fun onStop(owner: LifecycleOwner) { // App has moved to the background or has terminated. CastReceiverContext.getInstance().stop() } } // Add the observer when your application is being created. class MyApplication : Application() { fun onCreate() { super.onCreate() // Initialize CastReceiverContext. CastReceiverContext.initInstance(this /* android.content.Context */) // Register LifecycleObserver ProcessLifecycleOwner.get().lifecycle.addObserver( MyLifecycleObserver()) } }
// Create a LifecycleObserver class. public class MyLifecycleObserver implements DefaultLifecycleObserver { @Override public void onStart(LifecycleOwner owner) { // App prepares to enter foreground. CastReceiverContext.getInstance().start(); } @Override public void onStop(LifecycleOwner owner) { // App has moved to the background or has terminated. CastReceiverContext.getInstance().stop(); } } // Add the observer when your application is being created. public class MyApplication extends Application { @Override public void onCreate() { super.onCreate(); // Initialize CastReceiverContext. CastReceiverContext.initInstance(this /* android.content.Context */); // Register LifecycleObserver ProcessLifecycleOwner.get().getLifecycle().addObserver( new MyLifecycleObserver()); } }
// In AndroidManifest.xml set MyApplication as the application class
<application
...
android:name=".MyApplication">
Connecter MediaSession à MediaManager
Lorsque vous créez un MediaSession
, vous devez également fournir le jeton MediaSession
actuel à CastReceiverContext
pour qu'il sache où envoyer les commandes et récupérer l'état de lecture des contenus multimédias:
val mediaManager: MediaManager = receiverContext.getMediaManager() mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken())
MediaManager mediaManager = receiverContext.getMediaManager(); mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());
Lorsque vous libérez votre MediaSession
en raison d'une lecture inactive, vous devez définir un jeton nul sur MediaManager
:
myPlayer.stop() mediaSession.release() mediaManager.setSessionCompatToken(null)
myPlayer.stop(); mediaSession.release(); mediaManager.setSessionCompatToken(null);
Si votre application prend en charge la lecture de contenus multimédias en arrière-plan, au lieu d'appeler CastReceiverContext.stop()
lorsque votre application est envoyée en arrière-plan, vous ne devez l'appeler que lorsqu'elle est exécutée en arrière-plan et qu'elle ne lit plus de contenu multimédia. Exemple :
class MyLifecycleObserver : DefaultLifecycleObserver { ... // App has moved to the background. override fun onPause(owner: LifecycleOwner) { mIsBackground = true myStopCastReceiverContextIfNeeded() } } // Stop playback on the player. private fun myStopPlayback() { myPlayer.stop() myStopCastReceiverContextIfNeeded() } // Stop the CastReceiverContext when both the player has // stopped and the app has moved to the background. private fun myStopCastReceiverContextIfNeeded() { if (mIsBackground && myPlayer.isStopped()) { CastReceiverContext.getInstance().stop() } }
public class MyLifecycleObserver implements DefaultLifecycleObserver { ... // App has moved to the background. @Override public void onPause(LifecycleOwner owner) { mIsBackground = true; myStopCastReceiverContextIfNeeded(); } } // Stop playback on the player. private void myStopPlayback() { myPlayer.stop(); myStopCastReceiverContextIfNeeded(); } // Stop the CastReceiverContext when both the player has // stopped and the app has moved to the background. private void myStopCastReceiverContextIfNeeded() { if (mIsBackground && myPlayer.isStopped()) { CastReceiverContext.getInstance().stop(); } }
Utiliser Exoplayer avec Cast Connect
Si vous utilisez Exoplayer
, vous pouvez utiliser MediaSessionConnector
pour gérer automatiquement la session et toutes les informations associées, y compris l'état de lecture, au lieu de suivre les modifications manuellement.
MediaSessionConnector.MediaButtonEventHandler
permet de gérer les événements MediaButton en appelant setMediaButtonEventHandler(MediaButtonEventHandler)
, qui sont sinon gérés par MediaSessionCompat.Callback
par défaut.
Pour intégrer MediaSessionConnector
à votre application, ajoutez les éléments suivants à votre classe d'activité de lecteur ou à l'emplacement où vous gérez votre session multimédia:
class PlayerActivity : Activity() { private var mMediaSession: MediaSessionCompat? = null private var mMediaSessionConnector: MediaSessionConnector? = null private var mMediaManager: MediaManager? = null override fun onCreate(savedInstanceState: Bundle?) { ... mMediaSession = MediaSessionCompat(this, LOG_TAG) mMediaSessionConnector = MediaSessionConnector(mMediaSession!!) ... } override fun onStart() { ... mMediaManager = receiverContext.getMediaManager() mMediaManager!!.setSessionCompatToken(currentMediaSession.getSessionToken()) mMediaSessionConnector!!.setPlayer(mExoPlayer) mMediaSessionConnector!!.setMediaMetadataProvider(mMediaMetadataProvider) mMediaSession!!.isActive = true ... } override fun onStop() { ... mMediaSessionConnector!!.setPlayer(null) mMediaSession!!.release() mMediaManager!!.setSessionCompatToken(null) ... } }
public class PlayerActivity extends Activity { private MediaSessionCompat mMediaSession; private MediaSessionConnector mMediaSessionConnector; private MediaManager mMediaManager; @Override protected void onCreate(Bundle savedInstanceState) { ... mMediaSession = new MediaSessionCompat(this, LOG_TAG); mMediaSessionConnector = new MediaSessionConnector(mMediaSession); ... } @Override protected void onStart() { ... mMediaManager = receiverContext.getMediaManager(); mMediaManager.setSessionCompatToken(currentMediaSession.getSessionToken()); mMediaSessionConnector.setPlayer(mExoPlayer); mMediaSessionConnector.setMediaMetadataProvider(mMediaMetadataProvider); mMediaSession.setActive(true); ... } @Override protected void onStop() { ... mMediaSessionConnector.setPlayer(null); mMediaSession.release(); mMediaManager.setSessionCompatToken(null); ... } }
Configuration de l'application de l'expéditeur
Activer la compatibilité avec Cast Connect
Une fois que vous avez mis à jour votre application émettrice pour qu'elle soit compatible avec Cast Connect, vous pouvez indiquer qu'elle est prête en définissant l'indicateur androidReceiverCompatible
sur LaunchOptions
sur "true".
Nécessite play-services-cast-framework
version 19.0.0
ou ultérieure.
L'option androidReceiverCompatible
est définie dans LaunchOptions
(qui fait partie de CastOptions
):
class CastOptionsProvider : OptionsProvider { override fun getCastOptions(context: Context?): CastOptions { val launchOptions: LaunchOptions = Builder() .setAndroidReceiverCompatible(true) .build() return CastOptions.Builder() .setLaunchOptions(launchOptions) ... .build() } }
public class CastOptionsProvider implements OptionsProvider { @Override public CastOptions getCastOptions(Context context) { LaunchOptions launchOptions = new LaunchOptions.Builder() .setAndroidReceiverCompatible(true) .build(); return new CastOptions.Builder() .setLaunchOptions(launchOptions) ... .build(); } }
Nécessite google-cast-sdk
version v4.4.8
ou
ultérieure.
L'option androidReceiverCompatible
est définie dans GCKLaunchOptions
(qui fait partie de GCKCastOptions
):
let options = GCKCastOptions(discoveryCriteria: GCKDiscoveryCriteria(applicationID: kReceiverAppID)) ... let launchOptions = GCKLaunchOptions() launchOptions.androidReceiverCompatible = true options.launchOptions = launchOptions GCKCastContext.setSharedInstanceWith(options)
Nécessite le navigateur Chromium version M87
ou ultérieure.
const context = cast.framework.CastContext.getInstance(); const castOptions = new cast.framework.CastOptions(); castOptions.receiverApplicationId = kReceiverAppID; castOptions.androidReceiverCompatible = true; context.setOptions(castOptions);
Configuration de la console développeur de Cast
Configurer l'application Android TV
Ajoutez le nom de package de votre application Android TV dans la console de développement Cast pour l'associer à votre ID d'application Cast.
Enregistrer des appareils de développeur
Enregistrez le numéro de série de l'appareil Android TV que vous allez utiliser pour le développement dans la console de développement Cast.
Sans enregistrement, Cast Connect ne fonctionnera que pour les applications installées à partir du Google Play Store pour des raisons de sécurité.
Pour en savoir plus sur l'enregistrement d'un appareil Cast ou Android TV pour le développement Cast, consultez la page d'inscription.
Chargement de contenu multimédia
Si vous avez déjà implémenté la prise en charge des liens profonds dans votre application Android TV, une définition similaire doit être configurée dans votre fichier manifeste Android TV:
<activity android:name="com.example.activity">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<data android:scheme="https"/>
<data android:host="www.example.com"/>
<data android:pathPattern=".*"/>
</intent-filter>
</activity>
Charger par entité sur l'expéditeur
Sur les expéditeurs, vous pouvez transmettre le lien profond en définissant entity
dans les informations multimédias de la requête de chargement:
val mediaToLoad = MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") ... .build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build() remoteMediaClient.load(loadRequest)
MediaInfo mediaToLoad = new MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") ... .build(); MediaLoadRequestData loadRequest = new MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build(); remoteMediaClient.load(loadRequest);
let mediaInfoBuilder = GCKMediaInformationBuilder(entity: "https://example.com/watch/some-id") ... mediaInformation = mediaInfoBuilder.build() let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder() mediaLoadRequestDataBuilder.mediaInformation = mediaInformation mediaLoadRequestDataBuilder.credentials = "user-credentials" ... let mediaLoadRequestData = mediaLoadRequestDataBuilder.build() remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
Nécessite le navigateur Chromium version M87
ou ultérieure.
let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4'); mediaInfo.entity = 'https://example.com/watch/some-id'; ... let request = new chrome.cast.media.LoadRequest(mediaInfo); request.credentials = 'user-credentials'; ... cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);
La commande de chargement est envoyée via un intent avec votre lien profond et le nom du package que vous avez défini dans la Play Console.
Définir les identifiants ATV sur l'expéditeur
Il est possible que votre application Web Receiver et votre application Android TV prennent en charge des liens profonds et des credentials
différents (par exemple, si vous gérez l'authentification différemment sur les deux plates-formes). Pour résoudre ce problème, vous pouvez fournir d'autres entity
et credentials
pour Android TV:
val mediaToLoad = MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") .setAtvEntity("myscheme://example.com/atv/some-id") ... .build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") .setAtvCredentials("atv-user-credentials") ... .build() remoteMediaClient.load(loadRequest)
MediaInfo mediaToLoad = new MediaInfo.Builder("some-id") .setEntity("https://example.com/watch/some-id") .setAtvEntity("myscheme://example.com/atv/some-id") ... .build(); MediaLoadRequestData loadRequest = new MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") .setAtvCredentials("atv-user-credentials") ... .build(); remoteMediaClient.load(loadRequest);
let mediaInfoBuilder = GCKMediaInformationBuilder(entity: "https://example.com/watch/some-id") mediaInfoBuilder.atvEntity = "myscheme://example.com/atv/some-id" ... mediaInformation = mediaInfoBuilder.build() let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder() mediaLoadRequestDataBuilder.mediaInformation = mediaInformation mediaLoadRequestDataBuilder.credentials = "user-credentials" mediaLoadRequestDataBuilder.atvCredentials = "atv-user-credentials" ... let mediaLoadRequestData = mediaLoadRequestDataBuilder.build() remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
Nécessite le navigateur Chromium version M87
ou ultérieure.
let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4'); mediaInfo.entity = 'https://example.com/watch/some-id'; mediaInfo.atvEntity = 'myscheme://example.com/atv/some-id'; ... let request = new chrome.cast.media.LoadRequest(mediaInfo); request.credentials = 'user-credentials'; request.atvCredentials = 'atv-user-credentials'; ... cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);
Si l'application Web Receiver est lancée, elle utilise les éléments entity
et credentials
dans la requête de chargement. Toutefois, si votre application Android TV est lancée, le SDK remplace entity
et credentials
par vos atvEntity
et atvCredentials
(si spécifiés).
Chargement par Content ID ou MediaQueueData
Si vous n'utilisez pas entity
ni atvEntity
, et que vous utilisez Content ID ou Content URL dans vos informations multimédias, ou que vous utilisez les données de requête de chargement média plus détaillées, vous devez ajouter le filtre d'intent prédéfini suivant dans votre application Android TV:
<activity android:name="com.example.activity">
<intent-filter>
<action android:name="com.google.android.gms.cast.tv.action.LOAD"/>
<category android:name="android.intent.category.DEFAULT" />
</intent-filter>
</activity>
Du côté de l'expéditeur, comme avec le chargement par entité, vous pouvez créer une requête de chargement avec vos informations de contenu et appeler load()
.
val mediaToLoad = MediaInfo.Builder("some-id").build() val loadRequest = MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build() remoteMediaClient.load(loadRequest)
MediaInfo mediaToLoad = new MediaInfo.Builder("some-id").build(); MediaLoadRequestData loadRequest = new MediaLoadRequestData.Builder() .setMediaInfo(mediaToLoad) .setCredentials("user-credentials") ... .build(); remoteMediaClient.load(loadRequest);
let mediaInfoBuilder = GCKMediaInformationBuilder(contentId: "some-id") ... mediaInformation = mediaInfoBuilder.build() let mediaLoadRequestDataBuilder = GCKMediaLoadRequestDataBuilder() mediaLoadRequestDataBuilder.mediaInformation = mediaInformation mediaLoadRequestDataBuilder.credentials = "user-credentials" ... let mediaLoadRequestData = mediaLoadRequestDataBuilder.build() remoteMediaClient?.loadMedia(with: mediaLoadRequestData)
Nécessite le navigateur Chromium version M87
ou ultérieure.
let mediaInfo = new chrome.cast.media.MediaInfo('some-id"', 'video/mp4'); ... let request = new chrome.cast.media.LoadRequest(mediaInfo); ... cast.framework.CastContext.getInstance().getCurrentSession().loadMedia(request);
Traiter les requêtes de chargement
Dans votre activité, pour gérer ces requêtes de chargement, vous devez gérer les intents dans les rappels de cycle de vie de votre activité:
class MyActivity : Activity() { override fun onStart() { super.onStart() val mediaManager = CastReceiverContext.getInstance().getMediaManager() // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(intent)) { // If the SDK recognizes the intent, you should early return. return } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } // For some cases, a new load intent triggers onNewIntent() instead of // onStart(). override fun onNewIntent(intent: Intent) { val mediaManager = CastReceiverContext.getInstance().getMediaManager() // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(intent)) { // If the SDK recognizes the intent, you should early return. return } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } }
public class MyActivity extends Activity { @Override protected void onStart() { super.onStart(); MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(getIntent())) { // If the SDK recognizes the intent, you should early return. return; } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } // For some cases, a new load intent triggers onNewIntent() instead of // onStart(). @Override protected void onNewIntent(Intent intent) { MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); // Pass the intent to the SDK. You can also do this in onCreate(). if (mediaManager.onNewIntent(intent)) { // If the SDK recognizes the intent, you should early return. return; } // If the SDK doesn't recognize the intent, you can handle the intent with // your own logic. ... } }
Si MediaManager
détecte que l'intent est un intent de chargement, il extrait un objet MediaLoadRequestData
de l'intent et appelle MediaLoadCommandCallback.onLoad()
.
Vous devez remplacer cette méthode pour gérer la requête de chargement. Le rappel doit être enregistré avant l'appel de MediaManager.onNewIntent()
(nous vous recommandons d'utiliser une méthode onCreate()
d'activité ou d'application).
class MyActivity : Activity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val mediaManager = CastReceiverContext.getInstance().getMediaManager() mediaManager.setMediaLoadCommandCallback(MyMediaLoadCommandCallback()) } } class MyMediaLoadCommandCallback : MediaLoadCommandCallback() { override fun onLoad( senderId: String?, loadRequestData: MediaLoadRequestData ): Task{ return Tasks.call { // Resolve the entity into your data structure and load media. val mediaInfo = loadRequestData.getMediaInfo() if (!checkMediaInfoSupported(mediaInfo)) { // Throw MediaException to indicate load failure. throw MediaException( MediaError.Builder() .setDetailedErrorCode(DetailedErrorCode.LOAD_FAILED) .setReason(MediaError.ERROR_REASON_INVALID_REQUEST) .build() ) } myFillMediaInfo(MediaInfoWriter(mediaInfo)) myPlayerLoad(mediaInfo.getContentUrl()) // Update media metadata and state (this clears all previous status // overrides). castReceiverContext.getMediaManager() .setDataFromLoad(loadRequestData) ... castReceiverContext.getMediaManager().broadcastMediaStatus() // Return the resolved MediaLoadRequestData to indicate load success. return loadRequestData } } private fun myPlayerLoad(contentURL: String) { myPlayer.load(contentURL) // Update the MediaSession state. val playbackState: PlaybackStateCompat = Builder() .setState( player.getState(), player.getPosition(), System.currentTimeMillis() ) ... .build() mediaSession.setPlaybackState(playbackState) }
public class MyActivity extends Activity { @Override protected void onCreate(Bundle savedInstanceState) { super.onCreate(savedInstanceState); MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); mediaManager.setMediaLoadCommandCallback(new MyMediaLoadCommandCallback()); } } public class MyMediaLoadCommandCallback extends MediaLoadCommandCallback { @Override public TaskonLoad(String senderId, MediaLoadRequestData loadRequestData) { return Tasks.call(() -> { // Resolve the entity into your data structure and load media. MediaInfo mediaInfo = loadRequestData.getMediaInfo(); if (!checkMediaInfoSupported(mediaInfo)) { // Throw MediaException to indicate load failure. throw new MediaException( new MediaError.Builder() .setDetailedErrorCode(DetailedErrorCode.LOAD_FAILED) .setReason(MediaError.ERROR_REASON_INVALID_REQUEST) .build()); } myFillMediaInfo(new MediaInfoWriter(mediaInfo)); myPlayerLoad(mediaInfo.getContentUrl()); // Update media metadata and state (this clears all previous status // overrides). castReceiverContext.getMediaManager() .setDataFromLoad(loadRequestData); ... castReceiverContext.getMediaManager().broadcastMediaStatus(); // Return the resolved MediaLoadRequestData to indicate load success. return loadRequestData; }); } private void myPlayerLoad(String contentURL) { myPlayer.load(contentURL); // Update the MediaSession state. PlaybackStateCompat playbackState = new PlaybackStateCompat.Builder() .setState( player.getState(), player.getPosition(), System.currentTimeMillis()) ... .build(); mediaSession.setPlaybackState(playbackState); }
Pour traiter l'intent de chargement, vous pouvez l'analyser dans les structures de données que nous avons définies (MediaLoadRequestData
pour les requêtes de chargement).
Compatibilité avec les commandes multimédias
Compatibilité de base avec les commandes de lecture
Les commandes d'intégration de base incluent les commandes compatibles avec les sessions multimédias. Ces commandes sont notifiées via des rappels de session multimédia. Pour ce faire, vous devez enregistrer un rappel à la session multimédia (vous le faites peut-être déjà).
private class MyMediaSessionCallback : MediaSessionCompat.Callback() { override fun onPause() { // Pause the player and update the play state. myPlayer.pause() } override fun onPlay() { // Resume the player and update the play state. myPlayer.play() } override fun onSeekTo(pos: Long) { // Seek and update the play state. myPlayer.seekTo(pos) } ... } mediaSession.setCallback(MyMediaSessionCallback())
private class MyMediaSessionCallback extends MediaSessionCompat.Callback { @Override public void onPause() { // Pause the player and update the play state. myPlayer.pause(); } @Override public void onPlay() { // Resume the player and update the play state. myPlayer.play(); } @Override public void onSeekTo(long pos) { // Seek and update the play state. myPlayer.seekTo(pos); } ... } mediaSession.setCallback(new MyMediaSessionCallback());
Compatibilité avec les commandes Cast
Certaines commandes Cast ne sont pas disponibles dans MediaSession
, comme skipAd()
ou setActiveMediaTracks()
.
En outre, certaines commandes de file d'attente doivent être implémentées ici, car la file d'attente Cast n'est pas entièrement compatible avec la file d'attente MediaSession
.
class MyMediaCommandCallback : MediaCommandCallback() { override fun onSkipAd(requestData: RequestData?): Task{ // Skip your ad ... return Tasks.forResult(null) } } val mediaManager = CastReceiverContext.getInstance().getMediaManager() mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
public class MyMediaCommandCallback extends MediaCommandCallback { @Override public TaskonSkipAd(RequestData requestData) { // Skip your ad ... return Tasks.forResult(null); } } MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); mediaManager.setMediaCommandCallback(new MyMediaCommandCallback());
Spécifier les commandes multimédias compatibles
Comme pour votre récepteur Cast, votre application Android TV doit spécifier les commandes compatibles afin que les expéditeurs puissent activer ou désactiver certaines commandes d'interface utilisateur. Pour les commandes qui font partie de MediaSession
, spécifiez les commandes dans PlaybackStateCompat
.
Les commandes supplémentaires doivent être spécifiées dans le fichier MediaStatusModifier
.
// Set media session supported commands val playbackState: PlaybackStateCompat = PlaybackStateCompat.Builder() .setActions(PlaybackStateCompat.ACTION_PLAY or PlaybackStateCompat.ACTION_PAUSE) .setState(PlaybackStateCompat.STATE_PLAYING) .build() mediaSession.setPlaybackState(playbackState) // Set additional commands in MediaStatusModifier val mediaManager = CastReceiverContext.getInstance().getMediaManager() mediaManager.getMediaStatusModifier() .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT)
// Set media session supported commands PlaybackStateCompat playbackState = new PlaybackStateCompat.Builder() .setActions(PlaybackStateCompat.ACTION_PLAY | PlaybackStateCompat.ACTION_PAUSE) .setState(PlaybackStateCompat.STATE_PLAYING) .build(); mediaSession.setPlaybackState(playbackState); // Set additional commands in MediaStatusModifier MediaManager mediaManager = CastReceiverContext.getInstance().getMediaManager(); mediaManager.getMediaStatusModifier() .setMediaCommandSupported(MediaStatus.COMMAND_QUEUE_NEXT);
Masquer les boutons non compatibles
Si votre application Android TV n'est compatible qu'avec le contrôle multimédia de base, mais que votre application Web Receiver prend en charge des commandes plus avancées, vous devez vous assurer que l'application émettrice se comporte correctement lors de la diffusion vers l'application Android TV. Par exemple, si votre application Android TV ne permet pas de modifier la vitesse de lecture alors que votre application Web Receiver le fait, vous devez définir correctement les actions compatibles sur chaque plate-forme et vous assurer que l'application émettrice affiche correctement l'interface utilisateur.
Modifier MediaStatus
Pour prendre en charge les fonctionnalités avancées telles que les titres, les annonces, le direct et la mise en file d'attente, votre application Android TV doit fournir des informations supplémentaires qui ne peuvent pas être déterminées via MediaSession
.
Pour ce faire, nous fournissons la classe MediaStatusModifier
. MediaStatusModifier
fonctionnera toujours sur le MediaSession
que vous avez défini dans CastReceiverContext
.
Pour créer et diffuser MediaStatus
:
val mediaManager: MediaManager = castReceiverContext.getMediaManager() val statusModifier: MediaStatusModifier = mediaManager.getMediaStatusModifier() statusModifier .setLiveSeekableRange(seekableRange) .setAdBreakStatus(adBreakStatus) .setCustomData(customData) mediaManager.broadcastMediaStatus()
MediaManager mediaManager = castReceiverContext.getMediaManager(); MediaStatusModifier statusModifier = mediaManager.getMediaStatusModifier(); statusModifier .setLiveSeekableRange(seekableRange) .setAdBreakStatus(adBreakStatus) .setCustomData(customData); mediaManager.broadcastMediaStatus();
Notre bibliothèque cliente obtiendra le MediaStatus
de base à partir de MediaSession
. Votre application Android TV peut spécifier un état supplémentaire et le remplacer via un modificateur MediaStatus
.
Certains états et métadonnées peuvent être définis à la fois dans MediaSession
et MediaStatusModifier
. Nous vous recommandons vivement de ne les définir que dans MediaSession
. Vous pouvez toujours utiliser le modificateur pour remplacer les états dans MediaSession
. Nous vous déconseillons de le faire, car l'état du modificateur a toujours une priorité plus élevée que les valeurs fournies par MediaSession
.
Intercepter MediaStatus avant l'envoi
Comme pour le SDK Web Receiver, si vous souhaitez apporter des touches finales avant l'envoi, vous pouvez spécifier un MediaStatusInterceptor
pour traiter le MediaStatus
à envoyer. Nous transmettons un objet MediaStatusWriter
pour manipuler le MediaStatus
avant son envoi.
mediaManager.setMediaStatusInterceptor(object : MediaStatusInterceptor { override fun intercept(mediaStatusWriter: MediaStatusWriter) { // Perform customization. mediaStatusWriter.setCustomData(JSONObject("{data: \"my Hello\"}")) } })
mediaManager.setMediaStatusInterceptor(new MediaStatusInterceptor() { @Override public void intercept(MediaStatusWriter mediaStatusWriter) { // Perform customization. mediaStatusWriter.setCustomData(new JSONObject("{data: \"my Hello\"}")); } });
Gérer les identifiants utilisateur
Il est possible que votre application Android TV n'autorise que certains utilisateurs à lancer ou à rejoindre la session d'application. Par exemple, n'autorisez un expéditeur à participer à un événement ou à un lancement que si:
- L'application émettrice est connectée au même compte et au même profil que l'application Android TV.
- L'application émettrice est connectée au même compte, mais avec un profil différent de celui de l'application Android TV.
Si votre application peut gérer plusieurs utilisateurs ou des utilisateurs anonymes, vous pouvez autoriser n'importe quel autre utilisateur à rejoindre la session Android TV. Si l'utilisateur fournit des identifiants, votre application Android TV doit les gérer pour que sa progression et les autres données utilisateur puissent être correctement suivies.
Lorsque votre application émettrice lance ou rejoint votre application Android TV, elle doit fournir les identifiants correspondant à la personne qui rejoint la session.
Avant qu'un expéditeur lance et rejoint votre application Android TV, vous pouvez spécifier un vérificateur de lancement pour voir si les identifiants de l'expéditeur sont autorisés. Si ce n'est pas le cas, le SDK Cast Connect lance votre Web Receiver.
Données des identifiants pour le lancement de l'application émettrice
Côté expéditeur, vous pouvez spécifier CredentialsData
pour représenter qui rejoint la session.
Le credentials
est une chaîne définie par l'utilisateur, à condition que votre application Android TV puisse la comprendre. Le credentialsType
définit la plate-forme d'où provient l'CredentialsData
ou il peut s'agir d'une valeur personnalisée. Par défaut, il est défini sur la plate-forme à partir de laquelle il est envoyé.
Le CredentialsData
n'est transmis à votre application Android TV qu'au moment du lancement ou de la connexion. Si vous le définissez à nouveau lorsque vous êtes connecté, il ne sera pas transmis à votre application Android TV. Si votre émetteur change de profil alors que vous êtes connecté, vous pouvez rester dans la session ou appeler SessionManager.endCurrentCastSession(boolean stopCasting)
si vous pensez que le nouveau profil est incompatible avec la session.
Le CredentialsData
de chaque expéditeur peut être récupéré en utilisant getSenders
sur CastReceiverContext
pour obtenir SenderInfo
, getCastLaunchRequest()
pour obtenir CastLaunchRequest
, puis getCredentialsData()
.
Nécessite play-services-cast-framework
version 19.0.0
ou ultérieure.
CastContext.getSharedInstance().setLaunchCredentialsData( CredentialsData.Builder() .setCredentials("{\"userId\": \"abc\"}") .build() )
CastContext.getSharedInstance().setLaunchCredentialsData( new CredentialsData.Builder() .setCredentials("{\"userId\": \"abc\"}") .build());
Nécessite google-cast-sdk
version v4.8.1
ou
ultérieure.
Vous pouvez appeler à tout moment une fois les options définies : GCKCastContext.setSharedInstanceWith(options)
.
GCKCastContext.sharedInstance().setLaunch( GCKCredentialsData(credentials: "{\"userId\": \"abc\"}")
Nécessite le navigateur Chromium version M87
ou ultérieure.
Vous pouvez appeler à tout moment une fois les options définies : cast.framework.CastContext.getInstance().setOptions(options);
.
let credentialsData = new chrome.cast.CredentialsData("{\"userId\": \"abc\"}"); cast.framework.CastContext.getInstance().setLaunchCredentialsData(credentialsData);
Implémenter l'outil de vérification des demandes de lancement ATV
Le CredentialsData
est transmis à votre application Android TV lorsqu'un expéditeur tente de lancer ou de rejoindre un groupe. Vous pouvez implémenter un LaunchRequestChecker
.
pour autoriser ou refuser cette demande.
Si une requête est refusée, le récepteur Web est chargé au lieu d'être lancé de manière native dans l'application Android TV. Vous devez refuser une requête si votre Android TV n'est pas en mesure de gérer la demande de lancement ou de participation de l'utilisateur. Il peut s'agir, par exemple, qu'un utilisateur différent de celui qui la demande est connecté à l'application Android TV et que votre application ne puisse pas gérer le changement d'identifiant, ou qu'aucun utilisateur ne soit actuellement connecté à l'application Android TV.
Si une requête est autorisée, l'application Android TV se lance. Vous pouvez personnaliser ce comportement selon que votre application est compatible avec l'envoi de requêtes de chargement lorsqu'un utilisateur n'est pas connecté à l'application Android TV ou en cas de non-concordance des utilisateurs. Ce comportement est entièrement personnalisables dans LaunchRequestChecker
.
Créez une classe implémentant l'interface CastReceiverOptions.LaunchRequestChecker
:
class MyLaunchRequestChecker : LaunchRequestChecker { override fun checkLaunchRequestSupported(launchRequest: CastLaunchRequest): Task{ return Tasks.call { myCheckLaunchRequest( launchRequest ) } } } private fun myCheckLaunchRequest(launchRequest: CastLaunchRequest): Boolean { val credentialsData = launchRequest.getCredentialsData() ?: return false // or true if you allow anonymous users to join. // The request comes from a mobile device, e.g. checking user match. return if (credentialsData.credentialsType == CredentialsData.CREDENTIALS_TYPE_ANDROID) { myCheckMobileCredentialsAllowed(credentialsData.getCredentials()) } else false // Unrecognized credentials type. }
public class MyLaunchRequestChecker implements CastReceiverOptions.LaunchRequestChecker { @Override public TaskcheckLaunchRequestSupported(CastLaunchRequest launchRequest) { return Tasks.call(() -> myCheckLaunchRequest(launchRequest)); } } private boolean myCheckLaunchRequest(CastLaunchRequest launchRequest) { CredentialsData credentialsData = launchRequest.getCredentialsData(); if (credentialsData == null) { return false; // or true if you allow anonymous users to join. } // The request comes from a mobile device, e.g. checking user match. if (credentialsData.getCredentialsType().equals(CredentialsData.CREDENTIALS_TYPE_ANDROID)) { return myCheckMobileCredentialsAllowed(credentialsData.getCredentials()); } // Unrecognized credentials type. return false; }
Ensuite, définissez-le dans votre ReceiverOptionsProvider
:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) ... .setLaunchRequestChecker(MyLaunchRequestChecker()) .build() } }
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider { @Override public CastReceiverOptions getOptions(Context context) { return new CastReceiverOptions.Builder(context) ... .setLaunchRequestChecker(new MyLaunchRequestChecker()) .build(); } }
La résolution de true
dans LaunchRequestChecker
lance l'application Android TV et false
lance votre application Web Receiver.
Envoyer et recevoir des messages personnalisés
Le protocole Cast vous permet d'envoyer des messages sous forme de chaîne personnalisée entre les expéditeurs et l'application réceptrice. Vous devez enregistrer un espace de noms (canal) sur lequel envoyer des messages avant d'initialiser votre CastReceiverContext
.
Android TV : spécifier un espace de noms personnalisé
Vous devez spécifier les espaces de noms compatibles dans le fichier CastReceiverOptions
lors de la configuration:
class MyReceiverOptionsProvider : ReceiverOptionsProvider { override fun getOptions(context: Context?): CastReceiverOptions { return CastReceiverOptions.Builder(context) .setCustomNamespaces( Arrays.asList("urn:x-cast:com.example.cast.mynamespace") ) .build() } }
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider { @Override public CastReceiverOptions getOptions(Context context) { return new CastReceiverOptions.Builder(context) .setCustomNamespaces( Arrays.asList("urn:x-cast:com.example.cast.mynamespace")) .build(); } }
Android TV : envoi de messages
// If senderId is null, then the message is broadcasted to all senders. CastReceiverContext.getInstance().sendMessage( "urn:x-cast:com.example.cast.mynamespace", senderId, customString)
// If senderId is null, then the message is broadcasted to all senders. CastReceiverContext.getInstance().sendMessage( "urn:x-cast:com.example.cast.mynamespace", senderId, customString);
Android TV : recevoir des messages dans un espace de noms personnalisé
class MyCustomMessageListener : MessageReceivedListener { override fun onMessageReceived( namespace: String, senderId: String?, message: String ) { ... } } CastReceiverContext.getInstance().setMessageReceivedListener( "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());
class MyCustomMessageListener implements CastReceiverContext.MessageReceivedListener { @Override public void onMessageReceived( String namespace, String senderId, String message) { ... } } CastReceiverContext.getInstance().setMessageReceivedListener( "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());