Cómo agregar funciones principales a tu app receptora de Android TV

Esta página contiene fragmentos de código y descripciones de las funciones disponibles para personalizar una app receptora de Android TV.

Configura bibliotecas

A fin de que las API de Cast Connect estén disponibles en tu app para Android TV, haz lo siguiente:

Android
  1. Abre el archivo build.gradle dentro del directorio del módulo de tu aplicación.
  2. Verifica que google() esté incluido en la lista repositories.
      repositories {
        google()
      }
  3. Según el tipo de dispositivo de destino para tu app, agrega las versiones más recientes de las bibliotecas a tus dependencias:
    • Para la app receptora de Android:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast-tv:21.0.0'
          implementation 'com.google.android.gms:play-services-cast:21.3.0'
        }
    • Para la app de Android Sender:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.0.0'
          implementation 'com.google.android.gms:play-services-cast-framework:21.3.0'
        }
    Asegúrate de actualizar este número de versión cada vez que se actualicen los servicios.
  4. Guarda los cambios y haz clic en Sync Project with Gradle Files en la barra de herramientas.
iOS
  1. Asegúrate de que tu Podfile esté orientado a google-cast-sdk con una versión 4.8.0 o superior.
  2. Orienta la app a iOS 13 o una versión posterior. Consulta las notas de la versión para obtener más detalles.
      platform: ios, '13'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.0'
      end
Web
  1. Se requiere la versión M87 del navegador Chromium o una posterior.
  2. Agrega la biblioteca de la API de Web Sender a tu proyecto
      <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Requisito de AndroidX

Las versiones nuevas de los Servicios de Google Play requieren que se actualice una app para usar el espacio de nombres androidx. Sigue las instrucciones para migrar a AndroidX.

App de Android TV: Requisitos previos

Para admitir Cast Connect en tu app de Android TV, debes crear y admitir eventos desde una sesión multimedia. Los datos que proporciona tu sesión multimedia proporcionan información básica (por ejemplo, la posición, el estado de reproducción, etc.) del estado multimedia. La biblioteca de Cast Connect también usa tu sesión multimedia para indicar cuándo recibió ciertos mensajes de un remitente, como una pausa.

Para obtener más información sobre la sesión multimedia y cómo inicializarla, consulta la guía de trabajo con sesiones multimedia.

Ciclo de vida de la sesión multimedia

Tu app debe crear una sesión multimedia cuando se inicia la reproducción y liberarla cuando ya no se puede controlar. Por ejemplo, si tu app es una app de video, debes liberar la sesión cuando el usuario salga de la actividad de reproducción, ya sea seleccionando "atrás" para explorar otro contenido o colocando la app en segundo plano. Si es una app de música, debes liberarla cuando ya no esté reproduciendo ningún contenido multimedia.

Actualizando el estado de la sesión

Los datos de la sesión multimedia deben estar actualizados con el estado del reproductor. Por ejemplo, cuando la reproducción está en pausa, debes actualizar el estado de reproducción, así como las acciones compatibles. En las siguientes tablas, se enumeran los estados que debes mantener actualizados.

MediaMetadataCompat.

Campo de metadatos Descripción
METADATA_KEY_TITLE (obligatorio) El título del contenido multimedia.
METADATA_KEY_DISPLAY_SUBTITLE El subtítulo.
METADATA_KEY_DISPLAY_ICON_URI La URL del ícono.
METADATA_KEY_DURATION (obligatorio) Duración del contenido multimedia.
METADATA_KEY_MEDIA_URI; Content ID.
METADATA_KEY_ARTIST El artista.
METADATA_KEY_ÁLBUM El álbum.

PlaybackStateCompat;

Método obligatorio Descripción
setActions(). Establece comandos de contenido multimedia compatibles.
setState() Establece el estado de reproducción y la posición actual.

MediaSessionCompat;

