Limitazioni relative alle interfacce non SDK

A partire da Android 9 (livello API 28), la piattaforma limita le tipologie non SDK interfacce utilizzabili dalla tua app. Queste limitazioni si applicano ogni volta che un'app fa riferimento un'interfaccia non SDK o tenta di ottenerne l'handle usando la riflessione o JNI. Queste limitazioni sono state messe in atto per contribuire a migliorare l'utente e lo sviluppatore esperienza utente e di ridurre i rischi di arresti anomali per gli utenti e di implementazioni di emergenza per sviluppatori. Per ulteriori informazioni su questa decisione, consulta Miglioramento della stabilità riducendo l'utilizzo di interfacce non SDK.

Distinguere tra interfacce SDK e non SDK

In generale, le interfacce pubbliche dell'SDK sono quelle documentate Indice dei pacchetti del framework Android. La gestione delle interfacce non SDK è un dei dettagli dell'implementazione che l'API astrae, pertanto queste interfacce soggetti a modifiche senza preavviso.

Per evitare arresti anomali e comportamenti imprevisti, le app devono usare soltanto lo standard parti documentate delle classi nell'SDK. Ciò significa anche che metodi di accesso o campi non elencati nell'SDK quando interagisci con utilizzando meccanismi come la riflessione.

Elenchi di API non SDK

A ogni release di Android, sono previste limitazioni per altre interfacce non SDK. Me Sappiamo che queste restrizioni possono influire sul flusso di lavoro delle release, pertanto vogliamo assicurarsi di avere gli strumenti per rilevare l'utilizzo di interfacce non SDK, la possibilità inviarci un feedback e riservarti il tempo necessario per pianificare le tue attività e adeguarti alle nuove norme.

Per ridurre al minimo l'impatto delle restrizioni non legate all'SDK sul flusso di lavoro di sviluppo, il le interfacce non SDK sono suddivise in elenchi che ne definiscono il livello di utilizzo limitato, a seconda del livello API scelto come target. La tabella seguente descrive ognuno di questi elenchi:

Elenco Tag di codice Descrizione
Lista bloccata
  • blocked
  • Obsoleto: blacklist
 Interfacce non SDK che non puoi utilizzare a prescindere dalla specifica livello API target. Se la tua app tenta di accedere a una di queste interfacce, il sistema genera un errore.
Bloccato in modo condizionale
  • max-target-x
  • Obsoleto: greylist-max-x

A partire da Android 9 (livello API 28), ogni livello API ha un livello non SDK interfacce limitate quando un'app ha come target quel livello API.

Questi elenchi sono etichettati dal livello API massimo (max-target-x) che un'app può scegliere come target prima che l'app non possa non avranno più accesso alle interfacce non SDK presenti nell'elenco. Ad esempio, un un'interfaccia non SDK che non era bloccata in Android Pie, ma che ora è bloccata in Android 10 fa parte dell'max-target-p (greylist-max-p), dove "p" è l'acronimo di "Torta" o "Android" 9 (livello API 28).

Se la tua app tenta di accedere a un'interfaccia con limitazioni per il tuo al livello API target, il sistema si comporta come se l'API fa parte la lista bloccata.
Non supportato
  • unsupported
  • Obsoleto: greylist
 Interfacce non SDK senza limitazioni e che la tua app può utilizzare. Nota tuttavia, queste interfacce non sono supportate e soggetti a modifiche senza preavviso. È probabile che queste interfacce bloccato in modo condizionale nelle future versioni di Android in un Elenco max-target-x.
SDK
  • Sia public-api che sdk
  • Obsoleto: public-api e whitelist
 Le interfacce che possono essere utilizzate liberamente e che ora sono supportate come parte framework Android documentato ufficialmente Indice del pacchetto.
Testa le API
  • test-api
 Interfacce utilizzate per i test del sistema interno, come le API che semplificare i test tramite la Compatibility Test Suite (CTS). Le API di test non fanno parte dell'SDK. Inizia da Android 11 (livello API 30), le API di test sono incluse nella lista bloccata, quindi alle app non è consentito utilizzarle indipendentemente dal livello API target. Tutti le API di test non sono supportate e sono soggette a modifiche senza preavviso a livello di API della piattaforma.

