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 |
|
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 |
|
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
( 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 |
|
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 |
|
Schnittstellen, die frei genutzt werden können und jetzt als Teil des offiziell dokumentierten Android-Frameworks Paketindex: |
APIs testen |
|
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 zugehörigen 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 zugehörigen 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 zugehörigen 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:
- Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
- Extrahieren Sie den Inhalt der
appcompat.tar.gz
-Datei. - Suchen Sie im extrahierten Ordner nach der Datei
veridex-linux.zip
und extrahieren Sie sie. 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:
- Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
- Extrahieren Sie den Inhalt der
appcompat.tar.gz
-Datei. - Suchen Sie im extrahierten Ordner nach der Datei
veridex-mac.zip
und extrahieren Sie sie. 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:
- Laden Sie das Veridex-Tool aus den vordefinierten Android-Laufzeiten herunter. zu erstellen.
- Extrahieren Sie den Inhalt der
appcompat.tar.gz
-Datei. - Suchen Sie im extrahierten Ordner nach der Datei
veridex-linux.zip
und extrahieren Sie sie. 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
.