將 Android 傳送者應用程式從 Cast SDK v2 遷移至 Cast 應用程式架構 (CAF)

下列程序可讓您根據 CastContext 單例模式,將 Android 傳送端應用程式從 Cast SDK v2 轉換為 CAF 傳送者。

Cast CAF Sender SDK 會使用 CastContext 代您管理 GoogleAPIClient。 CastContext 會為您管理生命週期、錯誤和回呼,大幅簡化 Cast 應用程式的開發過程。

簡介

  • CAF 傳送者仍使用 Android SDK Manager,在 Google Play 服務中發布
  • 已新增套件,可負責遵守 Google Cast 設計檢查清單 (com.google.android.gms.cast.framework.*)
  • CAF 傳送者提供的小工具符合 Cast 使用者體驗規範;v2 不提供任何 UI 元件,且需要您實作這些小工具。
  • 使用 Cast API 時不再需要使用 GoogleApiClient。
  • CAF 傳送者的隱藏式輔助字幕與第 2 版類似。

依附元件

支援資料庫功能指南所述,第 2 版和 CAF 與支援資料庫和 Google Play 服務 (9.2.0 以上版本) 具有相同的依附元件

CAF 支援的最低 Android SDK 版本為 9 (Gingerbread)。

初始化

在 CAF 中,Cast 架構需要明確的初始化步驟。這包括初始化 CastContext 單例,並使用適當的 OptionsProvider 指定 Web Receiver 應用程式 ID 及其他任何全域選項。

public class CastOptionsProvider implements OptionsProvider {

    @Override
    public CastOptions getCastOptions(Context context) {
        return new CastOptions.Builder()
                .setReceiverApplicationId(context.getString(R.string.app_id))
                .build();
    }

    @Override
    public List<SessionProvider> getAdditionalSessionProviders(Context context) {
        return null;
    }
}

在應用程式 AndroidManifest.xml 檔案的「application」標記中宣告 OptionsProvider

<application>
...
    <meta-data
        android:name=
            "com.google.android.gms.cast.framework.OPTIONS_PROVIDER_CLASS_NAME"
        android:value="com.google.sample.cast.refplayer.CastOptionsProvider" />
</application>

延遲初始化每個 Activity 的 onCreate 方法中的 CastContext

private CastContext mCastContext;

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.video_browser);
    setupActionBar();

    mCastContext = CastContext.getSharedInstance(this);
}

第 2 版中不需要執行這些步驟。

探索裝置

在 CAF 中,架構會在應用程式進入前景並分別進入背景時,自動啟動和停止探索程序。請勿使用 MediaRouteSelectorMediaRouter.Callback

「投放」按鈕和「投放」對話方塊

與第 2 版一樣,這些元件由 MediaRouter 支援資料庫提供。

MediaRouteButton 仍會實作「投放」按鈕,並可透過選單項目的形式新增至活動 (使用 ActionBarToolbar)。

<item
    android:id="@+id/media_route_menu_item"
    android:title="@string/media_route_menu_title"
    app:actionProviderClass="android.support.v7.app.MediaRouteActionProvider"
    app:showAsAction="always"/>

使用 CastButtonFactoryMediaRouteButton 連接至 Cast 架構,以覆寫每個 Activity 的 onCreateOptionMenu() 方法:

private MenuItem mediaRouteMenuItem;

public boolean onCreateOptionsMenu(Menu menu) {
    super.onCreateOptionsMenu(menu);
    getMenuInflater().inflate(R.menu.browse, menu);
    mediaRouteMenuItem =
        CastButtonFactory.setUpMediaRouteButton(getApplicationContext(),
                                                menu,
                                                R.id.media_route_menu_item);
    return true;
}

有人輕觸按鈕時,「投放」對話方塊就會自動顯示。

裝置控制

在 CAF 中,裝置控制項主要是由架構處理。傳送者應用程式不需要處理 (且不應嘗試處理) 連線至裝置,並使用 GoogleApiClient 啟動 Web Receiver 應用程式。傳送者與網路接收器之間的互動現已表示為「工作階段」。SessionManager 類別會處理工作階段生命週期,並根據使用者手勢自動開始及停止工作階段:使用者在「投放」對話方塊中選取投放裝置時,就會啟動工作階段,並在使用者輕觸「投放」對話方塊中的「停止投放」按鈕,或傳送者應用程式本身終止時結束。使用 SessionManager 註冊 SessionManagerListener,即可收到工作階段生命週期事件的通知。SessionManagerListener 回呼會定義所有工作階段生命週期事件的回呼方法。

CastSession 類別代表使用投放裝置的工作階段。該類別含有控制裝置音量和靜音狀態的方法,這些方法先前在 v2 中已使用 Cast.CastApi 上的方法完成。

在第 2 版中,Cast.Listener 回呼會提供裝置狀態變更的通知,包括音量、靜音狀態、待機狀態等等。

在 CAF 中,音量/靜音狀態變更通知仍會透過 Cast.Listener 中的回呼方法傳送;這些事件監聽器已使用 CastSession 註冊。所有其他裝置狀態通知都會透過 CastStateListener 回呼傳送;這些事件監聽器會向 CastSession 註冊。當相關聯的片段、活動或應用程式移至背景時,請務必取消註冊事件監聽器。