Anche se puoi utilizzare alcune interfacce non SDK (a seconda dell'API target dell'app), a livello di progetto), l'utilizzo di qualsiasi metodo o campo non SDK comporta sempre un rischio elevato di causare errori la tua app. Se la tua app si basa su interfacce non SDK, dovresti iniziare a pianificare una migrazione a interfacce dell'SDK o altre alternative. Se non riesci a trovare anziché utilizzare un'interfaccia non SDK per una funzionalità della tua app, richiedere una nuova API pubblica.

Determinare a quale elenco appartiene un'interfaccia

Gli elenchi di interfacce non SDK sono creati come parte della piattaforma. Consulta le le sezioni seguenti per informazioni su ogni release di Android.

Android 15

Per Android 15 (livello API 35), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: 40134e205e58922a708c453726b279a296e6a1f34a988abd90cec0f3432ea5a9

Per scoprire di più sulle modifiche agli elenchi delle API non SDK in Android 15, consulta gli aggiornamenti alle limitazioni relative alle interfacce non SDK in Android 15.

Android 14

Per Android 14 (livello API 34), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: 7e00db074cbe51c51ff4b411f7b48e98692951395c5c17d069c822cc1d0eae0f

Per scoprire di più sulle modifiche agli elenchi di API non SDK in Android 14, consulta gli aggiornamenti alle limitazioni relative alle interfacce non SDK in Android 14.

Android 13

Per Android 13 (livello API 33), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: 233a277aa8ac475b6df61bffd95665d86aac6eb2ad187b90bf42a98f5f2a11a3

Per scoprire di più sulle modifiche agli elenchi delle API non SDK in Android 13, incluse le alternative suggerite di API pubbliche per le API bloccati in Android 13. Consulta Aggiornamenti all'interfaccia non SDK limitazioni in Android 13.

Android 12

Per Android 12 (livello API 31), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

Per scoprire di più sulle modifiche agli elenchi di API non SDK in Android 12, incluse le alternative suggerite di API pubbliche per le API bloccati in Android 12. Consulta l'articolo Elenco delle modifiche per Android 12.

Android 11

Per Android 11 (livello API 30), puoi scaricare il seguente file descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56

Per scoprire di più sulle modifiche agli elenchi di API non SDK in Android 11, ad esempio: alternative suggerite di API pubbliche per le API bloccate in modo condizionale Android 11, vedi Elenco delle modifiche per Android 11.

Android 10

Per Android 10 (livello API 29), puoi scaricare il seguente file descrive tutte le interfacce non SDK e i relativi elenchi:

File: hiddenapi-flags.csv

Checksum SHA-256: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

Per scoprire di più sulle modifiche agli elenchi di API non SDK in Android 10, ad esempio: alternative suggerite di API pubbliche per le API bloccate in modo condizionale Android 10, vedi Elenco delle modifiche per Android 10.

Android 9

Per Android 9 (livello API 28), il seguente file di testo contiene l'elenco delle API non SDK che non sono limitate (liste grigie): hiddenapi-light-greylist.txt

La lista bloccata (blacklist) e l'elenco di API bloccate in modo condizionale (darkgrey elenco) vengono derivati al momento della build.

Genera elenchi da AOSP

Quando lavori con AOSP, puoi generare un file hiddenapi-flags.csv che contiene tutte le interfacce non SDK e i relativi elenchi. Per farlo, scarica l'origine AOSP ed esegui questo comando:

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

Potrai quindi trovare il file nel seguente percorso:

out/soong/hiddenapi/hiddenapi-flags.csv

Comportamento previsto quando si accede a interfacce non SDK limitate

La seguente tabella descrive il comportamento che puoi aspettarti se la tua app tenta di accedere a un'interfaccia non SDK che fa parte della lista bloccata.