Método obligatorio Descripción
setRepeatMode(); Establece el modo de repetición.
setShuffleMode(). Establece el modo aleatorio.
setMetadata(). Establece metadatos de contenido multimedia.
setPlaybackState() Establece el estado de reproducción.
Kotlin
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)
}
Java
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);
}

Cómo controlar el control de transporte

Tu app debe implementar la devolución de llamada de control de transporte de sesiones multimedia. En la siguiente tabla, se muestran las acciones de control de transporte que deben controlar:

MediaSessionCompat.Callback.

Acciones Descripción
onPlay() Reanudar
onPause() Pausar
onSeekTo(). Saltar a una posición
onStop() Detener el contenido multimedia actual
Kotlin
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() );
Java
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());

Configuración de la compatibilidad con Cast

Cuando una aplicación emisora envía una solicitud de inicio, se crea un intent con un espacio de nombres de aplicación. Tu aplicación es responsable de controlarla y crear una instancia del objeto CastReceiverContext cuando se inicia la app de TV. El objeto CastReceiverContext es necesario para interactuar con Cast mientras se ejecuta la app de TV. Este objeto permite que tu aplicación para TV acepte mensajes multimedia de transmisión provenientes de cualquier remitente conectado.

Configuración de Android TV

Cómo agregar un filtro de intents de lanzamiento

Agrega un filtro de intents nuevo a la actividad que quieres controlar el intent de inicio desde tu app emisora:

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

Especifica el proveedor de opciones del receptor

Debes implementar un ReceiverOptionsProvider para proporcionar CastReceiverOptions:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
          .setStatusText("My App")
          .build()
    }
}
Java
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider {
  @Override
  public CastReceiverOptions getOptions(Context context) {
    return new CastReceiverOptions.Builder(context)
        .setStatusText("My App")
        .build();
  }
}

Luego, especifica el proveedor de opciones en tu AndroidManifest:

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

ReceiverOptionsProvider se usa para proporcionar el CastReceiverOptions cuando se inicializa CastReceiverContext.

Contexto de receptor de transmisión

Inicializa CastReceiverContext cuando se cree tu app:

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

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

  ...
}

Inicia el CastReceiverContext cuando la app pase al primer plano:

Kotlin
CastReceiverContext.getInstance().start()
Java
CastReceiverContext.getInstance().start();

Llama a stop() en CastReceiverContext después de que la app pase a segundo plano en las apps de video o que no son compatibles con la reproducción en segundo plano:

Kotlin
// Player has stopped.
CastReceiverContext.getInstance().stop()
Java
// Player has stopped.
CastReceiverContext.getInstance().stop();

Además, si tu app admite la reproducción en segundo plano, llama a stop() en CastReceiverContext cuando deje de reproducirse mientras se ejecuta en segundo plano.

Te recomendamos que uses LifecycleObserver desde la androidx.lifecycle biblioteca para administrar las llamadas CastReceiverContext.start() y CastReceiverContext.stop(), en especial si tu app nativa tiene varias actividades. Esto evita las condiciones de carrera cuando llamas a start() y stop() desde diferentes actividades.

Kotlin
// 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())
  }
}
Java
// 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">

Cómo conectar MediaSession a MediaManager

Cuando creas un MediaSession, también debes proporcionar el token MediaSession actual a CastReceiverContext para que sepa dónde enviar los comandos y recuperar el estado de reproducción de contenido multimedia:

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

Cuando lanzas tu MediaSession debido a la reproducción inactiva, debes establecer un token nulo en MediaManager:

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

Si tu app admite la reproducción de contenido multimedia mientras está en segundo plano, en lugar de llamar a CastReceiverContext.stop() cuando se envía a segundo plano, solo debes llamarla cuando esté en segundo plano. Por ejemplo:

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

Cómo usar ExoPlayer con Cast Connect

