Tools für das Kompatibilitäts-Framework

Mit Android 11 wurden neue Entwicklertools zum Testen und Debuggen Ihrer App im Hinblick auf die Verhaltensänderungen in neueren Versionen der Android-Plattform eingeführt. Diese Tools sind Teil eines Kompatibilitäts-Frameworks, mit dem App-Entwickler mithilfe von Entwickleroptionen oder ADB Breaking Changes einzeln aktivieren und deaktivieren können. Nutzen Sie diese Flexibilität, wenn Sie sich darauf vorbereiten, die aktuelle stabile API-Version als Ziel zu verwenden, 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 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.

So finden Sie heraus, welche Änderungen aktiviert sind

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

Aktivierte Änderungen über die Entwickleroptionen ermitteln

Abbildung 1: „Änderungen 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 Einstellungen und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen bei der App-Kompatibilität.

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

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

• Änderungen, die sich auf alle Apps auswirken, die auf dieser Android-Version ausgeführt werden, unabhängig vom 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 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 eingeschränkt 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. Eine Verhaltensänderung, die in Android 13 (API-Level 33) durch targetSDKVersion gesteuert wird, wird in der Benutzeroberfläche beispielsweise im Abschnitt Aktiviert für targetSdkVersion >=33 aufgeführt. In einigen älteren Android-Versionen heißt dieser Abschnitt stattdessen „Aktiviert nach SDK API_LEVEL“.

In Abbildung 1 sehen Sie auch den Abschnitt Standardmäßig deaktivierte Änderungen. Änderungen, die in diesen Abschnitt fallen, können verschiedene Zwecke haben. Bevor Sie diese Änderungen aktivieren, lesen Sie die Änderungsbeschreibung in der Liste der Kompatibilitäts-Frameworks für die entsprechende Android-Version.

Aktivierte Änderungen mit Logcat identifizieren

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 die folgende aus:

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

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 der App-Kompatibilität aufgeführt sind (siehe Abbildung 1). In diesem Beispiel wird 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 annehmen:

Bundesland	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 targetSDKVersion der App auf eine höhere Version aktualisiert wird.
LOGGED	Die Änderung wird über das Kompatibilitäts-Framework 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 der Kompatibilitäts-Frameworks für diese Android-Version. In vielen Fällen sind diese Änderungen experimentell und können ignoriert werden.

Aktivierte Änderungen mit 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

In der Ausgabe werden für jede Änderung die folgenden Informationen aufgeführt:

Änderungs-ID

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

Name

Der Name dieser Verhaltensänderung. Beispiel: NOTIFICATION_PERM_CHANGE_ID.

Kriterien für targetSDKVersion

