Kompatibilitäts-Framework-Tools

Mit Android 11 wurden neue Entwicklertools zum Testen und Debuggen deiner App anhand von Verhaltensänderungen in neueren Android-Versionen Plattform. Diese Tools sind Teil eines Kompatibilitätsframeworks, mit dem sich Apps funktionsgefährdende Änderungen einzeln über Entwickler oder ADB. Nutzen Sie diese Flexibilität, um die neuesten stabile API-Version und testen Sie Ihre App mit der Vorabversion der nächste Android-Version.

Wenn Sie die Kompatibilitäts-Framework-Tools verwenden, passt seine interne Logik automatisch an, sodass Sie Ihre targetSDKVersion oder kompilieren Sie Ihre App neu, um einfache Tests durchzuführen. Weil Änderungen können einzeln umgeschaltet werden. Sie können sie isolieren, testen und debuggen. Verhaltensänderungen zu einem bestimmten Zeitpunkt ändern oder eine einzelne Änderung deaktivieren, die Probleme verursacht, wenn müssen Sie zuerst etwas anderes testen.

Herausfinden, welche Änderungen aktiviert sind

Wenn eine Verhaltensänderung aktiviert ist, kann sich dies darauf auswirken, wie Ihre App auf die Plattform-APIs, die von dieser Änderung betroffen sind. Sie können prüfen, welches Verhalten Änderungen werden mit den Entwickleroptionen, logcat- oder ADB-Befehlen aktiviert.

Aktivierte Änderungen mithilfe von Entwickleroptionen identifizieren

Sie können sehen, welche Änderungen aktiviert sind, und diese über die entsprechende Schaltfläche aktivieren oder deaktivieren. die Entwickleroptionen eines Geräts. So greifen Sie auf diese Optionen zu:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffne auf deinem Gerät die Einstellungen und navigiere zu System > Erweitert > Entwickleroptionen > Änderungen der Kompatibilität von Apps.

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

Jede Verhaltensänderung gehört normalerweise zu einer der folgenden zwei Kategorien:

• Änderungen, die unabhängig von der Version alle Apps betreffen, die unter dieser Android-Version ausgeführt werden der targetSdkVersion der App.

  Diese Änderungen sind im Kompatibilitäts-Framework standardmäßig aktiviert die in der Benutzeroberfläche im Abschnitt Default Enabled Changes (Standard aktivierte Änderungen) aufgeführt sind.

• Ä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 Version der werden sie auch als „Änderungen“ bezeichnet, die durch Gated Content targetSDKVersion

  Diese Änderungen sind im Kompatibilitäts-Framework standardmäßig aktiviert, wenn Ihr App ist auf eine höhere Version ausgerichtet als die aufgeführte API-Version. Beispiel: eine Verhaltensänderung durch targetSDKVersion in Android 13 (API-Level 33) wird in der Benutzeroberfläche in einem Abschnitt namens Aktiviert für targetSdkVersion >=33. Bei einigen älteren Android-Versionen heißt dieser Abschnitt „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. Vorher Wenn Sie diese Änderungen aktivieren, lesen Sie die Beschreibung der Änderung im Abschnitt zur Kompatibilität Framework-Liste für diese Android-Version.

Aktivierte Änderungen mit Logcat identifizieren

Bei jeder Änderung des Verhaltens, wenn Ihre App zum ersten Mal während die betroffene API aufruft, gibt das System 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 sich auf die App auswirkt. Dieser Wert ist einem der Verhaltensänderungen, die auf dem Bildschirm Änderungen der App-Kompatibilität aufgeführt sind (siehe Abbildung 1). In diesem Beispiel entspricht 194833441 NOTIFICATION_PERM_CHANGE_ID.

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 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 liegt unter dem erforderlichen Grenzwert, der ist standardmäßig aktiviert, wenn die App ihre targetSDKVersion, um eine höhere Version als Ziel auszuwählen.
LOGGED	Die Änderung wird über das Kompatibilitäts-Framework protokolliert, aber kann nicht aktiviert oder deaktiviert werden. Diese Änderung kann zwar nicht geändert werden, weiterhin das Verhalten Ihrer App beeinflussen. Weitere Informationen finden Sie in der Beschreibung der Änderung in der Liste der Kompatibilitäts-Frameworks für dieser Android-Version. In vielen Fällen sind diese Änderungsarten sind experimentell und können ignoriert werden.

