Einschränkungen für Nicht-SDK-Schnittstellen

Ab Android 9 (API-Level 28) schränkt die Plattform ein, welches Nicht-SDK Schnittstellen, die Ihre App nutzen kann. Diese Einschränkungen gelten, wenn eine App auf eine Nicht-SDK-Schnittstelle oder versucht, ihren Handle mithilfe von Reflexion oder JNI zu erhalten. Diese Einschränkungen dienen dazu, Nutzern und Entwicklern und das Risiko von Abstürzen für Nutzer und Notfall-Rollouts für zu entwickeln. Weitere Informationen zu dieser Entscheidung finden Sie unter Stabilität verbessern indem Sie die Nutzung von Nicht-SDK-Schnittstellen reduzieren.

Zwischen SDK- und Nicht-SDK-Schnittstellen unterscheiden

Im Allgemeinen sind öffentliche SDK-Schnittstellen, die im Package Index des Android-Frameworks. Die Verarbeitung von Nicht-SDK-Schnittstellen ist ein Implementierungsdetails, die das API abstrahiert, sodass diese Schnittstellen können ohne vorherige Ankündigung geändert werden.

Um Abstürze und unerwartetes Verhalten zu vermeiden, sollten Apps nur die offizielle Teile der Klassen im SDK dokumentiert. Das bedeutet auch, dass Sie Zugriffsmethoden oder Felder, die nicht im SDK aufgeführt sind, wenn Sie mit einem mit Mechanismen wie der Reflexion.

Listen der Nicht-SDK-APIs

Mit jeder Version von Android sind zusätzliche Nicht-SDK-Schnittstellen eingeschränkt. Mi. wissen, dass sich diese Einschränkungen auf deinen Veröffentlichungs-Workflow auswirken können. um die Nutzung von Nicht-SDK-Schnittstellen zu erkennen. Feedback geben und Zeit haben, die neuen Richtlinien zu planen und sich daran zu gewöhnen.

Um die Auswirkungen von Nicht-SDK-Einschränkungen auf Ihren Entwicklungsworkflow zu minimieren, Nicht-SDK-Schnittstellen sind in Listen unterteilt, die definieren, wie intensiv ihre Verwendung ist eingeschränkt. In der folgenden Tabelle beschreibt jede dieser Listen:

Liste	Code-Tags	Beschreibung
Sperrliste	blocked Eingestellt: blacklist	Nicht-SDK-Schnittstellen, die unabhängig vom Ziel-API-Level an. Wenn Ihre App versucht, auf eine dieser Schnittstellen zuzugreifen, einen Fehler ausgibt.
Bedingt blockiert	max-target-x Eingestellt: greylist-max-x	Ab Android 9 (API-Level 28) hat jedes API-Level ein Nicht-SDK Schnittstellen, die eingeschränkt sind, wenn eine App auf dieses API-Level ausgerichtet ist. Diese Listen sind durch das maximale API-Level gekennzeichnet (max-target-x), auf die eine App ausgerichtet werden kann, bevor sie dies nicht kann auf die Nicht-SDK-Schnittstellen in dieser Liste zugreifen können. Beispiel: Nicht-SDK-Schnittstelle, die in Android Pie nicht blockiert wurde, aber jetzt blockiert ist in Android 10 gehört zur max-target-p (greylist-max-p)-Liste, wobei "p" steht für Pie oder Android 9 (API-Level 28). Wenn Ihre App versucht, auf eine Oberfläche zuzugreifen, die für Ihr auf das Ziel-API-Level ausgerichtet ist, verhält sich so, als wäre die API der Sperrliste.
Nicht unterstützt	unsupported Eingestellt: greylist	Nicht-SDK-Schnittstellen, die nicht eingeschränkt sind und von Ihrer App verwendet werden können. Hinweis Diese Schnittstellen werden jedoch nicht unterstützt und können ohne vorherige Ankündigung geändert werden. Erwarten Sie, dass diese Schnittstellen in zukünftigen Android-Versionen in einem Liste „max-target-x“.
SDK	public-api und sdk Eingestellt: public-api und whitelist	Schnittstellen, die frei genutzt werden können und jetzt als Teil des offiziell dokumentierten Android-Frameworks Paketindex:
APIs testen	test-api	Schnittstellen, die für interne Systemtests verwendet werden, z. B. APIs, die Erleichterung von Tests über die Compatibility Test Suite (CTS). Test-APIs sind nicht Teil des SDK. Beginnt in Android 11 (API-Level 30) haben, sind Test-APIs in der Sperrliste enthalten. Apps dürfen sie unabhängig von ihrem Ziel-API-Level nicht verwenden. Alle Test-APIs werden nicht unterstützt und können ohne vorherige Ankündigung geändert werden, unabhängig davon, des Plattform-API-Levels.

