Multitasking auf dem Fernseher

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

Standardmäßig wird die Vollbild-App von der BiB-App überlagert. Das entspricht dem Standardverhalten von Android-Bild-im-Bild.

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

App im BiB-Modus ausführen

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

Hinweis: Für API-Level 26 und niedriger gibt es eine eingestellte enterPictureInPictureMode()-Methode, die PictureInPictureParams.Builder nicht verwendet. Vermeide die Verwendung, 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 BiB-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
        }
}

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 die Systemfunktion FEATURE_PICTURE_IN_PICTURE hat. Wenn die Aktion ausgelöst wird, wird das Seitenverhältnis des BiB-Modus an das Seitenverhältnis des wiedergegebenen Videos angepasst.

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

Hinweis :Der Bild-im-Bild-Modus kann nur durch eine explizite und bewusste Aktion des Nutzers in der App aktiviert werden. Weitere Informationen finden Sie in den Qualitätsrichtlinien für TV-Apps.

Mit Apps, die im BiB-Modus ausgeführt werden, zusammenarbeiten

Wenn Ihre App als Vollbild-App ausgeführt wird, muss sie sich möglicherweise an andere Apps anpassen, die im BiB-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 wichtige UI-Komponenten identifizieren können, die nicht überlagert werden sollten. Das System versucht, die Anfragen zu berücksichtigen, um diese Komponenten nicht durch Neupositionierung des BiB-Fensters 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 bei der Verwendung dieser APIs.

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 das gesamte View freihalten, sondern nur einen Teil davon. Mit setPreferKeepClearRects() können Sie Bereiche des View angeben, die nicht überlagert werden sollen. Bei Benutzeroberflächen, die Views nicht nativ verwenden, z. B. Flutter, Jetpack Compose und WebView, kann es Unterbereiche geben, in denen keine Regionen platziert werden dürfen. Für diese Fälle kann diese API verwendet werden.

Hinweis: Wenn Sie setPreferKeepClear() auf true setzen, wird der gesamte View als „Freihalten“ markiert und alle mit setPreferKeepClearRects() angegebenen Regionen werden ignoriert.

Nutzungstypen

Ihre App muss ein meta-data value attribute von com.google.android.tv.pip.category deklarieren, das dem primären Typ oder den primären Typen der Verwendung für den Bild-im-Bild-Modus entspricht. Für jedes <activity>, für das android:supportsPictureInPicture="true" festgelegt ist, muss dieses Attribut mit einem relevanten Wert aus der Tabelle unten deklariert werden.

Nutzungsarten, 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 wie verbundene Türklingeln oder Babyfone.
„health“	Gesundheitsbezogene Anwendungsfälle wie Fitness-Tracking oder Gesundheitsüberwachung.
„ticker“	Ticker-Anwendungsfälle wie Live-Sportergebnisse oder Nachrichten- und Aktienticker.

Mehrere Werte werden durch einen senkrechten Strich (|) getrennt, z. B.:

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