Aktivierte Änderungen mithilfe von ADB identifizieren

Führen Sie den folgenden ADB-Befehl aus, um alle Änderungen zu sehen (beide aktivierte und deaktiviert) auf dem gesamten Gerät:

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. Beispiel: 194833441.

Name

Der Name dieser Verhaltensänderung. Beispiel: NOTIFICATION_PERM_CHANGE_ID.

targetSDKVersion-Kriterien

Von welchem targetSDKVersion die Änderung gesteuert wird (falls vorhanden).

Wenn diese Änderung beispielsweise nur für Apps aktiviert ist, die auf die SDK-Version ausgerichtet sind, 33 oder höher, wird enableAfterTargetSdk=32 ausgegeben. Wenn die Änderung nicht durch targetSDKVersion durchgestrichen, enableAfterTargetSdk=0 wird ausgegeben.

Paketüberschreibungen

Der Name jedes Pakets, für das der Standardstatus der Änderung gilt (aktiviert oder deaktiviert) wurde überschrieben.

Handelt es sich beispielsweise um eine Änderung, die standardmäßig aktiviert ist, wird aufgeführt, wenn Sie die Änderung mit der Entwickleroptionen oder ADB. In diesem Fall sieht die Ausgabe so aus:

packageOverrides={com.my.package=false}

Änderungen, die durch targetSDKVersion verwaltet werden, können entweder aktiviert oder standardmäßig deaktiviert, sodass die Liste der Pakete Instanzen beider true oder false, je nach targetSDKVersion dieser App. Für 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 hier: der Dokumentation für jede Android-Version. Unter den folgenden Links finden Sie Je nach Android-Version, mit der Sie Ihre App testen, erhalten Sie weitere Informationen. für:

• 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, Ihnen Kontrolle über die und Flexibilität beim Testen deiner App mit neueren Android-Versionen. Dieses werden einige Strategien beschrieben, mit denen Sie ermitteln können, während Sie Ihre App testen und debuggen.

Wann Änderungen deaktiviert werden sollten

Wann Änderungen deaktiviert werden, hängt in der Regel davon ab, durch targetSDKVersion gesperrt oder nicht.

Änderungen für alle Apps aktiviert

Änderungen, die alle Apps betreffen, werden durch für eine bestimmte Plattformversion, unabhängig von der Version targetSDKVersion, damit Sie sehen können, ob Ihre Anwendung durch das Ausführen des App auf dieser Plattformversion.

Wenn Sie eine Ausrichtung auf Android 15 (API-Level 35) vornehmen möchten, könnten Sie Ihre App zunächst auf einem Gerät Android 15 und testen Sie Ihre App mit den üblichen Tests. Workflows. Wenn Probleme auftreten, können Sie die Änderung deaktivieren, die verursacht, sodass Sie weitere Tests auf andere Probleme durchführen können.

Da sich diese Änderungen unabhängig von targetSDKVersion auf alle Apps auswirken können, solltest du deine App in der Regel vor Änderungen auf diese Änderungen testen und aktualisieren die durch targetSDKVersion gesperrt sind. So können Sie sicherstellen, hat die App keine beeinträchtigten Funktionen, wenn sie ihr Gerät auf ein neues Gerät aktualisieren. Plattformversion.

Sie sollten diese Änderungen auch priorisieren, da Sie wenn ein öffentlicher Release-Build von Android verwendet wird. Idealerweise sollten Sie diese Änderungen für jede Version Android, solange sich diese Version in der Vorabversion befindet

Änderungen durch targetSDKVersion