Modalità di accesso Risultato
Istruzione Dalvik che fa riferimento a un campo NoSuchFieldError lanciato
Istruzione Dalvik che fa riferimento a un metodo NoSuchMethodError lanciato
Riflesso usando Class.getDeclaredField() o Class.getField() NoSuchFieldException lanciato
Riflesso usando Class.getDeclaredMethod(), Class.getMethod() NoSuchMethodException lanciato
Riflesso usando Class.getDeclaredFields(), Class.getFields() Membri non appartenenti all'SDK non presenti nei risultati
Riflesso usando Class.getDeclaredMethods(), Class.getMethods() Membri non appartenenti all'SDK non presenti nei risultati
JNI con env->GetFieldID() NULL restituito, NoSuchFieldError lanciato
JNI con env->GetMethodID() NULL restituito, NoSuchMethodError lanciato

Testa la tua app per verificare la presenza di interfacce non SDK

Esistono diversi metodi che puoi utilizzare per testare le interfacce non SDK in la tua app.

Test con un'app di cui è possibile eseguire il debug

Puoi testare le interfacce non SDK creando ed eseguendo un app di cui è possibile eseguire il debug su un dispositivo o un emulatore con Android 9 (livello API 28) oppure in alto. Assicurati che il dispositivo o l'emulatore che stai utilizzando corrisponda alla livello API target della tua app.

Durante l'esecuzione dei test sulla tua app, il sistema stampa un messaggio di log se accede a determinate interfacce non SDK. Puoi esaminare i messaggi di log dell'app per trovare i seguenti dettagli:

  • La classe, il nome e il tipo di dichiarazione (nel formato utilizzato dal runtime Android).
  • Mezzo di accesso: collegamento, riflessione o JNI.
  • A quale elenco appartiene l'interfaccia non SDK.

Puoi utilizzare adb logcat per accedere a questi messaggi di log, che vengono visualizzati sotto PID dell'app in esecuzione. Ad esempio, una voce nel log potrebbe essere letta come segue:

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

Esegui un test con l'API StrictMode

Puoi anche testare le interfacce non SDK utilizzando l'API StrictMode. Utilizza la detectNonSdkApiUsage per attivare questa impostazione. Dopo aver attivato il StrictMode, puoi ricevere un callback per ogni utilizzo di una versione non SDK utilizzando un'interfaccia penaltyListener, in cui puoi implementare gestione dei problemi. L'oggetto Violation fornito nel callback deriva da Throwable e l'analisi dello stack allegata fornisce il contesto dell'utilizzo.

Esegui test con lo strumento Verridex

Sul tuo APK puoi anche eseguire lo strumento di analisi statica veridex. Lo strumento Verridex scansiona l'intero codebase dell'APK, incluse eventuali librerie di terze parti, e segnala qualsiasi utilizzo delle interfacce non SDK che trova.

I limiti dello strumento Verridex includono i seguenti:

  • Non può rilevare le chiamate tramite JNI.
  • Può rilevare solo un sottoinsieme di chiamate attraverso la riflessione.
  • La sua analisi dei percorsi di codice inattivi è limitata ai controlli a livello di API.
  • Può essere eseguito solo su macchine che supportano le istruzioni SSE4.2 e POPCNT.

Windows

I file binari nativi di Windows non vengono forniti, ma puoi eseguire lo strumento veridex Windows eseguendo i file binari di Linux utilizzando il sottosistema Windows per Linux (WSL). Prima di seguire la procedura descritta in questa sezione, installa la WSL e scegli Ubuntu come distribuzione Linux.

Dopo aver installato Ubuntu, avvia un terminale Ubuntu e segui questi passaggi:

  1. Scarica lo strumento Vertex dal runtime Android predefinito repository Git.
  2. Estrai i contenuti del file appcompat.tar.gz.
  3. Nella cartella estratta, individua il file veridex-linux.zip ed estrailo.

  4. Passa alla cartella decompressa ed esegui questo comando, your-app.apk è l'APK che vuoi testare:

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

macOS

