Android センダーアプリを Cast SDK v2 から Cast Application Framework(CAF)に移行する

次の手順では、Android センダーアプリを Cast SDK v2 から CastContext シングルトンに基づく CAF センダーに変換できます。

Cast CAF Sender SDK は CastContext を使用して、ユーザーに代わって GoogleAPIClient を管理します。 CastContext ではライフサイクル、エラー、コールバックが管理されるため、キャストアプリの開発が大幅に簡素化されます。

はじめに

  • CAF 送信者は、Android SDK Manager を使用して Google Play 開発者サービスの一部として引き続き配布されます。
  • Google Cast デザイン チェックリスト(com.google.android.gms.cast.framework.*)の遵守を担う新しいパッケージが追加されました。
  • CAF Sender は、Cast UX 要件を満たすウィジェットを提供しています。v2 では UI コンポーネントを提供しておらず、これらのウィジェットを実装する必要がありました。
  • Cast API を使用するために GoogleApiClient を使用する必要がなくなりました。
  • CAF Sender の字幕は v2 と類似しています。

依存関係

サポート ライブラリ機能ガイドに記載されているように、V2 と CAF は、サポート ライブラリと Google Play 開発者サービス(9.2.0 以降)に対して同じ依存関係を持ちます。

CAF がサポートする Android SDK の最小バージョンは 9(Gingerbread)です。

初期化

CAF では、キャスト フレームワークに対して明示的な初期化ステップが必要です。この手順では、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>

各アクティビティの onCreate メソッドで CastContext を遅延初期化します。

private CastContext mCastContext;

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

    mCastContext = CastContext.getSharedInstance(this);
}

この手順は v2 では不要です。

デバイス検出

CAF では、アプリがフォアグラウンドになり、バックグラウンドに移動したときに、フレームワークによって自動的に開始および停止されます。MediaRouteSelectorMediaRouter.Callback は使用しないでください。

キャスト アイコンとキャスト ダイアログ

v2 と同様に、これらのコンポーネントは MediaRouter サポート ライブラリによって提供されます。

キャスト アイコンは引き続き MediaRouteButton によって実装され、メニューのメニュー項目として(ActionBar または Toolbar を使用して)アクティビティに追加できます。

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

CastButtonFactory を使用して MediaRouteButton をキャスト フレームワークに接続し、各アクティビティの 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 を使用したウェブ レシーバー アプリケーションの起動を処理する必要はありません(処理を試行することもありません)。センダーとウェブレシーバー間のやり取りが「セッション」として表されるようになりました。SessionManager クラスはセッションのライフサイクルを処理し、ユーザーの操作に応じてセッションを自動的に開始および停止します。セッションは、ユーザーがキャスト ダイアログでキャスト デバイスを選択すると開始され、ユーザーがキャスト ダイアログの [キャストを停止] ボタンをタップするか、センダーアプリ自体が終了すると終了します。センダーアプリは、SessionManagerSessionManagerListener を登録することで、セッション ライフサイクル イベントを通知できます。SessionManagerListener コールバックは、すべてのセッション ライフサイクル イベントのコールバック メソッドを定義します。

CastSession クラスは、キャスト デバイスとのセッションを表します。このクラスには、デバイスの音量とミュート状態を制御するメソッドがあります。これは、これまで v2 で Cast.CastApi のメソッドを使用して行われていました。

v2 では、Cast.Listener コールバックが、音量、ミュート状態、スタンバイ ステータスなど、デバイスの状態の変更に関する通知を提供しました。

CAF では、音量/ミュート状態の変更通知は、引き続き Cast.Listener のコールバック メソッドを介して配信されます。これらのリスナーは CastSession に登録されます。残りのデバイスの状態の通知はすべて、CastStateListener コールバックを介して配信されます。これらのリスナーは CastSession に登録されます。関連付けられているフラグメント、アクティビティ、またはアプリがバックグラウンドに移行するときは、リスナーの登録を必ず解除してください。

再接続ロジック

v2 と同様に、CAF は一時的な Wi-Fi 信号の損失やその他のネットワーク エラーによって失われたネットワーク接続の再確立を試みます。これはセッション レベルで行われるようになりました。接続が失われた場合、セッションは「一時停止」状態になり、接続が回復すると「接続済み」状態に戻ります。フレームワークは、このプロセスの一環として、ウェブ レシーバー アプリへの再接続とキャスト チャンネルの再接続を処理します。