Sie können zwar einige Nicht-SDK-Schnittstellen verwenden (abhängig von der Ziel-API Ihrer App Wenn Sie eine Nicht-SDK-Methode oder ein beliebiges Feld verwenden, besteht immer ein hohes Risiko von Problemen für Ihre App. Wenn Ihre App Nicht-SDK-Schnittstellen benötigt, sollten Sie mit der Planung Migration zu SDK-Schnittstellen oder anderen Alternativen. Wenn Sie keine statt einer Nicht-SDK-Schnittstelle für eine Funktion in Ihrer App Neue öffentliche API anfordern

Bestimmen, zu welcher Liste eine Schnittstelle gehört

Die Listen der Nicht-SDK-Schnittstellen werden als Teil der Plattform erstellt. Weitere Informationen finden Sie in der finden Sie in den folgenden Abschnitten Informationen zu den einzelnen Android-Versionen.

Android 15

Für Android 15 (API-Level 35) können Sie die folgende Datei mit den folgenden Informationen herunterladen: alle Nicht-SDK-Schnittstellen und die entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 15 Siehe Updates zu Einschränkungen für Nicht-SDK-Schnittstellen in Android 15.

Android 14

Für Android 14 (API-Level 34) können Sie die folgende Datei mit den folgenden Informationen herunterladen: alle Nicht-SDK-Schnittstellen und die entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 14 Siehe Updates zu Einschränkungen für Nicht-SDK-Schnittstellen in Android 14.

Android 13

Für Android 13 (API-Level 33) können Sie die folgende Datei mit den folgenden Informationen herunterladen: alle Nicht-SDK-Schnittstellen und die entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 13 einschließlich vorgeschlagener öffentlicher API-Alternativen für APIs, die bedingt in Android 13 blockiert, siehe Updates für Nicht-SDK-Schnittstellen Einschränkungen in Android 13.

Android 12

Für Android 12 (API-Level 31) können Sie die folgende Datei mit den folgenden Informationen herunterladen: alle Nicht-SDK-Schnittstellen und die entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 12 einschließlich vorgeschlagener öffentlicher API-Alternativen für APIs, die bedingt in Android 12 blockiert, siehe Listenänderungen für Android 12

Android 11

Für Android 11 (API-Level 30) können Sie die folgende Datei herunterladen, beschreibt alle Nicht-SDK-Schnittstellen und ihre entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 11, darunter: vorgeschlagene öffentliche API-Alternativen für APIs, die bedingt blockiert sind in Android 11: Siehe Listenänderungen für Android 11

Android 10

Für Android 10 (API-Level 29) können Sie die folgende Datei herunterladen, beschreibt alle Nicht-SDK-Schnittstellen und ihre entsprechenden Listen:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 10, darunter: vorgeschlagene öffentliche API-Alternativen für APIs, die bedingt blockiert sind in Android 10: Siehe Listenänderungen für Android 10

Android 9

Für Android 9 (API-Level 28) enthält die folgende Textdatei eine Liste der Nicht-SDK-APIs, die nicht eingeschränkt sind (graue Liste): hiddenapi-light-greylist.txt

Sperrliste (blacklist) und Liste der bedingt blockierten APIs (dunkelgrau) werden zum Build-Zeitpunkt abgeleitet.

Listen aus AOSP generieren

Wenn du mit AOSP arbeitest, kannst du eine hiddenapi-flags.csv-Datei generieren, die enthält alle Nicht-SDK-Schnittstellen und die zugehörigen Listen. Gehen Sie dazu wie folgt vor: Laden Sie die AOSP-Quelle herunter und führen Sie den folgenden Befehl aus:

m out/soong/hiddenapi/hiddenapi-flags.csv

Sie finden die Datei dann an folgendem Speicherort:

out/soong/hiddenapi/hiddenapi-flags.csv

Erwartetes Verhalten beim Zugriff auf eingeschränkte Nicht-SDK-Schnittstellen

In der folgenden Tabelle wird das Verhalten beschrieben, das Sie erwarten können, wenn Ihre App versucht, auf eine Nicht-SDK-Schnittstelle zuzugreifen, die Teil der Sperrliste ist.

Zugriffsmöglichkeiten	Ergebnis
Dalvik-Anweisung, die auf ein Feld verweist	NoSuchFieldError geworfen
Dalvik-Anweisung, die auf eine Methode verweist	NoSuchMethodError geworfen
Reflexion mit Class.getDeclaredField() oder Class.getField()	NoSuchFieldException geworfen
Reflexion mit Class.getDeclaredMethod() und Class.getMethod()	NoSuchMethodException geworfen
Reflexion mit Class.getDeclaredFields() und Class.getFields()	Nicht-SDK-Mitglieder nicht in den Ergebnissen
Reflexion mit Class.getDeclaredMethods() und Class.getMethods()	Nicht-SDK-Mitglieder nicht in den Ergebnissen
JNI mit env->GetFieldID()	NULL zurückgegeben, NoSuchFieldError verworfen
JNI mit env->GetMethodID()	NULL zurückgegeben, NoSuchMethodError verworfen

Apps auf Nicht-SDK-Schnittstellen testen

Es gibt mehrere Methoden, mit denen Sie Nicht-SDK-Schnittstellen in für Ihre App.

Mit einer debugfähigen App testen

Sie können auf Nicht-SDK-Schnittstellen testen, indem Sie eine Debug-fähige App auf einem Gerät oder Emulator mit Android 9 (API-Level 28) oder höher liegen. Vergewissern Sie sich, dass das verwendete Gerät oder der Emulator mit der Ziel-API-Level der App an.

Während der Tests Ihrer Anwendung gibt das System eine Lognachricht aus, wenn Ihre App auf bestimmte Nicht-SDK-Schnittstellen zugreift. Sie können die Lognachrichten Ihrer Anwendung prüfen um die folgenden Details zu finden:

• Die deklarierende Klasse, der Name und der Typ (in dem Format, das vom Android-Laufzeit).
• Die Mittel des Zugriffs: entweder Verlinkung, Reflexion oder JNI.
• Liste der Nicht-SDK-Schnittstellen

Mit adb logcat können Sie auf diese Logeinträge zugreifen, die unter der PID der ausgeführten Anwendung. Ein Eintrag im Log könnte beispielsweise so aussehen:

Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)

