Limitazioni relative alle interfacce non SDK

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 introdotte 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 saperne di più su questa decisione, consulta Miglioramento della stabilità tramite la riduzione dell'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 nell'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 altre interfacce non SDK. Sappiamo che queste limitazioni possono influire sul tuo flusso di lavoro di rilascio e vogliamo assicurarci che tu abbia gli strumenti per rilevare l'utilizzo di interfacce non SDK, l'opportunità di fornirci un feedback e il tempo per pianificare e adattarti alle nuove norme.

Per ridurre al minimo l'impatto delle limitazioni relative alle interfacce non SDK sul tuo flusso di lavoro di sviluppo, le interfacce non SDK sono suddivise in elenchi che definiscono il livello di restrizione del loro utilizzo, a seconda del livello API scelto come target. La tabella seguente descrive ciascuno di questi elenchi:

Elenco Tag di codice Descrizione
Lista bloccata
  • blocked
  • Ritirato: blacklist
 Interfacce non SDK che non puoi utilizzare indipendentemente dal livello API target della tua app. Se la tua app tenta di accedere a una di queste interfacce, il sistema genera un errore.
Blocco condizionale
  • max-target-x
  • Ritirato: greylist-max-x

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

Questi elenchi sono etichettati in base al livello API massimo (max-target-x) che un'app può scegliere come target prima di non poter più accedere alle interfacce non SDK nell'elenco. Ad esempio, un'interfaccia non SDK che non era bloccata in Android Pie, ma che ora è bloccata in Android 10, fa parte dell'elenco max-target-p (greylist-max-p), dove "p" sta per Pie o Android 9 (livello API 28).

Se la tua app tenta di accedere a un'interfaccia limitata per il tuo livello API target, il sistema si comporta come se l'API facesse parte della lista bloccata.
Non supportato
  • unsupported
  • Ritirato: greylist
 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. Queste interfacce verranno bloccate in modo condizionale nelle future versioni di Android in un elenco max-target-x.
SDK
  • Sia public-api che sdk
  • Deprecato: sia public-api che whitelist
 Interfacce che possono essere utilizzate liberamente e che ora sono supportate nell'ambito dell'indice dei pacchetti del framework Android documentato ufficialmente.
API di test
  • test-api
 Interfacce utilizzate per i test interni del sistema, ad esempio API che facilitano i test tramite la 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 possono utilizzarle indipendentemente dal livello API target. Tutte le API di test non sono supportate e sono soggette a modifiche senza preavviso, indipendentemente dal livello API della piattaforma.

