Google berkomitmen untuk mendorong terwujudnya keadilan rasial bagi komunitas Kulit Hitam. Lihat caranya.

Dukungan Picture-in-picture

Android 8.0 (API level 26) memungkinkan peluncuran aktivitas dalam mode picture-in-picture (PIP). PIP adalah jenis khusus dari mode multi-aplikasi yang sebagian besar digunakan untuk pemutaran video. Dengan fitur ini, pengguna dapat menonton video di jendela kecil yang di-pin ke sudut layar sambil berpindah-pindah aplikasi atau menjelajahi konten di layar utama.

PIP memanfaatkan API multi-aplikasi yang tersedia di Android 7.0 untuk menyediakan jendela overlay video yang di-pin. Untuk menambahkan PIP ke aplikasi, Anda harus mendaftarkan aktivitas yang mendukung PIP, mengalihkan aktivitas ke mode PIP jika diperlukan, dan memastikan elemen UI disembunyikan dan pemutaran video berlanjut saat aktivitas berada dalam mode PIP.

Jendela PIP muncul di lapisan paling atas pada layar, di sudut yang dipilih oleh sistem. Anda dapat menarik jendela PIP ini ke lokasi lain. Saat jendela ini diketuk, dua kontrol khusus akan muncul: tombol layar penuh (di tengah jendela) dan tombol tutup (tanda "X" di sudut kanan atas).

Aplikasi Anda mengontrol kapan aktivitas yang sedang aktif akan memasuki mode PIP. Berikut beberapa contohnya:

  • Sebuah aktivitas dapat memasuki mode PIP jika pengguna mengetuk tombol layar utama atau terkini untuk memilih aplikasi lain. (Beginilah cara Google Maps terus menampilkan petunjuk arah sementara pengguna menjalankan aktivitas lain secara bersamaan.)
  • Aplikasi Anda dapat memindahkan video ke dalam mode PIP saat pengguna kembali dari video untuk menjelajahi konten lain.
  • Aplikasi Anda dapat mengalihkan video ke dalam mode PIP selagi pengguna menonton akhir dari sebuah episode konten. Layar utama menampilkan informasi promosi atau ringkasan tentang episode berikutnya dalam serial.
  • Aplikasi Anda dapat memberi pengguna cara mengantrekan konten tambahan selagi mereka menonton video. Video terus diputar dalam mode PIP sementara layar utama menampilkan aktivitas pemilihan konten.

Mendeklarasikan dukungan picture-in-picture

Secara default, sistem tidak otomatis mendukung PIP untuk aplikasi. Jika menginginkan dukungan PIP di aplikasi Anda, daftarkan aktivitas video Anda di manifes dengan menetapkan android:supportsPictureInPicture dan android:resizeableActivity ke true. Selain itu, tentukan bahwa aktivitas Anda menangani perubahan konfigurasi tata letak, sehingga aktivitas Anda tidak diluncurkan kembali saat perubahan tata letak terjadi selama transisi mode PIP.

    <activity android:name="VideoActivity"
        android:resizeableActivity="true"
        android:supportsPictureInPicture="true"
        android:configChanges=
            "screenSize|smallestScreenSize|screenLayout|orientation"
        ...
    

Mengalihkan aktivitas ke mode picture-in-picture

Untuk masuk ke mode picture-in-picture, aktivitas harus memanggil enterPictureInPictureMode(). Misalnya, kode berikut mengalihkan aktivitas ke mode PIP saat pengguna mengklik tombol khusus di UI aplikasi:

Kotlin

    override fun onActionClicked(action: Action) {
        if (action.id.toInt() == R.id.lb_control_picture_in_picture) {
            activity?.enterPictureInPictureMode()
            return
        }
    }
    

Java

    @Override
    public void onActionClicked(Action action) {
        if (action.getId() == R.id.lb_control_picture_in_picture) {
            getActivity().enterPictureInPictureMode();
            return;
        }
        ...
    }
    

