為 Android TV 接收器新增核心功能

本頁提供程式碼片段和說明,協助您瞭解如何自訂 Android TV 接收器應用程式。

設定程式庫

如何讓 Android TV 應用程式使用 Cast Connect API:

Android
  1. 開啟應用程式模組目錄中的 build.gradle 檔案。
  2. 確認 google() 包含在列出的 repositories 中。
      repositories {
        google()
      }
  3. 視應用程式的目標裝置類型而定,將最新版本的程式庫加入依附元件:
    • 如果是 Android 接收端應用程式:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast-tv:21.0.1'
          implementation 'com.google.android.gms:play-services-cast:21.4.0'
        }
    • Android 寄件者應用程式:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:21.0.1'
          implementation 'com.google.android.gms:play-services-cast-framework:21.4.0'
        }
    每次服務更新時,請務必更新這個版本號碼。
  4. 儲存變更,然後按一下工具列中的 Sync Project with Gradle Files
iOS 版
  1. 確認您的 Podfile 指定 google-cast-sdk 4.8.0 以上版本
  2. 指定 iOS 13 以上版本。詳情請參閱版本資訊
      platform: ios, '13'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.8.0'
      end
網頁
  1. 需要 Chromium 瀏覽器 M87 以上版本。
  2. 將 Web Sender API 程式庫新增至專案
      <script src="//www.gstatic.com/cv/js/sender/v1/cast_sender.js?loadCastFramework=1"></script>

AndroidX 需求

新版 Google Play 服務需要應用程式更新才能使用 androidx 命名空間。請按照遷移至 AndroidX 的說明操作。

Android TV 應用程式 (必備條件)

如要在 Android TV 應用程式中支援 Cast Connect,您必須透過媒體工作階段建立和支援事件。媒體工作階段提供的資料會提供位置和播放狀態等基本資訊,例如媒體狀態。Cast Connect 程式庫也會透過您的媒體工作階段,在收到傳送者傳送的特定訊息時 (例如暫停) 發出信號。

如要進一步瞭解媒體工作階段和如何初始化媒體工作階段,請參閱使用媒體工作階段指南

媒體工作階段生命週期

應用程式應在開始播放時建立媒體工作階段,並在無法再控制時放開工作階段。舉例來說,如果應用程式是影片應用程式,您應該在使用者結束播放活動時釋出工作階段,方法包括選取「返回」瀏覽其他內容,或將應用程式背景設為背景。如果您的應用程式是音樂應用程式,則應在應用程式不再播放任何媒體時再發布。

正在更新工作階段狀態

媒體工作階段中的資料應與玩家狀態保持同步。舉例來說,暫停播放時,您應更新播放狀態及支援的動作。下表列出您要負責更新的狀態。

MediaMetadataCompat

中繼資料欄位 說明
METADATA_KEY_TITLE (必要) 媒體標題。
METADATA_KEY_DISPLAY_SUBTITLE 子標題。
METADATA_KEY_DISPLAY_ICON_URI 圖示網址。
METADATA_KEY_DURATION (必要) 媒體時間長度。
METADATA_KEY_MEDIA_URI Content ID。
METADATA_KEY_ARTIST 藝人。
METADATA_KEY_ALBUM 專輯。

PlaybackStateCompat

必要方法 說明
setActions() 設定支援的媒體指令。
setState() 設定播放狀態和目前位置。

MediaSessionCompat

必要方法 說明
setRepeatMode() 設定重複播放模式。
setShuffleMode() 設定隨機播放模式。
setMetadata() 設定媒體中繼資料。
setPlaybackState() 設定播放狀態。
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);
}

處理傳輸控制

應用程式應實作媒體工作階段傳輸控制回呼。下表顯示他們需要處理的傳輸控制項動作:

MediaSessionCompat.Callback

動作 說明
onPlay() 恢復
onPause() 暫停
onSeekTo() 搜尋特定位置
onStop() 停止目前的媒體
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());

設定 Cast 支援

