Tools für das Kompatibilitäts-Framework

Mit Android 11 wurden neue Entwicklertools eingeführt, mit denen Sie Ihre App auf Verhaltensänderungen in neueren Versionen der Android-Plattform testen und beheben können. Diese Tools sind Teil eines Kompatibilitäts-Frameworks, mit dem App-Entwickler bahnbrechende Änderungen mithilfe von Entwickleroptionen oder ADB einzeln aktivieren und deaktivieren können. Nutzen Sie diese Flexibilität, wenn Sie sich darauf vorbereiten, Ihre App auf die neueste stabile API-Version auszurichten und Ihre App mit der Vorabversion der nächsten Android-Version zu testen.

Wenn Sie die Tools des Compatibility Framework verwenden, passt die Android-Plattform ihre interne Logik automatisch an. Sie müssen also weder Ihre targetSDKVersion ändern noch Ihre App neu kompilieren, um grundlegende Tests durchzuführen. Da Änderungen einzeln aktiviert und deaktiviert werden können, können Sie einzelne Verhaltensänderungen isolieren, testen und beheben oder eine einzelne Änderung deaktivieren, die Probleme verursacht, wenn Sie zuerst etwas anderes testen müssen.

So erkennen Sie, welche Änderungen aktiviert sind

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

Aktivierte Änderungen mithilfe der Entwickleroptionen ermitteln

Abbildung 1. Bildschirm „Änderungen der Kompatibilität von Apps“ in den Entwickleroptionen

In den Entwickleroptionen eines Geräts können Sie sehen, welche Änderungen aktiviert sind, und sie aktivieren oder deaktivieren. So greifen Sie auf diese Optionen zu:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
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.

   Hinweis: Sie müssen eine debuggbare Buildvariante Ihrer App verwenden, um Änderungen zu aktivieren und zu deaktivieren.

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 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 sich diese Änderungen nur auf Apps auswirken, die auf eine bestimmte Android-Version ausgerichtet sind, werden sie auch als Änderungen bezeichnet, die von 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 eingeschränkt ist, wird beispielsweise in der Benutzeroberfläche im Abschnitt Aktiviert für targetSdkVersion >=33 aufgeführt. In einigen niedrigeren Android-Versionen lautet der Titel dieses Abschnitts stattdessen „Nach SDK API_LEVEL aktiviert“.

  Hinweis :Während der Android 15-Vorabversion und bis zur endgültigen Festlegung der API-Ebene wird für einige Änderungen, die nur bei Ausrichtung auf Android 15 aktiviert sind, der Wert 10000 für die API-Ebene verwendet, anstatt der endgültigen, vermuteten API-Ebene 35.

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

Aktivierte Änderungen mit logcat ermitteln

Bei jeder Verhaltensänderung gibt das System beim ersten Aufruf der betroffenen API während des App-Prozesses eine Logcat-Meldung wie diese aus:

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

Hinweis :Jede Änderung wird pro Prozess höchstens einmal protokolliert. Beenden Sie den Prozess Ihrer App und starten Sie ihn neu, damit alle relevanten Logcat-Nachrichten angezeigt werden.

Jede Logcat-Nachricht enthält die folgenden Informationen:

ID ändern

Gibt an, welche Änderung sich auf die App auswirkt. Dieser Wert entspricht einer der Verhaltensänderungen, die auf dem Bildschirm Änderungen an der App-Kompatibilität aufgeführt sind (siehe Abbildung 1). In diesem Beispiel wird 194833441 zu 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 App aus, wenn die App 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 App unter dem erforderlichen Grenzwert liegt, wird sie standardmäßig aktiviert, wenn die App ihre targetSDKVersion erhöht, um eine höhere Version anzusteuern.
LOGGED	Die Änderung wird über das Kompatibilitäts-Framework protokolliert, kann aber nicht aktiviert oder deaktiviert werden. Auch wenn 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 Arten von Änderungen experimentell und können ignoriert werden.

Aktivierte Änderungen mit ADB ermitteln

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

Kriterien für „targetSDKVersion“

Die targetSDKVersion, die die Änderung steuert (falls zutreffend).

Wenn diese Änderung beispielsweise nur für Apps aktiviert ist, die auf die 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 es sich beispielsweise um eine standardmäßig aktivierte Änderung handelt, wird der Paketname Ihrer App aufgeführt, wenn Sie die Änderung entweder über die Entwickleroptionen oder ADB deaktiviert haben. In diesem Fall würde die Ausgabe so aussehen:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion gesteuert werden, können standardmäßig aktiviert oder deaktiviert werden. Die Liste der Pakete kann daher sowohl Instanzen von true als auch von false enthalten, je nach targetSDKVersion der jeweiligen App. 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 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 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 aktiviert werden

Der Hauptzweck des Kompatibilitäts-Frameworks besteht darin, Ihnen mehr Kontrolle und Flexibilität beim Testen Ihrer 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 Entwickeln Ihrer App aktivieren oder deaktivieren.

Änderungen deaktivieren

Ob Änderungen deaktiviert werden sollten, hängt in der Regel davon ab, ob die Änderung von targetSDKVersion gesteuert wird oder nicht.

Änderungen für alle Apps aktiviert

