為 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 物件的例項。需要 CastReceiverContext 物件,才能在 TV 應用程式執行時與 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" />

CastReceiverContext 初始化時,ReceiverOptionsProvider 是用來提供 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 處理。

如要在應用程式中整合 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

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

系統會透過含有深層連結的意圖和您在 Play 管理中心定義的套件名稱,傳送載入指令。

針對寄件者設定 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 不支援某些 Cast 指令,例如 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 應用程式僅支援基本媒體控制項,但 Web Receiver 應用程式支援更進階的控制項,則您應確保傳送端應用程式投放到 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 相同,如果您想在送出前完成一些最後調整,可以指定 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 Receiver。

傳送者應用程式啟動憑證資料

在傳送者端,您可以指定 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());