Tools für das Kompatibilitäts-Framework

Mit Android 11 wurden neue Entwicklertools zum Testen und Debuggen von Apps im Hinblick auf Verhaltensänderungen in neueren Versionen der Android-Plattform eingeführt. Diese Tools sind Teil eines Kompatibilitäts-Frameworks, mit dem App-Entwickler funktionsgefährdende Änderungen einzeln über die Entwickleroptionen oder ADB aktivieren und deaktivieren können. Nutze diese Flexibilität, wenn du dich darauf vorbereitest, die neueste stabile API-Version als Ziel festzulegen, und wenn du deine App mit der Vorabversion der nächsten Android-Version testest.

Wenn Sie die Tools des Kompatibilitäts-Frameworks verwenden, passt die Android-Plattform ihre interne Logik automatisch an. Sie müssen also weder Ihre targetSDKVersion ändern noch Ihre App neu kompilieren, um grundlegende Tests durchzuführen. Da Änderungen einzeln aktiviert werden können, können Sie eine Verhaltensänderung nach der anderen isolieren, testen und debuggen oder eine einzelne Änderung deaktivieren, die Probleme verursacht, wenn Sie zuerst etwas anderes testen müssen.

Herausfinden, welche Änderungen aktiviert sind

Wenn eine Verhaltensänderung aktiviert ist, kann sich das darauf auswirken, wie Ihre App auf die Plattform-APIs zugreift, die von dieser Änderung betroffen sind. Sie können die Entwickleroptionen, Logcat oder ADB-Befehle verwenden, um zu prüfen, welche Verhaltensänderungen aktiviert sind.

Aktivierte Änderungen mithilfe der Entwickleroptionen identifizieren

Abbildung 1. „Änderungen der App-Kompatibilität“ in den Entwickleroptionen.

In den Entwickleroptionen eines Geräts kannst du sehen, welche Änderungen aktiviert sind, und diese Änderungen aktivieren oder deaktivieren. So greifen Sie auf diese Optionen zu:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffne auf deinem Gerät die Einstellungen und gehe zu System > Erweitert > Entwickleroptionen > Änderungen der App-Kompatibilität.

3. Wählen Sie Ihre App aus der Liste aus.

Jede Verhaltensänderung gehört in der Regel zu einer der folgenden beiden Kategorien:

• Änderungen, die sich auf alle Apps auswirken, die auf dieser Android-Version ausgeführt werden, unabhängig vom targetSdkVersion der App.

  Diese Änderungen sind im Kompatibilitäts-Framework standardmäßig aktiviert und werden in der Benutzeroberfläche im Abschnitt Standardmäßig aktivierte Änderungen aufgeführt.

• Änderungen, die sich nur auf Apps auswirken, die auf bestimmte Android-Versionen ausgerichtet sind. Da sich diese Änderungen nur auf Apps auswirken, die auf eine bestimmte Android-Version ausgerichtet sind, werden sie auch als Änderungen bezeichnet, die durch targetSDKVersion beschränkt sind.

  Diese Änderungen sind im Kompatibilitäts-Framework standardmäßig aktiviert, wenn deine App auf eine höhere Version als die aufgeführte API-Version ausgerichtet ist. Beispielsweise wird eine Verhaltensänderung, die in Android 13 (API-Level 33) durch targetSDKVersion gesteuert wird, in der Benutzeroberfläche in einem Abschnitt mit dem Titel Aktiviert für targetSdkVersion >=33 aufgeführt. In einigen älteren Android-Versionen heißt dieser Abschnitt stattdessen „Aktiviert nach SDK API_LEVEL“.

In Abbildung 1 sehen Sie auch den Abschnitt Standardmäßig deaktivierte Änderungen. Änderungen, die in diesen Bereich fallen, können verschiedenen Zwecken dienen. Bevor du diese Änderungen aktivierst, lies die Änderungsbeschreibung in der Liste des Kompatibilitäts-Frameworks für diese Android-Version.

Aktivierte Änderungen mit Logcat identifizieren

Für jede Verhaltensänderung gibt das System beim ersten Aufruf der betroffenen API durch Ihre App eine Logcat-Nachricht wie diese aus:

D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED

Jede Logcat-Nachricht enthält die folgenden Informationen:

Änderungs-ID

Gibt an, welche Änderung sich auf die App auswirkt. Dieser Wert entspricht einer der Verhaltensänderungen, die auf dem Bildschirm App Compatibility Changes (siehe Abbildung 1) aufgeführt sind. In diesem Beispiel wird 194833441 NOTIFICATION_PERM_CHANGE_ID zugeordnet.

UID

Gibt an, welche App von der Änderung betroffen ist.

Status

Gibt an, ob sich die Änderung auf die App auswirkt.

Der Status kann einen der folgenden Werte haben:

