Strumenti del framework di compatibilità

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 più recente dell'API stabile e a testare la tua app con la release di anteprima della prossima versione di Android.

Quando utilizzi gli strumenti del framework per la compatibilità, la piattaforma Android adatta automaticamente la sua logica interna, in modo che non sia necessario modificare targetSDKVersion o ricompilare l'app per eseguire test di base. Poiché le modifiche possono essere attivate singolarmente, puoi isolare, testare ed eseguire il debug di una modifica di comportamento alla volta o disabilitare una singola modifica che causa problemi se prima devi testare qualcos'altro.

Come identificare le modifiche attivate

L'abilitazione di una modifica del comportamento può influire sul modo in cui la tua app accede alle API della piattaforma interessate da tale modifica. Puoi verificare quali modifiche del comportamento sono attivate utilizzando le opzioni sviluppatore, logcat o i comandi ADB.

Identificare le modifiche attivate utilizzando le opzioni sviluppatore

Figura 1. Schermata Modifiche compatibilità 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, procedi nel seguente modo:

  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à app.

  3. Seleziona l'app dall'elenco.

Generalmente, ogni modifica del comportamento appartiene a una delle seguenti due categorie:

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

    Queste modifiche sono abilitate per impostazione predefinita nel framework di compatibilità e sono elencate nella UI nella sezione Modifiche abilitate predefinite.

  • 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, sono anche definite modifiche limitate da targetSDKVersion.

    Queste modifiche sono abilitate 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 controllata da targetSDKVersion in Android 13 (livello API 33) verrebbe elencata nella UI con una sezione dal titolo 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 denominata Modifiche disattivate predefinite. Le modifiche che rientrano in questa sezione possono servire a diversi scopi. Prima di abilitare queste modifiche, leggi la descrizione delle modifiche nell'elenco dei framework di compatibilità per la versione di Android in questione.

Identificare le modifiche abilitate utilizzando logcat

Per ogni modifica del comportamento, la prima volta durante il processo dell'app, quando l'app chiama l'API interessata, il sistema genera 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 corrisponde a una delle modifiche del comportamento elencate nella schermata Modifiche alla compatibilità dell'app (vedi la figura 1). In questo esempio, 194833441 viene mappato a NOTIFICATION_PERM_CHANGE_ID.
UID
Indica quale app è interessata dalla modifica.
Stato

Indica se la modifica interessa l'app.

Lo stato può avere uno dei seguenti valori:

Stato Significato
ENABLED La modifica è abilitata e influirà sul comportamento dell'app se utilizza le API che sono state 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 ne aumenterà i 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. Sebbene non sia possibile attivare o disattivare questa modifica, questa modifica potrebbe comunque influire sul comportamento della tua app. Per maggiori informazioni, 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 attivate utilizzando ADB

Esegui questo comando ADB per visualizzare l'insieme completo delle 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 di questa modifica del comportamento. Ad esempio, 194833441.
Nome
Il nome di questo comportamento cambia. Ad esempio, NOTIFICATION_PERM_CHANGE_ID.
Criteri targetSDKVersion

Quale targetSDKVersion è controllato dalla modifica (se presente).

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

Override pacchetti

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 della tua app viene elencato se la disattivi utilizzando le opzioni per sviluppatori o ADB. In questo caso, l'output sarà:

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 sia di true che di false, a seconda dell'oggetto targetSDKVersion 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. Per saperne di più, consulta i seguenti link, a seconda della versione di Android per cui stai testando la tua app:

Quando attivare/disattivare le modifiche

Lo scopo principale del framework di compatibilità è offrirti controllo e flessibilità durante il test della 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 della tua app.

Quando disattivare le modifiche

La decisione di disattivare le modifiche in genere dipende dal fatto che la modifica sia limitata da targetSDKVersion o meno.

Modifiche attivate per tutte le app

Le modifiche che interessano tutte le app sono abilitate per impostazione predefinita per una versione specifica della piattaforma, indipendentemente dal targetSDKVersion della tua app, quindi puoi vedere se la tua 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 la tua app su un dispositivo con Android 14 e testandola utilizzando i tuoi flussi di lavoro di test tipici. Se si verificano problemi nell'app, puoi disattivare la modifica che li causa in modo da poter continuare a testare altri problemi.

Poiché queste modifiche possono interessare tutte le app indipendentemente da targetSDKVersion, in genere dovresti testare e aggiornare la tua app per applicare queste modifiche prima delle modifiche limitate da targetSDKVersion. Ciò contribuisce a garantire che gli utenti non abbiano un'esperienza con l'app ridotta quando aggiornano il proprio dispositivo a una nuova versione della piattaforma.

Inoltre, dovresti 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, tutte le modifiche controllate da quella versione vengono attivate per impostazione predefinita. Di conseguenza, 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 mentre esegui il test e il debug della tua 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 a quella con accesso riservato. In genere, quando ti prepari a scegliere come target un nuovo targetSdkVersion, avrai un elenco di modifiche del comportamento per le quali 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 ciascuna modifica ad accesso riservato, 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 tuoi flussi di lavoro di test tipici. In caso di problemi, controlla i log per determinarne la causa. Se non è chiaro se il problema sia causato da una modifica della piattaforma attiva, prova a disattivare la modifica e a ripetere il test dell'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. L'attivazione o la disattivazione delle modifiche può causare l'arresto anomalo dell'app o la disattivazione di importanti modifiche alla sicurezza, pertanto esistono alcune limitazioni relative all'attivazione/disattivazione 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:

  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à app.
  3. Seleziona l'app dall'elenco.

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

    Elenco delle modifiche che è possibile attivare o disattivare

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

Trasmetta CHANGE_ID (ad esempio 194833441) o 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/disattivazione delle modifiche

Per impostazione predefinita, ogni modifica del comportamento è attivata o disattivata. Le modifiche che interessano tutte le app sono attivate per impostazione predefinita. Le altre modifiche sono controllate da un targetSdkVersion. Queste modifiche vengono attivate per impostazione predefinita quando un'app ha come target la versione dell'SDK corrispondente o successiva e disattivate per impostazione predefinita quando l'app ha come target una versione dell'SDK precedente alla versione con accesso riservato. Quando attivi o disattivi una modifica, ne sostituisci lo stato predefinito.

Per evitare che il framework di compatibilità venga utilizzato in modo fraudolento, esistono alcune limitazioni relative al momento in cui puoi attivare/disattivare le modifiche. La possibilità di attivare o meno una modifica dipende dal tipo di modifica, dall'eventuale debug dell'app 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 cui è 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