Anda mungkin ingin menyertakan logika yang mengalihkan aktivitas ke mode PIP, bukan ke latar belakang. Misalnya, Google Maps beralih ke mode PIP jika pengguna menekan tombol layar utama atau terkini selagi aplikasi dibuka. Anda dapat merekam kasus ini dengan mengganti onUserLeaveHint():

Kotlin

    override fun onUserLeaveHint() {
        if (iWantToBeInPipModeNow()) {
            enterPictureInPictureMode()
        }
    }
    

Java

    @Override
    public void onUserLeaveHint () {
        if (iWantToBeInPipModeNow()) {
            enterPictureInPictureMode();
        }
    }
    

Menangani UI selama mode picture-in-picture

Saat aktivitas memasuki atau keluar dari mode picture-in-picture, sistem akan memanggil Activity.onPictureInPictureModeChanged() atau Fragment.onPictureInPictureModeChanged().

Anda harus mengganti callback ini untuk menggambar ulang elemen UI aktivitas. Perlu diingat bahwa dalam mode PIP, aktivitas Anda ditampilkan di jendela kecil. Pengguna tidak dapat berinteraksi dengan elemen UI saat berada dalam mode PIP, dan detail elemen UI kecil mungkin sulit dilihat. Aktivitas pemutaran video dengan UI yang minimal akan memberikan pengalaman pengguna terbaik. Sebaiknya aktivitas hanya menampilkan kontrol pemutaran video. Hapus elemen UI lainnya sebelum aktivitas memasuki PIP dan pulihkan saat aktivitas Anda kembali menjadi layar penuh:

Kotlin

    override fun onPictureInPictureModeChanged(isInPictureInPictureMode: Boolean,
                                               newConfig: Configuration) {
        if (isInPictureInPictureMode) {
            // Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
        } else {
            // Restore the full-screen UI.
        }
    }
    

Java

    @Override
    public void onPictureInPictureModeChanged (boolean isInPictureInPictureMode, Configuration newConfig) {
        if (isInPictureInPictureMode) {
            // Hide the full-screen UI (controls, etc.) while in picture-in-picture mode.
        } else {
            // Restore the full-screen UI.
            ...
        }
    }
    

Menambahkan kontrol

Jendela PIP dapat menampilkan kontrol saat pengguna membuka menu jendela tersebut (dengan mengetuk jendela di perangkat seluler, atau memilih menu dari remote TV.)

Jika aplikasi memiliki sesi media aktif, kontrol putar, jeda, berikutnya, dan sebelumnya akan muncul.

Anda juga dapat menentukan tindakan kustom secara eksplisit dengan membuat PictureInPictureParams dengan PictureInPictureParams.Builder.setActions() sebelum memasuki mode PIP, lalu meneruskan parameter saat memasuki mode PIP menggunakan enterPictureInPictureMode(android.app.PictureInPictureParams) atau setPictureInPictureParams(android.app.PictureInPictureParams). Harap berhati-hati. Jika mencoba menambahkan selain getMaxNumPictureInPictureActions(), Anda hanya akan mendapatkan angka maksimumnya.

Melanjutkan pemutaran video selagi dalam picture-in-picture

Saat aktivitas Anda beralih ke PIP, sistem akan menempatkan aktivitas itu dalam keadaan dijeda dan memanggil metode onPause() aktivitas. Pemutaran video tidak dijeda dan akan terus diputar jika aktivitas tersebut dijeda selagi dalam mode PIP.

Di Android 7.0 dan yang lebih baru, Anda harus menjeda dan melanjutkan pemutaran video saat sistem memanggil onStop() dan onStart() di aktivitas Anda. Dengan begitu, Anda tidak perlu memeriksa apakah aplikasi berada dalam mode PIP di onPause() dan melanjutkan pemutaran secara eksplisit.