また、CAF では、デフォルトで有効になっている自動セッション再開も追加されます(CastOptions で無効にできます)。キャスト セッションの進行中にセンダーアプリがバックグラウンドに送信されるか、終了した場合(スワイプによるかクラッシュによる)、センダーアプリがフォアグラウンドに戻るか再起動されると、フレームワークはそのセッションを再開しようとします。これは、SessionManager によって自動的に処理され、登録済みの SessionManagerListener インスタンスで適切なコールバックを発行します。

カスタム チャンネル登録

v2 では、カスタム チャネル(Cast.MessageReceivedCallback を使用して実装)は Cast.CastApi に登録されます。CAF では、カスタム チャネルは代わりに CastSession インスタンスに登録されます。登録は、SessionManagerListener.onSessionStarted コールバック メソッドで行うことができます。メディアアプリでは、Cast.CastApi.setMessageReceivedCallbacks を介してメディア コントロール チャネルを明示的に登録する必要がなくなりました。詳細については、次のセクションをご覧ください。

メディア コントロール

v2 クラスの RemoteMediaPlayer は非推奨のため使用しないでください。CAF では、より便利な API で同等の機能を提供する新しい RemoteMediaClient クラスに置き換わります。このオブジェクトを明示的に初期化または登録する必要はありません。接続先のウェブ レシーバー アプリがメディア名前空間をサポートしている場合、フレームワークはセッションの開始時にオブジェクトを自動的にインスタンス化し、基盤となるメディア チャネルを登録します。

RemoteMediaClient には、CastSession オブジェクトの getRemoteMediaClient メソッドとしてアクセスできます。

v2 では、RemoteMediaPlayer で発行されるすべてのメディア リクエストは、PendingResult コールバックを介して RemoteMediaPlayer.MediaChannelResult を返します。

CAF では、RemoteMediaClient で発行されたすべてのメディア リクエストが PendingResult コールバックを介して RemoteMediaClient.MediaChannelResult を返します。このコールバックを使用して、リクエストの進行状況と最終的な結果を追跡できます。

v2 の RemoteMediaPlayer は、ウェブレシーバーのメディア プレーヤーの状態の変化に関する通知を RemoteMediaPlayer.OnStatusUpdatedListener を介して送信します。

CAF では、RemoteMediaClient がその RemoteMediaClient.Listener インターフェースを介して同等のコールバックを提供します。RemoteMediaClient には任意の数のリスナーを登録できます。これにより、複数の送信者コンポーネントが、セッションに関連付けられた RemoteMediaClient の単一インスタンスを共有できます。

v2 では、送信側アプリは、ユーザー インターフェースをウェブ レシーバーのメディア プレーヤー状態と同期させるという負担を負う必要がありました。

CAF では、UIMediaController クラスがこの役割のほとんどを担います。

案内用のオーバーレイ

V2 には、入門レベルのオーバーレイ UI は用意されていません。

CAF には、キャスト アイコンが最初にユーザーに表示されたときにキャスト アイコンをハイライト表示するカスタムビュー IntroductoryOverlay が用意されています。

ミニ コントローラ

v2 では、センダーアプリにミニ コントローラをゼロから実装する必要があります。

CAF では、SDK に用意されているカスタムビュー MiniControllerFragment を、ミニ コントローラを表示するアクティビティのアプリ レイアウト ファイルに追加できます。

通知とロック画面

v2 では、通知とロック画面用のコントローラは 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();
}

拡張コントローラ

v2 では、送信側アプリに拡張コントローラをゼロから実装する必要があります。

CAF の UIMediaController ヘルパークラスを使用すると、独自の拡張コントローラを簡単に作成できます。

CAF により、ビルド済みの拡張コントローラ ウィジェット ExpandedControllerActivity が追加されます。これは簡単にアプリに追加できます。UIMediaController を使用してカスタム拡張コントローラを実装する必要がなくなりました。

音声フォーカス

v2 では、MediaSessionCompat を使用して音声フォーカスを管理する必要があります。

CAF では、音声フォーカスは自動的に管理されます。

デバッグログ

CAF にはロギング オプションがありません。

サンプルアプリ

CAF を使用する Codelab チュートリアルサンプルアプリがあります。