Einschränkungen für Nicht-SDK-Schnittstellen

Ab Android 9 (API-Level 28) schränkt die Plattform ein, welche Nicht-SDK-Schnittstellen Ihre App verwenden kann. Diese Einschränkungen gelten immer, wenn eine App auf eine Nicht-SDK-Schnittstelle verweist oder versucht, ihr Handle mithilfe von Reflexion 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.

Zwischen SDK- und Nicht-SDK-Schnittstellen unterscheiden

Im Allgemeinen sind öffentliche SDK-Schnittstellen diejenigen, die im Paketindex des Android-Frameworks dokumentiert sind. Die Verarbeitung von Nicht-SDK-Schnittstellen ist ein Implementierungsdetail, das von der API abstrahiert wird. Diese Schnittstellen können sich daher 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 Reflexion interagieren.

Listen mit Nicht-SDK-APIs

Mit jedem neuen Release von Android werden weitere Nicht-SDK-Schnittstellen eingeschränkt. Wir wissen, dass sich diese Einschränkungen auf euren Release-Workflow auswirken können. Deshalb möchten wir euch Tools zur Verfügung stellen, mit denen ihr die Verwendung von Nicht-SDK-Schnittstellen erkennen könnt. Außerdem möchten wir euch die Möglichkeit geben, uns Feedback zu geben, und euch Zeit geben, die neuen Richtlinien zu planen und euch darauf einzustellen.

Um die Auswirkungen von Nicht-SDK-Einschränkungen auf deinen Entwicklungsworkflow zu minimieren, sind die Nicht-SDK-Schnittstellen in Listen unterteilt, die festlegen, wie stark ihre Nutzung eingeschränkt ist, je nachdem, auf welches API-Level abgezielt wird. In der folgenden Tabelle werden die einzelnen Listen beschrieben:

Liste Code-Tags Beschreibung
Sperrliste
  • blocked
  • Eingestellt: blacklist
 Nicht-SDK-Schnittstellen, die du unabhängig vom Ziel-API-Level deiner App nicht verwenden kannst. Wenn deine App versucht, auf eine dieser Schnittstellen zuzugreifen, gibt das System einen Fehler aus.
Bedingt blockiert
  • max-target-x
  • Eingestellt: greylist-max-x

Ab Android 9 (API-Level 28) gibt es auf jedem 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 (max-target-x) gekennzeichnet, auf das eine App ausgerichtet sein kann, bevor sie nicht mehr auf die Nicht-SDK-Schnittstellen in dieser Liste zugreifen kann. Beispiel: Eine Nicht-SDK-Schnittstelle, die in Android Pie nicht blockiert wurde, aber jetzt in Android 10 blockiert wird, ist Teil der Liste max-target-p (greylist-max-p), wobei „p“ für Pie oder Android 9 (API-Level 28) steht.

Wenn deine App versucht, auf eine Schnittstelle zuzugreifen, die für dein Ziel-API-Level eingeschränkt ist, verhält sich das System so, als wäre die API Teil der Sperrliste.
Nicht unterstützt
  • unsupported
  • Eingestellt: greylist
 Nicht-SDK-Schnittstellen, die uneingeschrä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. Diese Schnittstellen werden in zukünftigen Android-Versionen voraussichtlich in einer max-target-x-Liste bedingt blockiert.
SDK
  • Sowohl public-api als auch sdk
  • Eingestellt: Sowohl public-api als auch whitelist
 Schnittstellen, die frei verwendet werden können und jetzt im Rahmen des offiziell dokumentierten Paketindex des Android-Frameworks unterstützt werden.
Test-APIs
  • test-api
 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, sodass Apps sie unabhängig von ihrem Ziel-API-Level nicht verwenden dürfen. Alle Test-APIs werden nicht unterstützt und können sich ohne Vorankündigung ändern, unabhängig vom API-Level der Plattform.

Einige Nicht-SDK-Schnittstellen können zwar verwendet werden (je nach Ziel-API-Level Ihrer App), die Verwendung von Nicht-SDK-Methoden oder ‑Feldern birgt jedoch immer ein hohes Risiko, dass Ihre App nicht mehr funktioniert. Wenn Ihre App auf Nicht-SDK-Schnittstellen angewiesen ist, sollten Sie eine Migration zu SDK-Schnittstellen oder anderen Alternativen planen. Wenn du keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle für eine Funktion in deiner App findest, solltest du eine neue öffentliche API anfordern.

Bestimmen, zu welcher Liste eine Schnittstelle gehört

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

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 werden:

