Android 11 ha introdotto nuovi strumenti per sviluppatori per testare ed eseguire il debug della tua app in base ai cambiamenti di comportamento nelle versioni più recenti della piattaforma Android. Questi strumenti fanno parte di un framework di compatibilità che consente agli sviluppatori di app di attivare e disattivare singolarmente le modifiche che provocano un errore utilizzando opzioni per sviluppatori o ADB. Sfrutta questa flessibilità mentre ti prepari a scegliere come target la versione stabile più recente dell'API e mentre testi la tua app con la release di anteprima della prossima versione di Android.
Quando utilizzi gli strumenti del framework di compatibilità, la piattaforma Android
adatta automaticamente la sua logica interna, quindi non devi modificare
targetSDKVersion
o ricompilare l'app per eseguire test di base. Poiché le modifiche sono attivabili singolarmente, puoi isolare, testare ed eseguire il debug di una modifica di comportamento alla volta oppure disabilitare una singola modifica che causa problemi se devi prima testare qualcos'altro.
Come identificare quali modifiche sono attivate
Quando una modifica del comportamento viene abilitata, può influire sul modo in cui l'app accede alle API della piattaforma interessate da questa modifica. Puoi controllare quali modifiche del comportamento sono abilitate utilizzando le opzioni sviluppatore, logcat o i comandi ADB.
Identificare le modifiche attivate utilizzando le opzioni sviluppatore
![](https://developer.android.com/static/images/guide/app-compatibility/appcompat-dev-options.png?authuser=6&hl=it)
Figura 1. Schermata Modifiche compatibilità app nelle Opzioni sviluppatore.
Puoi vedere quali modifiche sono abilitate e attivarle o disattivarle nelle opzioni sviluppatore di un dispositivo. Per accedere a queste opzioni, segui questi passaggi:
- Se le opzioni sviluppatore non sono già attivate, attivale.
- Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche alla compatibilità delle app.
Seleziona la tua app dall'elenco.
In genere, ciascuna modifica del comportamento appartiene a una delle due categorie seguenti:
Modifiche che interessano tutte le app eseguite sulla versione di Android in questione, indipendentemente dal valore
targetSdkVersion
dell'app.Queste modifiche sono abilitate per impostazione predefinita nel framework di compatibilità e sono elencate nella sezione Modifiche abilitate predefinite nella UI.
Modifiche che interessano solo le app destinate a determinate versioni di Android. Poiché queste modifiche riguardano solo le app che hanno come target una versione specifica di Android, sono anche definite modifiche gestite da
targetSDKVersion
.Queste modifiche sono abilitate per impostazione predefinita nel framework di compatibilità se la tua app ha come target una versione superiore rispetto alla versione API elencata. Ad esempio, una modifica del comportamento controllata da
targetSDKVersion
in Android 13 (livello API 33) viene elencata nell'interfaccia utente nella sezione Abilitata per targetSdkVersion >=33. In alcune versioni precedenti di Android, questa sezione è intitolata "Abilitata dopo l'SDK API_LEVEL".
Noterai anche una sezione nella Figura 1 chiamata Modifiche predefinite disattivate. Le modifiche che rientrano in questa sezione possono essere utili per diversi scopi. Prima di abilitare queste modifiche, leggi la descrizione della modifica nell'elenco dei framework di compatibilità per quella versione di Android.
Identificare le modifiche abilitate utilizzando Logcat
Per ogni modifica del comportamento, la prima volta durante il processo dell'app quando quest'ultima chiama l'API interessata, il sistema restituisce un messaggio logcat come il seguente:
D CompatibilityChangeReporter: Compat change id reported: 194833441; UID 10265; state: ENABLED
Ogni messaggio logcat include le seguenti informazioni:
- Modifica ID
- Indica la modifica che interessa l'app. Questo valore è mappato a una delle
modifiche di comportamento elencate nella schermata Modifiche alla compatibilità delle app
(vedi figura 1). In questo esempio,
194833441
viene mappato aNOTIFICATION_PERM_CHANGE_ID
. - UID
- Indica quale app è interessata dalla modifica.
- Stato
Indica se la modifica interessa l'app.
Lo stato può essere uno di questi valori:
Stato Significato ENABLED
La modifica è abilitata e influirà sul comportamento dell'app se quest'ultima utilizza le API che sono state modificate. DISABLED
La modifica è disattivata e non influirà sull'app.
Nota: se questa modifica viene disabilitata perché il valore
targetSDKVersion
dell'app è inferiore alla soglia richiesta, la modifica verrà attivata per impostazione predefinita quando l'app aumenta il relativotargetSDKVersion
per scegliere come target una versione superiore.LOGGED
La modifica viene registrata tramite il framework di compatibilità, ma non può essere attivata o disattivata. Questa modifica non può essere attivata/disattivata, ma potrebbe comunque influire sul comportamento della tua app. Per ulteriori informazioni, vedi la descrizione della modifica nell'elenco dei framework di compatibilità per quella versione di Android. In molti casi, questi tipi di modifiche sono sperimentali e possono essere ignorati.
Identificare le modifiche abilitate utilizzando ADB
Esegui questo comando ADB per visualizzare l'insieme completo di modifiche (sia abilitate che disabilitate) sull'intero dispositivo:
adb shell dumpsys platform_compat
Nell'output sono elencate le seguenti informazioni per ogni modifica:
- Modifica ID
- Un identificatore univoco per questa modifica del comportamento. Ad esempio,
194833441
. - Nome
- Il nome di questo comportamento è cambiato. Ad esempio,
NOTIFICATION_PERM_CHANGE_ID
. - Criteri targetSDKVersion
Quale
targetSDKVersion
è soggetto alla modifica (se presente).Ad esempio, se questa modifica viene attivata solo per le app che hanno come target la versione 33 o versioni successive dell'SDK, viene generato
enableAfterTargetSdk=32
. Se la modifica non è limitata datargetSDKVersion
, viene restituito l'outputenableAfterTargetSdk=0
.- Override pacchetto
Il nome di ogni pacchetto in cui è stato eseguito l'override dello stato predefinito della modifica (abilitato o disabilitato).
Ad esempio, se si tratta di una modifica abilitata per impostazione predefinita, il nome del pacchetto dell'app sarà elencato se hai disattivato la modifica utilizzando le opzioni sviluppatore o ADB. In questo caso, l'output sarebbe:
packageOverrides={com.my.package=false}
Le modifiche controllate da
targetSDKVersion
possono essere attivate o disabilitate per impostazione predefinita, quindi l'elenco dei pacchetti può includere istanze ditrue
ofalse
, a seconda dell'elementotargetSDKVersion
di ciascuna app. Ad esempio:packageOverrides={com.my.package=true, com.another.package=false}
Scopri di più su modifiche specifiche
L'elenco completo delle modifiche del comportamento nel framework di compatibilità è incluso nella documentazione per ogni versione di Android. Visita i seguenti link per maggiori informazioni, a seconda della versione di Android per cui stai testando la tua app:
- Android 15 (livello API 35)
- Android 14 (livello API 34)
- Android 13 (livello API 33)
- Android 12 (livelli API 31 e 32)
- Android 11 (livello API 30)
Quando attivare/disattivare le modifiche
Lo scopo principale del framework di compatibilità è offrirti controllo e flessibilità durante il test della tua app con versioni più recenti di Android. In questa sezione vengono descritte alcune strategie che puoi utilizzare per determinare quando attivare o disattivare le modifiche durante il test e il debug della tua app.
Quando disattivare le modifiche
Decidere quando disattivare le modifiche in genere dipende dal fatto che la modifica sia
limitata o meno da targetSDKVersion
.
- Modifiche attivate per tutte le app
Le modifiche che interessano tutte le app vengono attivate per impostazione predefinita per una specifica versione della piattaforma, indipendentemente dall'
targetSDKVersion
dell'app. In questo modo puoi verificare se l'app è interessata dall'esecuzione dell'app su quella versione della piattaforma.Ad esempio, se ti stai preparando a scegliere come target Android 14 (livello API 34), puoi iniziare installando l'app su un dispositivo con Android 14 e testala utilizzando i tuoi normali flussi di lavoro di test. Se l'app riscontra problemi, puoi disattivare la modifica che sta causa il problema per poter continuare a eseguire test per altri problemi.
Poiché queste modifiche possono interessare tutte le app indipendentemente da
targetSDKVersion
, in genere devi testare e aggiornare l'app per queste modifiche prima delle modifiche limitate datargetSDKVersion
. In questo modo, gli utenti non avranno un'esperienza con prestazioni ridotte nell'app quando aggiornano il dispositivo a una nuova versione della piattaforma.Dovresti anche dare la priorità al test di queste modifiche perché non puoi disattivarle quando utilizzi una build di release pubblica di Android. Idealmente, dovresti eseguire test su queste modifiche per ogni versione di Android mentre la versione è in anteprima.
- Modifiche controllate da
targetSDKVersion
Se la tua app ha come target un
targetSDKVersion
specifico, le eventuali modifiche controllate da quella versione vengono attivate per impostazione predefinita. Di conseguenza, quando passi a una nuova versione ditargetSDKVersion
, l'app inizierà a essere interessata da molte nuove modifiche contemporaneamente.Poiché la tua app potrebbe essere interessata da più di una di queste modifiche, potresti dover disattivare alcune di queste modifiche singolarmente durante il test e il debug dell'app.
Quando attivare le modifiche
Le modifiche controllate da un targetSDKVersion
specifico vengono disattivate per impostazione predefinita
ogni volta che un'app ha come target una versione dell'SDK inferiore rispetto alla versione con accesso riservato.
In genere, mentre ti prepari a scegliere come target un nuovo targetSdkVersion
, viene visualizzato un elenco di modifiche del comportamento per le quali devi testare ed eseguire il debug della tua app.
Ad esempio, potresti testare la tua app rispetto a una serie di modifiche delle piattaforme
nel prossimo targetSdkVersion
. Con le opzioni sviluppatore o i comandi ADB, potresti
abilitare e testare ogni modifica con accesso riservato una per volta, anziché modificare
il manifest dell'app e attivare ogni modifica contemporaneamente. Questo controllo aggiuntivo può aiutarti a testare le modifiche in modo isolato ed evitare il debug e l'aggiornamento di più parti della tua app contemporaneamente.
Dopo aver abilitato una modifica, puoi testare ed eseguire il debug della tua app utilizzando i tipici flussi di lavoro di test. In caso di problemi, controlla i log per determinare la causa del problema. Se non è chiaro se il problema sia causato da una modifica alla piattaforma che è stata attivata, prova a disabilitare la modifica e poi a testare nuovamente l'area dell'app.
Attiva o disattiva le modifiche
Il framework di compatibilità ti consente di attivare o disattivare ogni modifica utilizzando le opzioni per sviluppatori o i comandi ADB. Poiché l'attivazione o la disattivazione delle modifiche può causare l'arresto anomalo dell'app o la disattivazione di importanti modifiche alla sicurezza, sono previste alcune limitazioni relative all'attivazione delle modifiche.
Attiva/disattiva le modifiche utilizzando le opzioni sviluppatore
Utilizza le Opzioni sviluppatore per attivare o disattivare le modifiche. Per trovare le opzioni sviluppatore, segui questi passaggi:
- Se le opzioni sviluppatore non sono già attivate, attivale.
- Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche alla compatibilità delle app.
- Seleziona la tua app dall'elenco.
Nell'elenco delle modifiche, individua la modifica che vuoi attivare o disattivare e tocca l'opzione.
Attiva/disattiva le modifiche utilizzando ADB
Per attivare o disattivare una modifica utilizzando ADB, esegui uno dei seguenti comandi:
adb shell am compat enable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
adb shell am compat disable (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
Supera CHANGE_ID
(ad es. 194833441
) o CHANGE_NAME
(ad es. NOTIFICATION_PERM_CHANGE_ID
) e PACKAGE_NAME
.
Puoi utilizzare anche il seguente comando per ripristinare lo stato predefinito di una modifica, rimuovendo qualsiasi override impostato utilizzando ADB o le opzioni sviluppatore:
adb shell am compat reset (CHANGE_ID|CHANGE_NAME) PACKAGE_NAME
Limitazioni relative all'attivazione/disattivazione delle modifiche
Per impostazione predefinita, ogni modifica del comportamento può essere attivata o disattivata. Le modifiche che interessano tutte le app sono attive per impostazione predefinita. Le altre modifiche sono controllate da un
targetSdkVersion
. Queste modifiche sono attivate per impostazione predefinita quando un'app ha come target la versione dell'SDK corrispondente o superiore e disattivate per impostazione predefinita quando un'app ha come target una versione dell'SDK precedente alla versione riservata. Quando attivi o disattivi una modifica, viene sostituito lo stato predefinito.
Per evitare che il framework di compatibilità venga utilizzato in modo dannoso, sono previste alcune limitazioni relative a quando puoi attivare/disattivare le modifiche. La possibilità o meno di attivare o disattivare una modifica dipende dal tipo di modifica, dal fatto che la tua app sia debugbile e dal tipo di build in esecuzione sul dispositivo. La seguente tabella descrive quando puoi attivare/disattivare diversi tipi di modifiche:
Tipo di build | App non di cui non è possibile eseguire il debug | App di cui è possibile eseguire il debug | |
---|---|---|---|
Tutte le modifiche | Modifiche controllate da targetSDKVersion | Tutte le altre modifiche | |
Anteprima per sviluppatori o build beta | Impossibile attivare/disattivare | Può attivare/disattivare | Può attivare/disattivare |
Build pubblica dell'utente | Impossibile attivare/disattivare | Può attivare/disattivare | Impossibile attivare/disattivare |