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 singleton CastContext.

Peringatan: Jika Anda mem-build aplikasi pengirim CAF atau bermigrasi ke CAF, Anda harus menggunakan CastContext, bukan GoogleAPIClient untuk mengakses Cast API. Sebaiknya gunakan GoogleAPIClient untuk mengakses API layanan Google Play lainnya.

Cast CAF Sender SDK 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
• Paket baru telah ditambahkan yang bertanggung jawab untuk mematuhi checklist Desain Google Cast (com.google.android.gms.cast.framework.*)
• CAF Sender menyediakan widget yang mematuhi persyaratan UX Cast; v2 tidak menyediakan komponen UI apa pun dan mengharuskan Anda mengimplementasikan widget ini.
• Penggunaan GoogleApiClient tidak lagi diperlukan untuk menggunakan Cast API.
• Pemberian teks tertutup di Pengirim CAF mirip dengan v2.

Dependensi

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

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

Inisialisasi

Di CAF, langkah inisialisasi eksplisit diperlukan untuk framework Cast. Hal ini melibatkan inisialisasi singleton CastContext, menggunakan OptionsProvider yang sesuai 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 tag "application" pada file AndroidManifest.xml aplikasi:

<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 lambat CastContext dalam metode onCreate setiap 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

Di CAF, proses penemuan dimulai dan dihentikan secara otomatis oleh framework saat aplikasi beralih ke latar depan dan latar belakang, masing-masing. MediaRouteSelector dan MediaRouter.Callback tidak boleh digunakan.

Tombol Cast dan dialog Cast

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

Tombol Transmisi masih diimplementasikan 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() dari setiap Aktivitas 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;
}

Saat seseorang mengetuk tombol, dialog Transmisi akan otomatis ditampilkan.

Kontrol perangkat

Di CAF, kontrol perangkat sebagian besar ditangani oleh framework. Aplikasi pengirim tidak perlu menangani (dan tidak boleh mencoba menangani) koneksi ke perangkat dan meluncurkan aplikasi Penerima Web menggunakan GoogleApiClient. Interaksi antara pengirim dan Penerima Web kini direpresentasikan sebagai "sesi". Class SessionManager menangani siklus proses sesi serta otomatis memulai dan menghentikan sesi sebagai respons terhadap gestur pengguna: sesi dimulai saat pengguna memilih perangkat Cast dalam dialog Cast dan diakhiri saat pengguna mengetuk tombol "Hentikan Transmisi" dalam dialog Cast atau saat aplikasi pengirim itu sendiri berhenti. Aplikasi pengirim dapat diberi tahu tentang peristiwa siklus proses sesi dengan mendaftarkan SessionManagerListener dengan SessionManager. Callback SessionManagerListener menentukan metode callback untuk semua peristiwa siklus proses sesi.

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

Di v2, callback Cast.Listener memberikan notifikasi perubahan pada status perangkat, termasuk volume, status bisu, status standby, dan sebagainya.

Di CAF, notifikasi perubahan status volume/bisukan masih dikirim melalui metode callback di Cast.Listener; pemroses ini didaftarkan dengan CastSession. Semua notifikasi status perangkat yang tersisa dikirim melalui callback CastStateListener; pemroses ini didaftarkan dengan CastSession. Pastikan Anda tetap membatalkan pendaftaran pemroses saat fragmen, aktivitas, atau aplikasi terkait beralih ke latar belakang.

Logika koneksi ulang

Seperti halnya v2, CAF mencoba membangun kembali koneksi jaringan yang terputus karena hilangnya sinyal Wi-Fi sementara atau error jaringan lainnya. Hal ini sekarang dilakukan di tingkat sesi; sesi dapat memasuki status "ditangguhkan" saat koneksi terputus, dan akan beralih kembali ke status "terhubung" saat konektivitas dipulihkan. Framework akan menangani penyambungan ulang ke aplikasi Penerima Web dan menyambungkan ulang saluran Cast apa pun sebagai bagian dari proses ini.

