Ajouter des fonctionnalités essentielles à votre récepteur Android TV

Cette page contient des extraits de code et des descriptions des fonctionnalités disponibles pour personnaliser une application réceptrice Android TV.

Configurer les bibliothèques

Pour rendre les API Cast Connect disponibles dans votre application Android TV :

Exigence AndroidX

Les nouvelles versions des services Google Play nécessitent la mise à jour d'une application pour utiliser l'espace de noms androidx. Suivez les instructions pour migrer vers AndroidX.

Application Android TV : conditions préalables

Pour pouvoir 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 les informations de base (position, état de la lecture, etc.) pour l'état de votre contenu multimédia. Votre session multimédia est également utilisée par la bibliothèque Cast Connect pour signaler l'arrivée de certains messages d'un émetteur, comme une mise en pause.

Pour en savoir plus sur la session multimédia et sur la façon de l'initialiser, consultez le guide sur l'utilisation d'une session multimédia.

Cycle de vie de la session multimédia

Votre application doit créer une session multimédia lorsque la lecture commence et la libérer 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, soit 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

Les données de votre session multimédia doivent être tenues à jour 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 indiquent les états que vous devez tenir à jour.

MediaMetadataCompat

PlaybackStateCompat

MediaSessionCompat

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 les commandes de transport

Votre application doit implémenter le rappel de contrôle du transport de la session multimédia. Le tableau suivant indique les actions de contrôle du transport qu'ils doivent gérer :

MediaSessionCompat.Callback

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é Cast

Lorsqu'une application émettrice envoie une demande de lancement, une intention est créée avec un espace de noms d'application. Votre application est responsable de sa gestion et de la création d'une instance de l'objet CastReceiverContext lorsque l'application TV est lancée. L'objet CastReceiverContext est nécessaire pour interagir avec Cast lorsque l'application TV est en cours d'exécution. Cet objet permet à votre application TV d'accepter les messages multimédias Cast provenant de n'importe quel expéditeur connecté.

Configuration d'Android TV

Ajouter un filtre d'intent de lancement

Ajoutez un filtre d'intent à l'activité que vous souhaitez utiliser pour gérer l'intent de lancement 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();
  }
}

Indiquez ensuite le fournisseur d'options dans votre AndroidManifest :

 <meta-data
    android:name="com.google.android.gms.cast.tv.RECEIVER_OPTIONS_PROVIDER_CLASS_NAME"
    android:value="com.example.mysimpleatvapplication.MyReceiverOptionsProvider" />

ReceiverOptionsProvider est utilisé pour fournir CastReceiverOptions lorsque CastReceiverContext est initialisé.

Contexte du récepteur Cast

Initialisez CastReceiverContext lorsque votre application est créée :

override fun onCreate() {
  CastReceiverContext.initInstance(this)

  ...
}

@Override
public void onCreate() {
  CastReceiverContext.initInstance(this);

  ...
}

Démarrez le CastReceiverContext lorsque votre application passe au premier plan :

CastReceiverContext.getInstance().start()

CastReceiverContext.getInstance().start();

Appelez stop() sur CastReceiverContext après que l'application passe en arrière-plan pour les applications vidéo ou les applications qui ne prennent pas en charge 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 de lire 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 évite les conditions de course 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 afin de lui indiquer où envoyer les commandes et récupérer l'état de la lecture du contenu multimédia :

val mediaManager: MediaManager = receiverContext.getMediaManager()
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken())

MediaManager mediaManager = receiverContext.getMediaManager();
mediaManager.setSessionCompatToken(currentMediaSession.getSessionToken());

Lorsque vous n'utilisez plus la propriété MediaSession pour des raisons d'inactivité, nous vous conseillons de définir un jeton nul sur MediaManager :

myPlayer.stop()
mediaSession.release()
mediaManager.setSessionCompatToken(null)

myPlayer.stop();
mediaSession.release();
mediaManager.setSessionCompatToken(null);

Si votre application permet de lire des contenus multimédias en arrière-plan, au lieu d'appeler CastReceiverContext.stop() lorsque votre application est envoyée en arrière-plan, vous devez l'appeler uniquement lorsque votre application est en arrière-plan et ne lit plus de contenus multimédias. 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 peut être utilisé pour gérer les événements MediaButton en appelant setMediaButtonEventHandler(MediaButtonEventHandler), qui sont gérés par MediaSessionCompat.Callback par défaut.