Mit der StrictMode API testen

Mit der StrictMode API können Sie auch Nicht-SDK-Schnittstellen testen. Verwenden Sie die Methode detectNonSdkApiUsage können Sie dies aktivieren. Nach der Aktivierung der StrictMode-API können Sie bei jeder Verwendung eines Nicht-SDKs einen Callback erhalten. mithilfe von penaltyListener, wo Sie benutzerdefinierte Umgang mit Ihren Daten. Das im Callback angegebene Violation-Objekt stammt aus Throwable. Der beigefügte Stacktrace liefert den Kontext zur Nutzung.

Mit dem Veridex-Tool testen

Sie können auch das statische Analysetool von veridex auf Ihrem APK ausführen. Das veridex-Tool die gesamte Codebasis des APK, einschließlich aller Bibliotheken von Drittanbietern, scannt und erfasst jegliche Verwendung von Nicht-SDK-Schnittstellen, die es findet.

Zu den Einschränkungen des Veridex-Tools gehören:

• Aufrufe über JNI können nicht erkannt werden.
• Sie kann durch Reflexion nur einen Teil der Aufrufe erkennen.
• Die Analyse inaktiver Codepfade ist auf API-Level-Prüfungen beschränkt.
• Er kann nur auf Computern ausgeführt werden, die SSE4.2- und POPCNT-Anweisungen unterstützen.

