為您的 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:20.0.0'
          implementation 'com.google.android.gms:play-services-cast:21.2.0'
        }
    • Android 寄件者應用程式:
        dependencies {
          implementation 'com.google.android.gms:play-services-cast:20.0.0'
          implementation 'com.google.android.gms:play-services-cast-framework:21.2.0'
        }
    請務必在每次更新服務時更新版本號碼。
  4. 儲存變更,然後按一下工具列中的 Sync Project with Gradle Files
iOS
  1. 確認 Podfilegoogle-cast-sdk 4.7.0 以上版本
  2. 目標為 iOS 12 或以上版本。詳情請參閱版本資訊
      platform: ios, '12'
    
      def target_pods
         pod 'google-cast-sdk', '~>4.7.0'
      end
網頁
  1. 必須使用 Chromium 瀏覽器 M87 以上版本。
  2. 將 Web send 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 程式庫也會使用您的媒體工作階段,在收到寄件者的某些訊息 (例如暫停) 時發出通知。

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

媒體工作階段生命週期

應用程式應在播放開始時建立媒體工作階段,並在無法進一步控管的情況下釋出。舉例來說,如果您的應用程式是影片應用程式,當使用者結束播放活動時,您可以選取「#39;back'」來瀏覽其他內容或應用程式背景,您應釋出工作階段。如果您的應用程式是音樂應用程式,當應用程式不再播放任何媒體時,應釋出應用程式。

正在更新工作階段狀態

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

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 專輯。

playStateCompat

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

MediaSessionCompat

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

動作 說明
恢復
onPause() 暫停
SeeSeekTo() 跳轉到特定位置
停止播放目前的媒體
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());

設定投放支援

傳送者應用程式傳送啟動要求時,系統會使用應用程式命名空間建立意圖。電視啟動時,應用程式會負責處理該應用程式,並建立 CastReceiverContext 物件的執行個體。需要 CastReceiverContext 物件,才能在電視應用程式執行時與 Cast 互動。這個物件可讓電視應用程式接受來自任何已連線寄件者的 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();
  }
}