Status	Bedeutung
ENABLED	Die Änderung ist aktiviert und wirkt sich auf das Verhalten der App aus, wenn die App die geänderten APIs verwendet.
DISABLED	Die Änderung ist deaktiviert und hat keine Auswirkungen auf die App. Hinweis:Wenn diese Änderung deaktiviert ist, weil die targetSDKVersion der App unter dem erforderlichen Schwellenwert liegt, wird die Änderung standardmäßig aktiviert, wenn die targetSDKVersion der App erhöht wird, um eine höhere Version als Ziel festzulegen.
LOGGED	Die Änderung wird über das Kompatibilitäts-Framework protokolliert, kann aber nicht aktiviert oder deaktiviert werden. Auch wenn diese Änderung nicht aktiviert oder deaktiviert werden kann, kann sie sich dennoch auf das Verhalten deiner App auswirken. Weitere Informationen finden Sie in der Beschreibung der Änderung in der Liste des Kompatibilitäts-Frameworks für diese Android-Version. In vielen Fällen sind diese Arten von Änderungen experimentell und können ignoriert werden.

Aktivierte Änderungen mit ADB identifizieren

Führe den folgenden ADB-Befehl aus, um alle Änderungen (aktiviert und deaktiviert) auf dem gesamten Gerät zu sehen:

adb shell dumpsys platform_compat

In der Ausgabe werden für jede Änderung die folgenden Informationen aufgeführt:

Änderungs-ID

Eine eindeutige Kennung für diese Verhaltensänderung. Beispiel: 194833441.

Name

Der Name dieser Verhaltensänderung. Beispiel: NOTIFICATION_PERM_CHANGE_ID.

targetSDKVersion-Kriterien

Welche targetSDKVersion die Änderung einschränkt (falls vorhanden).

Wenn diese Änderung beispielsweise nur für Apps aktiviert ist, die auf SDK-Version 33 oder höher ausgerichtet sind, wird enableAfterTargetSdk=32 ausgegeben. Wenn die Änderung nicht durch targetSDKVersion eingeschränkt ist, wird enableAfterTargetSdk=0 ausgegeben.

Paketüberschreibungen

Der Name jedes Pakets, bei dem der Standardstatus der Änderung (entweder aktiviert oder deaktiviert) überschrieben wurde.

Wenn es sich beispielsweise um eine Änderung handelt, die standardmäßig aktiviert ist, wird der Paketname deiner App aufgeführt, wenn du die Änderung über die Entwickleroptionen oder ADB deaktiviert hast. In diesem Fall würde die Ausgabe so aussehen:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion gesteuert werden, können standardmäßig entweder aktiviert oder deaktiviert sein. Die Liste der Pakete kann also Instanzen von true oder false enthalten, je nach targetSDKVersion der jeweiligen App. Beispiel:

packageOverrides={com.my.package=true, com.another.package=false}

Weitere Informationen zu bestimmten Änderungen

Die vollständige Liste der Verhaltensänderungen im Kompatibilitäts-Framework ist in der Dokumentation für jede Android-Version enthalten. Weitere Informationen finden Sie unter den folgenden Links, je nachdem, für welche Android-Version Sie Ihre App testen:

• Android 16 (API-Level 36)
• Android 15 (API-Level 35)
• Android 14 (API-Level 34)
• Android 13 (API-Level 33)
• Android 12 (API-Level 31 und 32)
• Android 11 (API-Level 30)

Wann Änderungen aktiviert werden sollten

Der Hauptzweck des Kompatibilitäts-Frameworks besteht darin, dir beim Testen deiner App mit neueren Android-Versionen Kontrolle und Flexibilität zu bieten. In diesem Abschnitt werden einige Strategien beschrieben, mit denen Sie festlegen können, wann Änderungen beim Testen und Debuggen Ihrer App aktiviert oder deaktiviert werden sollen.

Wann Änderungen deaktiviert werden sollten

Die Entscheidung, wann Änderungen deaktiviert werden sollen, hängt in der Regel davon ab, ob die Änderung durch targetSDKVersion gesteuert wird oder nicht.

Änderungen für alle Apps aktiviert

Änderungen, die sich auf alle Apps auswirken, sind standardmäßig für eine bestimmte Plattformversion aktiviert, unabhängig von der targetSDKVersion Ihrer App. Sie können also sehen, ob Ihre App betroffen ist, indem Sie sie auf dieser Plattformversion ausführen.

Wenn Sie beispielsweise Android 16 (API-Level 36) als Zielversion festlegen möchten, können Sie Ihre App auf einem Gerät mit Android 16 installieren und mit Ihren üblichen Testworkflows testen. Wenn bei Ihrer App Probleme auftreten, können Sie die Änderung, die das Problem verursacht, deaktivieren und weiter nach anderen Problemen suchen.

Diese Änderungen können sich auf alle Apps auswirken, unabhängig von targetSDKVersion. Testen und aktualisieren Sie Ihre App daher für diese Änderungen, bevor Sie Änderungen vornehmen, die durch targetSDKVersion eingeschränkt sind. So wird verhindert, dass sich die Nutzererfahrung nach einem Update auf eine neue Plattformversion verschlechtert.

Du solltest diese Änderungen auch priorisiert testen, da sie bei Verwendung eines öffentlichen Release-Builds von Android nicht deaktiviert werden können. Idealerweise sollten Sie diese Änderungen für jede Android-Version testen, solange sich die Version in der Vorabversion befindet.

