Multitasking auf dem Fernseher

In Android 14 (API-Level 34) wurden einige Verbesserungen an den APIs für den Bild-im-Bild-Modus (PiP) vorgenommen, um Multitasking zu ermöglichen. Die Unterstützung für den PiP-Modus wurde in Android 8.0 (API-Level 26) eingeführt, war aber auf Android TV nicht weit verbreitet und vor Android 13 auf Google TV überhaupt nicht verfügbar. Beim Multitasking für TV wird der PiP-Modus verwendet, damit zwei separate Apps gleichzeitig auf dem Bildschirm angezeigt werden können: eine im Vollbildmodus und eine im PiP-Modus. Für Apps, die in einem dieser Modi ausgeführt werden, gelten unterschiedliche Anforderungen.

Standardmäßig überlagert die PiP-App die Vollbild-App. Das entspricht dem Standardverhalten des Bild-im-Bild-Modus unter Android.

Wenn Sie Multitasking einbinden, muss Ihre Anwendung ihre Nutzungstypen gemäß den Qualitätsrichtlinien für TV-Apps deklarieren.

App im PiP-Modus ausführen

Auf TV-Geräten mit Android 14 (API-Level 34) oder höher können Sie Ihre App im PiP Modus ausführen, indem Sie enterPictureInPictureMode() aufrufen. TV-Geräte mit älteren Android-Versionen unterstützen den PiP-Modus nicht.

Hinweis: Für API-Level 26 und niedriger gibt es eine eingestellte Methode enterPictureInPictureMode(), die PictureInPictureParams.Builder nicht verwendet. Verwenden Sie diese Methode nicht, da sie auf TV-Geräten nicht unterstützt wird.

Hier ist ein Beispiel für die Implementierung der Logik einer Schaltfläche zum Aufrufen des PiP-Modus:

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
        }
}
Multitasking.kt

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

Die Aktion wird nur hinzugefügt, wenn das Gerät das Systemfeature FEATURE_PICTURE_IN_PICTURE hat. Wenn die Aktion ausgelöst wird, wird das Seitenverhältnis des PiP-Modus außerdem so festgelegt, dass es dem Seitenverhältnis des wiedergegebenen Videos entspricht.

Fügen Sie einen Titel und einen Untertitel hinzu, um dem Nutzer Informationen dazu zu geben, wofür dieser PiP-Modus im Allgemeinen verwendet wird.

Hinweis: Für den Wechsel in den Bild-im-Bild-Modus ist eine explizite und beabsichtigte Aktion des Nutzers in der App erforderlich. Weitere Informationen finden Sie in den Qualitätsrichtlinien für TV-Apps.

Mit Apps im PiP-Modus zusammenarbeiten

Wenn Ihre App als Vollbild-App ausgeführt wird, muss sie möglicherweise an andere Apps angepasst werden, die im PiP-Modus ausgeführt werden.

Keep-clear-APIs

In einigen Fällen kann die PiP-App wichtige UI-Komponenten in der Vollbild-App überlagern. Um dies zu verhindern, gibt es Keep-clear-APIs, mit denen Apps kritische UI-Komponenten identifizieren können, die nicht überlagert werden sollen. Das System versucht, die Anfragen zu berücksichtigen und diese Komponenten nicht zu verdecken, indem es das PiP-Fenster neu positioniert.

Abbildung 1. Positionierung des PiP-Fensters, um wichtige UI-Komponenten nicht zu verdecken.

Hinweis: Das System berücksichtigt diese Anfragen möglicherweise nicht, wenn zu viele UI-Komponenten als „keep-clear“ markiert sind oder wenn sie große Teile des Bildschirms einnehmen. Beachten Sie dies, wenn Sie diese APIs verwenden.

Wenn Sie angeben möchten, dass eine Ansicht nicht überlagert werden soll, verwenden Sie preferKeepClear in Ihrem XML-Layout, wie im folgenden Beispiel:

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

Sie können dies auch programmatisch mit setPreferKeepClear() tun:

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

Manchmal müssen Sie nicht eine ganze View freihalten, sondern nur einen Teil davon. Die setPreferKeepClearRects() kann verwendet werden, um Bereiche der View anzugeben, die nicht überlagert werden sollen. Bei UIs, die keine nativen Views verwenden, z. B. Flutter, Jetpack Compose und WebView, müssen möglicherweise Unterbereiche freigehalten werden. Für diese Fälle kann diese API verwendet werden.

Hinweis: Wenn Sie setPreferKeepClear() auf true setzen, wird die gesamte View als „keep-clear“ markiert und alle mit setPreferKeepClearRects() angegebenen Bereiche werden ignoriert.

Nutzungstypen

Ihre App muss ein Metadatenattribut com.google.android.tv.pip.category deklarieren, das dem primären Nutzungstyp oder den primären Nutzungstypen für den Bild-im-Bild-Modus entspricht. Jede <activity>, für die festgelegt wurde android:supportsPictureInPicture="true", muss dieses Attribut mit einem relevanten Wert aus der folgenden Tabelle deklarieren.

Nutzungstypen, die nicht in eine dieser Kategorien fallen, insbesondere die Wiedergabe von Medieninhalten, sind im Bild-im-Bild-Modus auf dem Fernseher nicht zulässig.

Wert	Beschreibung
"communication"	Anwendungsfälle für die Kommunikation, z. B. Video- oder Sprachanrufe.
"smartHome"	Smart-Home-Integrationen, z. B. verbundene Türklingeln oder Babyphone.
"health"	Anwendungsfälle im Gesundheitsbereich, z. B. Fitness-Tracking oder Gesundheitsüberwachung.
"ticker"	Ticker-Anwendungsfälle, z. B. Live-Sportergebnisse oder Nachrichten- und Börsenticker.

Mehrere Werte werden durch einen senkrechten Strich (|) getrennt. Beispiel:

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