Von welcher targetSDKVersion die Änderung abhängt (falls zutreffend).

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, in dem der Standardstatus der Änderung (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 ADB deaktiviert haben. In diesem Fall wäre die Ausgabe:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion gesteuert werden, können standardmäßig aktiviert oder deaktiviert sein. Die Liste der Pakete kann also je nach targetSDKVersion der jeweiligen App Instanzen von true oder 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äts-Framework ist in 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:

• 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 ein- und ausgeschaltet werden sollten

Das Kompatibilitäts-Framework soll Ihnen die Möglichkeit geben, Ihre App mit neueren Android-Versionen zu testen. In diesem Abschnitt werden einige Strategien beschrieben, mit denen Sie festlegen können, wann Änderungen beim Testen und Debuggen Ihrer App aktiviert oder deaktiviert werden sollen.

Wann Änderungen deaktiviert werden sollten

Wann Ä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 sich auf alle Apps auswirken, sind für eine bestimmte Plattformversion standardmäßig aktiviert, unabhängig von der targetSDKVersion Ihrer App. Sie können also sehen, ob Ihre App betroffen ist, indem Sie sie auf dieser Plattformversion ausführen.

Wenn Sie beispielsweise planen, Android 16 (API-Level 36) als Zielplattform festzulegen, können Sie Ihre App auf einem Gerät mit Android 16 installieren und sie mit Ihren üblichen Testabläufen testen. Wenn bei Ihrer App Probleme auftreten, können Sie die Änderung, die das Problem verursacht, deaktivieren, damit Sie mit dem Testen auf andere Probleme fortfahren können.

Da sich diese Änderungen unabhängig von targetSDKVersion auf alle Apps auswirken können, sollten Sie Ihre App in der Regel vor Änderungen, die durch targetSDKVersion eingeschränkt werden, testen und aktualisieren. So wird sichergestellt, dass die Nutzer Ihrer App nach dem Aktualisieren ihres Geräts auf eine neue Plattformversion keine Beeinträchtigung der App-Nutzung erfahren.

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

Änderungen, die von targetSDKVersion abhängig sind

Wenn Ihre App auf eine bestimmte targetSDKVersion ausgerichtet ist, sind alle Änderungen, die durch diese Version eingeschränkt werden, 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, während Sie Ihre App testen und Fehler beheben.

Wann Änderungen aktiviert werden sollten

Änderungen, die durch ein bestimmtes targetSDKVersion eingeschränkt werden, sind standardmäßig deaktiviert, wenn eine App auf eine niedrigere SDK-Version als die eingeschränkte Version ausgerichtet ist. Wenn Sie auf eine neue targetSdkVersion abzielen, haben Sie in der Regel eine Liste mit Verhaltensänderungen, für die Sie Ihre App testen und debuggen müssen.

Sie testen Ihre App beispielsweise im Hinblick auf eine Reihe von Plattformänderungen in den nächsten targetSdkVersion. Mit Entwickleroptionen oder ADB-Befehlen können Sie jede eingeschränkte Änderung einzeln aktivieren und testen, anstatt Ihr App-Manifest zu ändern und alle Änderungen auf einmal zu aktivieren. So können Sie Änderungen isoliert testen und müssen nicht mehrere Teile Ihrer App gleichzeitig debuggen und aktualisieren.

Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre App mit Ihren üblichen Test-Workflows testen und debuggen. Wenn Probleme auftreten, können Sie in den Logs nachsehen, um die Ursache des Problems zu ermitteln. Wenn nicht klar ist, ob das Problem durch eine aktivierte Plattformänderung verursacht wird, deaktiviere die Änderung und teste den entsprechenden Bereich deiner App 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 Ein- oder Ausschalten von Änderungen dazu führen kann, dass Ihre App abstürzt oder wichtige Sicherheitsänderungen deaktiviert werden, gibt es einige Einschränkungen für das Ein- und Ausschalten von Änderungen.

Änderungen über die Entwickleroptionen ein- und ausschalten

Mit den Entwickleroptionen können Sie Änderungen aktivieren oder deaktivieren. So rufen Sie die Entwickleroptionen auf:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffnen Sie auf Ihrem Gerät die Einstellungen und gehen Sie zu System > Erweitert > Entwickleroptionen > Änderungen bei 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 festlegen

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 CHANGE_ID (z. B. 194833441) oder CHANGE_NAME (z. B. NOTIFICATION_PERM_CHANGE_ID) und PACKAGE_NAME Ihrer App.

Sie können auch den folgenden Befehl verwenden, um eine Änderung auf den Standardzustand zurückzusetzen und alle Überschreibungen zu entfernen, 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 sich auf alle Apps auswirken, sind standardmäßig aktiviert. Andere Änderungen sind durch eine targetSdkVersion geschützt. 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 SDK-Version ausgerichtet ist, die niedriger als die eingeschränkte Version ist. Wenn Sie eine Änderung aktivieren oder deaktivieren, überschreiben Sie den Standardstatus.

Damit das Kompatibilitäts-Framework nicht missbräuchlich verwendet werden kann, gibt es einige Einschränkungen, wann Sie Änderungen umschalten können. Ob Sie eine Änderung ein- oder ausschalten können, hängt vom Typ der Änderung, davon, ob Ihre App debuggable 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 ein- oder ausschalten dürfen: