A partire da Android 9 (livello API 28), la piattaforma limita le interfacce non SDK che la tua app può utilizzare. Queste limitazioni si applicano ogni volta che un'app fa riferimento a un'interfaccia non SDK o tenta di ottenere il relativo handle utilizzando la riflessione o JNI. Queste limitazioni sono state implementate per contribuire a migliorare l'esperienza utente e degli sviluppatori e ridurre i rischi di arresti anomali per gli utenti e di implementazioni di emergenza per gli sviluppatori. Per ulteriori informazioni su questa decisione, consulta Migliorare la stabilità riducendo l'utilizzo di interfacce non SDK.
Distinguere tra interfacce SDK e non SDK
In generale, le interfacce SDK pubbliche sono quelle documentate nell' indice dei pacchetti del framework Android. La gestione delle interfacce non SDK è un dettaglio di implementazione che l'API astrae, pertanto queste interfacce sono soggette a modifiche senza preavviso.
Per evitare arresti anomali e comportamenti imprevisti, le app devono utilizzare solo le parti delle classi dell'SDK documentate ufficialmente. Ciò significa anche che non devi accedere a metodi o campi non elencati nell'SDK quando interagisci con una classe utilizzando meccanismi come la riflessione.
Elenchi di API non SDK
Con ogni release di Android, vengono limitate ulteriori interfacce non SDK. Sappiamo che queste limitazioni possono influire sul flusso di lavoro di rilascio e vogliamo assicurarci che tu disponga degli strumenti per rilevare l'utilizzo di interfacce non SDK, di un'opportunità per fornirci feedback e del tempo per pianificare e adattarti alle nuove norme.
Per ridurre al minimo l'impatto delle limitazioni non SDK sul flusso di lavoro di sviluppo, le interfacce non SDK sono suddivise in elenchi che definiscono la rigidità delle limitazioni del loro utilizzo, a seconda del livello API di destinazione. La tabella seguente descrive ciascuno di questi elenchi:
| Elenco | Tag di codice | Descrizione |
|---|---|---|
| Lista bloccata |
|
Interfacce non SDK che non puoi utilizzare indipendentemente dal livello API di destinazione della tua app . Se la tua app tenta di accedere a una di queste interfacce, il sistema genera un errore. |
| Bloccato in modo condizionale |
|
A partire da Android 9 (livello API 28), ogni livello API ha interfacce non SDK con limitazioni quando un'app ha come target quel livello API. Questi elenchi sono etichettati con il livello API massimo
( Se la tua app tenta di accedere a un'interfaccia con limitazioni per il livello API di destinazione, il sistema si comporta come se l'API facesse parte della lista bloccata. |
| Non supportato |
|
Interfacce non SDK senza limitazioni che la tua app può utilizzare. Tieni presente
tuttavia, che queste interfacce non sono supportate e
sono soggette a modifiche senza preavviso. È previsto che queste interfacce vengano
bloccate in modo condizionale nelle future versioni di Android in un
max-target-x elenco. |
| SDK |
|
Interfacce che possono essere utilizzate liberamente e ora sono supportate come parte del framework Android documentato ufficialmente indice dei pacchetti. |
| API di test |
|
Interfacce utilizzate per i test di sistema interni, ad esempio le API che facilitano i test tramite Compatibility Test Suite (CTS). Le API di test non fanno parte dell'SDK. A partire da Android 11 (livello API 30), le API di test sono incluse nella lista bloccata, pertanto le app non sono autorizzate a utilizzarle indipendentemente dal livello API di destinazione. Tutte le API di test non sono supportate e sono soggette a modifiche senza preavviso, indipendentemente dal livello API della piattaforma. |
Sebbene tu possa utilizzare alcune interfacce non SDK (a seconda del livello API di destinazione della tua app), l'utilizzo di qualsiasi metodo o campo non SDK comporta sempre un elevato rischio di interruzione dell'app. Se la tua app si basa su interfacce non SDK, devi iniziare a pianificare una migrazione alle interfacce SDK o ad altre alternative. Se non riesci a trovare un alternativa all'utilizzo di un'interfaccia non SDK per una funzionalità della tua app, devi richiedere una nuova API pubblica.
Determinare a quale elenco appartiene un'interfaccia
Gli elenchi di interfacce non SDK fanno parte della piattaforma. Consulta le sezioni seguenti per informazioni su ogni release di Android.
Android 16
Per Android 16 (livello API 36), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:
File: hiddenapi-flags.csv
Checksum SHA-256:
9102af02fe6ab68b92464bdff5e5b09f3bd62c65d1130aaf85d3296f17d38074
Per scoprire di più sulle modifiche all'elenco di API non SDK in Android 16, consulta Aggiornamenti alle limitazioni delle interfacce non SDK in Android 16.
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 all'elenco di API non SDK in Android 15, consulta Aggiornamenti alle limitazioni delle 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 all'elenco di API non SDK in Android 14, consulta Aggiornamenti alle limitazioni delle 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 all'elenco di API non SDK in Android 13, incluse le alternative di API pubbliche suggerite per le API bloccate in modo condizionale in Android 13, consulta Aggiornamenti alle limitazioni delle interfacce non SDK 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 all'elenco di API non SDK in Android 12, incluse le alternative di API pubbliche suggerite per le API bloccate in modo condizionale in Android 12, consulta Modifiche all'elenco per Android 12.
Android 11
Per Android 11 (livello API 30), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:
File: hiddenapi-flags.csv
Checksum SHA-256:
a19d839f4f61dc9c94960ae977b2e0f3eb30f880ba1ffe5108e790010b477a56
Per scoprire di più sulle modifiche all'elenco di API non SDK in Android 11, incluse alternative di API pubbliche suggerite per le API bloccate in modo condizionale in Android 11, consulta Modifiche all'elenco per Android 11.
Android 10
Per Android 10 (livello API 29), puoi scaricare il seguente file che descrive tutte le interfacce non SDK e i relativi elenchi:
File: hiddenapi-flags.csv
Checksum SHA-256:
f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb
Per scoprire di più sulle modifiche all'elenco di API non SDK in Android 10, incluse le alternative di API pubbliche suggerite per le API bloccate in modo condizionale in Android 10, consulta Modifiche all'elenco per Android 10.
Android 9
Per Android 9 (livello API 28), il seguente file di testo contiene l'elenco delle
API non SDK senza limitazioni (in grigio):
hiddenapi-light-greylist.txt.
La lista bloccata (blacklist) e l'elenco delle API bloccate in modo condizionale (elenco in grigio scuro
) vengono derivati al momento della creazione.
Generare 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 il comando seguente:
m out/soong/hiddenapi/hiddenapi-flags.csv
Puoi trovare il file nella seguente posizione:
out/soong/hiddenapi/hiddenapi-flags.csv
Comportamento previsto quando si accede a interfacce non SDK con limitazioni
La tabella seguente descrive il comportamento previsto se la tua app tenta di accedere a un'interfaccia non SDK che fa parte della lista bloccata.
| Mezzo di accesso | Risultato |
|---|---|
| Istruzione Dalvik che fa riferimento a un campo | NoSuchFieldError generato |
| Istruzione Dalvik che fa riferimento a un metodo | NoSuchMethodError generato |
Riflessione che utilizza Class.getDeclaredField() o Class.getField() |
Viene generato NoSuchFieldException |
Riflessione che utilizza Class.getDeclaredMethod(), Class.getMethod() |
NoSuchMethodException generato |
Riflessione che utilizza Class.getDeclaredFields(), Class.getFields() |
I membri non SDK non sono inclusi nei risultati |
Riflessione che utilizza Class.getDeclaredMethods(), Class.getMethods() |
I membri non SDK non sono inclusi nei risultati |
JNI che utilizza env->GetFieldID() |
NULL restituito, NoSuchFieldError generato |
JNI che utilizza env->GetMethodID() |
NULL restituito, NoSuchMethodError generato |
Eseguire il test della tua app per le interfacce non SDK
Esistono diversi metodi che puoi utilizzare per testare le interfacce non SDK nella tua app.
Eseguire il test utilizzando 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 che esegue Android 9 (livello API 28) o versioni successive. Assicurati che il dispositivo o l'emulatore che stai utilizzando corrisponda al livello API di destinazione della tua app.
Durante l'esecuzione dei test sull'app, il sistema stampa un messaggio di log se la tua app accede a determinate interfacce non SDK. Puoi esaminare i messaggi di log dell'app per trovare i seguenti dettagli:
- La classe dichiarante, il nome e il tipo (nel formato utilizzato dal runtime Android).
- Il mezzo di accesso: collegamento, utilizzo della riflessione o utilizzo di JNI.
- L'elenco a cui appartiene l'interfaccia non SDK.
Puoi utilizzare adb logcat per accedere a questi messaggi di log, che vengono visualizzati sotto il
PID dell'app in esecuzione. Ad esempio, una voce nel log potrebbe essere la seguente:
Accessing hidden field Landroid/os/Message;->flags:I (light greylist, JNI)
Eseguire il test utilizzando l'API StrictMode
Puoi anche testare le interfacce non SDK utilizzando l'API StrictMode. Utilizza il
detectNonSdkApiUsage metodo per abilitarla. Dopo aver abilitato l'API
StrictMode, puoi ricevere un callback per ogni utilizzo di un'interfaccia non SDK
utilizzando un penaltyListener, in cui puoi implementare la gestione personalizzata. L'Violation oggetto fornito nel callback deriva da
Throwable e l'analisi dello stack inclusa fornisce il contesto dell'utilizzo.
Eseguire il test utilizzando lo strumento lint di Android Studio
Ogni volta che crei la tua app in Android Studio, lo strumento lint ispeziona il tuo codice per individuare potenziali problemi. Se la tua app utilizza interfacce non SDK, potresti visualizzare errori o avvisi di compilazione, a seconda di quale elenco a cui appartengono queste interfacce.
Puoi anche eseguire lo strumento lint dalla riga di comando o eseguire le ispezioni manualmente su un progetto, una cartella o un file specifico.
Eseguire il test utilizzando Play Console
Quando carichi la tua app in un canale di test in Play Console, l'app viene testata automaticamente per individuare potenziali problemi e viene generato un report pre-lancio. Se la tua app utilizza interfacce non SDK, nel report pre-lancio viene visualizzato un errore o un avviso, a seconda dell'elenco a cui appartengono queste interfacce.
Per ulteriori informazioni, consulta la sezione Compatibilità con Android in Utilizzare i report pre-lancio per identificare i problemi.
Richiedere una nuova API pubblica
Se non riesci a trovare un'alternativa all'utilizzo di un'interfaccia non SDK per una funzionalità della 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 che stai utilizzando, incluso il descrittore completo visualizzato in
nel
Accessing hidden ...messaggio logcat. - Il motivo per cui devi utilizzare queste API, inclusi i dettagli sulla funzionalità di alto livello per cui l'API è necessaria, non solo i dettagli di basso livello.
- Il motivo per cui le API SDK pubbliche correlate non sono sufficienti per i tuoi scopi.
- Qualsiasi altra alternativa che hai provato e il motivo per cui non ha funzionato.
Se fornisci questi dettagli nella richiesta di funzionalità, aumenti la probabilità che venga concessa una nuova API pubblica.
Altre domande
Questa sezione include alcune risposte ad altre domande che gli sviluppatori hanno posto di frequente:
Domande di carattere generale
Come può Google essere certa di poter soddisfare le esigenze di tutte le app tramite l'issue tracker?
Abbiamo creato gli elenchi iniziali per Android 9 (livello API 28) tramite l'analisi statica delle app, integrata con i seguenti metodi:
- Test manuali delle principali app di Play e non Play
- Report interni
- Raccolta automatica dei dati dagli utenti interni
- Report di anteprima per sviluppatori
- Analisi statica aggiuntiva progettata per includere in modo conservativo più falsi positivi
Quando valutiamo gli elenchi per ogni nuova release, teniamo conto dell'utilizzo delle API e del feedback degli sviluppatori tramite l'issue tracker.
Come posso abilitare l'accesso alle interfacce non SDK?
Puoi abilitare l'accesso alle interfacce non SDK sui dispositivi di sviluppo utilizzando i comandi adb per modificare le norme di applicazione delle API. I comandi che utilizzi variano, a seconda del livello API. Questi comandi non richiedono un dispositivo con accesso root.
- Android 10 (livello API 29) o versioni successive
Per abilitare l'accesso, utilizza il seguente comando adb:
Per reimpostare le norme di applicazione delle API sulle impostazioni predefinite, utilizza il comando seguente:
adb shell settings put global hidden_api_policy 1
Per ripristinare le impostazioni predefinite della policy di applicazione dell'API, utilizza il 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 1adb shell settings put global hidden_api_policy_p_apps 1Per reimpostare le norme di applicazione delle API sulle impostazioni predefinite, utilizza i comandi seguenti:
adb shell settings delete global hidden_api_policy_pre_p_appsadb shell settings delete global hidden_api_policy_p_apps
Puoi impostare l'intero nelle norme di applicazione delle API su uno dei seguenti valori:
- 0: disabilita il rilevamento di tutte le interfacce non SDK. L'utilizzo di questa impostazione disabilita
tutti i messaggi di log per l'utilizzo di interfacce non SDK e impedisce di testare la tua
app utilizzando l'API
StrictMode. Questa impostazione non è consigliata. - 1: abilita l'accesso a tutte le interfacce non SDK, ma stampa messaggi di log con
avvisi per qualsiasi utilizzo di interfacce non SDK. L'utilizzo di questa impostazione ti consente anche di
testare l'app utilizzando l'API
StrictMode. - 2: non consente l'utilizzo di interfacce non SDK che appartengono alla lista bloccata o sono bloccate in modo condizionale per il livello API di destinazione.
Domande sugli elenchi di interfacce non SDK
Dove posso trovare gli elenchi di API non SDK nell'immagine di sistema?
Sono codificati nei bit dei flag di accesso a campi e metodi nei file dex della piattaforma. Non esiste un file separato nell'immagine di sistema che contenga questi elenchi.
Gli elenchi di 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 di AOSP. Il CDD impedisce queste modifiche e i test CTS assicurano che Android Runtime applichi l'elenco.
Domande sulla compatibilità delle app correlate
Esistono limitazioni per le interfacce non NDK nel codice nativo?
L'SDK Android include interfacce Java. La piattaforma ha iniziato a limitare l'accesso alle interfacce non NDK per il codice C/C++ nativo in Android 7 (livello API 26). Per ulteriori informazioni, consulta Migliorare la stabilità con le limitazioni dei simboli C/C++ privati in Android N.
È previsto un piano per limitare la manipolazione di dex2oat o dei file DEX?
Non abbiamo piani attivi per limitare l'accesso al file binario dex2oat, ma non intendiamo che il formato del file DEX sia stabile o un'interfaccia pubblica oltre le parti specificate pubblicamente nel formato eseguibile Dalvik. Ci riserviamo il diritto di modificare o eliminare dex2oat e le parti non specificate del formato DEX in qualsiasi momento. Tieni presente inoltre 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 cruciale (ad esempio, un offuscatore) non può evitare di utilizzare interfacce non SDK, ma si impegna a mantenere la compatibilità con le future versioni di Android? In questo caso, Android può rinunciare ai requisiti di compatibilità?
Non abbiamo in programma di rinunciare ai requisiti di compatibilità in base all'SDK. Se uno sviluppatore di SDK può mantenere la compatibilità solo facendo affidamento sulle interfacce negli elenchi non supportati (in precedenza in grigio), deve iniziare a pianificare una migrazione alle interfacce SDK o ad altre alternative e richiedere una nuova API pubblica ogni volta che non riesce a trovare un'alternativa all'utilizzo di un'interfaccia non SDK.
Le limitazioni delle interfacce non SDK si applicano a tutte le app, incluse le app di sistema e proprietarie, non solo alle app di terze parti?
Sì, tuttavia, esentiamo le app firmate con la platform key e alcune app dell'immagine di sistema
Tieni presente che queste esenzioni si applicano solo alle app che fanno parte dell'immagine di sistema (o alle app dell'immagine di sistema aggiornate). L'elenco è destinato solo alle app che
vengono create in base alle API della piattaforma privata, anziché alle API SDK (dove
LOCAL_PRIVATE_PLATFORM_APIS := true).