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 su Google TV prima di Android 13. Il multitasking per la TV utilizza la modalità PIP per consentire la coesistenza di due app separate sullo schermo: una in esecuzione a schermo intero e l'altra in modalità PIP. Esistono requisiti diversi per le app eseguite in entrambe le modalità.

Per impostazione predefinita, l'app PIP sovrappone l'app a schermo intero. È equivalente al comportamento Picture in picture di Android standard.

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

Esegui 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 per corrispondere alle proporzioni del video in riproduzione.

Assicurati di aggiungere un titolo e un sottotitolo per fornire all'utente informazioni sulle finalità generalmente utilizzate di questo PIP.

Coesiste con le app in esecuzione in modalità PIP

Quando la tua app è in esecuzione come app a schermo intero, potrebbe dover adattarsi ad altre app in esecuzione in modalità PIP.

Mantieni la cancellazione delle API

In alcuni casi, l'app PIP può sovrapporre componenti importanti dell'interfaccia utente all'interno dell'app a schermo intero. Per ovviare a questo problema, esistono API di non divulgazione che le app possono utilizzare per identificare componenti critici dell'interfaccia utente che non devono essere sovrapposti. Il sistema cerca 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 farlo in modo programmatico 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);
}

In alcuni casi non è necessario tenere in chiaro un elemento View, ma solo una sua parte. L'elemento setPreferKeepClearRects() può essere utilizzato per specificare le regioni di View che non devono essere sovrapposte. Per le UI che non utilizzano View in modo nativo, come Flutter, Jetpack Compose e WebView, potrebbero essere presenti sottosezioni per cui è necessario mantenere chiare le regioni. In questi casi è possibile utilizzare l'API.

Tipi di utilizzo

La tua app deve dichiarare un attributo valore meta-data di com.google.android.tv.pip.category che corrisponda al tipo o ai tipi di utilizzo principale per la modalità Picture in picture. Qualsiasi elemento <activity> che è stato impostato android:supportsPictureInPicture="true" deve dichiarare questo attributo con un valore pertinente nella tabella seguente.

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.

Una barra verticale (|) separa più valori. Ad esempio:

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