Kompatibilitäts-Framework-Tools

Mit Android 11 wurden neue Entwicklertools eingeführt, mit denen du deine App im Hinblick auf Verhaltensänderungen in neueren Versionen der Android-Plattform testen und debuggen kannst. Diese Tools sind Teil eines Kompatibilitäts-Frameworks, mit dem App-Entwickler funktionsgefährdende Änderungen einzeln über Entwickleroptionen oder ADB aktivieren und deaktivieren können. Nutze diese Flexibilität, wenn du das Targeting auf die neueste stabile API-Version vornimmst und 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, sodass Sie targetSDKVersion nicht ändern oder Ihre App neu kompilieren müssen, um einfache Tests durchzuführen. Da Änderungen einzeln umschaltbar sind, können Sie eine Verhaltensänderung einzeln isolieren, testen und debuggen oder eine einzelne problematische Änderung deaktivieren, wenn Sie zuerst etwas anderes testen müssen.

Herausfinden, welche Änderungen aktiviert sind

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

Aktivierte Änderungen mithilfe von Entwickleroptionen identifizieren

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

In den Entwickleroptionen eines Geräts kannst du sehen, welche Änderungen aktiviert sind, und diese ein- oder ausschalten. 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 Einstellungen und rufen Sie System > Erweitert > Entwickleroptionen > Änderungen der App-Kompatibilität auf.

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

   Hinweis :Sie müssen eine Debug-fähige Build-Variante Ihrer App verwenden, um Änderungen ein- und auszuschalten.

Jede Verhaltensänderung gehört normalerweise zu einer der folgenden zwei Kategorien:

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

  Diese Änderungen sind standardmäßig im Kompatibilitäts-Framework aktiviert und 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 Android-Version ausgerichtet sind, werden sie auch als Änderungen bezeichnet, die durch targetSDKVersion gesteuert sind.

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

  Hinweis :Während der Android 15-Vorschau bis zur endgültigen Fertigstellung des API-Levels verwenden einige Änderungen, die nur aktiviert sind, wenn sie auf Android 15 ausgerichtet sind, den Wert 10000 für die API-Ebene anstelle des letztendlich angenommenen API-Levels 35.

Außerdem siehst du in Abbildung 1 einen Abschnitt namens Standardmäßig deaktivierte Änderungen. In diesem Abschnitt vorgenommene Änderungen können verschiedenen Zwecken dienen. Bevor Sie diese Änderungen aktivieren, lesen Sie die Beschreibung der Änderung in der Liste der Kompatibilitäts-Frameworks für diese Android-Version.

Aktivierte Änderungen mit Logcat identifizieren

Bei jeder Verhaltensänderung gibt das System bei jedem Aufruf der betroffenen API zum ersten Mal während eines Anwendungsprozesses eine Logcat-Nachricht wie die folgende aus:

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

Hinweis: Jede Änderung wird nur einmal pro Prozess protokolliert. Erzwingen Sie das Beenden der Anwendung und starten Sie sie neu, damit alle relevanten Logcat-Meldungen angezeigt werden.

Jede Logcat-Nachricht enthält die folgenden Informationen:

ID ändern

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

UID

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

Bundesland

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

Der Status kann einen der folgenden Werte haben:

Bundesland	Bedeutung
ENABLED	Die Änderung ist aktiviert und wirkt sich auf das Verhalten der Anwendung aus, wenn sie die geänderten APIs verwendet.
DISABLED	Die Änderung ist deaktiviert und wirkt sich nicht auf die Anwendung aus. Hinweis:Wenn diese Änderung deaktiviert ist, weil die targetSDKVersion der Anwendung unter dem erforderlichen Grenzwert liegt, wird die Änderung standardmäßig aktiviert, wenn die targetSDKVersion der Anwendung auf eine höhere Version erhöht wird.
LOGGED	Die Änderung wird über das Kompatibilitäts-Framework protokolliert, kann aber nicht aktiviert oder deaktiviert werden. Diese Änderung kann zwar nicht aktiviert oder deaktiviert werden, sie kann sich aber auf das Verhalten Ihrer Anwendung auswirken. Weitere Informationen findest du in der Beschreibung der Änderung in der Liste der 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 mithilfe von ADB identifizieren

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

Die Ausgabe enthält für jede Änderung die folgenden Informationen:

ID ändern

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

Name

Der Name dieser Verhaltensänderung. Beispiel: NOTIFICATION_PERM_CHANGE_ID.

targetSDKVersion-Kriterien

Von welchem targetSDKVersion die Änderung gesteuert wird (falls vorhanden).

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

Paketüberschreibungen

Der Name jedes Pakets, für das der Standardstatus (entweder 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 über die Entwickleroptionen oder über ADB deaktivieren. In diesem Fall sieht die Ausgabe so aus:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion gesteuert werden, können standardmäßig entweder aktiviert oder deaktiviert werden. Die Liste der Pakete kann daher Instanzen von true oder false enthalten, je nach targetSDKVersion dieser Anwendung. 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 finden Sie in der Dokumentation für jede Android-Version. Unter den folgenden Links findest du je nach Android-Version, für die du deine App testest, weitere Informationen:

• 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)

Zeitpunkt für das Wechseln zwischen Änderungen

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

Wann Änderungen deaktiviert werden sollten

Die Entscheidung, wann Änderungen deaktiviert werden sollen, hängt normalerweise davon ab, ob die Änderung durch targetSDKVersion blockiert wird oder nicht.

Änderungen für alle Apps aktiviert

Änderungen, die alle Anwendungen betreffen, sind standardmäßig für eine bestimmte Plattformversion aktiviert, unabhängig von der targetSDKVersion Ihrer Anwendung. So können Sie feststellen, ob Ihre Anwendung von der Ausführung der Anwendung auf dieser Plattformversion betroffen ist.

