Memigrasikan Aplikasi Pengirim Android dari Cast SDK v2 ke Cast Application Framework (CAF)

Prosedur berikut memungkinkan Anda mengonversi aplikasi pengirim Android dari Cast SDK v2 ke Pengirim CAF, yang didasarkan pada CastContext singleton.

Peringatan: Jika Anda membangun aplikasi pengirim CAF atau bermigrasi ke CAF, Anda harus menggunakan CastContext dan bukan GoogleAPIClient untuk mengakses Cast API. adalah layak untuk digunakan GoogleAPIClient untuk mengakses API layanan Google Play lainnya.

SDK Pengirim CAF Cast menggunakan CastContext untuk mengelola GoogleAPIClient atas nama Anda. CastContext mengelola siklus proses, error, dan callback untuk Anda, yang sangat menyederhanakan pengembangan aplikasi Cast.

Pengantar

• Pengirim CAF masih didistribusikan sebagai bagian dari layanan Google Play menggunakan Android SDK Manager
• Telah ditambahkan paket baru yang bertanggung jawab untuk mematuhi checklist Desain Google Cast (com.google.android.gms.cast.framework.*)
• Pengirim CAF menyediakan widget yang sesuai dengan persyaratan UX Cast; v2 tidak menyediakan komponen UI apa pun dan mengharuskan Anda untuk menerapkan widget.
• Penggunaan GoogleApiClient tidak lagi diperlukan untuk menggunakan Cast API.
• Pemberian teks tertutup dalam Pengirim CAF serupa dengan v2.

Dependensi

V2 dan CAF memiliki dependensi yang sama pada support library dan Google Play (9.2.0 atau yang lebih baru) seperti yang dijelaskan dalam Fitur Library Dukungan Panduan

Versi Android SDK minimum yang didukung CAF adalah 9 (Gingerbread).

Inisialisasi

Dalam CAF, langkah inisialisasi eksplisit diperlukan untuk framework Cast. Ini melibatkan inisialisasi CastContext singleton, menggunakan model OptionsProvider untuk menentukan ID aplikasi Penerima Web dan opsi global lainnya.

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;
    }
}

Deklarasikan OptionsProvider dalam "aplikasi" tag aplikasi File AndroidManifest.xml:

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

Lakukan inisialisasi CastContext dengan lambat di setiap metode onCreate Aktivitas:

private CastContext mCastContext;

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

    mCastContext = CastContext.getSharedInstance(this);
}

Langkah-langkah ini tidak diperlukan di v2.

Penemuan perangkat

Dalam CAF, proses penemuan dimulai dan dihentikan secara otomatis oleh saat aplikasi berada di latar depan dan berpindah ke latar belakang, secara berurutan. MediaRouteSelector dan MediaRouter.Callback tidak boleh data

Tombol Cast dan dialog Cast

Seperti di v2, komponen ini disediakan oleh dukungan MediaRouter library.

Tombol Cast masih diterapkan oleh MediaRouteButton dan dapat ditambahkan ke aktivitas Anda (menggunakan ActionBar atau Toolbar), sebagai item menu di menu Anda.

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

Ganti metode onCreateOptionMenu() setiap Aktivitas dengan menggunakan CastButtonFactory untuk menghubungkan MediaRouteButton ke framework Cast:

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;
}

Ketika seseorang mengetuk tombol, dialog Transmisi akan otomatis ditampilkan.

Kontrol perangkat

Dalam CAF, kontrol perangkat sebagian besar ditangani oleh framework. Pengirim aplikasi tidak perlu menangani (dan tidak boleh mencoba menangani) koneksi ke perangkat dan meluncurkan aplikasi {i>Web Receiver <i}menggunakan GoogleApiClient. Interaksi antara pengirim dan Penerima Web kini ditampilkan sebagai "sesi". Tujuan SessionManager menangani siklus proses sesi dan secara otomatis memulai dan menghentikan sesi untuk merespons gestur pengguna: sesi dimulai saat pengguna memilih Transmisi perangkat dalam dialog Cast dan berakhir saat pengguna mengetuk "Hentikan Transmisi" di dialog Cast atau saat aplikasi pengirim dihentikan. Pengirim aplikasi dapat diberi tahu tentang peristiwa siklus proses sesi dengan mendaftarkan SessionManagerListener dengan SessionManager. Callback SessionManagerListener menentukan untuk semua peristiwa siklus proses sesi.

Tujuan CastSession mewakili sesi dengan perangkat Cast. Class ini memiliki metode untuk mengontrol volume perangkat dan status bisukan, yang sebelumnya dilakukan di v2 menggunakan metode di Cast.CastApi.

Pada v2, atribut Cast.Listener callback memberikan notifikasi tentang perubahan status perangkat, termasuk volume, status bisukan, status standby, dan sebagainya.

Dalam CAF, notifikasi perubahan status volume/bisukan tetap dikirimkan melalui callback metode di Cast.Listener; pemroses ini terdaftar dengan CastSession. Semua notifikasi status perangkat lainnya dikirimkan melalui CastStateListener callback; pemroses ini terdaftar di CastSession. Pastikan Anda tetap membatalkan pendaftaran pemroses saat fragmen, aktivitas, atau aplikasi terkait ke latar belakang.

Logika menghubungkan kembali

Seperti halnya v2, CAF mencoba menghubungkan kembali koneksi jaringan yang hilang karena kehilangan sinyal WiFi sementara atau kesalahan jaringan lainnya. Hal ini sekarang dilakukan di tingkat sesi; sesi dapat masuk ke status "suspended" menyatakan kapan koneksi terputus, dan akan beralih kembali ke "terhubung" menyatakan kapan konektivitas pulih. Kerangka kerja ini akan membantu menghubungkan kembali ke Aplikasi Penerima Web dan menghubungkan kembali saluran Cast sebagai bagian dari proses ini.