Si usas Exoplayer, puedes usar MediaSessionConnector para mantener automáticamente la sesión y toda la información relacionada, incluido el estado de reproducción, en lugar de realizar un seguimiento de los cambios de forma manual.

Se puede usar MediaSessionConnector.MediaButtonEventHandler para controlar eventos de MediaButton si llamas a setMediaButtonEventHandler(MediaButtonEventHandler), que, de lo contrario, los controla MediaSessionCompat.Callback de forma predeterminada.

Para integrar MediaSessionConnector en tu app, agrega lo siguiente a la clase de actividad del reproductor o a donde administres tu sesión multimedia:

Kotlin
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)
    ...
  }
}
Java
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);
    ...
  }
}

Configuración de la app emisora

Habilita la compatibilidad con Cast Connect

Una vez que hayas actualizado la app emisora con la compatibilidad con Cast Connect, puedes declarar su preparación configurando la marca androidReceiverCompatible como LaunchOptions como verdadera.

Android

Requiere play-services-cast-framework versión 19.0.0 o superior.

La marca androidReceiverCompatible se establece en LaunchOptions (que forma parte de CastOptions):

Kotlin
class CastOptionsProvider : OptionsProvider {
  override fun getCastOptions(context: Context?): CastOptions {
    val launchOptions: LaunchOptions = Builder()
          .setAndroidReceiverCompatible(true)
          .build()
    return CastOptions.Builder()
          .setLaunchOptions(launchOptions)
          ...
          .build()
    }
}
Java
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();
  }
}
iOS

Requiere google-cast-sdk versión v4.4.8 o superior.

La marca androidReceiverCompatible se establece en GCKLaunchOptions (que forma parte de GCKCastOptions):

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

Se requiere la versión M87 del navegador Chromium o una posterior.

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

Configuración de la Consola para desarrolladores de Cast

Configura la app de Android TV

Agrega el nombre del paquete de tu app de Android TV a Play Console de Cast para asociarla con tu ID de app de Cast.

Cómo registrar los dispositivos de desarrollador

Registra el número de serie del dispositivo Android TV que usarás para el desarrollo en la consola para desarrolladores de Cast.

Sin registro, Cast Connect solo funcionará para apps instaladas desde Google Play Store por razones de seguridad.

Si quieres obtener más información sobre cómo registrar un dispositivo Cast o Android TV para desarrollar contenido, consulta la página de registro.

Carga de contenido multimedia

Si ya implementaste la compatibilidad con vínculos directos en tu app de Android TV, deberías tener una definición similar configurada en el manifiesto de 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>

Cargar por entidad en el remitente

En los remitentes, puedes configurar el entity en la información de medios para la solicitud de carga a fin de pasar el vínculo directo:

Kotlin
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)
En Android
Java
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);
iOS
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)
Web

Se requiere la versión M87 del navegador Chromium o una posterior.

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

El comando de carga se envía a través de un intent con tu vínculo directo y el nombre de paquete que definiste en la consola para desarrolladores.

Configura las credenciales de ATV en el remitente

Es posible que las apps de receptor web y de Android TV admitan diferentes vínculos directos y credentials (por ejemplo, si controlas la autenticación de manera diferente en las dos plataformas). Para solucionar este problema, puedes proporcionar entity y credentials alternativos para Android TV:

Android
Kotlin
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)
Java
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);
iOS
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)
Web

Se requiere la versión M87 del navegador Chromium o una posterior.

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 se inicia la app del receptor web, usa entity y credentials en la solicitud de carga. Sin embargo, si se inicia la app de Android TV, el SDK anula entity y credentials con atvEntity y atvCredentials (si se especifica).

Carga por Content ID o MediaQueueData

Si no usas entity o atvEntity, y si estás usando Content ID o la URL de contenido en tu información de medios, o usas los datos de solicitud de carga de contenido multimedia más detallados, debes agregar el siguiente filtro de intents predefinido en tu app de 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>

