Ab Android 9 (API-Level 28) schränkt die Plattform ein, welche Nicht-SDK-Schnittstellen Ihre App verwenden kann. Diese Einschränkungen gelten immer dann, wenn eine App auf eine Nicht-SDK-Schnittstelle verweist oder versucht, ihr Handle mithilfe von Reflection oder JNI abzurufen. Diese Einschränkungen wurden eingeführt, um die Nutzer- und Entwicklerfreundlichkeit zu verbessern und das Risiko von Abstürzen für Nutzer und Notfall-Rollouts für Entwickler zu verringern. Weitere Informationen zu dieser Entscheidung finden Sie unter Improving Stability by Reducing Usage of non-SDK Interfaces.
Unterscheidung zwischen SDK- und Nicht-SDK-Schnittstellen
Im Allgemeinen sind öffentliche SDK-Schnittstellen diejenigen, die im Android-Framework-Paketindex dokumentiert sind. Der Umgang mit Nicht-SDK-Schnittstellen ist ein Implementierungsdetail, das von der API abstrahiert wird. Daher können sich diese Schnittstellen ohne Vorankündigung ändern.
Um Abstürze und unerwartetes Verhalten zu vermeiden, sollten Apps nur die offiziell dokumentierten Teile der Klassen im SDK verwenden. Das bedeutet auch, dass Sie nicht auf Methoden oder Felder zugreifen sollten, die nicht im SDK aufgeführt sind, wenn Sie mit einer Klasse über Mechanismen wie Reflection interagieren.
Listen von Nicht-SDK-APIs
Mit jeder Android-Version werden zusätzliche Nicht-SDK-Schnittstellen eingeschränkt. Wir wissen, dass sich diese Einschränkungen auf Ihren Release-Workflow auswirken können. Deshalb möchten wir Ihnen die Tools zur Verfügung stellen, mit denen Sie die Verwendung von Nicht-SDK-Schnittstellen erkennen können. Außerdem möchten wir Ihnen die Möglichkeit geben, uns Feedback zu geben, und Ihnen Zeit geben, sich auf die neuen Richtlinien vorzubereiten.
Um die Auswirkungen von Nicht-SDK-Einschränkungen auf Ihren Entwicklungs-Workflow zu minimieren, werden die Nicht-SDK-Schnittstellen in Listen unterteilt, die definieren, wie stark ihre Verwendung eingeschränkt ist. Das hängt davon ab, auf welches API-Level die App ausgerichtet ist. In der folgenden Tabelle werden die einzelnen Listen beschrieben:
| Liste | Code-Tags | Beschreibung |
|---|---|---|
| Sperrliste |
|
Nicht-SDK-Schnittstellen, die Sie unabhängig vom Ziel-API-Level Ihrer App nicht verwenden können. Wenn Ihre App versucht, auf eine dieser Schnittstellen zuzugreifen, gibt das System einen Fehler aus. |
| Bedingt blockiert |
|
Ab Android 9 (API-Level 28) hat jedes API-Level Nicht-SDK Schnittstellen, die eingeschränkt sind, wenn eine App auf dieses API-Level ausgerichtet ist. Diese Listen sind mit dem maximalen API-Level
( Wenn Ihre App versucht, auf eine Schnittstelle zuzugreifen, die für Ihr Ziel-API-Level eingeschränkt ist, verhält sich das System so, als wäre die API Teil der Sperrliste. |
| Nicht unterstützt |
|
Nicht-SDK-Schnittstellen, die nicht eingeschränkt sind und von Ihrer App verwendet werden können. Beachten Sie
jedoch, dass diese Schnittstellen nicht unterstützt werden und
sich ohne Vorankündigung ändern können. Es ist wahrscheinlich, dass diese Schnittstellen in zukünftigen Android-Versionen in einer max-target-x Liste bedingt blockiert werden. |
| SDK |
|
Schnittstellen, die frei verwendet werden können und jetzt als Teil des offiziell dokumentierten Android-Framework Paketindex unterstützt werden. |
| Test-APIs |
|
Schnittstellen, die für interne Systemtests verwendet werden, z. B. APIs, die Tests über die Compatibility Test Suite (CTS) ermöglichen. Test-APIs sind nicht Teil des SDK. Ab Android 11 (API-Level 30) sind Test-APIs in der Sperrliste enthalten. Apps dürfen sie also unabhängig vom Ziel-API-Level nicht verwenden. Alle Test-APIs werden nicht unterstützt und können sich unabhängig vom Plattform-API-Level ohne Vorankündigung ändern. |
Sie können zwar einige Nicht-SDK-Schnittstellen verwenden (je nach Ziel-API-Level Ihrer App), aber die Verwendung einer Nicht-SDK-Methode oder eines Nicht-SDK-Felds birgt immer ein hohes Risiko, dass Ihre App nicht mehr funktioniert. Wenn Ihre App auf Nicht-SDK-Schnittstellen angewiesen ist, sollten Sie mit der Planung einer Migration zu SDK-Schnittstellen oder anderen Alternativen beginnen. Wenn Sie für eine Funktion in Ihrer App keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle finden, sollten Sie eine neue öffentliche API anfordern.
Bestimmen, zu welcher Liste eine Schnittstelle gehört
Die Listen von Nicht-SDK-Schnittstellen werden als Teil der Plattform erstellt. Informationen zu den einzelnen Android-Versionen finden Sie in den folgenden Abschnitten.
Android 16
Für Android 16 (API-Level 36) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
Datei: hiddenapi-flags.csv
SHA-256-Prüfsumme:
9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074
Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 16, siehe Updates to non-SDK interface restrictions in Android 16.
Android 15
Für Android 15 (API-Level 35) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
Datei: hiddenapi-flags.csv
SHA-256-Prüfsumme:
40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9
Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 15 finden Sie unter Updates to non-SDK interface restrictions in Android 15.
Android 14
Für Android 14 (API-Level 34) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
Datei: hiddenapi-flags.csv
SHA-256-Prüfsumme:
7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f
Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 14, finden Sie unter Updates to non-SDK interface restrictions in Android 14.
Android 13
Für Android 13 (API-Level 33) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
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 in Android 13 bedingt blockiert sind, finden Sie unter Updates to non-SDK interface restrictions in Android 13.
Android 12
Für Android 12 (API-Level 31) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
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 in Android 12 bedingt blockiert sind, finden Sie unter List changes for Android 12.
Android 11
Für Android 11 (API-Level 30) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
Datei: hiddenapi-flags.csv
SHA-256-Prüfsumme:
a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 11, einschließlich vorgeschlagener öffentlicher API-Alternativen für APIs, die in Android 11 bedingt blockiert sind, finden Sie unter List changes for Android 11.
Android 10
Für Android 10 (API-Level 29) können Sie die folgende Datei herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben sind:
Datei: hiddenapi-flags.csv
SHA-256-Prüfsumme:
f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 10, einschließlich vorgeschlagener öffentlicher API-Alternativen für APIs, die in Android 10 bedingt blockiert sind, finden Sie unter List changes for Android 10.
Android 9
Für Android 9 (API-Level 28) enthält die folgende Textdatei die Liste der
Nicht-SDK-APIs, die nicht eingeschränkt sind (Greylist):
hiddenapi-light-greylist.txt.
Die Sperrliste (blacklist) und die Liste der bedingt blockierten APIs (Darkgrey-Liste) werden zur Build-Zeit abgeleitet.
Listen aus AOSP generieren
Wenn Sie mit AOSP arbeiten, können Sie eine hiddenapi-flags.csv-Datei generieren, die alle Nicht-SDK-Schnittstellen und die entsprechenden Listen enthält. Laden Sie dazu die AOSP-Quelle herunter und führen Sie dann den folgenden Befehl aus:
m out/soong/hiddenapi/hiddenapi-flags.csv
Die Datei finden Sie dann unter folgendem Pfad:
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.
| Zugriffsmethode | Ergebnis |
|---|---|
| Dalvik-Anweisung, die auf ein Feld verweist | NoSuchFieldError ausgelöst |
| Dalvik-Anweisung, die auf eine Methode verweist | NoSuchMethodError ausgelöst |
Reflection mit Class.getDeclaredField() oder Class.getField() |
NoSuchFieldException ausgelöst |
Reflection mit Class.getDeclaredMethod(), Class.getMethod() |
NoSuchMethodException ausgelöst |
Reflection mit Class.getDeclaredFields(), Class.getFields() |
Nicht-SDK-Elemente nicht in den Ergebnissen |
Reflection mit Class.getDeclaredMethods(), Class.getMethods() |
Nicht-SDK-Elemente nicht in den Ergebnissen |
JNI mit env->GetFieldID() |
NULL zurückgegeben, NoSuchFieldError ausgelöst |
JNI mit env->GetMethodID() |
NULL zurückgegeben, NoSuchMethodError ausgelöst |
App auf Nicht-SDK-Schnittstellen testen
Es gibt mehrere Methoden, mit denen Sie in Ihrer App nach Nicht-SDK-Schnittstellen suchen können.
Mit einer debugfähigen App testen
Sie können nach Nicht-SDK-Schnittstellen suchen, indem Sie eine debugfähige App auf einem Gerät oder Emulator mit Android 9 (API-Level 28) oder höher erstellen und ausführen. Achten Sie darauf, dass das Gerät oder der Emulator dem Ziel-API-Level Ihrer App entspricht.
Während der Tests Ihrer App gibt das System einen Logeintrag aus, wenn Ihre App auf bestimmte Nicht-SDK-Schnittstellen zugreift. Sie können die Logmeldungen Ihrer App prüfen, um die folgenden Details zu finden:
- Die deklarierende Klasse, der Name und der Typ (im Format, das von der Android-Laufzeit verwendet wird).
- Die Zugriffsmethode: Verknüpfung, Reflection oder JNI.
- Die Liste, zu der die Nicht-SDK-Schnittstelle gehört.
Sie können mit adb logcat auf diese Logmeldungen zugreifen, die unter der PID der ausgeführten App angezeigt werden. 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
Sie können auch mit der StrictMode API nach Nicht-SDK-Schnittstellen suchen. Aktivieren Sie diese Option mit der
detectNonSdkApiUsage Methode. Nachdem Sie die
StrictMode API aktiviert haben, können Sie mit einem penaltyListener einen Callback für jede Verwendung einer Nicht-SDK
Schnittstelle erhalten, in dem Sie eine benutzerdefinierte
Verarbeitung implementieren können. Das in der Callback-Funktion bereitgestellte Violation-Objekt wird von Throwable abgeleitet und der beigefügte Stacktrace enthält den Kontext der Verwendung.
Mit dem Android Studio-Lint-Tool testen
Wenn Sie Ihre App in Android Studio erstellen, prüft das Lint-Tool Ihren Code auf potenzielle Probleme. Wenn Ihre App Nicht-SDK-Schnittstellen verwendet, werden je nach Liste, zu der diese Schnittstellen gehören , Build-Fehler oder Warnungen angezeigt.
Sie können das Lint-Tool auch über die Befehlszeile ausführen oder Prüfungen manuell für ein bestimmtes Projekt, einen bestimmten Ordner oder eine bestimmte Datei ausführen.
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 wird erstellt. Wenn Ihre App Nicht-SDK-Schnittstellen verwendet, wird je nach Liste, zu der diese Schnittstellen gehören, ein Fehler oder eine Warnung in dem Pre-Launch-Bericht angezeigt.
Weitere Informationen finden Sie im Abschnitt Android-Kompatibilität unter Pre-Launch Berichte zum Erkennen von Problemen verwenden.
Neue öffentliche API anfordern
Wenn Sie für eine Funktion in Ihrer App keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle finden, können Sie eine neue öffentliche API anfordern, indem Sie in unserem Issue Tracker einen Feature Request erstellen.
Geben Sie beim Erstellen eines Feature Requests die folgenden Informationen an:
- Welche nicht unterstützte API Sie verwenden, einschließlich des vollständigen Deskriptors in der Logcat-Meldung
Accessing hidden .... - Warum Sie diese APIs verwenden müssen, einschließlich Details zur Funktion auf hoher Ebene, für die die API erforderlich ist, nicht nur Details auf niedriger Ebene.
- Warum die zugehörigen öffentlichen SDK-APIs für Ihre Zwecke nicht ausreichen.
- Alle anderen Alternativen, die Sie ausprobiert haben, und warum sie nicht funktioniert haben.
Wenn Sie diese Details in Ihrem Feature Request angeben, erhöhen Sie die Wahrscheinlichkeit, dass eine neue öffentliche API gewährt wird.
Andere Fragen
In diesem Abschnitt finden Sie einige Antworten auf andere Fragen, die Entwickler häufig gestellt haben:
Allgemeine Fragen
Wie kann Google sicher sein, dass die Anforderungen aller Apps über den Issue Tracker erfasst werden können?
Wir haben die ersten Listen für Android 9 (API-Level 28) durch statische Analysen von Apps erstellt, die mit den folgenden Methoden ergänzt wurden:
- Manuelle Tests von Top-Apps in Google Play und anderen Apps
- Interne Berichte
- Automatische Datenerhebung von internen Nutzern
- Berichte zur Entwicklervorschau
- Zusätzliche statische Analysen, die konservativ mehr falsch positive Ergebnisse enthalten sollten
Bei der Bewertung der Listen für jede Neuveröffentlichung berücksichtigen wir sowohl die API-Nutzung als auch das Feedback von Entwicklern ü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 aktivieren, indem Sie mit adb-Befehlen die API-Erzwingungsrichtlinie ändern. Die verwendeten Befehle variieren je nach API-Level. Für diese Befehle ist kein gerootetes Gerät erforderlich.
- Android 10 (API-Level 29) oder höher
Verwenden Sie den folgenden adb-Befehl, um den Zugriff zu aktivieren:
command:
adb shell settings put global hidden_api_policy 1
Verwenden Sie den folgenden Befehl, um die API-Erzwingungsrichtlinie auf die Standardeinstellungen zurückzusetzen:
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 1adb shell settings put global hidden_api_policy_p_apps 1Verwenden Sie die folgenden Befehle, um die API-Erzwingungsrichtlinie auf die Standardeinstellungen zurückzusetzen:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
Sie können den Integer in der API-Erzwingungsrichtlinie auf einen der folgenden Werte festlegen:
- 0: Deaktiviert die Erkennung von Nicht-SDK-Schnittstellen. Wenn Sie diese Einstellung verwenden, werden
alle Logmeldungen zur Verwendung von Nicht-SDK-Schnittstellen deaktiviert und Sie können Ihre
App nicht mit der
StrictModeAPI testen. Diese Einstellung wird nicht empfohlen. - 1: Ermöglicht den Zugriff auf alle Nicht-SDK-Schnittstellen, gibt aber Logmeldungen mit Warnungen für jede Verwendung von Nicht-SDK-Schnittstellen aus. Mit dieser Einstellung können Sie Ihre App auch mit der
Testen Sie Ihre App mit der
StrictModeAPI. - 2: Verbietet die Verwendung von Nicht-SDK-Schnittstellen, die zur Sperrliste gehören oder für Ihr Ziel-API-Level bedingt blockiert sind.
Fragen zu Listen von Nicht-SDK-Schnittstellen
Wo finde ich die Listen von Nicht-SDK-APIs im System-Image?
Sie sind in den Zugriffsbits für Felder und Methoden in den DEX-Dateien der Plattform codiert. Es gibt keine separate Datei im System-Image, die diese Listen enthält.
Sind die Listen von Nicht-SDK-APIs auf verschiedenen OEM-Geräten mit denselben Android-Versionen identisch?
OEMs können der Sperrliste (Blacklist) eigene Schnittstellen hinzufügen, aber sie können keine Schnittstellen aus den AOSP-Listen von Nicht-SDK-APIs entfernen. Das CDD verhindert solche Änderungen und CTS-Tests sorgen dafür, dass die Android Runtime die Liste erzwingt.
Fragen zur Kompatibilität verwandter Apps
Gibt es Einschränkungen für Nicht-NDK-Schnittstellen in nativem Code?
Das Android SDK enthält Java-Schnittstellen. Die Plattform hat in Android 7 (API-Level 26) begonnen, den Zugriff auf Nicht-NDK-Schnittstellen für nativen C/C++-Code einzuschränken. Weitere Informationen finden Sie unter Improving Stability with Private C/C++ Symbol Restrictions in Android N.
Gibt es Pläne, die Manipulation von dex2oat oder DEX-Dateien einzuschränken?
Wir haben keine aktiven Pläne, den Zugriff auf die dex2oat-Binärdatei einzuschränken. Wir beabsichtigen jedoch nicht, dass das DEX-Dateiformat über die Teile hinaus, die öffentlich im Dalvik Executable-Format angegeben sind, stabil oder eine öffentliche Schnittstelle ist. Wir behalten uns das Recht vor, dex2oat und die nicht angegebenen Teile des DEX-Formats jederzeit zu ändern oder zu entfernen. Beachten Sie auch, dass abgeleitete Dateien, die von dex2oat erstellt wurden, wie ODEX (auch als OAT bezeichnet), VDEX und CDEX alle nicht angegebene Formate sind.
Was passiert, wenn ein wichtiges Drittanbieter-SDK (z. B. ein Obfuskator) die Verwendung von Nicht-SDK-Schnittstellen nicht vermeiden kann, sich aber verpflichtet, die Kompatibilität mit zukünftigen Android-Versionen aufrechtzuerhalten? Kann Android in diesem Fall auf seine Kompatibilitätsanforderungen verzichten?
Wir haben keine Pläne, auf Kompatibilitätsanforderungen pro SDK zu verzichten. Wenn ein SDK-Entwickler die Kompatibilität nur aufrechterhalten kann, indem er von Schnittstellen in den nicht unterstützten (ehemals grauen) Listen abhängig ist, sollte er mit der Planung einer Migration zu SDK-Schnittstellen oder anderen Alternativen beginnen und eine neue öffentliche API anfordern, wenn er keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle findet.
Gelten die Einschränkungen für Nicht-SDK-Schnittstellen für alle Apps, einschließlich System- und Erstanbieter-Apps, und nicht nur für Drittanbieter-Apps?
Ja. Wir machen jedoch Ausnahmen für Apps, die mit dem Plattformschlüssel signiert sind, und für einige System-Image-Apps. Beachten Sie, dass diese Ausnahmen nur für Apps gelten, die Teil des System-Image sind (oder für aktualisierte System-Image-Apps). Die Liste ist nur für Apps vorgesehen, die auf die privaten Plattform-APIs und nicht auf die SDK-APIs ausgerichtet sind (wobei LOCAL_PRIVATE_PLATFORM_APIS := true).