Multitasking di TV

Android 14 (level API 34) memperkenalkan beberapa peningkatan pada API Picture-in-picture (PiP) untuk memungkinkan multitasking. Meskipun dukungan PiP diperkenalkan di Android 8.0 (level API 26), dukungan ini tidak didukung secara luas di Android TV, dan tidak didukung sama sekali di Google TV sebelum Android 13. Multitasking untuk TV menggunakan mode PiP untuk memungkinkan dua aplikasi terpisah berdampingan di layar: satu aplikasi berjalan dalam layar penuh, dengan yang kedua berjalan dalam mode PiP. Ada persyaratan yang berbeda untuk aplikasi yang berjalan dalam salah satu mode ini.

Perilaku defaultnya adalah aplikasi PiP menempatkan aplikasi layar penuh. Ini sama dengan perilaku picture-in-picture Android standar.

Perhatikan bahwa saat mengintegrasikan multitasking, aplikasi Anda harus mendeklarasikan jenis penggunaannya sesuai sesuai dengan pedoman kualitas aplikasi TV.

Menjalankan aplikasi dalam mode PiP

Untuk perangkat TV yang menjalankan Android 14 (API level 34) atau yang lebih baru, jalankan aplikasi dalam mode PiP dengan memanggil enterPictureInPictureMode(). Perangkat TV yang menjalankan versi Android sebelumnya tidak mendukung mode PiP.

Catatan: Ada metode enterPictureInPictureMode() yang tidak digunakan lagi untuk level API 26 dan versi sebelumnya yang tidak menggunakan PictureInPictureParams.Builder. Hindari menggunakannya karena tidak didukung di perangkat TV.

Berikut adalah contoh cara menerapkan logika tombol untuk memasuki mode PiP:

Kotlin

override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
    super.onViewCreated(view, savedInstanceState)
    pictureInPictureButton.visibility =
        if (requireActivity().packageManager.hasSystemFeature(FEATURE_PICTURE_IN_PICTURE)) {
            pictureInPictureButton.setOnClickListener {
                val aspectRatio = Rational(view.width, view.height)
                val params = PictureInPictureParams.Builder()
                    .setAspectRatio(aspectRatio)
                    .build()
                val result = requireActivity().enterPictureInPictureMode(params)
            }
            View.VISIBLE
        } else {
            View.GONE
        }
}

Java

@Override
public void onViewCreated(@NonNull View view, @Nullable Bundle savedInstanceState) {
    super.onViewCreated(view, savedInstanceState);
    if (requireActivity().getPackageManager().hasSystemFeature(FEATURE_PICTURE_IN_PICTURE)) {
        pictureInPictureButton.setVisibility(View.VISIBLE);
        pictureInPictureButton.setOnClickListener(v -> {
            Rational aspectRatio = new Rational(view.getWidth(), view.getHeight());
            PictureInPictureParams params = new PictureInPictureParams.Builder()
                    .setAspectRatio(aspectRatio)
                    .setTitle("My Streaming App")
                    .setSubtitle("My On-Demand Content")
                    .build();
            Boolean result = requireActivity().enterPictureInPictureMode(params);
        });
    } else {
        pictureInPictureButton.setVisibility(View.GONE);
    }
}

Tindakan ini hanya ditambahkan jika perangkat memiliki fitur sistem FEATURE_PICTURE_IN_PICTURE. Selain itu, saat tindakan ini dipicu, rasio aspek mode PiP akan disetel agar sesuai dengan rasio aspek video yang sedang diputar.

Pastikan untuk menambahkan judul dan subtitel guna memberikan informasi kepada pengguna tentang kegunaan PIP ini.

Catatan: Memasuki mode picture-in picture memerlukan tindakan eksplisit dan disengaja oleh pengguna dalam aplikasi. Untuk mengetahui detailnya, lihat pedoman kualitas aplikasi TV.

Berdampingan dengan aplikasi yang berjalan dalam mode PiP

Saat berjalan sebagai aplikasi layar penuh, aplikasi mungkin perlu beradaptasi dengan aplikasi lain yang berjalan dalam mode PiP.

API yang tetap dihapus

Dalam beberapa kasus, aplikasi PiP dapat menempatkan komponen UI penting dalam aplikasi layar penuh. Untuk mengurangi hal ini, ada API yang tetap jelas yang dapat digunakan aplikasi untuk mengidentifikasi komponen UI penting yang tidak boleh di-overlay. Sistem mencoba memenuhi permintaan untuk menghindari mencakup komponen ini dengan mengubah posisi jendela PiP.

Catatan: Sistem mungkin tidak memenuhi permintaan ini jika terlalu banyak komponen UI yang ditandai sebagai tetap jelas, atau jika memenuhi sebagian besar layar. Harap perhatikan hal ini saat menggunakan API ini.

Untuk menentukan bahwa tampilan tidak boleh di-overlay, gunakan preferKeepClear dalam tata letak XML Anda seperti pada contoh berikut:

<TextView
    android:id="@+id/important_text"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:preferKeepClear="true"
    android:text="@string/app_name"/>

Anda juga dapat melakukannya secara terprogram menggunakan setPreferKeepClear():

Kotlin

private lateinit var binding: MyLayoutBinding

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    binding = MyLayoutBinding.inflate(layoutInflater)
    setContentView(binding.root)
    binding.importantText.isPreferKeepClear = true
}

Java

private MyLayoutBinding binding;

@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);

    binding = MyLayoutBinding.inflate(getLayoutInflater());
    setContentView(binding.getRoot());
    binding.importantText.setPreferKeepClear(true);
}

Mungkin ada saatnya Anda tidak perlu menjaga keseluruhan View tetap jelas, tetapi hanya sebagian. setPreferKeepClearRects() dapat digunakan untuk menentukan region View yang tidak boleh ditempatkan. UI yang tidak menggunakan View secara native, seperti Flutter, Jetpack Compose, dan WebView, mungkin memiliki subbagian yang memerlukan region yang tetap jelas. API ini dapat digunakan untuk kasus tersebut.

Catatan: Jika Anda menyetel setPreferKeepClear() ke true, seluruh View ditandai sebagai tetap jelas, dan setiap region yang ditentukan menggunakan setPreferKeepClearRects() akan diabaikan.

Jenis penggunaan

Aplikasi Anda harus mendeklarasikan atribut nilai meta-data com.google.android.tv.pip.category yang sesuai dengan jenis utama atau jenis penggunaan untuk mode picture-in-picture. Setiap <activity> yang telah menetapkan android:supportsPictureInPicture="true" harus mendeklarasikan atribut ini dengan nilai yang relevan dari tabel di bawah.

Jenis penggunaan yang tidak termasuk dalam kategori tersebut, khususnya pemutaran konten media, tidak diizinkan dalam mode picture-in-picture di TV.

Nilai	Deskripsi
"communication"	Kasus penggunaan komunikasi, seperti panggilan video atau suara.
"smartHome"	Integrasi smart home, seperti bel pintu yang terhubung atau alat pemantau bayi.
"health"	Kasus penggunaan kesehatan, seperti pelacakan kebugaran atau pemantauan kesehatan.
"ticker"	Kasus penggunaan ticker, seperti skor olahraga live atau berita dan ticker saham.

Beberapa nilai dipisahkan oleh garis vertikal (|). Misalnya:

<meta-data android:name="com.google.android.tv.pip.category" android:value="smartHome|health" />