Härtung von Audio im Hintergrund

Ab Android 17 gelten im Audio-Framework Einschränkungen für Audiointeraktionen im Hintergrund, einschließlich der Audiowiedergabe, Audiofokus-Anfragen und APIs für Lautstärkeänderungen. So soll sichergestellt werden, dass diese Änderungen vom Nutzer beabsichtigt sind.

Alle Apps, die unter Android 17 ausgeführt werden und diese Audiointeraktionen im Hintergrund haben, müssen eine sichtbare Aktivität haben oder einen Dienst im Vordergrund ausführen, der nicht vom Typ SHORT_SERVICE ist. Dies gilt unabhängig davon, ob die App auf API-Level 37 ausgerichtet ist oder nicht.

Wenn eine App auf Android 17 (API-Level 37) ausgerichtet ist, gilt eine zusätzliche Einschränkung. Wenn die App im Hintergrund ausgeführt wird, muss sie einen Dienst im Vordergrund ausführen, der während der Nutzung (WIU) verwendet werden kann. (Einem Dienst im Vordergrund werden WIU-Funktionen gewährt, wenn er als Reaktion auf einen vom Nutzer initiierten Vorgang oder während die App für den Nutzer sichtbar ist, gestartet wird.) Die Anforderung für WIU-Funktionen entfällt jedoch, wenn der App die Berechtigung exakter Alarm gewährt wurde und sie Änderungen an Audiostreams mit dem Attribut USAGE_ALARM vornimmt.

Wenn die App versucht, Audio-APIs aufzurufen, während sie sich nicht in einem gültigen Lebenszyklus befindet, schlagen die APIs für die Audiowiedergabe und die Lautstärkeänderung ohne Fehlermeldung oder Ausnahme fehl. Die Audiofokus-API schlägt mit dem Ergebniscode AUDIOFOCUS_REQUEST_FAILED fehl.

Warum wir diese Änderung vornehmen

Mit der Einführung dieser Einschränkungen sollen unbeabsichtigte Fehler bei der Audiowiedergabe im Hintergrund reduziert werden. Beispiele:

• Apps, die Audio ohne einen Dienst im Vordergrund wiedergeben, können eingefroren werden. Wenn die App schließlich wieder aktiviert wird, wird die Audiowiedergabe unerwartet fortgesetzt, möglicherweise Stunden später.
• Apps, die Audio ohne einen Dienst im Vordergrund wiedergeben, unterliegen verschiedenen Ausführungseinschränkungen, die zu einer unregelmäßigen Audiowiedergabe führen.
• Die Wiedergabe ist vom Aktivitätslebenszyklus getrennt, was zu einer Wiedergabesitzung oder zu Fokusereignissen führen kann, die nicht mehr gestoppt werden können.

Wir empfehlen Entwicklern, ihre Apps zu testen und Feedback zu den Verhaltensänderungen zu geben, falls beabsichtigte Audio-Anwendungsfälle negativ beeinflusst werden. Bitte melde alle Probleme über diesen Issue Tracker für die App-Kompatibilität mit Android 17.

Betroffene Anwendungsfälle für die Audiowiedergabe im Hintergrund identifizieren

Überprüfe die Implementierung der Audiowiedergabe und stelle fest, ob deine App auch unter bestimmten Bedingungen eine Funktion für die Audiointeraktion im Hintergrund bereitstellen soll.

Wenn deine App nur Audioinhalte abspielen oder Audio-APIs verwenden soll, während sie eine für den Nutzer sichtbare Aktivität anzeigt, einschließlich der Verwendung des Bild-im-Bild-Modus, ist sie von diesen Änderungen nicht betroffen.

Wenn deine App VoIP-Funktionen bietet, einschließlich Videoanruf-Apps, muss sie bereits die Anforderungen erfüllen, die für die Wiedergabe eingeführt werden (normalerweise durch die Verwendung der empfohlenen Telecom APIs), um Audio erfolgreich aufzunehmen. Daher ist es unwahrscheinlich, dass sie betroffen ist.

