Realiza varias tareas a la vez en la TV

Android 14 (nivel de API 34) introduce algunas mejoras en las APIs de pantalla en pantalla (PiP) para permitir la realización de varias tareas a la vez. Mientras que PIP compatibilidad se introdujo en Android 8.0 (nivel de API 26), no fue ampliamente es compatible con Android TV y no es compatible en absoluto con Google TV antes de Android. La función de tareas múltiples para TV usa el modo de PIP para permitir dos que diferentes apps coexistan en la pantalla: una que se ejecuta en su totalidad pantalla, con un segundo ejecutándose en modo de PIP. Existen requisitos diferentes para las apps que se ejecutan en cualquiera de estos modos.

El comportamiento predeterminado es que la app de PIP se superpone a la app de pantalla completa. Esto es similar al comportamiento estándar del modo pantalla en pantalla de Android.

Ten en cuenta que, cuando integras la multitarea, tu aplicación debe declarar sus tipos de uso de acuerdo con los lineamientos de calidad de apps para TV.

Cómo ejecutar tu app en modo de PIP

En el caso de los dispositivos de TV que ejecutan Android 14 (nivel de API 34) o versiones posteriores, llama a enterPictureInPictureMode() para ejecutar tu app en el modo PiP. Dispositivos de TV que funcionan antes de Android no son compatibles con el modo de PIP.

Nota: Hay un método enterPictureInPictureMode() obsoleto para el nivel de API. 26 y versiones anteriores que no usa PictureInPictureParams.Builder. Evita el uso porque no es compatible con dispositivos de TV.

Este es un ejemplo de cómo implementar la lógica de un botón para ingresar al modo 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);
    }
}

La acción solo se agrega si el dispositivo tiene la función del sistema FEATURE_PICTURE_IN_PICTURE. Además, cuando se activa la acción, el del modo de PIP se configura para que coincida con la relación de aspecto jugó.

Asegúrate de agregar un título y un subtítulo para brindarle al usuario información sobre el uso general de este PIP.

Nota: Para ingresar al modo de pantalla en pantalla, se requieren acciones intencionales y explícitas por el usuario dentro de la aplicación. Para obtener más información, consulta la Lineamientos de calidad de apps para TV.

Coexiste con apps que se ejecutan en modo de PIP

Cuando tu app se ejecuta como una app de pantalla completa, es posible que deba adaptarse a otras apps que se ejecutan en modo de PIP.

APIs de Keep-clear

En algunos casos, la app de PIP puede superponer componentes importantes de la IU dentro del pantalla completa. Para mitigar esto, existen APIs claras que las apps pueden usar para identificar componentes críticos de la interfaz de usuario que no deben superponerse. El sistema intenta cumplir con las solicitudes para evitar cubrir estos componentes cambiando la posición de la ventana del PiP.

Nota: Es posible que el sistema no respete estas solicitudes si hay demasiados componentes de la IU están marcados como “Keep-Clear” o si ocupan grandes partes de la pantalla. Ten esto en cuenta cuando uses estas APIs.

Para especificar que una vista no se debe superponer, usa preferKeepClear en tu un diseño XML como en el siguiente ejemplo:

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

También puedes hacerlo de forma programática con 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);
}

Puede haber ocasiones en las que no necesites mantener claro un View completo, pero solo una parte de ella. setPreferKeepClearRects() se puede usar para lo siguiente: especificar las regiones de View que no se deben superponer. Es posible que las IU que no usan View de forma nativa, como Flutter, Jetpack Compose y WebView, tengan sub secciones que necesiten que las regiones se mantengan claras. Esta API se puede usar para esos casos.

Nota: Si estableces setPreferKeepClear() en true, todo View se marca como zona de exclusión y se ignoran las regiones especificadas con setPreferKeepClearRects().

Tipos de uso

Tu app debe declarar un atributo de valor de metadatos de com.google.android.tv.pip.category que corresponda al tipo principal o a los tipos de uso del modo de imagen en imagen. Cualquier <activity> que haya configurado android:supportsPictureInPicture="true" debe declarar este atributo con un valor relevante de la siguiente tabla.

No se permiten los tipos de uso que no se incluyan en ninguna de estas categorías, en particular, la reproducción de contenido multimedia, en el modo de pantalla en pantalla en la TV.

Valor	Descripción
"communication"	Casos de uso de comunicaciones, como videollamadas o llamadas de voz
"smartHome"	Integraciones de casa inteligente, como timbres conectados o monitores para bebés
"health"	Casos de uso de salud, como el seguimiento de fitness o la supervisión de salud
"ticker"	Casos de uso de cotizaciones, como resultados deportivos en vivo o noticias y teletipos de acciones.

Los valores múltiples se separan con una barra vertical (|). Por ejemplo:

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