Adicionar os principais recursos ao receptor do Android TV

Esta página contém snippets de código e descrições dos recursos disponíveis para personalizar um app Android TV Receiver.

Como configurar bibliotecas

Para disponibilizar as APIs Cast Connect no seu app Android TV:

No Android
  1. Abra o arquivo build.gradle dentro do diretório do módulo do aplicativo.
  2. Verifique se google() está incluído no repositories listado.
      repositories {
        google()
      }
  3. Dependendo do tipo de dispositivo de destino para o app, adicione as versões mais recentes das bibliotecas às suas dependências:
    • Para o app Android Receiver:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast-tv:21.1.0'
          implementation 'com.google.android.gms:play-services-cast:21.5.0'
        }
    • Para o app Android Sender:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.1.0'
          implementation 'com.google.android.gms:play-services-cast-framework:21.5.0'
        }
    . Atualize esse número de versão sempre que os serviços forem atualizados.
  4. Salve as mudanças e clique em Sync Project with Gradle Files na barra de ferramentas.
.
iOS
  1. Verifique se o Podfile está segmentando google-cast-sdk 4.8.3 ou superior
  2. Segmente o iOS 14 ou mais recente. Consulte as notas da versão. para mais detalhes.
      platform: ios, '14'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.3'
      end
.
Web
  1. É necessário ter o navegador Chromium versão M87 ou mais recente.
  2. Adicionar a biblioteca da API Web Sender ao projeto
      <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

Requisito do AndroidX

Para usar as novas versões do Google Play Services, é preciso atualizar um app o namespace androidx. Siga as instruções para migrar para o AndroidX.

App Android TV: pré-requisitos

Para oferecer suporte ao Cast Connect no seu app para Android TV, você precisa criar e oferecer suporte a eventos de uma sessão de mídia. Os dados fornecidos pela sua sessão de mídia fornece as informações básicas, por exemplo, posição, estado da reprodução etc., para seu status de mídia. Sua sessão de mídia também é usada pela biblioteca do Cast Connect para sinalizar quando receber determinadas mensagens de um remetente, como uma pausa.

Para saber mais sobre a sessão de mídia e como inicializá-la, consulte como trabalhar com um guia de sessão de mídia.

Ciclo de vida da sessão de mídia

O app precisa criar uma sessão de mídia quando a reprodução começar e liberá-la quando ele não poderá mais ser controlado. Por exemplo, caso seu app seja de vídeo, deve liberar a sessão quando o usuário sair da atividade de reprodução, seja pelo selecionando "back" para navegar por outros conteúdos ou colocar o app em segundo plano. Se as é um app de música, você deve liberá-lo quando seu aplicativo não estiver mais tocando mídia.

Atualizando o status da sessão

Os dados da sua sessão de mídia devem se manter atualizados com o status da sua de futebol. Por exemplo, se a reprodução for pausada, você deve atualizar e as ações com suporte. As tabelas a seguir listam quais estados você é responsável por se manter atualizado.

MediaMetadataCompat

Campo de metadados Descrição
METADATA_KEY_TITLE (obrigatório) O título da mídia.
METADATA_KEY_DISPLAY_SUBTITLE O subtítulo.
METADATA_KEY_DISPLAY_ICON_URI O URL do ícone.
METADATA_KEY_DURATION (obrigatório) Duração da mídia.
METADATA_KEY_MEDIA_URI O Content ID.
METADATA_KEY_ARTIST O artista.
METADATA_KEY_ALBUM O álbum.

PlaybackStateCompat

Método exigido Descrição
setActions() Define os comandos de mídia compatíveis.
setState() Define o estado de reprodução e a posição atual.

MediaSessionCompat

Método exigido Descrição
setRepeatMode() Define o modo de repetição.
setShuffleMode() Define o modo de ordem aleatória.
setMetadata() Define metadados de mídia.
setPlaybackState() Define o estado da reprodução.
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);
}

Como gerenciar o controle de transporte

O app precisa implementar o callback do controle de transporte de sessão de mídia. A A tabela a seguir mostra as ações de controle de transporte que eles precisam processar:

MediaSessionCompat.Callback

Ações Descrição
onPlay() Retomar
onPause() Pausar
onSeekTo() Procurar uma posição
onStop() Parar a mídia atual
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());

Como configurar a compatibilidade com o Google Cast