Wenn Ihre App die Audiowiedergabe bei ausgeschaltetem Bildschirm oder bei nicht sichtbarer Aktivität fortsetzen soll, was am häufigsten bei Musik-Streaming-Apps oder Podcast-Apps der Fall ist, gilt sie als App mit Hintergrund-Audiofunktion und muss die neuen Anforderungen erfüllen.

Szenarien für Hintergrundaudio, die wahrscheinlich betroffen sind

Wenn deine App nicht dem Modell folgt, eine Audiointeraktion fortzusetzen, die initiiert wurde, während deine App geöffnet war, oder als Reaktion auf einen expliziten Nutzerauslöser, wird die Funktionalität deiner App wahrscheinlich ohne Benachrichtigung unterdrückt.

Wenn Ihre App beispielsweise als Reaktion auf BOOT_COMPLETE einen Dienst im Vordergrund startet und versucht, mit Audio zu interagieren, wird dies unterdrückt.

Best Practices für Hintergrundaudio zur Minimierung der Auswirkungen

• Verwenden Sie die Komponente MediaSessionService der Jetpack-Bibliothek media3, um die Audiowiedergabe im Hintergrund zu verwalten.

  In diesem Fall ist es unwahrscheinlich, dass deine App von der Härtung im Hintergrund betroffen ist, da die Bibliothek die Verwaltung des Wiedergabe-Lebenszyklus unterstützt.

• Wenn Sie die Media3-Bibliothek nicht verwenden, müssen Sie einen mediaPlayback Dienst im Vordergrund manuell starten. Starten Sie immer einen Dienst im Vordergrund, während sich die App im Vordergrund befindet, wenn Audio im Hintergrund wiedergegeben werden kann.

  Wenn Ihre App beispielsweise eine Videostreaming-App ist, die normalerweise nur im Vordergrund ausgeführt wird, aber eine Nutzeroption zum Fortsetzen der Wiedergabe bei ausgeschaltetem Bildschirm enthält, sollte Ihre App beim Auftreten des vom Nutzer initiierten Wiedergabe-Triggers trotzdem einen Dienst im Vordergrund starten.

  So wird sichergestellt, dass der Dienst im Vordergrund mit WIU-Funktionen gestartet wird.

• Lassen Sie die mediaPlayback-FGS bei vorübergehenden Fehlern von weniger als 10 Minuten aktiv.

  Wenn in deiner App ein vorübergehender Fehler auftritt, z. B. ein Problem mit der Zwischenspeicherung aufgrund von Netzwerkaktivität, oder wenn es eine erwartete vorübergehende Unterbrechung wie AUDIOFOCUS_LOSS_TRANSIENT gibt, sollte die Wiedergabe fortgesetzt werden. Daher sollte Ihr FGS aktiv bleiben.

• Beende den Dienst im Vordergrund am Ende der Wiedergabe und starte die Wiedergabe nur dann neu, wenn der Nutzer die Wiedergabe explizit fortsetzt.

  Wenn ein dauerhaftes Signal zum Beenden der Wiedergabe gesendet wird (z. B. wenn der Inhalt ohne automatische Wiedergabe beendet wurde, ein AUDIOFOCUS_LOSS, ein Pausenereignis vom UMO oder ein Medientastenereignis) oder ein nicht behebbarer Fehler auftritt, sollte deine App die Audiointeraktion beenden, den Dienst im Vordergrund beenden und die Mediensitzung beenden. All dies entspricht der Vorstellung des Nutzers, die gewünschte Hintergrund-Audiointeraktion „abzuschließen“. Danach hat Ihre App keine Funktionen mehr für die Audiointeraktion im Hintergrund.

  Wenn der Nutzer die Wiedergabe anschließend explizit fortsetzt, z. B. über die Benutzeroberfläche Ihrer App oder über die Wiedergabeschaltfläche des Universal Media Object, sollte der Intent zum Starten der Audiowiedergabe zurückgegeben werden, was zu einem neu gestarteten Dienst im Vordergrund führt.

• Testen Sie das Verhalten der Audiowiedergabe mit adb-Shell-Befehlen.

Änderungen testen

