Mit Android 11 wurden neue Entwicklertools zum Testen und Debuggen deiner App an das veränderte Verhalten in neueren Versionen der Android-Plattform eingeführt. Diese Tools sind Teil eines Kompatibilitäts-Frameworks, mit dem App-Entwickler funktionsgefährdende Änderungen mithilfe von Entwickleroptionen oder ADB einzeln aktivieren und deaktivieren können. Nutzen Sie diese Flexibilität, wenn Sie sich darauf vorbereiten, auf die neueste stabile API-Version auszurichten und Ihre App mit dem Vorabrelease der nächsten Android-Version zu testen.
Wenn du die Kompatibilitäts-Framework-Tools verwendest, passt die Android-Plattform automatisch die interne Logik an. Du musst targetSDKVersion
also nicht ändern und deine App nicht neu kompilieren, um einfache Tests durchzuführen. Da Änderungen einzeln umschaltbar sind, können Sie jeweils nur eine Verhaltensänderung 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 sie sich darauf auswirken, wie Ihre Anwendung auf die von dieser Änderung betroffenen Plattform-APIs zugreift. Mit den Entwickleroptionen, Logcat- oder ADB-Befehlen können Sie prüfen, welche Verhaltensänderungen aktiviert sind.
Aktivierte Änderungen mithilfe von Entwickleroptionen ermitteln
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:
- Aktivieren Sie die Entwickleroptionen.
- Öffnen Sie auf Ihrem Gerät die Einstellungen und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen an der App-Kompatibilität.
Wählen Sie Ihre App aus der Liste aus.
Jede Verhaltensänderung gehört normalerweise einer der folgenden zwei Kategorien an:
Änderungen, die alle Apps betreffen, die unter dieser Android-Version ausgeführt werden, unabhängig von der
targetSdkVersion
der App.Diese Änderungen sind im Kompatibilitäts-Framework standardmäßig aktiviert und werden in der Benutzeroberfläche im Bereich Standardmäßig aktivierte Änderungen aufgeführt.
Änderungen, die nur Apps betreffen, die auf bestimmte Android-Versionen ausgerichtet sind. Da diese Änderungen nur Apps betreffen, die auf eine bestimmte Android-Version ausgerichtet sind, werden sie auch als Änderungen bezeichnet, die durch
targetSDKVersion
gesteuert werden.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. Beispielsweise wird eine Verhaltensänderung, die durch
targetSDKVersion
in Android 13 (API-Level 33) beschränkt ist, in der UI im Abschnitt Aktiviert für targetSdkVersion >=33 aufgeführt. Bei einigen niedrigeren Android-Versionen heißt dieser Abschnitt stattdessen „Aktiviert nach SDK API_LEVEL“.
Außerdem sehen Sie in Abbildung 1 den Abschnitt Standardmäßig deaktivierte Änderungen. Die in diesen Abschnitt fallenden Änderungen können einer Vielzahl von Zwecken dienen. Bevor Sie diese Änderungen aktivieren, sollten Sie die Änderungsbeschreibung in der Liste des Kompatibilitäts-Frameworks für diese Android-Version lesen.
Aktivierte Änderungen mit Logcat ermitteln
Bei jeder Verhaltensänderung gibt das System beim ersten Aufruf des Prozesses Ihrer Anwendung, wenn die Anwendung die betroffene API aufruft, 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:
- ID ändern
- Gibt an, welche Änderung die App betrifft. Dieser Wert ist einer der Verhaltensänderungen zugeordnet, die auf dem Bildschirm App-Kompatibilitätsänderungen 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 einer der folgenden Werte sein:
Bundesland Bedeutung ENABLED
Die Änderung ist aktiviert und wirkt sich auf das Verhalten der Anwendung aus, wenn die Anwendung 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 Anwendung unter dem erforderlichen Grenzwert liegt, wird die Änderung standardmäßig aktiviert, wenn die AnwendungtargetSDKVersion
auf eine höhere Version erhöht.LOGGED
Die Änderung wird über das Kompatibilitäts-Framework protokolliert, kann aber nicht aktiviert oder deaktiviert werden. Auch wenn sich diese Änderung nicht aktivieren oder deaktivieren lässt, kann sie sich dennoch auf das Verhalten Ihrer App auswirken. Weitere Informationen finden Sie in der Beschreibung der Änderung in der Liste der Kompatibilitäts-Frameworks für die jeweilige Android-Version. In vielen Fällen sind diese Arten von Änderungen experimentell und können ignoriert werden.
Aktivierte Änderungen mit ADB identifizieren
Führen Sie den folgenden ADB-Befehl aus, um alle Änderungen (sowohl aktivierte als auch deaktivierte) auf dem gesamten Gerät zu sehen:
adb shell dumpsys platform_compat
Die Ausgabe enthält zu jeder Änderung die folgenden Informationen:
- ID ändern
- Eine eindeutige Kennung für diese Verhaltensänderung. z. B.
194833441
. - Name
- Der Name dieser Verhaltensänderung. z. B.
NOTIFICATION_PERM_CHANGE_ID
. - targetSDKVersion-Kriterien
Über welche
targetSDKVersion
die Änderung gesteuert wird (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 durchtargetSDKVersion
gesteuert wird, wirdenableAfterTargetSdk=0
ausgegeben.- Paketüberschreibungen
Der Name jedes Pakets, bei dem der Standardstatus der Änderung (entweder aktiviert oder deaktiviert) überschrieben wurde.
Wenn diese Änderung beispielsweise standardmäßig aktiviert ist, wird der Paketname Ihrer Anwendung aufgeführt, wenn Sie die Änderung mit den Entwickleroptionen oder mit ADB deaktiviert haben. In diesem Fall sieht die Ausgabe so aus:
packageOverrides={com.my.package=false}
Änderungen, die durch
targetSDKVersion
beschränkt sind, können standardmäßig entweder aktiviert oder deaktiviert werden. Die Liste der Pakete kann also je nachtargetSDKVersion
der jeweiligen Anwendung Instanzen vontrue
oderfalse
enthalten. Beispiel:packageOverrides={com.my.package=true, com.another.package=false}
Weitere Informationen zu bestimmten Änderungen
Eine vollständige Liste der Verhaltensänderungen im Kompatibilitäts-Framework finden Sie in der Dokumentation für jede Android-Version. Weitere Informationen finden Sie unter den folgenden Links, je nachdem, für welche Android-Version Sie Ihre App testen:
- Android 15 (Beta)
- 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 geben. In diesem Abschnitt werden einige Strategien beschrieben, mit denen Sie festlegen können, wann Sie Änderungen beim Testen und Debuggen Ihrer Anwendung aktivieren oder deaktivieren sollten.
Wann die Änderungen deaktiviert werden sollen
Ob die Änderungen deaktiviert werden, hängt in der Regel davon ab, ob die Änderung durch targetSDKVersion
gesteuert wird oder nicht.
- Änderungen für alle Apps aktiviert
Änderungen, die alle Anwendungen betreffen, werden unabhängig von der
targetSDKVersion
der Anwendung standardmäßig für eine bestimmte Plattformversion aktiviert. So können Sie sehen, ob Ihre Anwendung davon betroffen ist, wenn sie auf dieser Plattformversion ausgeführt wird.Wenn du dich beispielsweise auf Android 14 (API-Level 34) vorbereiten möchtest, kannst du deine App zuerst auf einem Gerät mit Android 14 installieren und dann mit deinen üblichen Testworkflows testen. Wenn bei Ihrer App Probleme auftreten, können Sie die Änderung deaktivieren, die das Problem verursacht, und so weiter auf andere Probleme testen.
Da sich diese Änderungen unabhängig von
targetSDKVersion
auf alle Anwendungen auswirken können, sollten Sie Ihre Anwendung normalerweise vor Änderungen testen und aktualisieren, die durchtargetSDKVersion
beschränkt sind. Dadurch wird sichergestellt, dass die App-Nutzung nicht beeinträchtigt wird, wenn sie ihr Gerät auf eine neue Plattformversion aktualisieren.Du solltest diese Änderungen auch priorisieren, da du diese Änderungen beim Verwenden eines öffentlichen Release-Builds von Android nicht deaktivieren kannst. Idealerweise sollten Sie diese Änderungen für jede Android-Version testen, solange sich diese Version noch in der Vorabversion befindet.
- Änderungen durch
targetSDKVersion
beschränkt Wenn deine App auf eine bestimmte
targetSDKVersion
ausgerichtet ist, sind alle Änderungen, die durch diese Version beschränkt sind, standardmäßig aktiviert. Wenn Sie also dastargetSDKVersion
Ihrer Anwendung auf eine neue Version umstellen, wird Ihre Anwendung von vielen neuen Änderungen gleichzeitig betroffen sein.Da Ihre Anwendung von mehr als einer dieser Änderungen betroffen sein könnte, müssen Sie einige dieser Änderungen möglicherweise beim Testen und Debuggen der Anwendung einzeln deaktivieren.
Wann Änderungen aktiviert werden sollten
Änderungen, die durch eine bestimmte targetSDKVersion
beschränkt sind, werden standardmäßig deaktiviert, wenn eine App auf eine niedrigere SDK-Version als die beschränkte Version abzielt.
Wenn Sie sich auf ein neues targetSdkVersion
-Ziel vorbereiten, erhalten Sie in der Regel eine Liste mit Verhaltensänderungen, mit denen Sie Ihre Anwendung testen und debuggen müssen.
Beispiel: Sie testen Ihre Anwendung im nächsten targetSdkVersion
anhand einer Reihe von Plattformänderungen. Mit Entwickleroptionen oder ADB-Befehlen können Sie jede Gated Änderung einzeln aktivieren und testen, anstatt Ihr App-Manifest zu ändern und jede Änderung auf einmal zu aktivieren. Mit dieser zusätzlichen Kontrolle können Sie Änderungen isoliert testen und vermeiden, Fehler in mehreren Teilen Ihrer Anwendung gleichzeitig zu beheben und zu aktualisieren.
Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre Anwendung mit den ü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, deaktivieren Sie diese Änderung und testen Sie dann den entsprechenden Bereich Ihrer Anwendung noch einmal.
Änderungen aktivieren oder deaktivieren
Mit dem Kompatibilitäts-Framework 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.
Änderungen über die Entwickleroptionen ein-/ausschalten
In den Entwickleroptionen können Sie Änderungen aktivieren oder deaktivieren. So finden Sie die Entwickleroptionen:
- Aktivieren Sie die Entwickleroptionen.
- Öffnen Sie die Einstellungen Ihres Geräts und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen an 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 ein-/ausschalten
Führen Sie einen der folgenden Befehle aus, um eine Änderung mithilfe von 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 CHANGE_ID
(z. B. 194833441
) oder CHANGE_NAME
(z. B. NOTIFICATION_PERM_CHANGE_ID
) und die PACKAGE_NAME
Ihrer Anwendung.
Sie können auch den folgenden Befehl verwenden, um eine Änderung auf den Standardzustand zurückzusetzen. Dabei wird jede Überschreibung entfernt, die Sie mit ADB oder den Entwickleroptionen festgelegt haben:
adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
Einschränkungen beim Umschalten von Änderungen
Standardmäßig ist jede Verhaltensänderung entweder aktiviert oder deaktiviert. Änderungen, die alle Anwendungen betreffen, sind standardmäßig aktiviert. Andere Änderungen sind durch targetSdkVersion
gesteuert. Diese Änderungen sind standardmäßig aktiviert, wenn eine App auf die entsprechende SDK-Version oder höher abzielt, und deaktiviert, wenn eine App auf eine niedrigere SDK-Version als die beschränkte Version ausgerichtet ist. Wenn Sie eine Änderung aktivieren oder deaktivieren, wird der Standardstatus überschrieben.
Damit das Kompatibilitäts-Framework nicht böswillig verwendet wird, gibt es einige Einschränkungen dafür, 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 ab, ob Ihre App Debug-fähig ist und vom Build-Typ, 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 | Debug-fähige App | |
---|---|---|---|
Alle Änderungen | Durch targetSDKVersion beschränkte Änderungen | Alle anderen Änderungen | |
Entwicklervorschau oder Beta-Build | Umschalten nicht möglich | Umschalten | Umschalten |
Öffentlicher Nutzer-Build | Umschalten nicht möglich | Umschalten | Umschalten nicht möglich |