當傳送者應用程式送出啟動要求時,系統會使用應用程式命名空間建立意圖。您的應用程式會負責處理它,並在啟動 TV 應用程式時建立 CastReceiverContext 物件的執行個體。在 TV 應用程式執行時,需要 CastReceiverContext 物件才能與 Cast 互動。這個物件可讓電視應用程式接受任何已連線寄件者的投放媒體訊息。

Android TV 設定

新增啟動意圖篩選器

將新的意圖篩選器加到您要處理傳送者應用程式中的啟動意圖的活動:

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

指定接收器選項提供者

您必須實作 ReceiverOptionsProvider,才能提供 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();
  }
}

然後在 AndroidManifest 中指定選項提供者:

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

ReceiverOptionsProvider 會在 CastReceiverContext 初始化時提供 CastReceiverOptions

投放接收端環境

在應用程式建立時初始化 CastReceiverContext

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

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

  ...
}

在應用程式移至前景時啟動 CastReceiverContext

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

應用程式進入背景後,針對不支援背景播放的影片應用程式或應用程式,在 CastReceiverContext 上呼叫 stop()

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

此外,如果應用程式支援在背景播放,當應用程式在背景停止播放時,請在 CastReceiverContext 上呼叫 stop()

我們強烈建議您使用 androidx.lifecycle 程式庫的 LifecycleObserver 來管理呼叫 CastReceiverContext.start()CastReceiverContext.stop(),尤其在原生應用程式有多個活動時更是如此。這可避免在不同活動中呼叫 start()stop() 時出現競爭狀況。

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

正在將 MediaSession 連結至 MediaManager

建立 MediaSession 時,您也必須將目前的 MediaSession 權杖提供給 CastReceiverContext,使其知道要在哪裡傳送指令並擷取媒體播放狀態:

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

因播放處於閒置狀態而釋出 MediaSession 時,您應在 MediaManager 上設定空值權杖:

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

如果應用程式支援在背景播放媒體,請勿在應用程式傳送至背景時呼叫 CastReceiverContext.stop(),而應只在應用程式於背景執行時呼叫,且不再播放媒體。例如:

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

搭配 Cast Connect 使用 Exoplayer

如果您使用 Exoplayer,則可使用 MediaSessionConnector 自動維護工作階段和所有相關資訊,包括播放狀態,而不是手動追蹤變更。

MediaSessionConnector.MediaButtonEventHandler 可以呼叫 setMediaButtonEventHandler(MediaButtonEventHandler),以處理 MediaButton 事件,根據預設,MediaSessionCompat.Callback 是由 MediaSessionCompat.Callback 處理。

如要在應用程式中整合 MediaSessionConnector,請將以下內容新增至玩家活動類別或管理媒體工作階段的任何位置:

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

寄件者應用程式設定

啟用 Cast Connect 支援

透過 Cast Connect 支援功能更新傳送端應用程式後,您可以將 LaunchOptionsandroidReceiverCompatible 標記設為 true,藉此宣告其就緒。

Android

需要 play-services-cast-framework 19.0.0 以上版本。

androidReceiverCompatible 標記是在 LaunchOptions 中設定 (這是 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

需要 google-cast-sdk v4.4.8 以上版本。

androidReceiverCompatible 標記是在 GCKLaunchOptions 中設定 (這是 GCKCastOptions 的一部分):

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

需要 Chromium 瀏覽器 M87 以上版本。

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

Cast 開發人員控制台設定

設定 Android TV 應用程式

Cast 開發人員控制台中加入 Android TV 應用程式的套件名稱,即可將該應用程式與 Cast 應用程式 ID 建立關聯。

註冊開發人員裝置

Cast 開發人員控制台中,註冊將用於開發的 Android TV 裝置序號。

基於安全考量,如未註冊,Cast Connect 將僅適用於從 Google Play 商店安裝的應用程式。

如要進一步瞭解如何註冊 Cast 或 Android TV 裝置以便進行 Cast 開發,請參閱註冊頁面

正在載入媒體

如果您已在 Android TV 應用程式中實作深層連結支援,應該就會在 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>

根據傳送者上的實體載入

在傳送者上,您可以在載入要求的媒體資訊中設定 entity,藉此傳遞深層連結:

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)
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)
網站

