Tools für das Kompatibilitäts-Framework

Mit Android 11 wurden neue Entwicklertools zum Testen und Debugging von Apps im Hinblick auf die Verhaltensänderungen in neueren Versionen der Android Plattform eingeführt. Diese Tools sind Teil eines Kompatibilitätsframeworks , mit dem App Entwickler mithilfe der Entwickler optionen oder ADB einzeln grundlegende Änderungen aktivieren und deaktivieren können. Nutzen Sie diese Flexibilität, wenn Sie sich darauf vorbereiten, auf die neueste stabile API-Version auszurichten, und wenn Sie Ihre App mit der Vorabversion der nächsten Android-Version testen.

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

Ermitteln, welche Änderungen aktiviert sind

Wenn eine Verhaltensänderung aktiviert ist, kann sich dies auf die Art und Weise auswirken, wie Ihre App auf die Plattform-APIs zugreift, die von dieser Änderung betroffen sind. Sie können mit den Entwickleroptionen, Logcat oder ADB-Befehlen prüfen, welche Verhaltens änderungen aktiviert sind.

Aktivierte Änderungen mit den Entwickleroptionen ermitteln

Abbildung 1 : Bildschirm „Änderungen bei der Kompatibilität von Apps“ in den Entwickleroptionen

In den Entwickleroptionen eines Geräts können Sie 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. Öffnen Sie auf Ihrem Gerät die App „Einstellungen“ und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen bei der Kompatibilität von Apps.

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

   **Hinweis**: Sie müssen eine debugfähige Build-Variante Ihrer App verwenden, um Änderungen zu aktivieren und zu deaktivieren.

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

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

  Diese Änderungen sind im Kompatibilitätsframework standardmäßig aktiviert und werden in der UI 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 Version von Android ausgerichtet sind, werden sie auch als Änderungen bezeichnet, die durch targetSDKVersion eingeschränkt sind.

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

  Hinweis: Während der Android 15-Vorabversion bis zur endgültigen Festlegung des API-Levels verwenden einige Änderungen, die nur aktiviert sind, wenn sie auf Android 15 ausgerichtet sind, den Wert 10000 für das API-Level anstelle des endgültigen, vermuteten API-Levels von 35.

In Abbildung 1 sehen Sie auch einen Abschnitt mit dem Titel Standardmäßig deaktivierte Änderungen. Änderungen in diesem Abschnitt können verschiedene Zwecke erfüllen. Bevor Sie diese Änderungen aktivieren, lesen Sie die Beschreibung der Änderung in der Kompatibilitäts framework-Liste für diese Android-Version.

Aktivierte Änderungen mit Logcat ermitteln

Bei jeder Verhaltensänderung gibt das System beim ersten Aufruf der betroffenen API durch Ihre App während des App-Prozesses eine Logcat-Meldung wie diese aus:

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

Hinweis: Jede Änderung wird maximal einmal pro Prozess protokolliert. Erzwingen Sie das Beenden und Neustarten des App-Prozesses, um sicherzustellen, dass alle relevanten Logcat-Meldungen angezeigt werden.

Jede Logcat-Meldung 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 Änderungen bei der Kompatibilität von Apps aufgeführt sind (siehe Abbildung 1). In diesem Beispiel entspricht 194833441 NOTIFICATION_PERM_CHANGE_ID.

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 wirkt sich nicht auf die App aus. Hinweis: Wenn diese Änderung deaktiviert ist, weil die targetSDKVersion der App unter dem erforderlichen Schwellenwert liegt, wird die Änderung standardmäßig aktiviert, wenn die App ihre targetSDKVersion erhöht, um auf eine höhere Version ausgerichtet zu sein.
LOGGED	Die Änderung wird über das Kompatibilitätsframework protokolliert, kann aber nicht aktiviert oder deaktiviert werden. Obwohl diese Änderung nicht aktiviert oder deaktiviert werden kann, kann sie sich dennoch auf das Verhalten Ihrer App auswirken. Weitere Informationen finden Sie in der Beschreibung der Änderung in der Liste des Kompatibilitätsframeworks für diese Android-Version. In vielen Fällen sind diese Arten von Änderungen experimentell und können ignoriert werden.

Aktivierte Änderungen mit ADB ermitteln

Führen Sie 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 ID für diese Verhaltensänderung. Beispiel: 194833441.

Name

Der Name dieser Verhaltensänderung. Beispiel: NOTIFICATION_PERM_CHANGE_ID.

Kriterien für targetSDKVersion