Datei: hiddenapi-flags.csv

SHA-256-Prüfsumme: 9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074

Weitere Informationen zu den Änderungen an der Liste der Nicht-SDK-APIs in Android 16 finden Sie unter Aktualisierungen der Einschränkungen für Nicht-SDK-Schnittstellen 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 werden:

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 Aktualisierungen der 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 herunterladen, in der alle Nicht-SDK-Schnittstellen und die entsprechenden Listen beschrieben werden:

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 Aktualisierungen der Einschränkungen für Nicht-SDK-Schnittstellen in Android 14.

Android 13

Für Android 13 (API-Level 33) kannst du 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 Aktualisierungen der Einschränkungen für Nicht-SDK-Schnittstellen 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 werden:

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 Änderungen an der Liste für 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 werden:

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 Listenänderungen für 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 werden:

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 Änderungen an der Liste für Android 10.

Android 9

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

Die Sperrliste (blacklist) und die Liste der bedingt blockierten APIs (dunkelgraue Liste) werden zur Build-Zeit abgeleitet.

Listen aus dem AOSP generieren

Wenn Sie mit dem 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

Sie finden die Datei dann am folgenden 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 auf der Sperrliste steht.

Zugriffsmethode 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(), Class.getMethod() NoSuchMethodException geworfen
Reflexion mit Class.getDeclaredFields(), Class.getFields() Nicht-SDK-Mitglieder nicht in den Ergebnissen
Reflexion mit Class.getDeclaredMethods(), Class.getMethods() Nicht-SDK-Mitglieder sind nicht in den Ergebnissen enthalten
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 du deine App auf Nicht-SDK-Schnittstellen testen kannst.

Mit einer debugfähigen App testen

Sie können auf Nicht-SDK-Schnittstellen testen, indem Sie eine App im Debug-Modus auf einem Gerät oder Emulator mit Android 9 (API-Level 28) oder höher erstellen und ausführen. Achten Sie darauf, dass das von Ihnen verwendete Gerät oder der Emulator dem Ziel-API-Level Ihrer App entspricht.

Wenn Sie Tests für Ihre App ausführen, gibt das System eine Logeintrag aus, wenn Ihre App auf bestimmte Nicht-SDK-Schnittstellen zugreift. Sie können die Logeinträge Ihrer Anwendung prüfen, um die folgenden Details zu finden:

  • Die deklarierende Klasse, der Name und der Typ (im Format, das von der Android Runtime verwendet wird).
  • Die Zugriffsmethode: entweder Verknüpfung, Reflexion oder JNI.
  • Die Liste, zu der die Nicht-SDK-Schnittstelle gehört.

Sie können mit adb logcat auf diese Logeinträge zugreifen, die unter der PID der laufenden Anwendung 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

Du kannst auch mit der StrictMode API auf Nicht-SDK-Schnittstellen testen. Verwenden Sie die Methode detectNonSdkApiUsage, um dies zu aktivieren. Nachdem Sie die StrictMode API aktiviert haben, können Sie für jede Verwendung einer Nicht-SDK-Schnittstelle einen Callback erhalten. Verwenden Sie dazu einen penaltyListener, in dem Sie eine benutzerdefinierte Verarbeitung implementieren können. Das im Callback bereitgestellte Violation-Objekt wird von Throwable abgeleitet und der enthaltene Stacktrace liefert den Kontext der Nutzung.

Mit dem Lint-Tool von Android Studio testen

Wenn Sie Ihre App in Android Studio erstellen, prüft das Lint-Tool Ihren Code auf potenzielle Probleme. Wenn deine App Nicht-SDK-Schnittstellen verwendet, werden je nachdem, zu welcher Liste diese Schnittstellen gehören, möglicherweise 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 der Play Console in einen Test-Track hochladen, wird sie automatisch auf potenzielle Probleme getestet und es wird ein Pre-Launch-Bericht erstellt. Wenn Ihre App Nicht-SDK-Schnittstellen verwendet, wird im Pre-Launch-Bericht je nach Liste, zu der diese Schnittstellen gehören, ein Fehler oder eine Warnung 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 keine Alternative zur Verwendung einer Nicht-SDK-Schnittstelle für eine Funktion in Ihrer App 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, der in der Accessing hidden ...-Logcat-Nachricht angezeigt wird.
  • Warum Sie diese APIs verwenden müssen, einschließlich Details zur übergeordneten Funktion, 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.
  • Andere Alternativen, die Sie ausprobiert haben, und warum diese 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 Antworten auf weitere 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?