需要 Chromium 瀏覽器 M87 以上版本。

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

載入指令會透過含有您的深層連結和您在開發人員控制台定義的套件名稱的意圖傳送。

為傳送者設定 ATV 憑證

您的 Web Receiver 應用程式和 Android TV 應用程式可能支援不同的深層連結和 credentials (舉例來說,如果您在兩個平台上以不同方式處理驗證作業)。如要解決這個問題,請為 Android TV 提供替代 entitycredentials

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)
網站

需要 Chromium 瀏覽器 M87 以上版本。

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

如果啟動 Web Receiver 應用程式,會在載入要求中使用 entitycredentials。不過,如果 Android TV 應用程式已啟動,SDK 會以您的 atvEntityatvCredentials (如有指定) 覆寫 entitycredentials

依 Content ID 或 MediaQueueData 載入

如果您並未使用 entityatvEntity,且在媒體資訊中使用 Content ID 或內容網址,或使用更詳細的媒體載入要求資料,就必須在 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>

在傳送者端,與依實體載入類似,您可以使用內容資訊建立載入要求並呼叫 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)
網站

需要 Chromium 瀏覽器 M87 以上版本。

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

處理載入要求

在活動中,您必須處理活動生命週期回呼中的意圖,才能處理這些載入要求:

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

如果 MediaManager 偵測到意圖是載入意圖,就會從意圖中擷取 MediaLoadRequestData 物件,並叫用 MediaLoadCommandCallback.onLoad()。您必須覆寫這個方法來處理載入要求。回呼必須先註冊才能呼叫 MediaManager.onNewIntent() (建議在活動或應用程式 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);
}

如要處理載入意圖,您可以將意圖剖析為我們定義的資料結構 (針對載入要求 MediaLoadRequestData)。

支援媒體指令

基本播放控制支援

基本整合指令包括與媒體工作階段相容的指令,這些指令會透過媒體工作階段回呼通知。您需要註冊媒體工作階段的回呼來支援這項功能 (這項操作也許已經執行)。

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

支援投放控制指令

MediaSession 不提供部分投放指令,例如 skipAd()setActiveMediaTracks()。此外,由於 Cast 佇列與 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());

指定支援的媒體指令

和 Cast 接收器一樣,Android TV 應用程式應指定支援的指令,讓寄件者可以啟用或停用特定 UI 控制項。針對屬於 MediaSession 的指令,請在 PlaybackStateCompat 中指定指令。其他指令應在 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);

隱藏不支援的按鈕

如果您的 Android TV 應用程式僅支援基本媒體控制項,但網路接收器應用程式支援更進階的控制選項,則您應確保傳送來源應用程式在投放到 Android TV 應用程式時能正確運作。舉例來說,如果您的 Android TV 應用程式在 Web Receiver 應用程式支援時,不支援變更播放率,您應在每個平台上正確設定支援的動作,並確保傳送端應用程式能正確轉譯 UI。

修改 MediaStatus

為了支援曲目、廣告、直播和佇列等進階功能,Android TV 應用程式必須提供無法透過 MediaSession 進行確認的額外資訊。

為此,我們提供 MediaStatusModifier 類別。MediaStatusModifier 一律會在 CastReceiverContext 中設定的 MediaSession 上執行。

如要建立及廣播 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();

我們的用戶端程式庫會從 MediaSession 取得基礎 MediaStatus,您的 Android TV 應用程式可以透過 MediaStatus 修飾符指定其他狀態並覆寫狀態。

部分狀態和中繼資料可在 MediaSessionMediaStatusModifier 中設定。強烈建議您只在 MediaSession 中設定這些變數。您仍然可以使用修飾符覆寫 MediaSession 中的狀態,我們不建議這麼做,因為修飾符狀態的優先順序一律高於 MediaSession 提供的值。