Quando uma solicitação de inicialização é enviada por um aplicativo remetente, uma intent é criada com um namespace de aplicativo. Seu aplicativo é responsável por lidar com isso e criar uma instância do CastReceiverContext quando o app de TV é iniciado. O objeto CastReceiverContext é necessário para interagir com o Google Cast enquanto o app para TV estiver em execução. Esse objeto ativa o comando da TV para aceitar mensagens de mídia do Google Cast vindas de qualquer remetente conectado.

Configuração do Android TV

Adicionar um filtro de intent de inicialização

Adicione um novo filtro de intent à atividade que você quer gerenciar com a inicialização. intent do app remetente:

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

Especificar o provedor de opções do receptor

Você precisa implementar ReceiverOptionsProvider para fornecer 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();
  }
}

Em seguida, especifique o provedor de opções no seu AndroidManifest:

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

O ReceiverOptionsProvider é usado para fornecer o CastReceiverOptions quando CastReceiverContext foi inicializado.

Contexto do receptor de transmissão

Inicialize o CastReceiverContext quando o app é criado:

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

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

  ...
}

Inicie a CastReceiverContext quando o app for para o primeiro plano:

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

Ligação stop() no(a) CastReceiverContext depois que o app é colocado em segundo plano no caso de apps de vídeo ou que não têm suporte reprodução em segundo plano:

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

Além disso, caso seu app tenha suporte à reprodução em segundo plano, chame stop(). no CastReceiverContext quando a reprodução for interrompida em segundo plano.

Recomendamos que você use o LifecycleObserver do androidx.lifecycle para gerenciar as chamadas CastReceiverContext.start() e CastReceiverContext.stop(), especialmente se o aplicativo nativo tiver várias atividades. Isso evita disputas condições quando você chama start() e stop() em atividades diferentes.

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

Como conectar a MediaSession ao MediaManager

Quando você cria MediaSession, você também precisa fornecer o token MediaSession atual para CastReceiverContext para que ele saiba para onde enviar os comandos e recuperar o estado da reprodução de mídia:

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

Ao liberar o MediaSession devido à reprodução inativa, defina um token nulo ativado MediaManager:

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

Se o app oferecer suporte à reprodução de mídia enquanto estiver em segundo plano, faça o seguinte: de ligar CastReceiverContext.stop() quando o app for enviado para o segundo plano, chame-o somente quando o app está em segundo plano e não está mais tocando mídia. Exemplo:

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

Como usar o Exoplayer com a Cast Connect

Se você estiver usando Exoplayer, é possível usar o MediaSessionConnector para manter automaticamente a sessão e todas as informações relacionadas, incluindo a o estado de reprodução em vez de monitorar as mudanças manualmente.

MediaSessionConnector.MediaButtonEventHandler pode ser usada para processar eventos do MediaButton chamando setMediaButtonEventHandler(MediaButtonEventHandler) que são tratados pela MediaSessionCompat.Callback por padrão.

Fazer a integração MediaSessionConnector no app, adicione o seguinte à sua classe de atividade do jogador ou ao gerenciar sua sessão de mídia:

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

Configuração do app do remetente

Ativar a compatibilidade com a Cast Connect

Depois de atualizar o app remetente com suporte ao Cast Connect, você poderá declarar sua prontidão definindo androidReceiverCompatible flag ativado LaunchOptions como verdadeiro.

No Android

Requer a versão play-services-cast-framework 19.0.0 ou superior.

A sinalização androidReceiverCompatible é definida em LaunchOptions (que faz 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

Requer a versão v4.4.8 do google-cast-sdk ou mais alto.

A sinalização androidReceiverCompatible é definida em GCKLaunchOptions, que faz parte do GCKCastOptions):

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

Requer a versão do navegador Chromium M87 ou superior.

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

Configuração do Play Console do Google Cast

Configurar o app Android TV

Adicione o nome do pacote do seu app para Android TV em Console para desenvolvedores do Google Cast para associá-lo ao ID do app Google Cast.

Registrar dispositivos de desenvolvedor

Registre o número de série do dispositivo Android TV que você vai usar. para desenvolvimento na Console para desenvolvedores do Google Cast

Sem registro, o Cast Connect só funciona para apps instalados na na Google Play Store por motivos de segurança.

Para mais informações sobre como registrar um dispositivo com Google Cast ou Android TV para transmitir desenvolvimento, consulte a página de registro.

Como carregar mídia

Se você já implementou o suporte a links diretos no app para Android TV: Você deve ter uma definição semelhante configurada no manifesto do 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>

Carregamento por entidade no remetente

Nos remetentes, é possível transmitir o link direto definindo o entity na mídia para a solicitação de carregamento:

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