Die ersten Listen für Android 9 (API-Level 28) wurden durch eine statische Analyse von Apps erstellt, die mit den folgenden Methoden ergänzt wurde:

  • Manuelle Tests der beliebtesten Apps aus Google Play und anderen Quellen
  • interne Berichte
  • Automatische Datenerhebung von internen Nutzern
  • Entwicklervorschau-Berichte
  • zusätzliche statische Analyse, die so konzipiert wurde, dass sie mehr falsch positive Ergebnisse enthält

Bei der Bewertung der Listen für jede neue Version berücksichtigen wir die API-Nutzung sowie das Feedback von Entwicklern über den Issue Tracker.

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

Du kannst den Zugriff auf Nicht-SDK-Schnittstellen auf Entwicklungsgeräten aktivieren, indem du die Richtlinie zur Durchsetzung von APIs mithilfe von adb-Befehlen änderst. Die Befehle, die Sie verwenden, variieren je nach API-Ebene. 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  1
adb shell settings put global hidden_api_policy_p_apps 1

Verwenden Sie die folgenden Befehle, um die API-Erzwingungsrichtlinie auf die Standardeinstellungen zurückzusetzen:

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 Richtlinie zur Durchsetzung der API auf einen der folgenden Werte festlegen:

  • 0: Deaktiviert die Erkennung von Nicht-SDK-Schnittstellen. Wenn Sie diese Einstellung verwenden, werden alle Logeinträge für die Nutzung von Nicht-SDK-Schnittstellen deaktiviert und Sie können Ihre App nicht mit der StrictMode API testen. Diese Einstellung wird nicht empfohlen.
  • 1: Zugriff auf alle Nicht-SDK-Schnittstellen aktivieren, aber Logeinträge mit Warnungen für jede Verwendung von Nicht-SDK-Schnittstellen ausgeben. Mit dieser Einstellung können Sie Ihre App auch mit der StrictMode API testen.
  • 2: Die Verwendung von Nicht-SDK-Schnittstellen, die auf der Sperrliste stehen oder für Ihr Ziel-API-Level bedingt blockiert sind, ist nicht zulässig.

Fragen zu Listen mit Nicht-SDK-Schnittstellen

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

Sie sind in den Feld- und Methodenzugriffs-Flag-Bits in den DEX-Dateien der Plattform codiert. Im System-Image gibt es keine separate Datei, die diese Listen enthält.

Sind die Listen der Nicht-SDK-APIs auf verschiedenen OEM-Geräten mit denselben Android-Versionen identisch?

OEMs können der Sperrliste eigene Schnittstellen hinzufügen, aber keine Schnittstellen aus den AOSP-Listen für Nicht-SDK-APIs entfernen. Die CDD verhindert solche Änderungen und CTS-Tests stellen sicher, dass die Android Runtime die Liste erzwingt.

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

Das Android SDK enthält Java-Schnittstellen. Seit Android 7 (API-Level 26) wird der Zugriff auf Nicht-NDK-Schnittstellen für nativen C/C++-Code eingeschränkt. 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, aber wir beabsichtigen nicht, das DEX-Dateiformat stabil oder als öffentliche Schnittstelle über die Teile hinaus zu machen, die im Dalvik Executable-Format öffentlich spezifiziert sind. Wir behalten uns das Recht vor, dex2oat und die nicht spezifizierten Teile des DEX-Formats jederzeit zu ändern oder zu entfernen. Beachten Sie auch, dass von dex2oat erzeugte abgeleitete Dateien wie ODEX (auch als OAT bezeichnet), VDEX und CDEX alle nicht spezifizierte Formate sind.

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

Wir haben nicht vor, die Kompatibilitätsanforderungen für einzelne SDKs aufzuheben. Wenn ein SDK-Entwickler die Kompatibilität nur durch die Verwendung von Schnittstellen in den nicht unterstützten (früher grauen) Listen aufrechterhalten kann, sollte er eine Migration zu SDK-Schnittstellen oder anderen Alternativen planen 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 nehmen jedoch Apps, die mit dem Plattformschlüssel signiert sind, und einige System-Image-Apps aus. Diese Ausnahmen gelten nur für Apps, die Teil des System-Images sind (oder aktualisierte System-Image-Apps). Die Liste ist nur für Apps gedacht, die auf den privaten Plattform-APIs und nicht auf den SDK-APIs basieren (wobei LOCAL_PRIVATE_PLATFORM_APIS := true).