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
![](https://developer.android.com/static/images/guide/app-compatibility/appcompat-dev-options.png?authuser=6&hl=de)
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:
- Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
- Öffnen Sie auf Ihrem Gerät die Einstellungen und rufen Sie System > Erweitert > Entwickleroptionen > Änderungen der App-Kompatibilität auf.
Wählen Sie Ihre App aus der Liste aus.
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“.
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
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 dietargetSDKVersion
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 durchtargetSDKVersion
definiert ist, wirdenableAfterTargetSdk=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 vontrue
oderfalse
enthalten, je nachtargetSDKVersion
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 durchtargetSDKVersion
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 dietargetSDKVersion
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.
Änderungen mit den Entwickleroptionen ein-/ausschalten
Verwenden Sie die Entwickleroptionen, um Änderungen zu aktivieren oder zu deaktivieren. So finden Sie die Entwickleroptionen:
- Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
- Öffne auf deinem Gerät die Einstellungen und gehe zu System > Erweitert > Entwickleroptionen > Änderungen der App-Kompatibilität.
- Wählen Sie Ihre App aus der Liste aus.
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 |