Strumenti del framework di compatibilità

Android 11 ha introdotto nuovi strumenti per sviluppatori per testare e eseguire il debug della tua app in base alle modifiche del 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 causano interruzioni utilizzando le opzioni sviluppatore o ADB. Utilizza questa flessibilità mentre ti prepari a scegliere come target la versione stabile dell'API più recente 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 propria logica interna, quindi non devi modificare il targetSDKVersion o ricompilare l'app per eseguire test di base. Poiché le modifiche sono attivabili singolarmente, puoi isolare, testare e eseguire il debug di una variazione del comportamento alla volta o disattivare una singola modifica che causa problemi se devi prima testare qualcos'altro.

Come identificare le modifiche attivate

Quando una modifica del comportamento è attiva, può influire sulla modalità di accesso della tua app alle API di piattaforma interessate dalla modifica. Puoi controllare quali modifiche al comportamento sono attivate utilizzando le opzioni per gli sviluppatori, logcat o i comandi ADB.

Identificare le modifiche attivate utilizzando le opzioni sviluppatore

Figura 1. Schermata Modifiche di compatibilità dell'app nelle opzioni sviluppatore.

Puoi vedere quali modifiche sono attivate e attivarle o disattivarle nelle opzioni sviluppatore di un dispositivo. Per accedere a queste opzioni:

  1. Se le Opzioni sviluppatore non sono già attive, attivale.
  2. Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche alla compatibilità delle app.

  3. Seleziona l'app dall'elenco.

Ogni variazione di comportamento di solito rientra in una delle due seguenti categorie:

  • Modifiche che interessano tutte le app che funzionano su quella versione di Android, indipendentemente dal targetSdkVersion dell'app.

    Queste modifiche sono attivate per impostazione predefinita nel framework di compatibilità e sono elencate nell'interfaccia utente nella sezione Modifiche attive per impostazione predefinita.

  • Modifiche che interessano solo le app che hanno come target determinate versioni di Android. Poiché queste modifiche interessano solo le app che hanno come target una versione specifica di Android, vengono chiamate anche modifiche a accesso controllato datargetSDKVersion.

    Queste modifiche sono attivate per impostazione predefinita nel framework di compatibilità se la tua app ha come target una versione successiva a quella dell'API elencata. Ad esempio, una modifica del comportamento limitata da targetSDKVersion in Android 13 (livello API 33) verrà elencata nell'interfaccia utente in una sezione intitolata Attivata per targetSdkVersion >=33. In alcune versioni precedenti di Android, invece, questa sezione si chiama "Attivato dopo SDK API_LEVEL".

Nella figura 1 noterai anche una sezione denominata Modifiche disattivate per impostazione predefinita. Le modifiche che rientrano in questa sezione possono avere vari scopi. Prima di attivare queste modifiche, leggi la descrizione della modifica nell'elenco del framework di compatibilità per la versione di Android.

Identificare le modifiche attivate utilizzando logcat

Per ogni modifica del comportamento, la prima volta durante il processo dell'app quando l'app chiama l'API interessata, il sistema emette un messaggio logcat come questo:

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 corrisponde a una delle modifiche del comportamento elencate nella schermata Modifiche alla compatibilità dell'app (vedi figura 1). In questo esempio, 194833441 corrisponde a NOTIFICATION_PERM_CHANGE_ID.
UID
Indica l'app interessata dalla modifica.
Stato

Indica se la modifica interessa l'app.

Lo stato può essere uno dei seguenti valori:

Stato Significato
ENABLED La modifica viene attivata e influisce sul comportamento dell'app se l'app utilizza le API modificate.
DISABLED

La modifica è disattivata e non influisce sull'app.

Nota: se questa modifica è disattivata perché il valore targetSDKVersion dell'app è inferiore alla soglia richiesta, la modifica verrà attivata per impostazione predefinita quando l'app aumenterà il valore targetSDKVersion per avere come target una versione successiva.
LOGGED La modifica viene registrata tramite il framework di compatibilità, ma non può essere attivata o disattivata. Anche se non può essere attivata o disattivata, potrebbe comunque influire sul comportamento della tua app. Per ulteriori informazioni, consulta la descrizione della modifica nell'elenco del framework di compatibilità per la versione di Android in questione. In molti casi, questi tipi di modifiche sono sperimentali e possono essere ignorati.

Identificare le modifiche attivate utilizzando ADB

Esegui il seguente comando ADB per visualizzare l'insieme completo di modifiche (sia attivate che disattivate) sull'intero dispositivo:

adb shell dumpsys platform_compat

L'output elenca le seguenti informazioni per ogni modifica:

Modifica ID
Un identificatore univoco per questa modifica del comportamento. Ad esempio, 194833441.
Nome
Il nome di questa modifica del comportamento. Ad esempio, NOTIFICATION_PERM_CHANGE_ID.
Criteri targetSDKVersion

L'eventuale targetSDKVersion a cui è associata la modifica.

Ad esempio, se questa modifica è abilitata solo per le app che hanno come target la versione SDK 33 o successive, viene visualizzato enableAfterTargetSdk=32. Se la modifica non è controllata da targetSDKVersion, viene visualizzato enableAfterTargetSdk=0.

Sostituzioni del pacchetto

Il nome di ogni pacchetto in cui è stato ignorato lo stato predefinito della modifica (attivato o disattivato).

Ad esempio, se si tratta di una modifica abilitata per impostazione predefinita, il nome del pacchetto dell'app verrà elencato se hai disattivato la modifica utilizzando le opzioni per gli sviluppatori o ADB. In questo caso, l'output sarà:

packageOverrides={com.my.package=false}

Le modifiche bloccate da targetSDKVersion possono essere attivate o disattivate per impostazione predefinita, pertanto l'elenco dei pacchetti può includere istanze sia di true che di false, a seconda del targetSDKVersion di ciascuna app. Per esempio:

packageOverrides={com.my.package=true, com.another.package=false}

Scopri di più su modifiche specifiche

L'elenco completo delle modifiche al comportamento nel framework di compatibilità è incluso nella documentazione di ogni versione di Android. Per maggiori informazioni, consulta i seguenti link, a seconda della versione di Android per cui stai testando l'app:

Quando attivare/disattivare le modifiche

Lo scopo principale del framework di compatibilità è offrirti il controllo e la flessibilità necessari per testare la tua app con le versioni più recenti di Android. Questa sezione descrive alcune strategie che puoi utilizzare per determinare quando attivare o disattivare le modifiche durante il test e il debug dell'app.

Quando disattivare le modifiche

La decisione di disattivare le modifiche di solito dipende dal fatto che la modifica sia o meno gestita da targetSDKVersion.

Modifiche attivate per tutte le app

Le modifiche che interessano tutte le app sono attivate per impostazione predefinita per una versione della piattaforma specifica, indipendentemente dal valore targetSDKVersion della tua app, in modo da poter vedere se la tua app è interessata dall'esecuzione su quella versione della piattaforma.

Ad esempio, se ti stai preparando a scegliere come target Android 15 (livello API 35), potresti iniziare installando la tua app su un dispositivo con Android 15 e testarla utilizzando le tue normali procedure di test. Se la tua app riscontra problemi, puoi disattivare la modifica che li causa per continuare a testare la presenza di altri problemi.

Poiché queste modifiche possono interessare tutte le app indipendentemente da targetSDKVersion, solitamente devi testare e aggiornare l'app per queste modifiche prima di quelle bloccate da targetSDKVersion. In questo modo, gli utenti non avranno un'esperienza con l'app degradata quando aggiorneranno il dispositivo a una nuova versione della piattaforma.

Inoltre, devi 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 è in anteprima.

Modifiche con gating da targetSDKVersion

Se la tua app ha come target untargetSDKVersion specifico, tutte le modifiche bloccate da quella versione sono attivate per impostazione predefinita. Pertanto, quando passi a una nuova versione di targetSDKVersion della tua app, quest'ultima 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 bloccate da un targetSDKVersion specifico sono disattivate per impostazione predefinita ogni volta che un'app ha come target una versione dell'SDK precedente alla versione bloccata. In genere, quando ti prepari a scegliere come target un nuovo targetSdkVersion, hai a disposizione un elenco di modifiche del comportamento per cui dovrai testare e eseguire il debug della tua app.

Ad esempio, potresti testare la tua app in base a una serie di modifiche della piattaforma nel prossimo targetSdkVersion. Utilizzando le opzioni per gli sviluppatori o i comandi ADB, puoi attivare e testare ogni modifica con limitazioni una alla volta, anziché modificare il manifest dell'app e attivare tutte le modifiche contemporaneamente. Questo controllo aggiuntivo può aiutarti a testare le modifiche in isolamento ed evitare di eseguire il debug e l'aggiornamento di più parti della tua app contemporaneamente.

Dopo aver attivato una modifica, puoi testare e eseguire il debug dell'app utilizzando i tuoi normali flussi di lavoro di test. Se riscontri problemi, controlla i log per determinare la causa del problema. Se non è chiaro se il problema è causato da una modifica della piattaforma abilitata, prova a disattivarla e poi testa di nuovo la funzionalità in questione della tua app.

Attivare o disattivare le modifiche

Il framework di compatibilità ti consente di attivare o disattivare ogni modifica utilizzando le opzioni per gli sviluppatori o i comandi ADB. Poiché l'attivazione o la disattivazione delle modifiche può causare un arresto anomalo dell'app o la disattivazione di modifiche di sicurezza importanti, esistono alcune limitazioni relative al momento in cui puoi attivare o disattivare le modifiche.

Attivare/disattivare le modifiche utilizzando le opzioni sviluppatore

Utilizza le opzioni sviluppatore per attivare o disattivare le modifiche. Per trovare le opzioni sviluppatore:

  1. Se le Opzioni sviluppatore non sono già attive, attivale.
  2. Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche alla compatibilità delle app.
  3. Seleziona l'app dall'elenco.

  4. Nell'elenco delle modifiche, trova la modifica che vuoi attivare o disattivare e tocca l'opzione.

    Elenco di modifiche che possono essere attivate o disattivate

Attivare/disattivare 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

Passa il valore CHANGE_ID (ad es. 194833441) o il valore CHANGE_NAME (ad es. NOTIFICATION_PERM_CHANGE_ID) e il valore PACKAGE_NAME della tua app.

Puoi anche utilizzare il seguente comando per ripristinare una modifica allo stato predefinito, rimuovendo qualsiasi sostituzione impostata utilizzando ADB o le opzioni per gli sviluppatori:

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 è attivata o disattivata. Le modifiche che interessano tutte le app sono abilitate per impostazione predefinita. Altre modifiche sono bloccate da un targetSdkVersion. Queste modifiche sono attivate per impostazione predefinita quando un'app ha come target la corrispondente versione dell'SDK o una versione successiva e sono disattivate per impostazione predefinita quando un'app ha come target una versione dell'SDK precedente alla versione con limitazioni. Quando attivi o disattivi una modifica, sostituisci il relativo stato predefinito.

Per impedire l'uso fraudolento del framework di compatibilità, esistono alcune limitazioni su quando puoi attivare/disattivare le modifiche. La possibilità di attivare o disattivare una modifica dipende dal tipo di modifica, dal fatto che l'app sia debuggabile e dal tipo di build in esecuzione sul dispositivo. La tabella seguente descrive quando puoi attivare/disattivare diversi tipi di modifiche:

Tipo di build App non di debug App di cui è possibile eseguire il debug
Tutte le modifiche Modifiche bloccate da targetSDKVersion Tutte le altre modifiche
Anteprima per gli sviluppatori o build beta Impossibile attivare/disattivare Può essere attivato/disattivato Può essere attivato/disattivato
Build utente pubblico Impossibile attivare/disattivare Può essere attivato/disattivato Impossibile attivare/disattivare