Härtung von Audio im Hintergrund

Ab Android 17 werden im Audio-Framework Einschränkungen für Audiointeraktionen im Hintergrund erzwungen, darunter Audiowiedergabe, Audiofokus-Anfragen und Lautstärkeänderungs-APIs. So soll sichergestellt werden, dass diese Änderungen vom Nutzer bewusst initiiert werden.

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

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-Funktionen (WIU) hat. Ein Dienst im Vordergrund erhält WIU-Funktionen, 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 wird jedoch aufgehoben, wenn der App die Berechtigung exact alarm erteilt 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 Lautstärkeänderung fehl, ohne eine Ausnahme auszulösen oder eine Fehlermeldung auszugeben. Die Audio-Fokus-API schlägt mit dem Ergebniscode AUDIOFOCUS_REQUEST_FAILED fehl.

Warum wir diese Änderung vornehmen

Mit diesen Einschränkungen möchten wir verhindern, dass es zu unbeabsichtigten Problemen mit Hintergrundaudio kommt. Beispiele:

• Apps, die Audio ohne Dienst im Vordergrund wiedergeben, können eingefroren werden. Wenn die App schließlich reaktiviert wird, wird die Audiowiedergabe unerwartet fortgesetzt, möglicherweise Stunden später.
• Apps, die Audio ohne Dienst im Vordergrund abspielen, unterlagen verschiedenen Laufzeitbeschränkungen, die zu einer ungleichmäßigen Audioleistung führten.
• Die Wiedergabe ist vom Aktivitätslebenszyklus getrennt, was zu einer nicht beendeten Wiedergabesitzung oder nicht beendeten Fokusereignissen führen kann, ohne dass der Nutzer die Wiedergabe beenden kann.

Wir empfehlen Entwicklern, ihre Apps zu testen und Feedback zu den Verhaltensänderungen zu geben, wenn beabsichtigte Audio-Anwendungsfälle negativ beeinträchtigt werden. Bitte melden Sie alle Probleme über diesen Issue-Tracker für die App-Kompatibilität unter Android 17.

Betroffene Anwendungsfälle für Hintergrundaudio identifizieren

Überprüfen Sie die Implementierung der Audiowiedergabe und stellen Sie fest, ob Ihre App auch unter bestimmten Bedingungen Funktionen zur Interaktion mit Audio im Hintergrund bereitstellen soll.

Wenn Ihre App nur Audio wiedergeben oder Audio-APIs verwenden soll, während eine für den Nutzer sichtbare Aktivität angezeigt wird, einschließlich der Verwendung des Bild-im-Bild-Modus (BiB), ist sie von diesen Änderungen nicht betroffen.

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

Wenn Ihre App die Audiowiedergabe bei ausgeschaltetem Bildschirm oder wenn Ihre Aktivität nicht sichtbar ist fortsetzen soll, was am häufigsten bei Musikstreaming- oder Podcast-Apps der Fall ist, gilt Ihre App als App mit Hintergrundaudiofunktion und muss die neuen Anforderungen erfüllen.

Szenarien mit Hintergrundaudio, die wahrscheinlich betroffen sind

Wenn Ihre App nicht dem Modell folgt, eine Audiointeraktion fortzusetzen, die gestartet wurde, als Ihre App geöffnet war, oder als Reaktion auf einen expliziten Nutzer-Trigger, wird die Funktion Ihrer App wahrscheinlich im Hintergrund unterdrückt.

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

Best Practices für Hintergrundaudio zur Minimierung von Auswirkungen

• Verwende die media3-Jetpack-Bibliothek und die Komponente MediaSessionService, um die Audiowiedergabe im Hintergrund zu verwalten.

  In diesem Fall ist es unwahrscheinlich, dass Ihre App von der Hintergrundhärtung betroffen ist, da die Bibliothek bei der Verwaltung des Wiedergabe-Lebenszyklus hilft.

• Wenn Sie die Media3-Bibliothek nicht verwenden, müssen Sie manuell einen mediaPlayback-Dienst im Vordergrund starten. Starten Sie einen Dienst im Vordergrund immer, wenn die App im Vordergrund ausgeführt wird und Audio im Hintergrund wiedergegeben werden soll.

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

  Dadurch 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 dem Puffern aufgrund von Netzwerkaktivität, oder eine erwartete vorübergehende Unterbrechung wie AUDIOFOCUS_LOSS_TRANSIENT vorliegt, sollte die Wiedergabe fortgesetzt werden. Ihr FGS sollte also aktiv bleiben.