Durch welche targetSDKVersion die Änderung eingeschränkt ist (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 (aktiviert oder deaktiviert) überschrieben wurde.

Wenn es sich beispielsweise um eine Änderung handelt, die standardmäßig aktiviert ist, wird der Paketname Ihrer App aufgeführt, wenn Sie die Änderung entweder über die Entwickleroptionen oder ADB deaktiviert haben. In diesem Fall sieht die Ausgabe so aus:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion eingeschränkt sind, können standardmäßig aktiviert oder deaktiviert sein. Die Liste der Pakete kann also je nach targetSDKVersion der jeweiligen App sowohl true als auch false enthalten. Beispiel:

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

Weitere Informationen zu bestimmten Änderungen

Die vollständige Liste der Verhaltensänderungen im Kompatibilitätsframework ist als Teil 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 für:

• 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 oder deaktiviert werden sollten

Der Hauptzweck des Kompatibilitätsframeworks besteht darin, Ihnen Kontrolle und Flexibilität zu bieten, wenn Sie Ihre App mit neueren Android-Versionen testen. In diesem Abschnitt werden einige Strategien beschrieben, mit denen Sie festlegen können, wann Sie Änderungen aktivieren oder deaktivieren sollten, wenn Sie Ihre App testen und debuggen.

Wann Änderungen deaktiviert werden sollten

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

Änderungen, die für alle Apps aktiviert sind

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

Wenn Sie sich beispielsweise darauf vorbereiten, auf Android 16 (API-Level 36) auszurichten, können Sie Ihre App zuerst auf einem Gerät mit Android 16 installieren und sie mit Ihren üblichen Testabläufen testen. Wenn Probleme mit Ihrer App auftreten, können Sie die Änderung deaktivieren, die das Problem verursacht, damit Sie weiter nach anderen Problemen suchen können.

Da sich diese Änderungen unabhängig von targetSDKVersion auf alle Apps auswirken können, sollten Sie Ihre App in der Regel zuerst auf diese Änderungen testen und aktualisieren, bevor Sie Änderungen vornehmen, die durch targetSDKVersion eingeschränkt sind. So können Sie sicherstellen, dass die Nutzer beim Aktualisieren ihres Geräts auf eine neue Plattformversion keine schlechtere App-Erfahrung haben.

Sie sollten diese Änderungen auch vorrangig testen, da Sie sie bei Verwendung eines öffentlichen Release-Builds von Android nicht deaktivieren können. Idealerweise sollten Sie diese Änderungen für jede Version von Android testen, während sich diese Version in der Vorabversion befindet.

Änderungen, die durch targetSDKVersion eingeschränkt sind

Wenn Ihre App auf eine bestimmte targetSDKVersion, 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, ist Ihre App sofort von vielen neuen Änderungen betroffen.

Da Ihre App möglicherweise von mehr als einer dieser Änderungen betroffen ist, müssen Sie einige dieser Änderungen möglicherweise einzeln deaktivieren, wenn Sie Ihre App testen und debuggen.

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 darauf vorbereiten, auf eine neue targetSdkVersion auszurichten, haben Sie in der Regel eine Liste von Verhaltensänderungen, für die Sie Ihre App testen und debuggen müssen.

Möglicherweise testen Sie Ihre App beispielsweise im Hinblick auf eine Reihe von Plattformänderungen in der nächsten targetSdkVersion. Mit den Entwickleroptionen oder ADB-Befehlen können Sie jede eingeschränkte Änderung einzeln aktivieren und testen, anstatt das App-Manifest zu ändern und alle Änderungen gleichzeitig zu aktivieren. Diese zusätzliche Kontrolle kann Ihnen helfen, Änderungen isoliert zu testen und zu 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 Testabläufen testen und debuggen. Wenn Probleme auftreten, prüfen Sie die Logs, um die Ursache des Problems zu ermitteln. Wenn nicht klar ist, ob das Problem durch eine aktivierte Plattformänderung verursacht wird, deaktivieren Sie diese Änderung und testen Sie diesen Bereich Ihrer App noch einmal.

Änderungen aktivieren oder deaktivieren

Mit dem Kompatibilitätsframework können Sie 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.

Hinweis: Wenn Sie eine Änderung für eine App entweder über die Entwickleroptionen oder ADB-Befehle aktivieren oder deaktivieren, wird die App beendet, damit Ihre Überschreibung sofort wirksam wird.

Änderungen über die Entwickleroptionen aktivieren oder deaktivieren

Verwenden Sie die Entwickleroptionen, um Änderungen zu aktivieren oder zu deaktivieren. So rufen Sie die Entwickler optionen auf:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffnen Sie auf Ihrem Gerät die App „Einstellungen“ und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen bei der Kompatibilität von Apps.
3. Wählen Sie Ihre App in 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 oder deaktivieren

Führen Sie einen der folgenden Befehle aus, um eine Änderung mit ADB zu aktivieren oder zu deaktivieren:

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 den PACKAGE_NAME Ihrer App.

Mit dem folgenden Befehl können Sie eine Änderung auch auf den Standardstatus zurücksetzen und alle Überschreibungen entfernen, die Sie mit ADB oder den Entwickleroptionen festgelegt haben:

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Einschränkungen beim Aktivieren oder Deaktivieren von Änderungen

Standardmäßig ist jede Verhaltensänderung entweder aktiviert oder deaktiviert. Änderungen, die sich auf alle Apps auswirken, sind standardmäßig aktiviert. Andere Änderungen sind durch eine targetSdkVersion eingeschränkt. 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 niedrigere SDK-Version als die eingeschränkte Version ausgerichtet ist. Wenn Sie eine Änderung aktivieren oder deaktivieren, überschreiben Sie den Standardstatus.

Um zu verhindern, dass das Kompatibilitätsframework böswillig verwendet wird, gibt es einige Einschränkungen, wann Sie Änderungen aktivieren oder deaktivieren 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 oder deaktivieren dürfen:

Build-Typ	Nicht debugfähige App	Debugfähige App
	Alle Änderungen	Änderungen, die durch targetSDKVersion eingeschränkt sind	Alle anderen Änderungen
Entwicklervorschau oder Beta-Build	Kann nicht aktiviert oder deaktiviert werden	Kann aktiviert oder deaktiviert werden	Kann aktiviert oder deaktiviert werden
Build für öffentliche Nutzer	Kann nicht aktiviert oder deaktiviert werden	Kann aktiviert oder deaktiviert werden	Kann nicht aktiviert oder deaktiviert werden