Strumenti del framework di compatibilità

Android 11 ha introdotto nuovi strumenti per sviluppatori per testare ed eseguire il debug dell'app in base alle modifiche al 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 l'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 possono essere attivate e disattivate singolarmente, puoi isolare, testare ed eseguire il debug di una modifica al comportamento alla volta oppure disattivare una singola modifica che causa problemi se devi testare qualcos'altro prima.

Come identificare le modifiche attivate

Quando una modifica al comportamento è attivata, può influire sul modo in cui l'app accede alle API della piattaforma interessate dalla modifica. Puoi controllare quali modifiche al comportamento sono attivate utilizzando le opzioni sviluppatore, 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à attivate, attivale.
2. Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche di compatibilità dell'app.

3. Seleziona l'app dall'elenco.

Ogni modifica al comportamento in genere appartiene a una delle due categorie seguenti:

• Modifiche che interessano tutte le app in esecuzione su quella versione di Android, indipendentemente da targetSdkVersion dell'app.

  Queste modifiche sono attivate per impostazione predefinita nel framework di compatibilità e sono elencate nell'interfaccia utente nella sezione Modifiche attivate 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 vincolate da targetSDKVersion.

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

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

Identificare le modifiche attivate utilizzando logcat

Per ogni modifica al comportamento, la prima volta durante il processo dell'app in cui l'app chiama l'API interessata, il sistema genera un messaggio logcat simile al 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 corrisponde a una delle modifiche al 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 è attivata 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é targetSDKVersion dell'app è inferiore alla soglia richiesta, la modifica verrà attivata per impostazione predefinita quando l'app aumenta 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 questa modifica non può essere attivata o disattivata, potrebbe comunque influire sul comportamento dell'app. Per ulteriori informazioni, consulta la descrizione della modifica nell'elenco del framework di compatibilità per quella versione di Android. 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 (attivate e 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 al comportamento. Ad esempio, 194833441.

Nome

Il nome di questa modifica al comportamento. Ad esempio, NOTIFICATION_PERM_CHANGE_ID.

Criteri targetSDKVersion

Il valore targetSDKVersion in base al quale la modifica è vincolata (se presente).

Ad esempio, se questa modifica è attivata solo per le app che hanno come target la versione 33 dell'SDK o versioni successive, viene generato l'output enableAfterTargetSdk=32. Se la modifica non è vincolata da targetSDKVersion, viene generato l'output enableAfterTargetSdk=0.

Override dei pacchetti

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

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

packageOverrides={com.my.package=false}

Le modifiche vincolate da targetSDKVersion possono essere attivate o disattivate per impostazione predefinita, quindi l'elenco dei pacchetti può includere istanze di true o false, a seconda di targetSDKVersion di ciascuna di queste app. Ad esempio:

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

Ulteriori informazioni su modifiche specifiche

L'elenco completo delle modifiche al comportamento nel framework di compatibilità è incluso nella documentazione di ogni versione di Android. Per ulteriori informazioni, consulta i seguenti link, a seconda della versione di Android per cui stai testando l'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 o disattivare le modifiche

Lo scopo principale del framework di compatibilità è fornirti controllo e flessibilità durante il test dell'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 in genere dipende dal fatto che la modifica sia vincolata o meno da targetSDKVersion.

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 da targetSDKVersion dell'app, quindi puoi 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), puoi iniziare installando l'app su un dispositivo con Android 16 e testarla utilizzando i normali flussi di lavoro di test. Se l'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 vincolate da targetSDKVersion. In questo modo, gli utenti non avranno un'esperienza dell'app degradata quando aggiornano il dispositivo a una nuova versione della piattaforma.

Dovresti anche dare la priorità al test di queste modifiche perché non puoi disattivare queste modifiche quando utilizzi una build di release pubblica di Android. Idealmente, dovresti eseguire i test su queste modifiche per ogni versione di Android mentre la versione è in anteprima.

Modifiche vincolate da targetSDKVersion

Se la tua app ha come target un valore targetSDKVersion specifico, tutte le modifiche vincolate da quella versione sono attivate per impostazione predefinita. Pertanto, quando passi a una nuova versione di targetSDKVersion dell'app, 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 vincolate da un valore targetSDKVersion specifico sono disattivate per impostazione predefinita ogni volta che un'app ha come target una versione dell'SDK precedente alla versione vincolata. 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 dell'app.

Ad esempio, potresti testare l'app in base a una serie di modifiche della piattaforma nel prossimo targetSdkVersion. Utilizzando le opzioni sviluppatore o i comandi ADB, puoi attivare e testare ogni modifica vincolata 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 dell'app contemporaneamente.

Dopo aver attivato una modifica, puoi testare ed eseguire il debug dell'app utilizzando i 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 disattivare la modifica e poi a testare di nuovo l'area dell'app.

Attivare o disattivare le modifiche

Il framework di compatibilità ti 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 o 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à attivate, attivale.
2. Apri l'app Impostazioni del dispositivo e vai a Sistema > Avanzate > Opzioni sviluppatore > Modifiche di compatibilità dell'app.
3. Seleziona l'app dall'elenco.

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

   

Attivare o 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

Trasmetti CHANGE_ID (ad esempio, 194833441) o il CHANGE_NAME (ad esempio, NOTIFICATION_PERM_CHANGE_ID) e PACKAGE_NAME dell'app.

Puoi anche utilizzare il seguente comando per reimpostare una modifica allo stato predefinito, 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 o alla disattivazione delle modifiche

Per impostazione predefinita, ogni modifica al comportamento è attivata o disattivata. Le modifiche che interessano tutte le app sono attivate per impostazione predefinita. Altre modifiche sono vincolate da targetSdkVersion. Queste modifiche sono attivate per impostazione predefinita quando un'app ha come target la versione dell'SDK corrispondente o versioni successive e disattivate per impostazione predefinita quando un'app ha come target una versione dell'SDK precedente alla versione vincolata. Quando attivi o disattivi una modifica, sostituisci il suo stato predefinito.

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