Änderungen, die sich auf alle Apps auswirken, werden für eine bestimmte Plattformversion standardmäßig aktiviert, unabhängig von der targetSDKVersion Ihrer App. So können Sie sehen, ob Ihre App davon betroffen ist, wenn Sie sie auf dieser Plattformversion ausführen.

Wenn Sie beispielsweise eine App für Android 15 (API-Level 35) entwickeln, können Sie damit beginnen, Ihre App auf einem Gerät mit Android 15 zu installieren und sie mit Ihren üblichen Testabläufen zu testen. Wenn bei Ihrer App Probleme auftreten, können Sie die Änderung deaktivieren, die das Problem verursacht, und so weiter nach anderen Problemen suchen.

Da sich diese Änderungen unabhängig von targetSDKVersion auf alle Apps auswirken können, sollten Sie Ihre App in der Regel vor Änderungen testen und aktualisieren, die von targetSDKVersion abhängig sind. So wird sichergestellt, dass die App auch dann ordnungsgemäß funktioniert, wenn Nutzer ihr Gerät auf eine neue Plattformversion aktualisieren.

Sie sollten diese Änderungen auch priorisieren, da sie bei Verwendung eines öffentlichen Release-Builds von Android nicht deaktiviert werden können. Idealerweise sollten Sie diese Änderungen für jede Version von Android testen, während diese Version in der Vorabversion verfügbar ist.

Änderungen, die von targetSDKVersion abhängig sind

Wenn Ihre App auf eine bestimmte targetSDKVersion ausgerichtet ist, sind alle Änderungen, die von dieser Version abhängig sind, standardmäßig aktiviert. Wenn Sie also die targetSDKVersion Ihrer App auf eine neue Version umstellen, werden viele neue Änderungen gleichzeitig auf Ihre App angewendet.

Da Ihre App möglicherweise von mehreren dieser Änderungen betroffen ist, müssen Sie möglicherweise einige dieser Änderungen beim Testen und Entfernen von Fehlern in Ihrer App einzeln deaktivieren.

Wann Änderungen aktiviert werden

Änderungen, die durch eine bestimmte targetSDKVersion eingeschränkt sind, werden standardmäßig deaktiviert, wenn eine App auf eine niedrigere SDK-Version ausgerichtet ist als die eingeschränkte Version. Wenn Sie sich darauf vorbereiten, Ihre App auf eine neue targetSdkVersion auszurichten, haben Sie in der Regel eine Liste mit Verhaltensänderungen, die Sie testen und beheben müssen.

Beispielsweise testen Sie Ihre App im nächsten targetSdkVersion auf eine Reihe von Plattformänderungen. Mithilfe von Entwickleroptionen oder ADB-Befehlen können Sie jede vorab genehmigte Änderung einzeln aktivieren und testen, anstatt das App-Manifest zu ändern und alle Änderungen gleichzeitig zu aktivieren. Mit dieser zusätzlichen Funktion können Sie Änderungen einzeln testen und vermeiden, dass mehrere Teile Ihrer App gleichzeitig debuggt und aktualisiert werden.

Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre App mit Ihren üblichen Testabläufen testen und debuggen. Wenn Probleme auftreten, sehen Sie in den Protokollen nach, um die Ursache zu ermitteln. Wenn nicht klar ist, ob das Problem durch eine aktivierte Plattformänderung verursacht wird, deaktivieren Sie diese Änderung und testen Sie den Bereich Ihrer App dann 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- und 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 die Aktivierung und Deaktivierung von Änderungen.

Hinweis :Wenn Sie eine Änderung für eine App entweder über die Entwickleroptionen oder ADB-Befehle aktivieren oder deaktivieren, wird die App beendet, damit die Überschreibung sofort wirksam wird.

Änderungen mit den Entwickleroptionen aktivieren und deaktivieren

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 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 aktivieren und deaktivieren

Wenn Sie eine Änderung mit ADB aktivieren oder deaktivieren möchten, führen Sie einen der folgenden Befehle aus:

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

Mit dem folgenden Befehl können Sie eine Änderung auf den Standardzustand zurücksetzen und alle Überschreibungen 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 ein targetSdkVersion eingeschränkt. 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 gesperrte Version ist. Wenn Sie eine Änderung aktivieren oder deaktivieren, wird der Standardstatus überschrieben.

Um zu verhindern, dass das Compatibility Framework missbraucht wird, gibt es einige Einschränkungen, wann Änderungen aktiviert werden können. Ob Sie eine Änderung aktivieren oder deaktivieren können, hängt von der Art der Änderung, davon ab, ob Ihre App debugfähig ist, und davon, welche Art von Build auf Ihrem Gerät ausgeführt wird. In der folgenden Tabelle wird beschrieben, wann Sie verschiedene Arten von Änderungen aktivieren können:

Build-Typ	Nicht debuggbare App	Debugfähige App
	Alle Änderungen	Änderungen, die von der targetSDKVersion abhängig sind	Alle anderen Änderungen
Entwicklervorschau oder Betaversion	Funktion kann nicht aktiviert oder deaktiviert werden	Kann ein- und ausgeschaltet werden	Kann ein- und ausgeschaltet werden
Öffentlicher Nutzer-Build	Funktion kann nicht aktiviert oder deaktiviert werden	Kann ein- und ausgeschaltet werden	Funktion kann nicht aktiviert oder deaktiviert werden