Windows

Es werden keine nativen Windows-Binärdateien bereitgestellt, Sie können das veridex-Tool aber auf Windows durch Ausführen der Linux-Binärdateien mithilfe des Windows-Subsystems für Linux (WSL) Bevor Sie die Schritte in diesem Abschnitt ausführen, installieren Sie den WSL und wählen Sie als Linux-Distribution Ubuntu aus.

Nachdem Ubuntu installiert ist, starten Sie ein Ubuntu-Terminal und führen dann die folgenden Schritte aus:

1. Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
2. Extrahieren Sie den Inhalt der appcompat.tar.gz-Datei.
3. Suchen Sie im extrahierten Ordner nach der Datei veridex-linux.zip und extrahieren Sie sie.

4. Gehen Sie zum entpackten Ordner und führen Sie den folgenden Befehl aus, wobei your-app.apk ist das APK, das Sie testen möchten:

   ./appcompat.sh --dex-file=your-app.apk
   

macOS

So führen Sie das Veridex-Tool unter macOS aus:

1. Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
2. Extrahieren Sie den Inhalt der appcompat.tar.gz-Datei.
3. Suchen Sie im extrahierten Ordner nach der Datei veridex-mac.zip und extrahieren Sie sie.

4. Gehen Sie zum entpackten Ordner und führen Sie den folgenden Befehl aus, wobei /path-from-root/your-app.apk ist der Pfad zum APK. die Sie testen möchten, beginnend mit dem Stammverzeichnis Ihres Systems:

   ./appcompat.sh --dex-file=/path-from-root/your-app.apk
   

Linux

So führen Sie das veridex-Tool unter Linux aus:

1. Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
2. Extrahieren Sie den Inhalt der appcompat.tar.gz-Datei.
3. Suchen Sie im extrahierten Ordner nach der Datei veridex-linux.zip und extrahieren Sie sie.

4. Gehen Sie zum entpackten Ordner und führen Sie den folgenden Befehl aus, wobei your-app.apk ist das APK, das Sie testen möchten:

   ./appcompat.sh --dex-file=your-app.apk
   

Mit dem Lint-Tool in Android Studio testen

Immer wenn Sie Ihre App in Android Studio erstellen, prüft das Lint-Tool Ihre um mögliche Probleme zu beheben. Wenn Ihre App Nicht-SDK-Schnittstellen verwendet, sehen Sie möglicherweise Fehler oder Warnungen erstellen, je nachdem, zu welcher Liste diese Schnittstellen gehören an.

Sie können das Lint-Tool auch über die Befehlszeile oder Prüfungen ausführen. manuell für ein bestimmtes Projekt, einen Ordner oder eine Datei.

Mit der Play Console testen

Wenn Sie Ihre App in einen Test-Track in der Play Console hochladen, wird Ihre App automatisch auf potenzielle Probleme getestet und ein Pre-Launch-Bericht generiert. Wenn Ihre App Nicht-SDK-Schnittstellen verwendet, wird ein Fehler oder eine Warnung in Pre-Launch-Bericht, je nachdem, zu welcher Liste diese Oberflächen gehören.