Selain itu, CAF juga menambahkan melanjutkan sesi otomatis yang diaktifkan oleh default (dan dapat dinonaktifkan melalui CastOptions Jika aplikasi pengirim dikirim ke latar belakang atau dihentikan (oleh meninggalkan layar atau karena terjadi tabrakan) saat sesi Transmisi berlangsung, akan mencoba melanjutkan sesi itu ketika aplikasi pengirim kembali ke latar depan atau diluncurkan kembali; ini ditangani secara otomatis oleh SessionManager, yang akan mengeluarkan callback yang sesuai di setiap SessionManagerListener instance.

Pendaftaran saluran khusus

Di v2, saluran khusus (diimplementasikan menggunakan Cast.MessageReceivedCallback) terdaftar dengan Cast.CastApi. Di CAF, saluran khusus didaftarkan dengan Instance CastSession. Pendaftaran dapat dilakukan di SessionManagerListener.onSessionStarted . Untuk aplikasi media, tidak perlu lagi mendaftarkan saluran kontrol media melalui Cast.CastApi.setMessageReceivedCallbacks; lihat bagian berikut untuk detail selengkapnya.

Kontrol media

Class v2 RemoteMediaPlayer tidak digunakan lagi dan tidak boleh digunakan. Dalam CAF, model ini digantikan oleh RemoteMediaClient , yang menyediakan fungsi setara dalam API yang lebih praktis. Penting tidak perlu menginisialisasi atau mendaftarkan objek ini secara eksplisit; kerangka kerja akan otomatis membuat instance objek dan mendaftarkan media yang mendasarinya saluran pada waktu mulai sesi jika aplikasi Penerima Web tersambung ke mendukung namespace media.

RemoteMediaClient dapat diakses sebagai Metode getRemoteMediaClient dari objek CastSession.

Di v2, semua permintaan media yang dikeluarkan pada RemoteMediaPlayer akan menampilkan RemoteMediaPlayer.MediaChannelResult melalui callback PendingResult.

Di CAF, semua permintaan media yang dikeluarkan pada RemoteMediaClient akan menampilkan RemoteMediaClient.MediaChannelResult melalui PendingResult yang dapat digunakan untuk melacak kemajuan dan hasil akhir dari permintaan.

RemoteMediaPlayer v2 akan mengirimkan notifikasi tentang perubahan di media status pemutar di Penerima Web melalui RemoteMediaPlayer.OnStatusUpdatedListener.

Dalam CAF, RemoteMediaClient memberikan callback yang setara melalui RemoteMediaClient.Listener dalam antarmuka berbasis web yang sederhana. Sejumlah pemroses bisa didaftarkan dengan RemoteMediaClient, yang memungkinkan beberapa komponen pengirim berbagi satu instance RemoteMediaClient yang terkait dengan sesi.

Pada v2, aplikasi pengirim harus memikul beban menjaga pengguna sinkron dengan status pemutar media pada Web Receiver.

Di CAF, class UIMediaController mengambil sebagian besar tanggung jawab ini.

Overlay perkenalan

V2 tidak menyediakan UI overlay pengantar.

CAF memberikan tampilan kustom IntroductoryOverlay untuk menyoroti tombol Cast saat pertama kali ditampilkan kepada pengguna.

Pengontrol mini

Di v2, Anda perlu mengimplementasikan pengontrol mini dari awal di aplikasi pengirim.

Pada CAF, SDK menyediakan tampilan kustom, MiniControllerFragment, yang dapat Anda tambahkan ke file tata letak aplikasi dari aktivitas di mana Anda ingin menampilkan pengontrol mini.

Notifikasi dan layar kunci

Di v2, pengontrol untuk notifikasi dan layar kunci tidak disediakan oleh SDK. Untuk SDK tersebut, Anda perlu membangun fitur ini ke dalam aplikasi pengirim menggunakan API framework Android.

Dalam CAF, SDK menyediakan NotificationsOptions.Builder untuk membantu Anda membuat kontrol media untuk notifikasi dan layar kunci ke aplikasi pengirim. Kontrol notifikasi dan layar kunci dapat diaktifkan dengan CastOptions saat melakukan inisialisasi CastContext.

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

Pengontrol yang diperluas

Di v2, Anda perlu mengimplementasikan pengontrol yang diperluas dari awal di aplikasi pengirim.

CAF menyediakan UIMediaController helper yang memudahkan Anda membuat build sendiri yang diperluas pengontrol.

CAF menambahkan widget pengontrol bawaan yang diperluas ExpandedControllerActivity yang bisa Anda tambahkan ke aplikasi. Anda tidak perlu lagi mengimplementasikan pengontrol kustom yang diperluas menggunakan UIMediaController.

Fokus audio

Di v2, Anda perlu menggunakan MediaSessionCompat untuk mengelola fokus audio.

Dalam CAF, fokus audio dikelola secara otomatis.

Logging debug

Dalam CAF, tidak ada opsi logging.

Aplikasi contoh

Kita memiliki tutorial codelab dan aplikasi contoh yang menggunakan CAF.

Peringatan: Jika Anda telah memigrasikan aplikasi ke CAF dan aplikasi masih digunakan GoogleAPIClient untuk mengakses Cast API, Anda perlu menghapus GoogleAPIClient dan ikuti kursus Inisialisasi prosedur untuk menggunakan CastContext.