En el lado del remitente, de manera similar a load by entity, puedes crear una solicitud de carga con tu información de contenido y llamar a load().

Android
Kotlin
val mediaToLoad = MediaInfo.Builder("some-id").build()
val loadRequest = MediaLoadRequestData.Builder()
    .setMediaInfo(mediaToLoad)
    .setCredentials("user-credentials")
    ...
    .build()
remoteMediaClient.load(loadRequest)
Java
MediaInfo mediaToLoad =
    new MediaInfo.Builder("some-id").build();
MediaLoadRequestData loadRequest =
    new MediaLoadRequestData.Builder()
        .setMediaInfo(mediaToLoad)
        .setCredentials("user-credentials")
        ...
        .build();
remoteMediaClient.load(loadRequest);
iOS
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)
Web

Se requiere la versión M87 del navegador Chromium o una posterior.

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

Cómo controlar solicitudes de carga

En tu actividad, para controlar estas solicitudes de carga, debes controlar los intents en las devoluciones de llamada del ciclo de vida de la actividad:

Kotlin
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.
    ...
  }
}
Java
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 detecta que el intent es un intent de carga, extrae un objeto MediaLoadRequestData del intent y, luego, invoca a MediaLoadCommandCallback.onLoad(). Debes anular este método para controlar la solicitud de carga. La devolución de llamada debe registrarse antes de que se llame a MediaManager.onNewIntent() (se recomienda estar en un método onCreate() de la actividad o de la aplicación).

Kotlin
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)
  }
Java
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);
}

Para procesar el intent de carga, puedes analizarlo en las estructuras de datos que definimos (MediaLoadRequestData para solicitudes de carga).

Cómo brindar compatibilidad con comandos multimedia

Compatibilidad básica con el control de reproducción

Los comandos de integración básica incluyen los que son compatibles con la sesión multimedia. Estos comandos se notifican mediante devoluciones de llamada de sesiones multimedia. Para ello, debes registrar una devolución de llamada a la sesión multimedia (es posible que ya lo estés haciendo).

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

Cómo brindar compatibilidad con comandos de control de transmisión

Hay algunos comandos de Cast que no están disponibles en MediaSession, como skipAd() o setActiveMediaTracks(). Además, algunos comandos de cola deben implementarse aquí porque la cola de transmisión no es completamente compatible con la cola de MediaSession.

Kotlin
class MyMediaCommandCallback : MediaCommandCallback() {
    override fun onSkipAd(requestData: RequestData?): Task {
        // Skip your ad
        ...
        return Tasks.forResult(null)
    }
}

val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
Java
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());

Cómo especificar comandos de medios compatibles

Al igual que con el receptor de transmisiones, la app para Android TV debe especificar qué comandos son compatibles, de modo que los remitentes puedan habilitar o inhabilitar ciertos controles de la IU. Para los comandos que forman parte de MediaSession, especifica los comandos en PlaybackStateCompat. Se deben especificar comandos adicionales en MediaStatusModifier.

Kotlin
// 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)
Java
// 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);

Ocultar botones no admitidos

Si tu app de Android TV solo admite el control de contenido multimedia básico, pero tu app de app receptora admite controles más avanzados, debes asegurarte de que tu app emisora se comporte correctamente cuando transmita a la app de Android TV. Por ejemplo, si tu app de Android TV no admite el cambio de velocidad mientras la app receptora web lo hace, debes configurar correctamente las acciones admitidas en cada plataforma y asegurarte de que tu app emisora renderice correctamente la IU.

Cómo modificar MediaStatus

Para admitir funciones avanzadas, como pistas, anuncios, transmisiones en vivo y colas, la app de Android TV debe proporcionar información adicional que no se pueda determinar mediante MediaSession.

Proporcionamos la clase MediaStatusModifier para que lo logres. MediaStatusModifier siempre funcionará en el MediaSession que configuraste en CastReceiverContext.