Weitere Informationen finden Sie im Abschnitt zur Android-Kompatibilität unter Pre-Launch-Nutzung verwenden zur Identifizierung von Problemen.

Neue öffentliche API anfordern

Wenn Sie keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle für ein Feature in finden können, Ihrer Anwendung können Sie eine neue öffentliche API anfordern, indem Sie eine Funktionsanfrage erstellen. in unserem Issue Tracker.

Geben Sie beim Erstellen einer Funktionsanfrage die folgenden Informationen an:

• Welche nicht unterstützte API Sie verwenden, einschließlich des vollständigen Deskriptors aus Die Logcat-Nachricht Accessing hidden ....
• Warum Sie diese APIs verwenden müssen, einschließlich Details zur allgemeinen für die die API notwendig ist, und nicht nur auf Low-Level-Details.
• Warum zugehörige öffentliche SDK APIs für deine Zwecke nicht ausreichen.
• Haben Sie andere Alternativen ausprobiert und warum diese nicht funktioniert haben?

Wenn Sie diese Details in Ihrer Funktionsanfrage angeben, erhöhen Sie den Wahrscheinlichkeit, dass eine neue öffentliche API gewährt wird.

Sonstige Fragen

In diesem Abschnitt finden Sie Antworten auf weitere Fragen von Entwicklern. häufig gestellte Fragen:

Allgemeine Fragen

Wie kann Google sicherstellen, dass die Anforderungen aller Apps über den Issue Tracker erfasst werden?

Wir haben die ursprünglichen Listen für Android 9 (API-Level 28) über statische Analysen von Apps, die durch folgende Methoden ergänzt wurden:

• Manuelle Tests von Top-Apps bei Google Play und anderen Apps
• interne Berichte
• Automatische Datenerfassung von internen Nutzern
• Entwicklervorschauberichte
• zusätzliche statische Analyse, die konservativ weitere Falsch positive Ergebnisse

Bei der Auswertung der Listen für jede neue Version berücksichtigen wir die API-Nutzung und Entwicklerfeedback über den Issue Tracker.

Wie kann ich den Zugriff auf Nicht-SDK-Schnittstellen aktivieren?

Sie können den Zugriff auf Nicht-SDK-Schnittstellen auf Entwicklungsgeräten mithilfe von ADB aktivieren um die API-Erzwingungsrichtlinie zu ändern. Die verwendeten Befehle variieren, je nach API-Ebene. Für diese Befehle ist kein Root-Gerät erforderlich.

Android 10 (API-Level 29) oder höher

Verwenden Sie das folgende ADB, um den Zugriff zu aktivieren

command:

adb shell settings put global hidden_api_policy  1

Um die Richtlinie für die API-Erzwingung auf die Standardeinstellungen zurückzusetzen, verwenden Sie die Methode folgenden Befehl:

adb shell settings delete global hidden_api_policy

Android 9 (API-Level 28)

Verwenden Sie die folgenden ADB-Befehle, um den Zugriff zu aktivieren:

adb shell settings put global hidden_api_policy_pre_p_apps  1
adb shell settings put global hidden_api_policy_p_apps 1

Um die Richtlinie für die API-Erzwingung auf die Standardeinstellungen zurückzusetzen, verwenden Sie die Methode folgenden Befehle:

adb shell settings delete global hidden_api_policy_pre_p_apps
adb shell settings delete global hidden_api_policy_p_apps

Sie können die Ganzzahl in der API-Erzwingungsrichtlinie auf eine der folgenden Optionen festlegen: Werte:

• 0: Erkennung von Nicht-SDK-Schnittstellen vollständig deaktivieren. Bei Verwendung dieser Einstellung werden alle Logeinträge für die Nutzung von Nicht-SDK-Schnittstellen und verhindert, dass Sie Ihre mithilfe der StrictMode API. Diese Einstellung wird nicht empfohlen.
• 1: Zugriff auf alle Nicht-SDK-Schnittstellen aktivieren, aber Protokollmeldungen mit Warnungen für die Verwendung von Nicht-SDK-Schnittstellen. Mit dieser Einstellung können Sie außerdem Ihre App mithilfe der StrictMode API testen.
• 2: Verwendung von Nicht-SDK-Schnittstellen nicht zulassen, die auf der Sperrliste stehen oder die für Ihr Ziel-API-Level bedingt blockiert.

Fragen zu Listen mit Nicht-SDK-Schnittstellen

Wo finde ich die Listen der Nicht-SDK-APIs im System-Image?

Sie werden in den Flag-Bits für den Feld- und Methodenzugriff in Plattform-DEX-Dateien codiert. Das System-Image enthält keine separate Datei, die diese Listen enthält.

Sind die Nicht-SDK-API-Listen auf verschiedenen OEM-Geräten mit derselben Android-Version identisch?

OEMs können der Sperrliste (schwarze Liste) ihre eigenen Schnittstellen hinzufügen, Schnittstellen aus den Listen der AOSP-Nicht-SDK-APIs entfernen. Das CDD verhindert solche Änderungen und CTS-Tests stellen sicher, dass Android Runtime die Liste erzwingt.

Fragen zur Kompatibilität ähnlicher Apps

Gibt es Einschränkungen für Nicht-NDK-Schnittstellen in nativem Code?

Das Android SDK enthält Java-Schnittstellen. Die Plattform hat angefangen, Zugriff auf Nicht-NDK-Schnittstellen für nativen C/C++ Code in Android 7 (API-Level 26) Weitere Informationen finden Sie unter Stabilität verbessern mit dem Symbol für privates C/C++ Einschränkungen in Android N

Gibt es Pläne, die Manipulation von dex2oat- oder DEX-Dateien einzuschränken?

Wir planen nicht, den Zugriff auf das dex2oat-Binärprogramm aktiv einzuschränken, das DEX-Dateiformat nicht stabil sein oder eine öffentliche Schnittstelle ist, Die Teile, die öffentlich im Dalvik Executable-Format angegeben sind. Wir behalten uns das Recht vor, dex2oat und die nicht angegebenen Teile zu ändern oder zu entfernen. des DEX-Formats ändern. Beachten Sie außerdem, dass abgeleitete Dateien, die von dex2oat erstellt wurden, wie ODEX (auch als OAT bezeichnet), VDEX und CDEX sind alles nicht spezifizierte Formate.

Was ist, wenn ein wichtiges Drittanbieter-SDK (z. B. ein Obfuscator) Nicht-SDK-Schnittstellen verwenden kann, aber die Kompatibilität mit zukünftigen Android-Versionen gewährleistet? Kann Android in diesem Fall auf seine Kompatibilitätsanforderungen verzichten?

Wir planen nicht, auf Kompatibilitätsanforderungen für einzelne SDKs zu verzichten. Wenn kann ein SDK-Entwickler die Kompatibilität nur aufrechterhalten, wenn er nicht unterstützten (zuvor grauen) Listen, sollte mit der Planung einer Migration SDK-Schnittstellen oder andere Alternativen verwenden und bei Bedarf eine neue öffentliche API anfordern können sie keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle finden.

Gelten Einschränkungen für Nicht-SDK-Schnittstellen für alle Apps, einschließlich System- und Erstanbieter-Apps, nicht nur Drittanbieter-Apps?

Ja, Apps, die mit dem Plattformschlüssel und einigen System-Images signiert sind, sind jedoch von der Regel ausgenommen. Apps. Beachten Sie, dass diese Ausnahmen nur für Apps gelten, die Teil des Systems sind, oder aktualisierte System-Image-Apps. Die Liste ist nur für Apps gedacht, die auf den APIs der privaten Plattform und nicht auf den SDK-APIs aufbauen (wobei LOCAL_PRIVATE_PLATFORM_APIS := true.