Pour intégrer MediaSessionConnector dans votre application, ajoutez ce qui suit à votre classe d'activité du lecteur ou à l'endroit 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 émettrice

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 déclarer qu'elle est prête en définissant le flag androidReceiverCompatible sur LaunchOptions sur "true".

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();
  }
}

let options = GCKCastOptions(discoveryCriteria: GCKDiscoveryCriteria(applicationID: kReceiverAppID))
...
let launchOptions = GCKLaunchOptions()
launchOptions.androidReceiverCompatible = true
options.launchOptions = launchOptions
GCKCastContext.setSharedInstanceWith(options)

const context = cast.framework.CastContext.getInstance();
const castOptions = new cast.framework.CastOptions();
castOptions.receiverApplicationId = kReceiverAppID;
castOptions.androidReceiverCompatible = true;
context.setOptions(castOptions);

Configurer la Cast Developer Console

Configurer l'application Android TV

Ajoutez le nom du package de votre application Android TV dans la console de développement Cast pour l'associer à l'identifiant de votre application Cast.

Enregistrer des appareils de développeur

Enregistrez le numéro de série de l'appareil Android TV que vous utiliserez pour le développement dans la console développeur Cast.

Si l'enregistrement n'est pas effectué, Cast Connect ne fonctionnera que pour les applications installées depuis le 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'enregistrement.

Chargement de contenu multimédia

Si vous avez déjà implémenté la compatibilité avec les liens profonds dans votre application Android TV, vous devriez avoir une définition similaire 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>

Chargement par entité sur l'expéditeur

Sur les émetteurs, vous pouvez transmettre le lien profond en définissant entity dans les informations média pour la demande 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)

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 de package que vous avez défini dans la console de développement.

Définir les identifiants ATV sur l'expéditeur

Il est possible que votre application Web Receiver et votre application Android TV soient compatibles avec 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)

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 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 ID de contenu ou MediaQueueData

Si vous n'utilisez pas entity ni atvEntity, mais que vous utilisez Content ID ou l'URL du contenu dans vos informations sur le contenu multimédia, ou que vous utilisez les données plus détaillées de la requête de chargement de contenu multimédia, 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 pour load by entity, vous pouvez créer une demande de chargement avec les informations sur votre 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)

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);

Gérer 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() (il est recommandé 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 Task onLoad(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'intention de chargement, vous pouvez l'analyser dans les structures de données que nous avons définies (MediaLoadRequestData pour les demandes de chargement).

Compatibilité avec les commandes multimédias

Compatibilité avec les commandes de lecture de base

Les commandes d'intégration de base incluent les commandes compatibles avec la session multimédia. Ces commandes sont signalées par le biais de rappels de session multimédia. Pour ce faire, vous devez enregistrer un rappel dans la session multimédia (vous l'avez peut-être déjà fait).

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(). De plus, 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<Void?> {
        // Skip your ad
        ...
        return Tasks.forResult(null)
    }
}

val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())