Para crear y transmitir MediaStatus, haz lo siguiente:

Kotlin
val mediaManager: MediaManager = castReceiverContext.getMediaManager()
val statusModifier: MediaStatusModifier = mediaManager.getMediaStatusModifier()

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData)

mediaManager.broadcastMediaStatus()
Java
MediaManager mediaManager = castReceiverContext.getMediaManager();
MediaStatusModifier statusModifier = mediaManager.getMediaStatusModifier();

statusModifier
    .setLiveSeekableRange(seekableRange)
    .setAdBreakStatus(adBreakStatus)
    .setCustomData(customData);

mediaManager.broadcastMediaStatus();

Nuestra biblioteca cliente obtendrá el MediaStatus base de MediaSession, la app de Android TV puede especificar el estado adicional y anular el estado a través de un modificador MediaStatus.

Algunos estados y metadatos se pueden configurar en MediaSession y MediaStatusModifier. Te recomendamos que solo las configures en MediaSession. Aún puedes usar el modificador para anular los estados de MediaSession. No se recomienda porque el estado del modificador siempre tiene una prioridad más alta que los valores proporcionados por MediaSession.

Cómo interceptar el MediaStatus antes de su envío

Al igual que con el SDK de Web Receiver, si deseas realizar algunos toques finales antes de enviar datos, puedes especificar un MediaStatusInterceptor para procesar el MediaStatus que se enviará. Pasamos un MediaStatusWriter para manipular el MediaStatus antes de enviarlo.

Kotlin
mediaManager.setMediaStatusInterceptor(object : MediaStatusInterceptor {
    override fun intercept(mediaStatusWriter: MediaStatusWriter) {
      // Perform customization.
        mediaStatusWriter.setCustomData(JSONObject("{data: \"my Hello\"}"))
    }
})
Java
mediaManager.setMediaStatusInterceptor(new MediaStatusInterceptor() {
    @Override
    public void intercept(MediaStatusWriter mediaStatusWriter) {
        // Perform customization.
        mediaStatusWriter.setCustomData(new JSONObject("{data: \"my Hello\"}"));
    }
});

Controla las credenciales de los usuarios

Es posible que tu app de Android TV solo permita que ciertos usuarios inicien la sesión de la app o se unan a ella. Por ejemplo, permite que solo un remitente inicie o se una en los siguientes casos:

  • La app del remitente accede a la misma cuenta y perfil que la app de ATV.
  • La app del remitente accede a la misma cuenta, pero diferente de la de ATV.

Si tu app puede controlar usuarios múltiples o anónimos, puedes permitir que cualquier usuario adicional se una a la sesión de ATV. Si el usuario proporciona credenciales, la app de ATV debe controlarlas para que se pueda realizar un seguimiento adecuado de su progreso y de otros datos del usuario.

Cuando tu app emisora se inicia o se une a tu app para Android TV, esta debe proporcionar las credenciales que representan quién se unirá a la sesión.

Antes de que un remitente se inicie y se una a tu app de Android TV, puedes especificar un verificador de inicio para ver si se permiten las credenciales del remitente. De lo contrario, el SDK de Cast Connect recurre al inicio de tu receptor web.

Datos de credenciales de inicio de la app emisora

En el lado del remitente, puedes especificar el CredentialsData para representar quién se unirá a la sesión.

credentials es una string que puede definir el usuario, siempre que tu app de ATV pueda comprenderla. El credentialsType define de qué plataforma proviene CredentialsData o puede ser un valor personalizado. De forma predeterminada, se configura en la plataforma desde la que se envían.

CredentialsData solo se pasa a tu app de Android TV durante el inicio o la unión. Si lo vuelves a configurar mientras estás conectado, no se pasará a tu app de Android TV. Si el remitente cambia de perfil mientras está conectado, puedes permanecer en la sesión o llamar a SessionManager.endCurrentCastSession(boolean stopCasting) si crees que el perfil nuevo no es compatible con la sesión.