Requer a versão do navegador Chromium M87 ou superior.

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

O comando de carregamento é enviado por uma intent com seu link direto e o nome do pacote. definidos no console do desenvolvedor.

Como definir credenciais do ATV no remetente

É possível que o app Receptor da Web e o app Android TV ofereçam suporte a diferentes links diretos e credentials (por exemplo, se você lida com autenticação de forma diferente nas duas plataformas). Para resolver isso, você pode fornecer entity e credentials para Android TV:

No 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

Requer a versão do navegador Chromium M87 ou superior.

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

Se o app receptor da Web for iniciado, ele usará o entity e o credentials em a solicitação de carregamento. No entanto, se o app para Android TV for iniciado, o SDK vai substituir entity e credentials com atvEntity e atvCredentials (se especificado).

Carregar por Content ID ou MediaQueueData

Se você não usa o entity ou o atvEntity, mas usa o Content ID, ou URL de conteúdo nas informações de mídia ou use a opção de carregamento de mídia mais detalhada Solicitar dados, você precisa adicionar o seguinte filtro de intent predefinido em seu app para 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>

No lado do remetente, assim como no carregamento por entidade, você pode criar uma solicitação de carregamento com as informações do conteúdo e chamar load().

No 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

Requer a versão do navegador Chromium M87 ou superior.

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

Como processar solicitações de carregamento

Na sua atividade, para processar essas solicitações de carregamento, é necessário processar as intents nos callbacks do ciclo de vida da atividade:

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

Se MediaManager detectar que a intent é de carregamento, extrai uma MediaLoadRequestData da intent e invoque MediaLoadCommandCallback.onLoad(). Você precisa substituir esse método para lidar com a solicitação de carregamento. A chamada de retorno deve ser registrado antes de MediaManager.onNewIntent() é chamado (é recomendável estar em uma atividade ou aplicativo onCreate() ).

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 processar a intent de carregamento, é possível analisá-la nas estruturas de dados que definimos (MediaLoadRequestData) para solicitações de carregamento).

Suporte a comandos de mídia

Suporte básico a controles de mídia

Os comandos básicos de integração incluem os comandos compatíveis com mídia sessão. Esses comandos são notificados por callbacks de sessão de mídia. Você precisa registrar um callback para a sessão de mídia para dar suporte a isso (você pode estar fazendo isso já).

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

Suporte a comandos de controle do Cast

Alguns comandos do Cast não estão disponíveis no MediaSession, como skipAd() ou setActiveMediaTracks(). Além disso, alguns comandos de fila precisam ser implementados aqui porque a fila do Cast não é totalmente compatível com a fila 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());

Especificar comandos de mídia compatíveis

Assim como acontece com o receptor do Cast, seu app para Android TV precisa especificar quais comandos são suportados, de modo que os remetentes podem ativar ou desativar certos controles de interface. Para que fazem parte MediaSession, especificar os comandos PlaybackStateCompat Comandos adicionais devem ser especificados no 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 botões sem suporte

Se o app Android TV oferecer suporte apenas ao controle de mídia básico, mas seu receptor da Web app oferece suporte a um controle mais avançado, verifique se o app remetente se comporta corretamente ao transmitir para o app Android TV. Por exemplo, se o Android TV não oferece suporte à mudança da velocidade do vídeo, ao contrário do app receptor da Web, defina as ações com suporte corretamente em cada plataforma e verifique se o app remetente renderizar a interface corretamente.

Como modificar o MediaStatus

Para oferecer suporte a recursos avançados, como faixas, anúncios, transmissões ao vivo e filas, o Android O app de TV precisa fornecer informações adicionais que não podem ser determinadas por meio de MediaSession

Fornecemos o MediaStatusModifier para isso. O MediaStatusModifier sempre vai operar no MediaSession que você definiu CastReceiverContext.

Para criar e transmitir MediaStatus:

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

Nossa biblioteca de cliente receberá a MediaStatus de base de MediaSession, sua O app Android TV pode especificar outros status e modificar os status por meio de uma Modificador MediaStatus.

Alguns estados e metadados podem ser definidos em MediaSession e MediaStatusModifier. É altamente recomendável defini-los apenas nos MediaSession Você ainda pode usar o modificador para substituir os estados em MediaSession: não recomendado, porque o status no modificador sempre têm uma prioridade maior do que os valores fornecidos por MediaSession.

Como interceptar o MediaStatus antes de enviar