重新連線邏輯

與 v2 一樣,CAF 會嘗試重新建立因 Wi-Fi 訊號遺失或其他網路錯誤而中斷的網路連線。現在在工作階段層級完成。工作階段可以在連線中斷時進入「已停權」狀態,並在連線恢復時切換回「已連線」狀態。在這個過程中,架構會重新連線到 Web Receiver 應用程式,並重新連結任何投放管道。

此外,CAF 還會新增自動工作階段恢復功能。系統預設會啟用該功能 (可透過 CastOptions 停用)。如果傳送方應用程式送至背景,或在投放工作階段執行期間終止 (滑行或因當機而終止),架構會在傳送者應用程式返回前景或重新啟動時嘗試繼續執行該工作階段;此功能將由 SessionManager 自動處理,這會在任何已註冊的 SessionManagerListener 執行個體上發出適當的回呼。

自訂管道註冊

在 v2 中,自訂管道 (使用 Cast.MessageReceivedCallback 實作) 會註冊 Cast.CastApi。在 CAF 中,自訂管道會改為向 CastSession 執行個體註冊。您可在 SessionManagerListener.onSessionStarted 回呼方法中完成註冊。媒體應用程式不再需要透過 Cast.CastApi.setMessageReceivedCallbacks 明確註冊媒體控制管道,詳情請參閱下一節。

媒體管理

v2 類別 RemoteMediaPlayer 已淘汰,不應使用。在 CAF 中,它已由新的RemoteMediaClient 類別,在更便利的 API 中提供同等功能。您不需要明確初始化或註冊這個物件;如果連接的 Web Receiver 應用程式支援媒體命名空間,架構就會在工作階段啟動時自動建立物件例項,並註冊基礎媒體管道。

RemoteMediaClient 可做為 CastSession 物件的 getRemoteMediaClient 方法存取。

在 v2 中,RemoteMediaPlayer 上發出的所有媒體要求都會透過 PendingResult 回呼傳回 RemoteMediaPlayer.MediaChannelResult

在 CAF 中,所有在 RemoteMediaClient 上發出的媒體要求都會透過 PendingResult 回呼傳回 RemoteMediaClient.MediaChannelResult,這個回呼可用於追蹤要求的進度和最終結果。

第 2 版 RemoteMediaPlayer 會透過 RemoteMediaPlayer.OnStatusUpdatedListener,傳送關於網路接收器狀態變更的通知。

在 CAF 中,RemoteMediaClient 會透過其 RemoteMediaClient.Listener 介面提供對等的回呼。您可在 RemoteMediaClient 註冊任意數量的事件監聽器,讓多個傳送者元件共用與工作階段相關聯的單一 RemoteMediaClient 執行個體。

在 v2 中,傳送者應用程式必須承擔讓使用者介面與網路接收器上的媒體播放器狀態保持同步的負擔。

在 CAF 中,UIMediaController 類別負責執行大部分的責任。

引言重疊元素

V2 不提供簡介重疊使用者介面。

CAF 提供自訂檢視 IntroductoryOverlay,可在使用者首次向使用者顯示時醒目顯示「投放」按鈕。

Mini 控制器

在第 2 版中,您必須在傳送者應用程式中從頭開始實作迷你控制器。

在 CAF 中,SDK 提供自訂檢視區塊 MiniControllerFragment,可將其新增至要顯示迷你控制器的活動的應用程式版面配置檔案。

通知與螢幕鎖定

在第 2 版中,通知和螢幕鎖定的控制器不是由 SDK 提供。針對該 SDK,您必須使用 Android 架構 API 在寄件者應用程式中建構這些功能。

在 CAF 中,SDK 提供的 NotificationsOptions.Builder 可協助您在傳送者應用程式中建構通知和螢幕鎖定畫面的媒體控制項。在初始化 CastContext 時,您可以使用 CastOptions 啟用通知和螢幕鎖定控制項。

public CastOptions getCastOptions(Context context) {
    NotificationOptions notificationOptions = new NotificationOptions.Builder()
            .setTargetActivityClassName(VideoBrowserActivity.class.getName())
            .build();
    CastMediaOptions mediaOptions = new CastMediaOptions.Builder()
            .setNotificationOptions(notificationOptions)
            .build();

    return new CastOptions.Builder()
            .setReceiverApplicationId(context.getString(R.string.app_id))
            .setCastMediaOptions(mediaOptions)
            .build();
}

展開的控制器

在第 2 版中,您需要在傳送者應用程式中從頭開始實作展開的控制器。

CAF 提供 UIMediaController 輔助類別,可讓您輕鬆建構自己的擴充控制器。

CAF 會新增預先建構的展開控制器小工具 ExpandedControllerActivity,您可以直接將其新增至應用程式。您不再需要使用 UIMediaController 實作自訂的展開控制器,

音訊焦點

在第 2 版中,您必須使用 MediaSessionCompat 管理音訊焦點。

在 CAF 中,系統會自動管理音訊焦點。

偵錯記錄功能

CAF 中沒有記錄選項。

範例應用程式

我們提供程式碼研究室教學課程和使用 CAF 的範例應用程式