La CredentialsData de cada remitente se puede recuperar mediante getSenders en CastReceiverContext para obtener SenderInfo, getCastLaunchRequest() a fin de obtener CastLaunchRequest y, luego, getCredentialsData().

Android

Requiere play-services-cast-framework versión 19.0.0 o superior.

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

Requiere google-cast-sdk versión v4.8.0 o superior.

Se puede llamar en cualquier momento después de que se establecen las opciones: GCKCastContext.setSharedInstanceWith(options).

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

Se requiere la versión M87 del navegador Chromium o una posterior.

Se puede llamar en cualquier momento después de que se establecen las opciones: cast.framework.CastContext.getInstance().setOptions(options);.

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

Cómo implementar el verificador de solicitudes de inicio de ATV

El CredentialsData se pasa a la app Android TV cuando un remitente intenta iniciar o unirse. Puedes implementar un LaunchRequestChecker. para permitir o rechazar esta solicitud.

Si se rechaza una solicitud, el receptor web se cargará en lugar de iniciarse de forma nativa en la app de ATV. Debes rechazar una solicitud si tu ATV no puede controlar al usuario que solicita iniciar o unirse. Por ejemplo, es posible que un usuario haya accedido a la app de ATV diferente de la solicitada y que tu app no pueda controlar el cambio de credenciales o que no haya un usuario que haya accedido a la app de ATV.

Si se permite una solicitud, se iniciará la app de ATV. Puedes personalizar este comportamiento según si tu app admite el envío de solicitudes de carga cuando un usuario no accedió a la app de ATV o si este no coincide. Este comportamiento es completamente reconocible en LaunchRequestChecker.

Crea una clase mediante la implementación de la interfaz CastReceiverOptions.LaunchRequestChecker:

Kotlin
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.
}
Java
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;
}

Luego, configúralo en tu ReceiverOptionsProvider:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
        ...
        .setLaunchRequestChecker(MyLaunchRequestChecker())
        .build()
  }
}
Java
public class MyReceiverOptionsProvider implements ReceiverOptionsProvider {
  @Override
  public CastReceiverOptions getOptions(Context context) {
    return new CastReceiverOptions.Builder(context)
        ...
        .setLaunchRequestChecker(new MyLaunchRequestChecker())
        .build();
  }
}

La resolución de true en LaunchRequestChecker inicia la app de ATV y false inicia la app de receptor web.

Cómo enviar y recibir mensajes personalizados

El protocolo de transmisión te permite enviar mensajes de string personalizados entre los remitentes y tu aplicación receptora. Debes registrar un espacio de nombres (canal) para enviar mensajes antes de inicializar tu CastReceiverContext.

Android TV: Especifica un espacio de nombres personalizado

Durante la configuración, debes especificar los espacios de nombres compatibles en el CastReceiverOptions:

Kotlin
class MyReceiverOptionsProvider : ReceiverOptionsProvider {
  override fun getOptions(context: Context?): CastReceiverOptions {
    return CastReceiverOptions.Builder(context)
        .setCustomNamespaces(
            Arrays.asList("urn:x-cast:com.example.cast.mynamespace")
        )
        .build()
  }
}
Java
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: Cómo enviar mensajes

Kotlin
// If senderId is null, then the message is broadcasted to all senders.
CastReceiverContext.getInstance().sendMessage(
    "urn:x-cast:com.example.cast.mynamespace", senderId, customString)
Java
// 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: Recibe mensajes de espacio de nombres personalizados

Kotlin
class MyCustomMessageListener : MessageReceivedListener {
    override fun onMessageReceived(
        namespace: String, senderId: String?, message: String ) {
        ...
    }
}

CastReceiverContext.getInstance().setMessageReceivedListener(
    "urn:x-cast:com.example.cast.mynamespace", new MyCustomMessageListener());
Java
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());