• Beenden Sie den Dienst im Vordergrund am Ende der Wiedergabe und starten Sie die Wiedergabe nur neu, wenn der Nutzer sie explizit fortsetzt.

  Bei einem permanenten Signal zum Beenden der Wiedergabe (z. B. wenn Inhalte ohne automatische Wiedergabe vollständig wiedergegeben wurden, bei einem AUDIOFOCUS_LOSS, einem Pausenereignis vom UMO oder einem Media-Schlüsselereignis) oder bei einem nicht behebaren Fehler sollte Ihre App die Audiointeraktion beenden, den Dienst im Vordergrund stoppen und die Mediensitzung beenden. All das entspricht der Vorstellung des Nutzers, die gewünschte Hintergrundaudio-Interaktion „abzuschließen“. Danach kann Ihre App nicht mehr im Hintergrund auf Audio reagieren.

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

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

Änderungen testen

Sie können die Konformität 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 für die Audio-Härtung für alle Apps. Die Anforderung für WIU-Vordergrunddienste gilt unabhängig davon, ob eine App auf Android 17 (API-Level 37) ausgerichtet ist. Außerdem wird die Anforderung auch dann erzwungen, wenn die App Änderungen an Alarmstreams vornimmt und die genaue Alarmberechtigung hat.

• disable: Deaktiviert alle Einschränkungen für die Audio-Härtung.

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

Mit adb dumpsys audio oder logcat können Sie feststellen, ob in der App aufgrund der Durchsetzung der Audio-Härtung stille Fehler aufgetreten sind. Wenn das der Fall ist, sehen Sie einen Eintrag mit dem Präfix AudioHardening und Ihrem Paketnamen. Wenn die Meldung level: full enthält, wird in Ihrer App ein Dienst im Vordergrund ausgeführt, der jedoch nicht die Funktion „Während der Nutzung“ hat. Wenn die Meldung level: partial enthält, wird in Ihrer App kein Dienst im Vordergrund ausgeführt.

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

Dienste im Vordergrund müssen in der Regel gestartet werden, während sich eine App im Vordergrund befindet, um vom Nutzer initiierte Vorgänge zu verlängern. In bestimmten Fällen dürfen Apps einen Dienst im Vordergrund starten, während die App im Hintergrund ausgeführt wird. Diesen Diensten im Vordergrund werden jedoch in der Regel keine Berechtigungen für die Nutzung während der Nutzung (While-In-Use, WIU) gewährt.

WIU fungiert als Sicherheitstor. Es verhindert, dass FGS, die im Hintergrund gestartet werden, bestimmte sensible Verhaltensweisen ausführen, wenn der Nutzer sich der Aktivität der App möglicherweise nicht bewusst ist. Dadurch wird verhindert, dass die App auf sensible Daten wie Standort, Kamera oder Mikrofon zugreift. Ab Android 17 werden auch Audio-APIs blockiert, für die normalerweise ein sichtbarer UI-Kontext erforderlich ist.

Hier finden Sie eine praktische Referenz:

• Standard-FGS: Dienste, die gestartet werden, während die App sichtbar ist oder die Funktion zum Starten von Hintergrundaktivitäten gewährt wurde, erhalten WIU-Zugriff.
• Im Hintergrund gestartete FGS (BFSL): Die meisten gewähren keinen WIU-Zugriff. Die primären Ausnahmen, die WIU gewähren, sind Interaktionen mit expliziter Nutzerabsicht, z. B. Benachrichtigungsklicks, Widget-Interaktionen oder Media-Key-Ereignisse von einem externen Gerät.
• Vom System gestartete FGS: Vordergrunddienste erhalten WIU-Zugriff, wenn sie durch die Systemserverdelegierung (z. B. über die Telecom-Jetpack-Bibliothek) oder durch Systembindungen gestartet werden, die einen erhöhten Vordergrundstatus darstellen, um bestimmte Funktionen auszuführen (z. B. für ein VoiceInteractionService).

Weitere Informationen finden Sie unter Beschränkungen für das Starten eines Dienstes im Vordergrund aus dem Hintergrund.

Vollständige Liste der betroffenen Audio-APIs