Sie können die Compliance Ihrer App auf Geräten mit Android 17 oder höher (ab Beta 3) mit dem folgenden ADB-Befehl testen:

adb shell cmd audio set-enable-hardening <enable|disable|throw>

Dieser Befehl hat die folgenden Optionen:

• enable: Aktiviert alle Einschränkungen zur Audiohärtung für alle Apps. Die Anforderung für WIU-Dienste im Vordergrund gilt unabhängig davon, ob eine App auf Android 17 (API-Level 37) ausgerichtet ist oder nicht. Darüber hinaus wird die Anforderung auch dann erzwungen, wenn die App Änderungen an Wecker-Streams vornimmt und die Berechtigung für genaue Wecker hat.

• disable: Deaktiviert alle Einschränkungen für die Audiohärtung.

• throw: Aktiviert alle Einschränkungen zur Audiohärtung für alle Apps, z. B. enable. Außerdem werden durch dieses Flag laute Fehler aktiviert, die bei Interaktionen mit der Lautstärke und dem Fokus IllegalStateException auslösen. Bei der Audiowiedergabe gibt die Schreibmethode dauerhaft einen Fehlercode zurück. Bei Wiedergabemodi ohne explizite Schreibvorgänge stürzt die App ab.

Verwenden Sie adb dumpsys audio oder logcat, um festzustellen, ob die App aufgrund der Erzwingung der Audiohärtung unbemerkt Fehler aufweist. In diesem Fall gibt es einen Eintrag mit dem Präfix AudioHardening und Ihrem Paketnamen. Wenn die Nachricht level: full enthält, wird in Ihrer App ein Dienst im Vordergrund ausgeführt, der jedoch nicht die Funktion „Nur bei Nutzung der App“ hat. Wenn die Nachricht level: partial enthält, wird in Ihrer App überhaupt kein Dienst im Vordergrund ausgeführt.

Dienste im Vordergrund mit der Funktion „Während der Nutzung“

Im Allgemeinen müssen Dienste im Vordergrund gestartet werden, während sich eine App im Vordergrund befindet, um von Nutzern initiierte Vorgänge zu erweitern. In einigen bestimmten Fällen dürfen Apps einen Dienst im Vordergrund starten, während sich die App im Hintergrund befindet. Diesen Diensten im Vordergrund werden jedoch in der Regel keine WIU-Berechtigungen (While-In-Use) gewährt.

WIU fungiert als Sicherheitsmaßnahme. Es verhindert, dass im Hintergrund gestartete FGS bestimmte sensible Verhaltensweisen ausführen, wenn der Nutzer sich der Aktivität der App möglicherweise nicht bewusst ist. Sie verhindert, dass die App auf sensible Daten wie Standort, Kamera oder Mikrofon zugreift. Ab Android 17 werden auch Audio-APIs blockiert, die normalerweise einen sichtbaren UI-Kontext erfordern.

Hier ist eine praktische Übersicht:

• Standard-FGS: Dienste, die gestartet werden, während die App sichtbar ist oder die Berechtigung zum Starten von Hintergrundaktivitäten hat, erhalten WIU-Zugriff.
• Im Hintergrund gestartete FGS (BFSL): Die meisten gewähren keinen WIU-Zugriff. Die wichtigsten Ausnahmen, die eine WIU gewähren, sind Interaktionen, die eine explizite Nutzerabsicht beinhalten, z. B. Klicks auf Benachrichtigungen, Widget-Interaktionen oder Medientastenereignisse von einem externen Gerät.
• Vom System gestartete Dienste im Vordergrund: Dienste im Vordergrund erhalten WIU-Zugriff, wenn sie durch die Delegierung des Systemservers (z. B. aus der Telecom-Jetpack-Bibliothek) oder durch Systembindungen gestartet werden, die einen erhöhten Vordergrundstatus darstellen, um dedizierte Funktionen auszuführen (z. B. für einen VoiceInteractionService).

Weitere Informationen finden Sie unter Einschränkungen beim Starten eines Dienstes im Vordergrund aus dem Hintergrund.

Vollständige Liste der betroffenen Audio-APIs