Selain itu, CAF juga menambahkan pelanjutan sesi otomatis yang diaktifkan secara default (dan dapat dinonaktifkan melalui CastOptions. Jika aplikasi pengirim dikirim ke latar belakang atau dihentikan (dengan menggeser atau karena error) saat sesi Cast sedang berlangsung, framework akan mencoba melanjutkan sesi tersebut saat aplikasi pengirim kembali ke latar depan atau diluncurkan kembali; hal ini ditangani secara otomatis oleh SessionManager, yang akan mengeluarkan callback yang sesuai pada instance SessionManagerListener yang terdaftar.

Pendaftaran saluran kustom

Di v2, saluran kustom (yang diimplementasikan menggunakan Cast.MessageReceivedCallback) didaftarkan dengan Cast.CastApi. Di CAF, saluran kustom didaftarkan dengan instance CastSession. Pendaftaran dapat dilakukan dalam metode callback SessionManagerListener.onSessionStarted. Untuk aplikasi media, Anda tidak perlu lagi mendaftarkan saluran kontrol media secara eksplisit melalui Cast.CastApi.setMessageReceivedCallbacks; lihat bagian berikut untuk mengetahui detail selengkapnya.

Kontrol media

Class v2 RemoteMediaPlayer tidak digunakan lagi dan tidak boleh digunakan. Di CAF, class ini digantikan oleh class RemoteMediaClient baru, yang menyediakan fungsi yang setara dalam API yang lebih praktis. Anda tidak perlu melakukan inisialisasi atau mendaftarkan objek ini secara eksplisit; framework akan otomatis membuat instance objek dan mendaftarkan saluran media yang mendasarinya pada waktu mulai sesi jika aplikasi Penerima Web yang terhubung mendukung namespace media.

RemoteMediaClient dapat diakses sebagai metode getRemoteMediaClient dari objek CastSession.

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

Di CAF, semua permintaan media yang dikeluarkan di RemoteMediaClient menampilkan RemoteMediaClient.MediaChannelResult melalui callback PendingResult yang dapat digunakan untuk melacak progres dan hasil akhir permintaan.

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

Di CAF, RemoteMediaClient menyediakan callback yang setara melalui antarmuka RemoteMediaClient.Listener. Berapa pun jumlah pemroses dapat didaftarkan dengan RemoteMediaClient, yang memungkinkan beberapa komponen pengirim berbagi satu instance RemoteMediaClient yang terkait dengan sesi.

Di v2, aplikasi pengirim harus menanggung beban untuk menjaga antarmuka pengguna tetap sinkron dengan status pemutar media di Penerima Web.

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

Overlay perkenalan

V2 tidak menyediakan UI overlay pengantar.

CAF menyediakan tampilan kustom IntroductoryOverlay untuk memperjelas tombol Transmisi saat pertama kali ditampilkan kepada pengguna.

Pengontrol mini

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

Di CAF, SDK menyediakan tampilan kustom, MiniControllerFragment, yang dapat Anda tambahkan ke file tata letak aplikasi dari aktivitas tempat 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 mem-build fitur ini ke dalam aplikasi pengirim menggunakan Android framework API.

Di CAF, SDK menyediakan NotificationsOptions.Builder untuk membantu Anda membuat kontrol media untuk notifikasi dan layar kunci ke dalam 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 harus menerapkan pengontrol yang diperluas dari awal di aplikasi pengirim.

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

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

Fokus audio

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

Di CAF, fokus audio dikelola secara otomatis.

Logging debug

Di CAF, tidak ada opsi logging.

Aplikasi contoh

Kami memiliki tutorial codelab dan aplikasi contoh yang menggunakan CAF.

Peringatan: Jika Anda telah memigrasikan aplikasi ke CAF dan aplikasi tersebut masih menggunakan GoogleAPIClient untuk mengakses Cast API, Anda harus menghapus GoogleAPIClient dan mengikuti prosedur Inisialisasi untuk menggunakan CastContext.