Sebbene sia possibile utilizzare alcune interfacce non SDK (a seconda del livello API target dell'app), l'utilizzo di qualsiasi metodo o campo non SDK comporta sempre un rischio elevato 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.

Determina a quale elenco appartiene un'interfaccia

Gli elenchi di interfacce non SDK vengono creati come parte della piattaforma. Per informazioni su ogni release di Android, consulta le sezioni seguenti.

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 delle API non SDK in Android 16, consulta Aggiornamenti alle limitazioni relative alle 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 delle 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 delle API non SDK in Android 14, consulta 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 all'elenco di API non SDK in Android 13, incluse le alternative alle 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 corrispondenti:

File: hiddenapi-flags.csv

Checksum SHA-256: 40674ff4291eb268f86561bf687e69dbd013df9ec9531a460404532a4ac9a761

Per scoprire di più sulle modifiche all'elenco delle API non SDK in Android 12, incluse le alternative alle 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 delle API non SDK in Android 11, incluse le alternative alle 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 corrispondenti:

File: hiddenapi-flags.csv

Checksum SHA-256: f22a59c215e752777a114bd9b07b0b6b4aedfc8e49e6efca0f99681771c5bfeb

Per scoprire di più sulle modifiche all'elenco delle API non SDK in Android 10, incluse le alternative alle 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 che non sono limitate (inserite nella lista grigia): hiddenapi-light-greylist.txt.

La lista bloccata (blacklist) e l'elenco delle API bloccate in modo condizionale (lista grigio scuro) vengono derivati in fase di 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 corrispondenti. Per farlo, scarica il codice sorgente AOSP, quindi esegui questo comando:

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 limitate

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

Mezzi di accesso Risultato
Istruzione Dalvik che fa riferimento a un campo NoSuchFieldError lanciato
Istruzione Dalvik che fa riferimento a un metodo NoSuchMethodError lanciato
Riflessione con Class.getDeclaredField() o Class.getField() NoSuchFieldException lanciato
Riflessione con Class.getDeclaredMethod(), Class.getMethod() NoSuchMethodException lanciato
Riflessione con Class.getDeclaredFields(), Class.getFields() I membri non SDK non sono inclusi nei risultati
Riflessione con Class.getDeclaredMethods(), Class.getMethods() I membri non SDK non sono inclusi nei risultati
JNI con env->GetFieldID() NULL restituito, NoSuchFieldError generato
JNI con env->GetMethodID() NULL restituito, NoSuchMethodError generato

Esegui 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.

Esegui i test utilizzando un'app abilitata al debug

Puoi testare le interfacce non SDK creando ed eseguendo un'app abilitata al debug su un dispositivo o un emulatore con Android 9 (livello API 28) o versioni successive. Assicurati che il dispositivo o l'emulatore che utilizzi corrisponda al livello API target della tua app.

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

  • La classe, il nome e il tipo di dichiarazione (nel formato utilizzato da Android Runtime).
  • I mezzi 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 simile alla seguente:

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

Esegui i test utilizzando l'API StrictMode

Puoi anche eseguire test per le interfacce non SDK utilizzando l'API StrictMode. Utilizza il metodo detectNonSdkApiUsage per attivarlo. Dopo aver attivato 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'oggetto Violation fornito nel callback deriva da Throwable e l'analisi dello stack allegata fornisce il contesto di utilizzo.

Esegui i test utilizzando lo strumento lint di Android Studio

Ogni volta che crei la tua app in Android Studio, lo strumento lint ispeziona il codice per individuare potenziali problemi. Se la tua app utilizza interfacce non SDK, potresti visualizzare errori o avvisi di build, a seconda dell'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.

Esegui i test utilizzando Play Console

Quando carichi la tua app su un canale di test in Play Console, l'app viene testata automaticamente per rilevare 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 le interfacce.

Per saperne di più, consulta la sezione Compatibilità con Android in Utilizza i report pre-lancio 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à 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:

  • Quale API non supportata stai utilizzando, incluso il descrittore completo visualizzato nel messaggio logcat Accessing hidden ....
  • Perché devi utilizzare queste API, inclusi i dettagli sulla funzionalità di alto livello per cui l'API è necessaria, non solo i dettagli di basso livello.
  • Perché le API SDK pubbliche correlate non sono sufficienti per i tuoi scopi.
  • Eventuali altre alternative che hai provato e il motivo per cui non hanno 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 frequenti degli sviluppatori:

Domande di carattere generale

In che modo Google può essere certa di poter soddisfare le esigenze di tutte le app tramite Issue Tracker?

Abbiamo creato gli elenchi iniziali per Android 9 (livello API 28) tramite l'analisi statica delle app, integrata utilizzando i seguenti metodi:

  • test manuali delle principali app di Google Play e non
  • report interni
  • raccolta automatica dei dati degli utenti interni
  • report di Anteprima per gli sviluppatori
  • un'analisi statica aggiuntiva progettata per includere in modo conservativo più falsi positivi

Quando valutiamo gli elenchi per ogni nuova release, prendiamo in considerazione l'utilizzo delle API e il feedback degli sviluppatori tramite Issue Tracker.

Come faccio ad attivare 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 relative all'applicazione delle norme relative alle 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 attivare l'accesso, utilizza il seguente comando adb

command:

adb shell settings put global hidden_api_policy  1

Per ripristinare le impostazioni predefinite della policy di applicazione delle norme relative all'API, utilizza il seguente comando:

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

Per attivare 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 ripristinare le impostazioni predefinite della policy di applicazione delle norme relative all'API, utilizza i 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 l'intero nella policy di applicazione delle norme dell'API su uno dei seguenti valori:

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

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 ai campi e ai metodi nei file dex della piattaforma. Nell'immagine di sistema non esiste un file separato che contiene 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 (blacklist), ma non possono rimuovere le interfacce dagli elenchi di API non SDK di AOSP. Il CDD impedisce queste modifiche e i test CTS garantiscono che Android Runtime applichi l'elenco.

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 saperne di più, consulta Miglioramento della stabilità con le limitazioni dei simboli C/C++ privati in Android N.

È previsto un piano per limitare la manipolazione dei file dex2oat o DEX?

Non abbiamo piani attivi per limitare l'accesso al file binario dex2oat, ma non intendiamo rendere stabile il formato file DEX o un'interfaccia pubblica oltre alle 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 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 fondamentale (ad esempio un offuscatore) non può evitare di utilizzare interfacce non SDK, ma si impegna a mantenere la compatibilità con le versioni future di Android? Android può rinunciare ai suoi requisiti di compatibilità in questo caso?

Non abbiamo in programma di rinunciare ai requisiti di compatibilità per ogni SDK. Se uno sviluppatore di SDK può mantenere la compatibilità solo basandosi su interfacce negli elenchi non supportati (precedentemente grigi), 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 relative alle interfacce non SDK si applicano a tutte le app, incluse quelle di sistema e proprietarie, non solo alle app di terze parti?

Sì, tuttavia sono esenti le app firmate con la platform key e alcune app di immagini di sistema. Tieni presente che queste esenzioni si applicano solo alle app che fanno parte dell'immagine di sistema (o alle app di immagini di sistema aggiornate). L'elenco è destinato solo alle app che si basano sulle API della piattaforma privata, anziché sulle API SDK (dove LOCAL_PRIVATE_PLATFORM_APIS := true).