Multitasking di TV

Android 14 (API level 34) memperkenalkan beberapa peningkatan pada API picture-in-picture (PiP) untuk memungkinkan multitasking. Meskipun dukungan PiP diperkenalkan di Android 8.0 (API level 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 berjalan bersama di layar: satu 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 menimpa aplikasi layar penuh. Ini sama dengan perilaku picture-in-picture Android standar.

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

Menjalankan aplikasi dalam mode PiP

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

Berikut adalah contoh cara menerapkan logika tombol untuk masuk ke mode PiP:

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

@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 dipicu, rasio aspek mode PiP ditetapkan agar sesuai dengan rasio aspek video yang sedang diputar.

Pastikan untuk menambahkan judul dan subjudul untuk memberikan informasi kepada pengguna tentang penggunaan PIP ini secara umum.

Berjalan bersama aplikasi yang berjalan dalam mode PiP

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

API keep-clear

Dalam beberapa kasus, aplikasi PiP dapat menimpa komponen UI penting dalam aplikasi layar penuh. Untuk mengatasinya, ada API keep-clear yang dapat digunakan aplikasi untuk mengidentifikasi komponen UI penting yang tidak boleh ditimpa. Sistem mencoba memenuhi permintaan untuk menghindari penutupan komponen ini dengan memposisikan ulang jendela PiP.

Untuk menentukan bahwa tampilan tidak boleh ditimpa, gunakan preferKeepClear dalam tata letak XML seperti dalam 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():

private lateinit var binding: MyLayoutBinding

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

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

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 seluruh View tetap jelas, tetapi hanya bagiannya saja. setPreferKeepClearRects() dapat digunakan untuk menentukan wilayah View yang tidak boleh ditimpa. UI yang tidak menggunakan View secara native, seperti Flutter, Jetpack Compose, dan WebView, mungkin memiliki sub-bagian yang memerlukan wilayah yang tetap jelas. API ini dapat digunakan untuk kasus tersebut.

Jenis penggunaan

Aplikasi Anda harus mendeklarasikan atribut nilai meta-data dari com.google.android.tv.pip.category yang sesuai dengan jenis penggunaan 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 salah satu kategori ini, khususnya pemutaran konten media apa pun, tidak diizinkan dalam mode picture-in-picture di TV.

Beberapa nilai dipisahkan dengan batang vertikal (|). Misalnya:

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