Wenn Ihre App auf eine bestimmte targetSDKVersion, alle Änderungen, die durch diese Version geregelt werden, sind aktiviert ist standardmäßig aktiviert. Wenn du also das targetSDKVersion deiner App auf ein neues wird Ihre App von vielen neuen Änderungen gleichzeitig betroffen sein.

Da Ihre App von mehreren dieser Änderungen betroffen sein kann, müssen Sie möglicherweise einige dieser Änderungen einzeln deaktivieren, während Sie Fehler in der App beheben.

Wann Änderungen aktiviert werden sollten

Änderungen, die durch eine bestimmte targetSDKVersion verwaltet werden, sind standardmäßig deaktiviert. Wenn eine App auf eine niedrigere SDK-Version ausgerichtet ist als die Version mit Gated Content. In der Regel sehen Sie bei der Vorbereitung für das Targeting auf eine neue targetSdkVersion eine Liste Verhaltensänderungen, für die Sie Ihre App testen und debuggen müssen.

Beispiel: Sie testen Ihre App im Hinblick auf eine Reihe von Plattformänderungen. in den nächsten targetSdkVersion. Mithilfe von Entwickleroptionen oder ADB-Befehlen können Sie jede bearbeitete Änderung einzeln aktivieren und testen, anstatt Ihre App-Manifest ein und aktiviere jede Änderung auf einmal. Mit diesem zusätzlichen Steuerelement testen Sie Änderungen isoliert und vermeiden Sie das Debugging und Aktualisieren mehrerer Teile der auf einmal ansehen.

Nachdem Sie eine Änderung aktiviert haben, können Sie Ihre App mit den üblichen das Testen von Workflows. Prüfen Sie bei Problemen Ihre Logs, um festzustellen, die Ursache des Problems zu finden. Wenn nicht klar ist, ob das Problem durch eine aktiviert haben, deaktivieren Sie die Änderung und testen Sie dann noch einmal, Bereich Ihrer App.

Änderungen aktivieren oder deaktivieren

Mit dem Kompatibilitäts-Framework können Sie jede Änderung mithilfe der Entwickleroptionen oder ADB-Befehlen. Das Aktivieren bzw. Deaktivieren von Änderungen kann dazu führen, zum Absturz bringen oder wichtige Sicherheitsänderungen deaktivieren, gibt es einige mit Einschränkungen, wann Änderungen umgeschaltet werden können.

Änderungen mit den Entwickleroptionen ein-/ausschalten

Verwenden Sie die Entwickleroptionen, um die Änderungen zu aktivieren oder zu deaktivieren. Um den Entwickler zu finden Optionen:

1. Wenn die Entwickleroptionen noch nicht aktiviert sind, aktivieren Sie sie.
2. Öffnen Sie auf Ihrem Gerät die Einstellungen und navigieren Sie zu System > Erweitert > Entwickleroptionen > Änderungen der Kompatibilität von Apps.
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 tippe 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 CHANGE_NAME (z. B. NOTIFICATION_PERM_CHANGE_ID) und die PACKAGE_NAME

Sie können auch den folgenden Befehl verwenden, um eine Änderung auf die Standardeinstellungen zurückzusetzen. Entfernen Sie 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 sind standardmäßig aktiviert. Andere Änderungen werden durch eine targetSdkVersion Diese Änderungen sind standardmäßig aktiviert, wenn eine App auf die entsprechende SDK-Version oder höher und ist standardmäßig deaktiviert, wenn eine App auf eine SDK-Version ausgerichtet ist, die niedriger ist als die Version mit Gated Content. Wenn Sie eine Änderung wird die Standardeinstellung überschrieben.

Um zu verhindern, dass das Kompatibilitätsframework böswillig verwendet wird, gibt es einige Einschränkungen beim Wechseln zwischen Änderungen. Ob Sie die Funktion aktivieren oder deaktivieren können hängt von der Art der Änderung ab, ob Ihre App Debug-fähig ist, und den Build-Typ, der auf Ihrem Gerät ausgeführt wird. In der folgenden Tabelle wird beschrieben, können Sie zwischen verschiedenen Arten von Änderungen wechseln:

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