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

本頁面提供程式碼片段和功能說明，可用來自訂 Android TV 接收端應用程式。

設定程式庫

如要讓 Android TV 應用程式使用 Cast Connect API，請按照下列步驟操作：

Android
  1. 開啟應用程式模組目錄中的 build.gradle 檔案。
  2. 確認列出的 repositories 包含 google()。 
      repositories {
    google()
  }
  3. 根據應用程式的目標裝置類型，將最新版本的程式庫新增至依附元件：
    • Android 接收端應用程式： 
        dependencies {
    implementation 'com.google.android.gms:play-services-cast-tv:21.1.1'
    implementation 'com.google.android.gms:play-services-cast:23.0.0'
  }
    • Android 傳送端應用程式： 
        dependencies {
    implementation 'com.google.android.gms:play-services-cast:21.1.1'
    implementation 'com.google.android.gms:play-services-cast-framework:23.0.0'
  }
    每次更新服務時，請務必更新這個版本號碼。
  4. 儲存變更，然後按一下工具列中的 Sync Project with Gradle Files。
iOS
  1. 確認 Podfile 指定 google-cast-sdk 4.8.6 以上版本
  2. 指定 iOS 16 以上版本。詳情請參閱版本資訊。
      platform: ios, '16'

  def target_pods
     pod 'google-cast-sdk', '~>4.8.6'
  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 內容 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 物件的例項。電視應用程式執行時，必須使用 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();
  }
}

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

搭配使用 Exoplayer 和 Cast Connect

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

MediaSessionConnector.MediaButtonEventHandler 可用於處理 MediaButton 事件，方法是呼叫 setMediaButtonEventHandler(MediaButtonEventHandler)，否則預設會由 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 後，您可以在 LaunchOptions 上將 androidReceiverCompatible 旗標設為 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

必須使用 v4.4.8 以上版本的 google-cast-sdk。

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

網路接收器應用程式和 Android TV 應用程式可能支援不同的深層連結和 credentials (例如，您在兩個平台上處理驗證的方式不同)。如要解決這個問題，您可以為 Android TV 提供替代的 entity 和 credentials：

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 接收端應用程式已啟動，則會使用載入要求中的 entity 和 credentials。不過，如果 Android TV 應用程式已推出，SDK 會將 entity 和 credentials 覆寫為 atvEntity 和 atvCredentials (如有指定)。

依 Content ID 或 MediaQueueData 載入

如果您未使用 entity 或 atvEntity，而是在媒體資訊中使用 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() 之前註冊 (建議在 Activity 或 Application 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 不支援某些 Cast 指令，例如 skipAd() 或 setActiveMediaTracks()。此外，由於 Cast 佇列與 MediaSession 佇列不完全相容，因此部分佇列指令必須在此實作。

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

val mediaManager = CastReceiverContext.getInstance().getMediaManager()
mediaManager.setMediaCommandCallback(MyMediaCommandCallback())
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 應用程式僅支援基本媒體遙控器，但 Web 接收端應用程式支援更進階的控制，請務必確保投放至 Android TV 應用程式時，傳送端應用程式能正常運作。舉例來說，如果 Android TV 應用程式不支援變更播放速率，但 Web 接收端應用程式支援，請在各平台正確設定支援的操作，並確保傳送端應用程式能正確顯示 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 修飾符指定其他狀態並覆寫狀態。

部分狀態和中繼資料可以在 MediaSession 和 MediaStatusModifier 中設定。強烈建議您只在 MediaSession 中設定這些值。您仍可使用修飾符覆寫 MediaSession 中的狀態，但不建議這麼做，因為修飾符中的狀態一律優先於 MediaSession 提供的值。

在傳送前攔截 MediaStatus

與 Web 接收端 SDK 相同，如果您想在傳送前進行一些最後調整，可以指定 MediaStatusInterceptor 來處理要傳送的 MediaStatus。我們傳入 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)。

如要擷取每個寄件者的CredentialsData，請在CastReceiverContext上使用getSenders取得SenderInfo，使用getCastLaunchRequest()取得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

必須使用 v4.8.6 以上版本的 google-cast-sdk。

設定選項後，隨時可以呼叫：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 接收端，而不是在 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 接收端應用程式。

傳送及接收自訂訊息

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());
上一頁
總覽
下一頁
曲目