Wenn du deine App beispielsweise auf Android 14 (API-Level 34) ausrichten möchtest, kannst du sie zuerst auf einem Gerät mit Android 14 installieren und sie dann mit deinen üblichen Testworkflows testen. Wenn bei der Anwendung Probleme auftreten, können Sie die entsprechende Änderung deaktivieren, um den Test auf andere Probleme fortzusetzen.

Da sich diese Änderungen unabhängig von targetSDKVersion auf alle Anwendungen auswirken können, sollten Sie Ihre Anwendung normalerweise auf diese Änderungen testen und aktualisieren, bevor Änderungen durch targetSDKVersion blockiert werden. So wird dafür gesorgt, dass die App-Nutzung Ihrer Nutzer nicht beeinträchtigt wird, wenn sie ihr Gerät auf eine neue Plattformversion aktualisieren.

Du solltest auch das Testen dieser Änderungen priorisieren, da sie bei Verwendung eines öffentlichen Release-Builds von Android nicht deaktiviert werden können. Idealerweise solltest du diese Änderungen für jede Android-Version testen, während sich diese Version in der Vorabversion befindet.

Änderungen durch targetSDKVersion

Wenn Ihre App auf eine bestimmte targetSDKVersion ausgerichtet ist, sind alle Änderungen, die durch diese Version gesteuert werden, standardmäßig aktiviert. Wenn du also die targetSDKVersion deiner App auf eine neue Version umstellst, wird sie von vielen neuen Änderungen gleichzeitig betroffen sein.

Da Ihre Anwendung von mehr als einer dieser Änderungen betroffen sein kann, müssen Sie einige dieser Änderungen beim Testen und Debuggen der Anwendung möglicherweise einzeln deaktivieren.

Wann Änderungen aktiviert werden sollten

Änderungen, die durch eine bestimmte targetSDKVersion gesteuert werden, werden standardmäßig deaktiviert, wenn eine App auf eine niedrigere SDK-Version als die Gated-Version ausgerichtet ist. Wenn Sie sich auf eine neue targetSdkVersion vorbereiten, erhalten Sie in der Regel eine Liste der Verhaltensänderungen, für die Sie Ihre Anwendung testen und debuggen müssen.

Du kannst beispielsweise deine App im nächsten targetSdkVersion mit einer Reihe von Plattformänderungen testen. Mithilfe von Entwickleroptionen oder ADB-Befehlen können Sie jede gate-gesteuerte Änderung einzeln aktivieren und testen, anstatt Ihr App-Manifest zu ändern und für jede Änderung auf einmal zu aktivieren. Mit dieser zusätzlichen Kontrolle können Sie Änderungen isoliert testen und vermeiden, Fehler an mehreren Teilen Ihrer Anwendung gleichzeitig zu beheben und diese zu aktualisieren.

Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre Anwendung mit Ihren üblichen Testworkflows testen und debuggen. Falls Probleme auftreten, sehen Sie sich die Logs an, 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 Anwendung noch einmal.

Änderungen aktivieren oder deaktivieren

Mit dem Kompatibilitäts-Framework kannst du jede Änderung mithilfe der 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, gibt es einige Einschränkungen dafür, wann Sie Änderungen umschalten können.

Hinweis :Wenn Sie eine Änderung für eine App mithilfe der Entwickleroptionen oder ADB-Befehle umschalten, wird die App beendet, damit die Überschreibung sofort wirksam wird.

Änderungen mit den Entwickleroptionen ein-/ausschalten

Verwenden Sie die Entwickleroptionen, um Änderungen zu aktivieren oder zu deaktivieren. So finden Sie 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 nach der Änderung, die Sie aktivieren oder deaktivieren möchten, und tippen Sie auf den Schalter.

   

Änderungen mit ADB aktivieren/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 das CHANGE_ID (z. B. 194833441) oder das CHANGE_NAME (z. B. NOTIFICATION_PERM_CHANGE_ID) und das PACKAGE_NAME Ihrer Anwendung.

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

adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME

Einschränkungen beim Wechseln von Änderungen

Standardmäßig ist jede Verhaltensänderung entweder aktiviert oder deaktiviert. Änderungen, die alle Apps betreffen, sind standardmäßig aktiviert. Andere Änderungen werden durch ein targetSdkVersion gesteuert. Diese Änderungen sind standardmäßig aktiviert, wenn eine App auf die entsprechende oder eine höhere SDK-Version ausgerichtet ist, und standardmäßig deaktiviert, wenn eine App auf eine SDK-Version ausgerichtet ist, die niedriger ist als die Gated-Version. Wenn Sie eine Änderung aktivieren oder deaktivieren, wird deren Standardstatus überschrieben.

Um zu verhindern, dass das Kompatibilitäts-Framework böswillig verwendet wird, gibt es einige Einschränkungen dafür, wann Änderungen übernommen werden können. Ob Sie eine Änderung aktivieren oder deaktivieren können, hängt von der Art der Änderung, davon ab, ob Ihre App Debug-fähig ist und welchen Build-Typ auf Ihrem Gerät ausgeführt wird. In der folgenden Tabelle wird beschrieben, wann Sie zwischen verschiedenen Änderungsarten wechseln können:

Build-Typ	Nicht Debug-fähige App	Debug-fähige Anwendung
	Alle Änderungen	Durch targetSDKVersion geschützte Änderungen	Alle anderen Änderungen
Entwicklervorschau oder Beta-Build	Deaktivieren nicht möglich	Kann ein- und ausgeblendet werden	Kann ein- und ausgeblendet werden
Öffentlicher Nutzer-Build	Deaktivieren nicht möglich	Kann ein- und ausgeblendet werden	Deaktivieren nicht möglich