Igual ao SDK do receptor da Web, se você quiser fazer alguns retoques finais antes você pode especificar MediaStatusInterceptor para processar MediaStatus para ser enviada. Passamos uma MediaStatusWriter para manipular o MediaStatus antes que ele seja enviado.

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\"}"));
    }
});

Como gerenciar credenciais do usuário

Talvez o app Android TV só permita que determinados usuários iniciem ou participem do app sessão. Por exemplo, só permita que um remetente inicie ou participe se:

  • O app remetente está conectado à mesma conta e perfil do app ATV.
  • O app remetente está conectado na mesma conta, mas em um perfil diferente do app ATV.

Caso seu app possa lidar com usuários múltiplos ou anônimos, você pode permitir outras que o usuário entre na sessão do ATV. Se o usuário informar credenciais, o app ATV precisa processar suas credenciais para que seu progresso e outros dados do usuário possam ser de forma adequada.

Quando o app remetente iniciar ou participar do app Android TV, o app remetente devem apresentar as credenciais que representam quem está entrando na sessão.

Antes de um remetente iniciar e participar do seu app Android TV, você pode especificar uma iniciar o verificador para conferir se as credenciais do remetente são permitidas. Caso contrário, a transmissão O SDK do Connect volta à inicialização do receptor da Web.

Dados das credenciais de inicialização do app do remetente

No lado do remetente, é possível especificar o CredentialsData para representar quem é de participar da sessão.

O credentials é uma string que pode ser definida pelo usuário, desde que o ATV conseguem entendê-lo. O credentialsType define para qual plataforma CredentialsData vem de ou pode ser um valor personalizado. Por padrão, ele é definido para a plataforma de origem do envio.

O CredentialsData só é transmitido ao app Android TV durante a inicialização ou hora de entrar. Se você configurá-la novamente enquanto estiver conectado, ela não será passada para no seu app Android TV. Se o remetente mudar o perfil durante a conexão, você permanecer na sessão ou ligar para SessionManager.endCurrentCastSession(boolean stopCasting) se você achar que o novo perfil é incompatível com a sessão.

A CredentialsData de cada remetente pode ser recuperada usando getSenders no(a) CastReceiverContext para obter o SenderInfo, getCastLaunchRequest() para conseguir CastLaunchRequest, e depois getCredentialsData().

No Android

Requer a versão play-services-cast-framework 19.0.0 ou superior.

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

Requer a versão v4.8.3 do google-cast-sdk ou mais alto.

Podem ser chamados a qualquer momento depois que as opções forem definidas: GCKCastContext.setSharedInstanceWith(options):

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

Requer a versão do navegador Chromium M87 ou superior.

Pode ser chamado a qualquer momento depois que as opções forem definidas: cast.framework.CastContext.getInstance().setOptions(options);:

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

Como implementar o verificador de solicitação de inicialização do ATV

A CredentialsData são transmitidos ao app Android TV quando um remetente tenta iniciar ou participar. Você pode a implementar LaunchRequestChecker para permitir ou rejeitar a solicitação.

Se uma solicitação for rejeitada, o receptor da Web será carregado em vez de iniciar nativamente no app ATV. Você deverá rejeitar uma solicitação se o ATV não conseguir lida com a solicitação do usuário para iniciar ou participar. Por exemplo, um objeto diferente o usuário está conectado ao app ATV do que o solicitado, e o app não consegue lidam com a troca de credenciais ou não há um usuário conectado no momento App ATV.

Se uma solicitação for permitida, o app ATV será iniciado. Você pode personalizar isso comportamento, dependendo de o app oferecer suporte ao envio de solicitações de carregamento quando um usuário não esteja conectado ao app ATV ou se houver uma incompatibilidade do usuário. Esse comportamento é totalmente personalizável no LaunchRequestChecker.

Criar uma classe que implemente o CastReceiverOptions.LaunchRequestChecker - interface:

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

Em seguida, defina-o 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();
  }
}

Resolvendo true no LaunchRequestChecker inicia o app ATV e o false inicia o app Receptor Web.

Envio e Como receber mensagens personalizadas

O protocolo Cast permite que você envie mensagens de string personalizadas entre os remetentes e seu aplicativo receptor. Você deve registrar um namespace (canal) para enviar mensagens antes de inicializar CastReceiverContext

Android TV: especifique o namespace personalizado

Você precisa especificar os namespaces compatíveis no CastReceiverOptions durante a configuração:

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: como enviar mensagens

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: receber mensagens de namespace personalizado

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