Jika Anda harus menjeda pemutaran dalam implementasi onPause(), periksa status mode PIP dengan memanggil isInPictureInPictureMode() dan menangani pemutaran dengan semestinya, misalnya:

Kotlin

    override fun onPause() {
        super.onPause()
        // If called while in PIP mode, do not pause playback
        if (isInPictureInPictureMode) {
            // Continue playback
        } else {
            // Use existing playback logic for paused Activity behavior.
        }
    }
    

Java

    @Override
    public void onPause() {
        // If called while in PIP mode, do not pause playback
        if (isInPictureInPictureMode()) {
            // Continue playback
            ...
        } else {
            // Use existing playback logic for paused Activity behavior.
            ...
        }
    }
    

Saat aktivitas Anda keluar dari mode PIP dan kembali ke mode layar penuh, sistem akan melanjutkan aktivitas dan memanggil metode onResume().

Menggunakan aktivitas pemutaran tunggal untuk picture-in-picture

Di aplikasi Anda, pengguna dapat memilih video baru saat mencari konten di layar utama, selagi aktivitas pemutaran video berlangsung dalam mode PIP. Putar video baru dalam aktivitas pemutaran yang ada dalam mode layar penuh, bukan meluncurkan aktivitas baru yang dapat membingungkan pengguna.

Untuk memastikan bahwa aktivitas tunggal digunakan untuk permintaan pemutaran video dan dialihkan ke dalam atau ke luar mode PIP sesuai keperluan, tetapkan android:launchMode aktivitas ke singleTask dalam manifes Anda:

    <activity android:name="VideoActivity"
        ...
        android:supportsPictureInPicture="true"
        android:launchMode="singleTask"
        ...
    

Dalam aktivitas Anda, ganti onNewIntent() dan tangani video baru, sehingga pemutaran video yang ada akan dihentikan, jika diperlukan.

Praktik terbaik

PIP mungkin dinonaktifkan pada perangkat yang memiliki RAM rendah. Sebelum aplikasi Anda menggunakan PIP, pastikan ketersediaannya dengan memanggil hasSystemFeature(PackageManager.FEATURE_PICTURE_IN_PICTURE).

PIP ditujukan untuk aktivitas yang memutar video dalam mode layar penuh. Saat mengalihkan aktivitas Anda ke mode PIP, hindari menampilkan apa pun kecuali konten video. Pantau kapan aktivitas Anda memasuki mode PIP, dan sembunyikan elemen UI seperti yang dijelaskan dalam Menangani UI selama mode picture-in-picture.

Karena jendela PIP ditampilkan sebagai jendela mengambang di sudut layar, sebaiknya hindari menampilkan informasi penting di layar utama di area mana pun yang dapat tertutup oleh jendela PIP.

Secara default, aktivitas tidak mendapatkan fokus input saat berada dalam mode PIP. Untuk menerima peristiwa input selagi berada dalam mode PIP, gunakan MediaSession.setCallback(). Untuk informasi selengkapnya tentang penggunaan setCallback(), lihat Menampilkan Kartu Now Playing.

Saat aplikasi Anda berada dalam mode PIP, pemutaran video di jendela PIP dapat menyebabkan gangguan audio pada aplikasi lain, seperti aplikasi pemutar musik atau aplikasi penelusuran suara. Untuk menghindari hal ini, mintalah fokus audio saat Anda mulai memutar video, dan tangani notifikasi perubahan fokus audio, seperti yang dijelaskan dalam Mengelola Fokus Audio. Jika Anda menerima notifikasi kehilangan fokus audio saat dalam mode PIP, jeda atau hentikan pemutaran video.

Kode contoh tambahan

Untuk mendownload contoh aplikasi yang ditulis di Android, lihat Contoh Picture-in-Picture. Untuk mendownload contoh aplikasi yang ditulis di Kotlin, lihat Contoh PictureInPicture Android (Kotlin).