傳送前攔截 MediaStatus

與 Web Receiver SDK 相同,如果您想在結束之前進行一些最後的調整,可以指定用於處理要傳送的 MediaStatusMediaStatusInterceptor。我們會在傳送 MediaStatusWriter 之前傳入 MediaStatus

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

處理使用者憑證

您的 Android TV 應用程式可能只允許特定使用者啟動或加入應用程式工作階段。舉例來說,只有在下列情況下,寄件者才能發起或加入會議:

  • 傳送者應用程式登入的帳戶和設定檔與 ATV 應用程式相同。
  • 寄件者應用程式登入的帳戶,但設定檔與 ATV 應用程式不同。

如果您的應用程式可以處理多個或匿名使用者,您可以允許其他使用者加入 ATV 工作階段。如果使用者提供憑證,您的 ATV 應用程式就必須處理自己的憑證,才能正確追蹤其進度和其他使用者資料。

傳送者應用程式啟動或加入 Android TV 應用程式時,傳送者應用程式應提供代表工作階段參與者的憑證。

在傳送者啟動及加入 Android TV 應用程式之前,您可以指定啟動檢查工具,確認是否允許傳送端憑證。否則,Cast Connect SDK 會改回啟動 Web 接收器。

寄件者應用程式啟動憑證資料

在傳送者端,您可以指定 CredentialsData 來代表已加入工作階段的使用者。

credentials 是一個可以定義的字串,只要您的 ATV 應用程式能夠解讀即可。credentialsType 會定義 CredentialsData 的來源平台,也可以是自訂值。根據預設,它會設為發送來源的平台。

CredentialsData 只會在啟動或加入時傳遞至 Android TV 應用程式。如果您在連線後再次設定設定檔,系統就不會將其傳送至 Android TV 應用程式。如果傳送方在連線後切換設定檔,可以留在工作階段中;如果您認為新的設定檔與工作階段不相容,可以呼叫 SessionManager.endCurrentCastSession(boolean stopCasting)

您可以使用 CastReceiverContext 上的 getSenders 擷取每位傳送者的 CredentialsData,取得 SenderInfogetCastLaunchRequest() 取得 CastLaunchRequest,以及 getCredentialsData()

Android

需要 play-services-cast-framework 19.0.0 以上版本。

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

需要 google-cast-sdk v4.8.0 以上版本。

設定選項後,就可以隨時呼叫:GCKCastContext.setSharedInstanceWith(options)

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

需要 Chromium 瀏覽器 M87 以上版本。

設定選項後,就可以隨時呼叫:cast.framework.CastContext.getInstance().setOptions(options);

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

實作 ATV 啟動要求檢查工具

當傳送者嘗試啟動或加入時,系統會將 CredentialsData 傳遞至 Android TV 應用程式。您可以實作 LaunchRequestChecker。來允許或拒絕這項要求

如果要求遭拒,系統會載入 Web Receiver,而不是原生啟動 ATV 應用程式。如果 ATV 無法處理使用者要求啟動或加入,您應拒絕要求。舉例來說,如果使用者目前登入 ATV 應用程式而非提出要求,且應用程式無法處理切換憑證,或是目前沒有使用者登入 ATV 應用程式,就屬於這種情況。

如果要求獲準, ATV 應用程式就會啟動。您可以根據應用程式是否支援在使用者未登入 ATV 應用程式的情況下傳送載入要求,或使用者不相符的情況自訂此行為。您可以在 LaunchRequestChecker 中完全自訂這個行為。

建立實作 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;
}

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

LaunchRequestChecker 中解決 true 會啟動 ATV 應用程式,false 則會啟動 Web Receiver 應用程式。

收發自訂訊息

Cast 通訊協定可讓您在寄件者與接收器應用程式之間傳送自訂字串訊息。您必須先註冊命名空間 (管道),才能在初始化 CastReceiverContext 之前傳送訊息。

Android TV:指定自訂命名空間

您必須在設定期間在 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—傳送訊息

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 - 接收自訂命名空間訊息

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