Per eseguire lo strumento Verridex su macOS, segui questi passaggi:

  1. Scarica lo strumento Vertex dal runtime Android predefinito repository Git.
  2. Estrai i contenuti del file appcompat.tar.gz.
  3. Nella cartella estratta, individua il file veridex-mac.zip ed estrailo.

  4. Passa alla cartella decompressa ed esegui questo comando, /path-from-root/your-app.apk è il percorso dell'APK che vuoi testare, a partire dalla directory radice del sistema:

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

Linux

Per eseguire lo strumento veridex su Linux, attieniti alla seguente procedura:

  1. Scarica lo strumento Vertex dal runtime Android predefinito repository Git.
  2. Estrai i contenuti del file appcompat.tar.gz.
  3. Nella cartella estratta, individua il file veridex-linux.zip ed estrailo.

  4. Passa alla cartella decompressa ed esegui questo comando, your-app.apk è l'APK che vuoi testare:

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

Esegui test con lo strumento Lint di Android Studio

Ogni volta che crei la tua app in Android Studio, lo strumento Lint controlla le tue per individuare potenziali problemi. Se la tua app utilizza interfacce non SDK, potresti notare generare errori o avvisi, a seconda dell'elenco a cui appartengono le interfacce a.

Puoi anche eseguire lo strumento Lint dalla riga di comando o eseguire ispezioni manualmente su un progetto, una cartella o un file specifici.

Eseguire test con Play Console

Quando carichi l'app in un canale di test in Play Console, l'app viene testato automaticamente per individuare potenziali problemi e viene visualizzato un report pre-lancio generati. Se la tua app utilizza interfacce non SDK, viene visualizzato un errore o un avviso in Il report pre-lancio, a seconda dell'elenco a cui appartengono queste interfacce.

Per ulteriori informazioni, consulta la sezione Compatibilità Android in Utilizzare pre-lancio i report per identificare i problemi.

Richiedi una nuova API pubblica

Se non riesci a trovare un'alternativa all'utilizzo di un'interfaccia non SDK per una funzionalità in la tua app, puoi richiedere una nuova API pubblica creando una richiesta di funzionalità nel nostro Issue Tracker.

Quando crei una richiesta di funzionalità, fornisci le seguenti informazioni:

  • L'API non supportata in uso, incluso il descrittore completo il messaggio logcat Accessing hidden ....
  • Perché è necessario utilizzare queste API, inclusi i dettagli sull'implementazione funzionalità per cui l'API è necessaria, non solo i dettagli di basso livello.
  • Perché eventuali API SDK pubbliche correlate non sono sufficienti per i tuoi scopi.
  • Altre alternative che hai provato e perché non hanno funzionato.

Se fornisci questi dettagli nella tua richiesta di funzione, aumenti il probabilità che venga concessa una nuova API pubblica.

Altre domande

Questa sezione include alcune risposte ad altre domande poste dagli sviluppatori domande frequenti:

Domande di carattere generale

In che modo Google può assicurarsi di soddisfare le esigenze di tutte le app con il tracker dei problemi?

Abbiamo creato gli elenchi iniziali per Android 9 (livello API 28) tramite delle app che sono state integrate utilizzando i seguenti metodi:

  • test manuale delle principali app Google Play e non Google Play
  • report interni
  • raccolta automatica dei dati degli utenti interni
  • report sulle anteprime per sviluppatori
  • un'ulteriore analisi statica progettata per includere in modo conservativo falsi positivi

Durante la valutazione degli elenchi per ogni nuova release, teniamo conto dell'utilizzo dell'API come oltre al feedback degli sviluppatori tramite lo strumento Issue Tracker.

Come faccio ad attivare l'accesso a interfacce non SDK?

Puoi attivare l'accesso a interfacce non SDK sui dispositivi di sviluppo utilizzando ADB per modificare il criterio di applicazione forzata delle API. I comandi che utilizzi variano, a seconda del livello API. Questi comandi non richiedono un dispositivo rooted.

Android 10 (livello API 29) o versioni successive

Per abilitare l'accesso, usa il seguente ADB

:

adb shell settings put global hidden_api_policy  1

Per reimpostare le impostazioni predefinite del criterio di applicazione forzata delle API, utilizza la seguente comando:

