Multitasking sulla TV

Android 14 (livello API 34) introduce alcuni miglioramenti alle API picture-in-picture (PiP) per consentire il multitasking. Sebbene il supporto PiP sia stato introdotto in Android 8.0 (livello API 26), non era ampiamente supportato su Android TV e non era supportato affatto su Google TV prima di Android 13. Il multitasking per la TV utilizza la modalità PiP per consentire la coesistenza sullo schermo di due app distinte: una in esecuzione a schermo intero e una in modalità PiP. Esistono requisiti diversi per le app in esecuzione in una di queste modalità.

Il comportamento predefinito è che l'app PiP sovrapponga l'app a schermo intero. È molto simile al comportamento standard della modalità Picture in picture di Android.

Tieni presente che, quando integri il multitasking, la tua applicazione deve dichiarare i suoi tipi di utilizzo in conformità con le norme sulla qualità delle app TV.

Eseguire l'app in modalità PiP

Per i dispositivi TV con Android 14 (livello API 34) o versioni successive, esegui l'app in modalità PiP chiamando enterPictureInPictureMode(). I dispositivi TV con versioni precedenti di Android non supportano la modalità PiP.

Ecco un esempio di come implementare la logica di un pulsante per attivare la modalità 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);
    }
}

L'azione viene aggiunta solo se il dispositivo dispone della funzionalità di sistema FEATURE_PICTURE_IN_PICTURE. Inoltre, quando l'azione viene attivata, le proporzioni della modalità PiP vengono impostate in modo da corrispondere a quelle del video in riproduzione.

Assicurati di aggiungere un titolo e un sottotitolo per fornire all'utente informazioni su come viene generalmente utilizzato questo PIP.

Coesistere con le app in esecuzione in modalità PiP

Quando la tua app viene eseguita a schermo intero, potrebbe dover essere adattata ad altre app in esecuzione in modalità PiP.

API Keep-clear

In alcuni casi, l'app PiP potrebbe sovrapporre componenti importanti dell'interfaccia utente all'interno dell'app in modalità a schermo intero. Per ridurre il problema, esistono API keep-clear che le app possono utilizzare per identificare i componenti critici dell'interfaccia utente che non devono essere sovrapposti. Il sistema tenta di soddisfare le richieste per evitare di coprire questi componenti riposizionando la finestra PiP.

Per specificare che una visualizzazione non deve essere sovrapposta, utilizza preferKeepClear nel layout XML come nell'esempio seguente:

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

Puoi anche eseguire questa operazione tramite programmazione utilizzando 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);
}

A volte potrebbe non essere necessario mantenere vuoto un intero View, ma solo una sezione. setPreferKeepClearRects() può essere utilizzato per specificare le regioni del View che non devono essere sovrapposte. Le UI che non utilizzano View in modo nativo, come Flutter, Jetpack Compose e WebView, possono avere sottosezioni che richiedono regioni non occupate. Questa API può essere utilizzata per questi casi.

Tipi di utilizzo

L'app deve dichiarare un attributo del valore dei metadati di com.google.android.tv.pip.category che corrisponda al tipo o ai tipi di utilizzo principali per la modalità PiP. Qualsiasi <activity> che ha impostato android:supportsPictureInPicture="true" deve dichiarare questo attributo con un valore pertinente riportato nella tabella di seguito.

I tipi di utilizzo che non rientrano in nessuna di queste categorie, in particolare la riproduzione di contenuti multimediali, non sono consentiti in modalità Picture in Picture sulla TV.

Più valori sono separati da una barra verticale (|). Ad esempio:

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