Kompatibilitäts-Framework-Tools

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

Abbildung 1: Bildschirm mit den Kompatibilitätsänderungen der App 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. Aktivieren Sie die Entwickleroptionen.
2. Öffnen Sie auf Ihrem Gerät die Einstellungen und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen an der App-Kompatibilität.

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

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

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“.

  Hinweis :Während der Android 15-Vorschau bis zum endgültigen API-Level wird bei einigen Änderungen, die nur bei Ausrichtung auf Android 15 aktiviert werden, der Wert 10000 für das API-Level und nicht das letztendlich vermutete API-Level 35 verwendet.

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

Hinweis: Jede Änderung wird nur einmal pro Prozess protokolliert. Erzwingen Sie das Beenden und Neustarten des Prozesses Ihrer Anwendung, damit alle relevanten Logcat-Nachrichten angezeigt werden.

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 Anwendung targetSDKVersion 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 durch targetSDKVersion gesteuert wird, wird enableAfterTargetSdk=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 nach targetSDKVersion der jeweiligen Anwendung Instanzen von true oder false 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 durch targetSDKVersion 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 das targetSDKVersion 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.

Hinweis: Wenn Sie mit den Entwickleroptionen oder ADB-Befehlen eine Änderung an einer App umschalten, wird die App beendet, damit die Überschreibung sofort wirksam wird.

Änderungen über die Entwickleroptionen ein-/ausschalten

In den Entwickleroptionen können Sie Änderungen aktivieren oder deaktivieren. So finden Sie die Entwickleroptionen:

1. Aktivieren Sie die Entwickleroptionen.
2. Öffnen Sie die Einstellungen Ihres Geräts und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen an 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 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