adb shell settings delete global hidden_api_policy
Android 9 (livello API 28)

Per abilitare l'accesso, utilizza i seguenti comandi adb:

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

Per reimpostare le impostazioni predefinite del criterio di applicazione forzata delle API, utilizza la seguenti comandi:

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

Puoi impostare il numero intero nel criterio di applicazione delle API su uno dei seguenti valori: valori:

  • 0: disattiva tutto il rilevamento delle interfacce non SDK. L'uso di questa impostazione disattiva tutti i messaggi di log per l'utilizzo di un'interfaccia non SDK e ti impedisce di testare utilizzando l'API StrictMode. Questa impostazione non è consigliata.
  • 1: Abilita l'accesso a tutte le interfacce non SDK, ma stampa i messaggi di log con per qualsiasi utilizzo di un'interfaccia non SDK. L'uso di questa impostazione ti consente anche Testa l'app utilizzando l'API StrictMode.
  • 2: Non consentire l'utilizzo di interfacce non SDK che appartengono alla lista bloccata o che sono bloccato in modo condizionale per il livello API target.

Domande sugli elenchi di interfacce non SDK

Dove posso trovare gli elenchi delle API non SDK nell'immagine di sistema?

Sono codificati nei bit dei flag di accesso al campo e al metodo nei file dex della piattaforma. Non esiste un file separato nell'immagine di sistema contenente questi elenchi.

Gli elenchi delle API non SDK sono gli stessi su dispositivi OEM diversi con le stesse versioni di Android?

Gli OEM possono aggiungere le proprie interfacce alla lista bloccata, ma non possono Rimuovere le interfacce dagli elenchi di API non SDK AOSP. Il CDD impedisce tali modifiche e i test CTS assicurano che l'elenco venga applicato da Android Runtime.

Esistono limitazioni per le interfacce non NDK nel codice nativo?

L'SDK per Android include interfacce Java. La piattaforma ha iniziato a applicare limitazioni Accesso a interfacce non NDK per il codice C/C++ nativo in Android 7 (livello API 26). Per ulteriori informazioni, vedi Migliorare la stabilità con il simbolo privato C/C++ Limitazioni in Android N.

Esiste un piano per limitare la manipolazione di file DEX o dex2oat?

Non abbiamo in programma di limitare l'accesso al file binario dex2oat, ma non intendiamo che il formato file DEX sia stabile o che venga utilizzata un'interfaccia pubblica le parti specificate pubblicamente nel formato Dalvik Executable. Ci riserviamo il diritto di modificare o eliminare dex2oat e le parti non specificate del formato DEX in qualsiasi momento. Tieni inoltre presente che i file derivati prodotti da dex2oat come ODEX (noto anche come OAT), VDEX e CDEX sono tutti formati non specificati.

Cosa succede se un SDK di terze parti fondamentale (ad esempio un offuscato) non può evitare di utilizzare interfacce non SDK, ma si impegna a mantenere la compatibilità con le versioni di Android future? In questo caso Android può rinunciare ai requisiti di compatibilità?

Non prevediamo di rinunciare ai requisiti di compatibilità in base al singolo SDK. Se uno sviluppatore di SDK può mantenere la compatibilità solo a seconda delle interfacce in per gli elenchi non supportati (in grigio), dovrebbero iniziare a pianificare una migrazione verso interfacce dell'SDK o altre alternative e richiedi una nuova API pubblica ogni volta che non riescono a trovare un'alternativa all'utilizzo di un'interfaccia non SDK.

Le limitazioni relative all'interfaccia non SDK si applicano a tutte le app, incluse quelle di sistema e proprietarie, non solo alle app di terze parti?

Sì. Tuttavia, sono escluse le app firmate con la chiave della piattaforma e un'immagine di sistema app. Tieni presente che queste esenzioni si applicano solo alle app che fanno parte del sistema (o app per immagini di sistema aggiornate). L'elenco è destinato solo alle app che sulla base delle API della piattaforma privata, anziché delle API SDK (dove LOCAL_PRIVATE_PLATFORM_APIS := true).