public class MyMediaCommandCallback extends MediaCommandCallback {
  @Override
  public Task onSkipAd(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 émetteurs puissent activer ou désactiver certains contrôles d'interface utilisateur. Pour les commandes qui font partie de MediaSession, spécifiez-les dans PlaybackStateCompat. Les commandes supplémentaires doivent être spécifiées dans 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 est compatible avec un contrôle plus avancé, vous devez vous assurer que votre application émettrice se comporte correctement lors de la diffusion sur l'application Android TV. Par exemple, si votre application Android TV n'est pas compatible avec la modification de la vitesse de lecture, contrairement à votre application Web Receiver, vous devez définir correctement les actions compatibles sur chaque plate-forme et vous assurer que votre application émettrice affiche correctement l'UI.

Modifier MediaStatus

Pour prendre en charge les fonctionnalités avancées telles que les pistes, 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 obtenues via MediaSession.

Pour ce faire, nous vous fournissons la classe MediaStatusModifier. MediaStatusModifier fonctionnera toujours sur la session MediaSession que vous avez définie dans CastReceiverContext.

Pour créer et diffuser un 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 obtient le MediaStatus de base à partir de MediaSession. Votre application Android TV peut spécifier un état supplémentaire et remplacer l'état à l'aide d'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. Toutefois, cela est déconseillé, car l'état du modificateur a toujours une priorité plus élevée que les valeurs fournies par MediaSession.

Intercepter l'état MediaStatus avant sa diffusion

Comme pour le SDK du récepteur Web, si vous souhaitez apporter quelques touches finales avant l'envoi, vous pouvez spécifier un MediaStatusInterceptor pour traiter le MediaStatus à envoyer. Nous transmettons un 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 de l'application. Par exemple, n'autorisez un expéditeur à lancer ou à rejoindre une réunion 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 à un profil différent de celui de l'application ATV.

Si votre application peut gérer plusieurs utilisateurs ou des utilisateurs anonymes, vous pouvez autoriser n'importe quel utilisateur supplémentaire à rejoindre la session ATV. Si l'utilisateur fournit des identifiants, votre application ATV doit les gérer afin 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 qui représentent la personne qui rejoint la session.

Avant qu'un expéditeur ne lance et ne rejoigne 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. Sinon, le SDK Cast Connect lance votre Web Receiver.

Données d'identifiants de lancement de l'application émettrice

Du côté de l'expéditeur, vous pouvez spécifier le CredentialsData pour représenter la personne qui rejoint la session.

credentials est une chaîne que l'utilisateur peut définir, à condition que votre application ATV puisse la comprendre. credentialsType définit la plate-forme d'origine de CredentialsData ou peut être 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 participation. Si vous le définissez à nouveau lorsque vous êtes connecté, il ne sera pas transmis à votre application Android TV. Si l'expéditeur change de profil lorsqu'il est 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é à l'aide de getSenders sur CastReceiverContext pour obtenir SenderInfo, getCastLaunchRequest() pour obtenir CastLaunchRequest, puis getCredentialsData().

CastContext.getSharedInstance().setLaunchCredentialsData(
    CredentialsData.Builder()
        .setCredentials("{\"userId\": \"abc\"}")
        .build()
)

CastContext.getSharedInstance().setLaunchCredentialsData(
    new CredentialsData.Builder()
        .setCredentials("{\"userId\": \"abc\"}")
        .build());

GCKCastContext.sharedInstance().setLaunch(
    GCKCredentialsData(credentials: "{\"userId\": \"abc\"}")

let credentialsData =
    new chrome.cast.CredentialsData("{\"userId\": \"abc\"}");
cast.framework.CastContext.getInstance().setLaunchCredentialsData(credentialsData);

Implémenter un vérificateur de demandes de lancement ATV

CredentialsData est transmis à votre application Android TV lorsqu'un expéditeur tente de lancer ou de rejoindre une session. Vous pouvez implémenter un LaunchRequestChecker. pour autoriser ou refuser cette demande.

Si une requête est refusée, le Web Receiver est chargé au lieu de se lancer de manière native dans l'application ATV. Vous devez refuser une requête si votre ATV n'est pas en mesure de gérer la demande de l'utilisateur de lancer ou de rejoindre une application. Par exemple, il se peut qu'un autre utilisateur soit connecté à l'application ATV que celui qui effectue la demande, et que votre application ne soit pas en mesure de gérer le changement d'identifiants, ou qu'aucun utilisateur ne soit actuellement connecté à l'application ATV.

Si une requête est autorisée, l'application ATV se lance. Vous pouvez personnaliser ce comportement selon que votre application accepte ou non l'envoi de demandes de chargement lorsqu'un utilisateur n'est pas connecté à l'application ATV ou en cas d'incohérence d'utilisateur. Ce comportement est entièrement personnalisable 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 Task checkLaunchRequestSupported(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;
}

Définissez-le ensuite 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();
  }
}

Résoudre 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 de chaîne personnalisés entre les expéditeurs et votre application réceptrice. Vous devez enregistrer un espace de noms (canal) pour envoyer des messages avant d'initialiser votre CastReceiverContext.

Android TV : spécifier un espace de noms personnalisé

Vous devez spécifier vos espaces de noms compatibles dans votre 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 : envoyer des 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 d'espace de noms personnalisés

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());