Änderungen, die durch targetSDKVersion eingeschränkt sind

Wenn Ihre App auf eine bestimmte targetSDKVersion ausgerichtet ist, sind alle Änderungen, die durch diese Version eingeschränkt sind, standardmäßig aktiviert. Wenn Sie also die targetSDKVersion Ihrer App auf eine neue Version umstellen, wird Ihre App von vielen neuen Änderungen gleichzeitig betroffen sein.

Da Ihre App möglicherweise von mehreren dieser Änderungen betroffen ist, müssen Sie einige dieser Änderungen beim Testen und Debuggen Ihrer App möglicherweise einzeln deaktivieren.

Wann Änderungen aktiviert werden sollten

Änderungen, die durch eine bestimmte targetSDKVersion eingeschränkt sind, sind standardmäßig deaktiviert, wenn eine App auf eine niedrigere SDK-Version als die eingeschränkte Version ausgerichtet ist. Wenn Sie sich auf die Ausrichtung auf ein neues targetSdkVersion vorbereiten, haben Sie in der Regel eine Liste mit Verhaltensänderungen, für die Sie Ihre App testen und debuggen müssen.

Beispielsweise testen Sie Ihre App möglicherweise in den nächsten targetSdkVersion auf eine Reihe von Plattformänderungen. Mithilfe von Entwickleroptionen oder ADB-Befehlen kannst du jede einzelne Änderung aktivieren und testen, anstatt das App-Manifest zu ändern und alle Änderungen auf einmal zu aktivieren.

Mit dieser zusätzlichen Kontrolle können Sie Änderungen isoliert testen und vermeiden, dass Sie mehrere Teile Ihrer App gleichzeitig debuggen und aktualisieren müssen.

Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre App mit Ihren üblichen Testworkflows testen und debuggen. Wenn Probleme auftreten, prüfen Sie Ihre Logs, um die Ursache des Problems zu ermitteln. Wenn nicht klar ist, ob das Problem durch eine aktivierte Plattformänderung verursacht wird, deaktiviere diese Änderung und teste den entsprechenden Bereich deiner App noch einmal.

Änderungen aktivieren oder deaktivieren

Mit dem Kompatibilitäts-Framework kannst du jede Änderung über die Entwickleroptionen oder ADB-Befehle aktivieren oder deaktivieren. Da das Aktivieren oder Deaktivieren von Änderungen dazu führen kann, dass Ihre App abstürzt oder wichtige Sicherheitsänderungen deaktiviert werden, gibt es einige Einschränkungen, wann Sie Änderungen aktivieren oder deaktivieren können.

Änderungen über die Entwickleroptionen aktivieren oder deaktivieren

Mit den Entwickleroptionen kannst du Änderungen aktivieren oder deaktivieren. So findest du die Entwickleroptionen:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffne auf deinem Gerät die Einstellungen und gehe zu System > Erweitert > Entwickleroptionen > Änderungen der App-Kompatibilität.
3. Wählen Sie Ihre App aus der Liste aus.
4. Suchen Sie in der Liste der Änderungen die Änderung, die Sie aktivieren oder deaktivieren möchten, und tippen Sie auf den Schalter.

Änderungen mit ADB aktivieren/deaktivieren

Wenn Sie eine Änderung mit ADB aktivieren oder deaktivieren möchten, führen Sie einen der folgenden Befehle aus:

adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Übergeben Sie entweder die CHANGE_ID (z. B. 194833441) oder die CHANGE_NAME (z. B. NOTIFICATION_PERM_CHANGE_ID) und die PACKAGE_NAME Ihrer App.

Sie können auch den folgenden Befehl verwenden, um eine Änderung auf den Standardzustand zurückzusetzen und alle Überschreibungen zu entfernen, die Sie mit ADB oder den Entwickleroptionen festgelegt haben:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Einschränkungen beim Ändern der Einstellungen

Standardmäßig ist jede Verhaltensänderung entweder aktiviert oder deaktiviert. Änderungen, die sich auf alle Apps auswirken, sind standardmäßig aktiviert. Andere Änderungen werden durch ein targetSdkVersion gesteuert. Diese Änderungen sind standardmäßig aktiviert, wenn eine App auf die entsprechende SDK-Version oder höher ausgerichtet ist, und standardmäßig deaktiviert, wenn eine App auf eine SDK-Version ausgerichtet ist, die niedriger als die eingeschränkte Version ist. Wenn Sie eine Änderung aktivieren oder deaktivieren, überschreiben Sie den Standardstatus.

Damit das Kompatibilitäts-Framework nicht böswillig verwendet wird, gibt es einige Einschränkungen, wann Änderungen aktiviert oder deaktiviert werden können. Ob Sie eine Änderung aktivieren oder deaktivieren können, hängt von der Art der Änderung, davon, ob Ihre App debugfähig ist, und vom Typ des Builds ab, der auf Ihrem Gerät ausgeführt wird. In der folgenden Tabelle wird beschrieben, wann Sie verschiedene Arten von Änderungen aktivieren können: