Strumenti del framework di compatibilità

Android 11 ha introdotto nuovi strumenti per sviluppatori per testare ed 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. Sfrutta questa flessibilità mentre ti prepari a scegliere come target l'ultima versione stabile 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 il tuo targetSDKVersion o ricompilare la tua app per eseguire test di base. Poiché le modifiche sono attivabili/disattivabili singolarmente, puoi isolare, testare ed eseguire il debug di una modifica del comportamento alla volta o disattivare una singola modifica che causa problemi se devi testare qualcos'altro prima.

Come identificare le modifiche attivate

Quando viene attivata una modifica del comportamento, può influire sul modo in cui la tua app accede alle API della piattaforma interessate dalla modifica. Puoi controllare quali modifiche al comportamento sono attive utilizzando le opzioni sviluppatore, logcat o i comandi ADB.

Identificare le modifiche abilitate utilizzando le opzioni sviluppatore

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

Puoi vedere quali modifiche sono attive e attivarle o disattivarle nelle opzioni sviluppatore di un dispositivo. Per accedere a queste opzioni, segui questi passaggi:

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 modifica del comportamento di solito rientra in una delle due categorie seguenti:

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

  Queste modifiche sono attive 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 anche chiamate modifiche controllate da targetSDKVersion.

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

Nella figura 1 noterai anche una sezione chiamata Modifiche disattivate per impostazione predefinita. Le modifiche che rientrano in questa sezione possono servire a una serie di scopi. Prima di attivare queste modifiche, leggi la descrizione della modifica nell'elenco dei framework di compatibilità per quella versione di Android.

Identificare le modifiche attivate utilizzando logcat

Per ogni modifica del comportamento, la prima volta durante il processo dell'app in cui l'app chiama l'API interessata, il sistema restituisce 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 quale modifica influisce sull'app. Questo valore corrisponde a una delle modifiche del comportamento elencate nella schermata Modifiche di 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ò assumere uno dei seguenti valori:

Stato	Significato
ENABLED	La modifica è abilitata e influirà sul comportamento dell'app se l'app utilizza le API modificate.
DISABLED	La modifica è disattivata e non influirà sull'app. Nota:se questa modifica è disattivata perché il targetSDKVersion dell'app è inferiore alla soglia richiesta, la modifica verrà attivata per impostazione predefinita quando l'app aumenterà il targetSDKVersion per avere come target una versione superiore.
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, la modifica potrebbe comunque influire sul comportamento della tua app. Per saperne di più, consulta 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 il seguente comando ADB per visualizzare l'insieme completo delle 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

Il targetSDKVersion da cui dipende la modifica (se presente).

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

Override dei pacchetti

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

Ad esempio, se si tratta di una modifica attivata per impostazione predefinita, il nome del pacchetto dell'app verrà visualizzato 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 disattivate per impostazione predefinita, pertanto l'elenco dei pacchetti può includere istanze di true o false, a seconda del targetSDKVersion di ciascuna app. Per esempio:

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

Scopri di più sulle modifiche specifiche

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

• Android 16 (livello API 36)
• 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à è quello di 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 dipende in genere dal fatto che la modifica sia controllata da targetSDKVersion o meno.

Modifiche attivate per tutte le app

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

Ad esempio, se ti stai preparando a scegliere come target Android 16 (livello API 36), potresti iniziare installando la tua app su un dispositivo con Android 16 e testarla utilizzando i tuoi flussi di lavoro di test tipici. Se la tua app riscontra problemi, puoi disattivare la modifica che causa il problema per continuare a testare 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 di quelle controllate da targetSDKVersion. In questo modo, gli utenti non avranno un'esperienza app peggiore quando aggiornano il dispositivo a una nuova versione della piattaforma.

Devi 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 i test di queste modifiche per ogni versione di Android mentre la versione è in anteprima.

Modifiche controllate da targetSDKVersion

Se la tua app ha come target una targetSDKVersion specifica, tutte le modifiche controllate da quella versione sono attivate per impostazione predefinita. Pertanto, quando passi a una nuova versione dell'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 controllate da un targetSDKVersion specifico sono disattivate per impostazione predefinita ogni volta che un'app ha come target una versione dell'SDK precedente a quella controllata. In genere, quando ti prepari a scegliere come target un nuovo targetSdkVersion, avrai un elenco di modifiche al comportamento per cui dovrai testare ed eseguire il debug della tua app.

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

Dopo aver attivato una modifica, puoi testare ed 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 attivata, prova a disattivarla e a testare di nuovo l'area dell'app.

Attivare o disattivare le modifiche

Il framework di compatibilità consente di attivare o disattivare ogni modifica utilizzando le opzioni sviluppatore 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, esistono alcune limitazioni relative al momento in cui è possibile 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, segui questi passaggi:

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 quella che vuoi attivare o disattivare e tocca l'interruttore.

   

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

Supera il test CHANGE_ID (ad esempio, 194833441) o il test CHANGE_NAME (ad esempio, NOTIFICATION_PERM_CHANGE_ID) e il test PACKAGE_NAME della tua app.

Puoi anche utilizzare 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 è attivata o disattivata. Le modifiche che interessano tutte le app sono attive per impostazione predefinita. Altre modifiche sono protette da un targetSdkVersion. Queste modifiche sono attivate per impostazione predefinita quando un'app ha come target la versione dell'SDK corrispondente o una versione successiva e disattivate per impostazione predefinita quando un'app ha come target una versione dell'SDK precedente alla versione controllata. Quando attivi o disattivi un'impostazione, ne sostituisci lo stato predefinito.

Per impedire l'utilizzo dannoso del framework di compatibilità, esistono alcune limitazioni relative al momento in cui è possibile attivare/disattivare le modifiche. La possibilità di attivare/disattivare una modifica dipende dal tipo di modifica, dalla possibilità di eseguire il debug dell'app e dal tipo di build in esecuzione sul dispositivo. La tabella seguente descrive quando puoi attivare/disattivare diversi tipi di modifiche: