Understanding Android API Levels (Informazioni sui livelli API Android)

  • Articolo

Xamarin.Android include diverse impostazioni a livello di API Android che determinano la compatibilità dell'app con più versioni di Android. Questa guida spiega cosa significano queste impostazioni, come configurarle e quali effetti hanno sull'app in fase di esecuzione.

Avvio rapido

Xamarin.Android espone tre impostazioni del progetto a livello di API Android:

  • Framework di destinazione: specifica il framework da usare per la compilazione dell'applicazione. Questo livello api viene usato in fase di compilazione da Xamarin.Android.

  • Versione minima di Android: specifica la versione android meno recente che si vuole supportare per l'app. Questo livello api viene usato in fase di esecuzione da Android.

  • Versione android di destinazione: specifica la versione di Android in cui deve essere eseguita l'app. Questo livello api viene usato in fase di esecuzione da Android.

Prima di poter configurare un livello API per il progetto, è necessario installare i componenti della piattaforma SDK per tale livello di API. Per altre informazioni sul download e l'installazione di componenti android SDK, vedere Installazione di Android SDK.

Nota

A partire da agosto 2021, Google Play Console richiede che le nuove app siano destinate al livello API 30 (Android 11.0) o superiore. Le app esistenti devono essere destinate al livello API 30 o superiore a partire da novembre 2021. Per altre informazioni, vedere Requisiti a livello di API di destinazione per la console di riproduzione in "Creare e configurare l'app" nella documentazione di Play Console.

In genere, tutti e tre i livelli di API Xamarin.Android vengono impostati sullo stesso valore. Nella pagina Applicazione impostare Compila usando la versione android (Framework di destinazione) sulla versione più recente dell'API stabile (o, almeno, sulla versione android con tutte le funzionalità necessarie). Nello screenshot seguente, Il framework di destinazione è impostato su Android 7.1 (livello API 25 - Nougat):In the following screenshot, the Target Framework is set to Android 7.1 (API Level 25 - Nougat):

Target Framework version defaults to Compile using Android version

Nella pagina Manifesto Android impostare versione minima di Android su Usa compilazione con la versione dell'SDK e impostare la versione di Android di destinazione sullo stesso valore della versione di Framework di destinazione (nello screenshot seguente il framework Android di destinazione è impostato su Android 7.1 (Nougat)):

Minimum and Target Android versions set to Target Framework version

Se si vuole mantenere la compatibilità con le versioni precedenti di Android, impostare Versione minima di Android come destinazione alla versione meno recente di Android che si vuole supportare l'app. Si noti che il livello API 14 è il livello API minimo necessario per Supporto di Google Play Services e Firebase. La configurazione di esempio seguente supporta le versioni di Android dal livello API 14 al livello API 25:

Compile using API level 25 Nougat, Minimum Android version set to API level 14

Se l'app supporta più versioni di Android, il codice deve includere controlli di runtime per assicurarsi che l'app funzioni con l'impostazione Versione minima di Android (vedi Controlli di runtime per le versioni Android di seguito per informazioni dettagliate). Se si usa o si crea una libreria, vedere Livelli API e librerie di seguito per le procedure consigliate per la configurazione delle impostazioni a livello di API per le librerie.

Versioni di Android e livelli api

Man mano che la piattaforma Android evolve e vengono rilasciate nuove versioni di Android, a ogni versione di Android viene assegnato un identificatore integer univoco, denominato livello API. Di conseguenza, ogni versione di Android corrisponde a un singolo livello API Android. Poiché gli utenti installano app in versioni precedenti e nelle versioni più recenti di Android, le app Android reali devono essere progettate per funzionare con più livelli di API Android.

Versioni di Android

Ogni versione di Android passa da più nomi:

  • La versione di Android, ad esempio Android 9.0
  • Un nome di codice (o dessert), ad esempio Pie
  • Livello API corrispondente, ad esempio il livello API 28

Un nome di codice Android può corrispondere a più versioni e livelli di API (come illustrato nella tabella seguente), ma ogni versione di Android corrisponde esattamente a un livello API.

Inoltre, Xamarin.Android definisce i codici di versione di compilazione che eseguono il mapping ai livelli api Android attualmente noti. La tabella seguente consente di tradurre tra il livello API, la versione android, il nome del codice e il codice della versione di compilazione di Xamarin.Android (i codici di versione della build sono definiti nello spazio dei Android.OS nomi):

Nome Versione Livello API Rilasciato Codice della versione di compilazione
T 10.0 29 Ago 2020 BuildVersionCodes.Q
Torta 9.0 28 Aug 2018 BuildVersionCodes.P
Oreo 8.1 27 Dic 2017 BuildVersionCodes.OMr1
Oreo 8.0 26 Agosto 2017 BuildVersionCodes.O
Nougat 7.1 25 Dicembre 2016 BuildVersionCodes.NMr1
Nougat 7.0 24 Agosto 2016 BuildVersionCodes.N
Marshmallow 6.0 23 Agosto 2015 BuildVersionCodes.M
Lollipop 5.1 22 Mar 2015 BuildVersionCodes.LollipopMr1
Lollipop 5.0 21 Nov 2014 BuildVersionCodes.Lollipop
Kitkat Watch 4,4W 20 Giugno 2014 BuildVersionCodes.KitKatWatch
Kitkat 4.4 19 Ottobre 2013 BuildVersionCodes.KitKat
Medusa Bean 4.3 18 Luglio 2013 BuildVersionCodes.JellyBeanMr2
Medusa Bean 4.2-4.2.2 17 Novembre 2012 BuildVersionCodes.JellyBeanMr1
Medusa Bean 4.1-4.1.1 16 Giugno 2012 BuildVersionCodes.JellyBean
Panino gelato 4.0.3-4.0.4 15 Dicembre 2011 BuildVersionCodes.IceCreamSandwichMr1
Panino gelato 4.0-4.0.2 14 Oct 2011 BuildVersionCodes.IceCreamSandwich
Favo 3.2 13 Giugno 2011 BuildVersionCodes.HoneyCombMr2
Favo 3.1.x 12 Maggio 2011 BuildVersionCodes.HoneyCombMr1
Favo 3.0.x 11 Febbraio 2011 BuildVersionCodes.HoneyComb
Gingerbread 2.3.3-2.3.4 10 Febbraio 2011 BuildVersionCodes.GingerBreadMr1
Gingerbread 2.3-2.3.2 9 Novembre 2010 BuildVersionCodes.GingerBread
Froyo 2.2.x 8 Giugno 2010 BuildVersionCodes.Froyo
Eclair 2.1.x 7 gen 2010 BuildVersionCodes.EclairMr1
Eclair 2.0.1 6 Dicembre 2009 BuildVersionCodes.Eclair01
Eclair 2.0 5 Novembre 2009 BuildVersionCodes.Eclair
Donut 1.6 4 Settembre 2009 BuildVersionCodes.Donut
Cupcake 1.5 3 Maggio 2009 BuildVersionCodes.Cupcake
Base 1.1 2 Febbraio 2009 BuildVersionCodes.Base11
Base 1.0 1 Ottobre 2008 BuildVersionCodes.Base

Come indicato in questa tabella, le nuove versioni di Android vengono rilasciate frequentemente, a volte più di una versione all'anno. Di conseguenza, l'universo dei dispositivi Android che potrebbero eseguire l'app include un'ampia gamma di versioni precedenti e più recenti di Android. Come puoi garantire che l'app venga eseguita in modo coerente e affidabile su così tante versioni diverse di Android? I livelli API di Android consentono di gestire questo problema.

Livelli di API Android

Ogni dispositivo Android viene eseguito esattamente a un livello API: questo livello di API è garantito che sia univoco per ogni versione della piattaforma Android. Il livello API identifica con precisione la versione del set di API in cui l'app può chiamare; identifica la combinazione di elementi manifesto, autorizzazioni e così via, rispetto a cui si esegue il codice come sviluppatore. Il sistema android dei livelli API aiuta Android a determinare se un'applicazione è compatibile con un'immagine di sistema Android prima di installare l'applicazione in un dispositivo.

Quando un'applicazione viene compilata, contiene le informazioni seguenti sul livello API:

  • Livello API di destinazione di Android in cui viene compilata l'app.

  • Il livello minimo di API Android che un dispositivo Android deve eseguire l'app.

Queste impostazioni vengono usate per assicurarsi che le funzionalità necessarie per eseguire correttamente l'app siano disponibili nel dispositivo Android in fase di installazione. In caso contrario, l'app non è in esecuzione nel dispositivo. Ad esempio, se il livello API di un dispositivo Android è inferiore al livello api minimo specificato per l'app, il dispositivo Android impedirà all'utente di installare l'app.

Impostazioni a livello di API del progetto

Le sezioni seguenti illustrano come usare SDK Manager per preparare l'ambiente di sviluppo per i livelli api di destinazione, seguiti da spiegazioni dettagliate su come configurare framework di destinazione, versione minima di Android e Impostazioni della versione android di destinazione in Xamarin.Android.

Piattaforme Android SDK

Prima di poter selezionare un livello api di destinazione o minimo in Xamarin.Android, è necessario installare la versione della piattaforma Android SDK corrispondente a tale livello di API. La gamma di opzioni disponibili per Framework di destinazione, Versione minima di Android e Versione android di destinazione è limitata alla gamma di versioni di Android SDK installate. È possibile usare SDK Manager per verificare che siano installate le versioni necessarie di Android SDK ed è possibile usarlo per aggiungere nuovi livelli di API necessari per l'app. Se non si ha familiarità con come installare i livelli api, vedere Installazione di Android SDK.

Framework di destinazione

Il framework di destinazione (noto anche come compileSdkVersion) è la versione specifica del framework Android (livello API) per cui l'app viene compilata in fase di compilazione. Questa impostazione specifica le API che l'app prevede di usare durante l'esecuzione, ma non ha alcun effetto sulle API effettivamente disponibili per l'app quando viene installata. Di conseguenza, la modifica dell'impostazione Framework di destinazione non modifica il comportamento di runtime.

Il framework di destinazione identifica le versioni della libreria a cui è collegata l'applicazione. Questa impostazione determina le API che è possibile usare nell'app. Ad esempio, se si vuole usare il metodo NotificationBuilder.SetCategory introdotto in Android 5.0 Lollipop, è necessario impostare Target Framework su Livello API 21 (Lollipop) o versione successiva. Se si imposta Il framework di destinazione del progetto su un livello API, ad esempio il livello API 19 (KitKat) e si tenta di chiamare il SetCategory metodo nel codice, si otterrà un errore di compilazione.

È consigliabile compilare sempre con la versione più recente disponibile di Framework di destinazione. In questo modo vengono forniti messaggi di avviso utili per tutte le API deprecate che potrebbero essere chiamate dal codice. L'uso della versione più recente di Framework di destinazione è particolarmente importante quando usi le versioni più recenti della libreria di supporto. Ogni libreria prevede che l'app venga compilata a livello api minimo o superiore della libreria di supporto.

Per accedere all'impostazione Framework di destinazione in Visual Studio, aprire le proprietà del progetto in Esplora soluzioni e selezionare la pagina Applicazione:

Application page of project Properties

Impostare Framework di destinazione selezionando un livello API nel menu a discesa in Compila usando la versione di Android, come illustrato in precedenza.

Versione minima di Android

La versione minima di Android (nota anche come minSdkVersion) è la versione meno recente del sistema operativo Android (ad esempio, il livello API più basso) che può installare ed eseguire l'applicazione. Per impostazione predefinita, un'app può essere installata solo nei dispositivi che corrispondono all'impostazione Framework di destinazione o versione successiva; se l'impostazione Versione minima di Android è inferiore all'impostazione Framework di destinazione, l'app può essere eseguita anche nelle versioni precedenti di Android. Ad esempio, se si imposta Target Framework su Android 7.1 (Nougat) e si imposta la versione minima di Android su Android 4.0.3 (Ice Cream Sandwich), l'app può essere installata in qualsiasi piattaforma dal livello API 15 al livello API 25, incluso.

Anche se l'app può essere compilata e installata correttamente in questa gamma di piattaforme, ciò non garantisce che venga eseguito correttamente in tutte queste piattaforme. Ad esempio, se l'app è installata in Android 5.0 (Lollipop) e il codice chiama un'API disponibile solo in Android 7.1 (Nougat) e versioni successive, l'app riceverà un errore di runtime e probabilmente si arresterà in modo anomalo. Di conseguenza, il codice deve assicurarsi, in fase di esecuzione, di chiamare solo le API supportate dal dispositivo Android in cui è in esecuzione. In altre parole, il codice deve includere controlli di runtime espliciti per assicurarsi che l'app usi API più recenti solo nei dispositivi sufficientemente recenti per supportarli. I controlli di runtime per le versioni android, più avanti in questa guida, illustrano come aggiungere questi controlli di runtime al codice.

Per accedere all'impostazione Versione minima di Android in Visual Studio, aprire le proprietà del progetto in Esplora soluzioni e selezionare la pagina Manifesto Android. Nel menu a discesa in Versione minima android è possibile selezionare la versione minima di Android per l'applicazione:

Minimum Android to target option set to Compile using SDK version

Se si seleziona Usa compilazione con la versione dell'SDK, la versione minima di Android sarà identica all'impostazione Framework di destinazione.

Versione di Android di destinazione

La versione android di destinazione (nota anche come targetSdkVersion) è il livello API del dispositivo Android in cui l'app prevede l'esecuzione. Android usa questa impostazione per determinare se abilitare eventuali comportamenti di compatibilità. Ciò garantisce che l'app continui a funzionare nel modo previsto. Android usa l'impostazione Versione android di destinazione dell'app per determinare quali modifiche di comportamento possono essere applicate all'app senza interromperla (questo è il modo in cui Android offre compatibilità con l'inoltro).

Il framework di destinazione e la versione di Android di destinazione, pur avendo nomi molto simili, non sono la stessa cosa. L'impostazione Framework di destinazione comunica le informazioni a livello di API di destinazione a Xamarin.Android da usare in fase di compilazione, mentre la versione android di destinazione comunica le informazioni sul livello API di destinazione ad Android per l'uso in fase di esecuzione (quando l'app viene installata e in esecuzione in un dispositivo).

Per accedere a questa impostazione in Visual Studio, aprire le proprietà del progetto in Esplora soluzioni e selezionare la pagina Manifesto Android. Nel menu a discesa in Versione android di destinazione è possibile selezionare la versione android di destinazione per l'applicazione:

Target Android version set to Compile using SDK version

È consigliabile impostare in modo esplicito la versione di Android di destinazione sulla versione più recente di Android usata per testare l'app. Idealmente, deve essere impostata sulla versione più recente di Android SDK. Ciò consente di usare nuove API prima di usare le modifiche del comportamento. Per la maggior parte degli sviluppatori, non è consigliabile impostare la versione di Android di destinazione su Usa compilazione con la versione dell'SDK.

In generale, la versione android di destinazione deve essere vincolata dalla versione minima di Android e dal framework di destinazione. Ovvero:

Versione <minima di Android = Versione <android di destinazione = Framework di destinazione

Per altre informazioni sui livelli SDK, vedere la documentazione relativa agli sviluppatori Android uses-sdk .

Controlli di runtime per le versioni di Android

Man mano che viene rilasciata ogni nuova versione di Android, l'API del framework viene aggiornata per fornire funzionalità nuove o sostitutive. Con poche eccezioni, la funzionalità API delle versioni precedenti di Android viene portata avanti in versioni più recenti di Android senza modifiche. Di conseguenza, se l'app viene eseguita in un determinato livello api Android, in genere sarà in grado di essere eseguita in un livello api Android successivo senza modifiche. Ma cosa succede se si vuole anche eseguire l'app in versioni precedenti di Android?

Se si seleziona una versione minima di Android inferiore all'impostazione Framework di destinazione, alcune API potrebbero non essere disponibili per l'app in fase di esecuzione. Tuttavia, l'app può comunque essere eseguita in un dispositivo precedente, ma con funzionalità ridotte. Per ogni API non disponibile nelle piattaforme Android corrispondenti all'impostazione Versione minima di Android, il codice deve controllare in modo esplicito il valore della Android.OS.Build.VERSION.SdkInt proprietà per determinare il livello API della piattaforma in cui è in esecuzione l'app. Se il livello API è inferiore alla versione minima di Android che supporta l'API che si vuole chiamare, il codice deve trovare un modo per funzionare correttamente senza effettuare questa chiamata API.

Si supponga, ad esempio, di voler usare il metodo NotificationBuilder.SetCategory per classificare una notifica durante l'esecuzione in Android 5.0 Lollipop (e versioni successive), ma si vuole comunque che l'app venga eseguita in versioni precedenti di Android, ad esempio Android 4.1 Jelly Bean (dove SetCategory non è disponibile). Facendo riferimento alla tabella delle versioni di Android all'inizio di questa guida, si noterà che il codice della versione di compilazione per Android 5.0 Lollipop è Android.OS.BuildVersionCodes.Lollipop. Per supportare le versioni precedenti di Android in cui SetCategory non è disponibile, il codice può rilevare il livello API in fase di esecuzione e chiamare SetCategory in modo condizionale solo quando il livello API è maggiore o uguale al codice della versione di compilazione Lollipop:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    builder.SetCategory(Notification.CategoryEmail);
}

In questo esempio il framework di destinazione dell'app è impostato su Android 5.0 (livello API 21) e la versione minima di Android è impostata su Android 4.1 (livello API 16). Poiché SetCategory è disponibile a livello Android.OS.BuildVersionCodes.Lollipop di API e versioni successive, questo codice di esempio chiamerà SetCategory solo quando è effettivamente disponibile. Non tenterà di chiamare SetCategory quando il livello API è 16, 17, 18, 19 o 20. La funzionalità viene ridotta in queste versioni precedenti di Android solo nella misura in cui le notifiche non vengono ordinate correttamente (perché non sono classificate per tipo), ma le notifiche vengono comunque pubblicate per avvisare l'utente. La nostra app funziona ancora, ma la sua funzionalità è leggermente diminuita.

In generale, il controllo della versione di compilazione consente al codice di decidere in fase di esecuzione tra l'esecuzione di un metodo nuovo rispetto al vecchio modo. Ad esempio:

if (Android.OS.Build.VERSION.SdkInt >= Android.OS.BuildVersionCodes.Lollipop)
{
    // Do things the Lollipop way
}
else
{
    // Do things the pre-Lollipop way
}

Non esiste una regola veloce e semplice che spiega come ridurre o modificare le funzionalità dell'app quando viene eseguita in versioni precedenti di Android che mancano di una o più API. In alcuni casi, ad esempio nell'esempio SetCategory precedente, è sufficiente omettere la chiamata API quando non è disponibile. In altri casi, tuttavia, potrebbe essere necessario implementare funzionalità alternative per quando Android.OS.Build.VERSION.SdkInt viene rilevato che è minore del livello API che l'app deve presentare l'esperienza ottimale.

Livelli e librerie delle API

Quando si crea un progetto di libreria Xamarin.Android ,ad esempio una libreria di classi o una libreria di associazioni, è possibile configurare solo l'impostazione Framework di destinazione: la versione minima di Android e le impostazioni della versione android di destinazione non sono disponibili. Ciò è dovuto al fatto che non esiste alcuna pagina manifesto Android:

Only the Compile using Android version option is available

Le impostazioni Versione minima di Android e Versione android di destinazione non sono disponibili perché la libreria risultante non è un'app autonoma. La libreria può essere eseguita in qualsiasi versione di Android, a seconda dell'app con cui è incluso. È possibile specificare la modalità di compilazione della libreria, ma non è possibile stimare il livello api della piattaforma in cui verrà eseguita la libreria. Tenendo presente questo aspetto, è consigliabile osservare le procedure consigliate seguenti quando si usano o si creano librerie:

  • Quando si usa una libreria Android: se si usa una libreria Android nell'applicazione, assicurarsi di impostare l'impostazione Framework di destinazione dell'app su un livello API almeno elevato dell'impostazione Framework di destinazione della libreria.

  • Quando si crea una libreria Android: se si crea una libreria Android per l'uso da parte di altre applicazioni, assicurarsi di impostare l'impostazione Framework di destinazione sul livello API minimo necessario per la compilazione.

Queste procedure consigliate sono consigliate per evitare la situazione in cui una libreria tenta di chiamare un'API non disponibile in fase di esecuzione (che può causare l'arresto anomalo dell'app). Gli sviluppatori di librerie devono cercare di limitare l'utilizzo delle chiamate API a un subset ridotto e ben stabilito della superficie totale dell'API. In questo modo è possibile assicurarsi che la libreria possa essere usata in modo sicuro in un'ampia gamma di versioni di Android.

Riepilogo

Questa guida ha illustrato come vengono usati i livelli api Android per gestire la compatibilità delle app tra versioni diverse di Android. Sono stati forniti passaggi dettagliati per configurare il framework di destinazione Xamarin.Android, la versione minima di Android e le impostazioni del progetto versione android di destinazione. Sono state fornite istruzioni per l'uso di Android SDK Manager per installare pacchetti SDK, inclusi esempi di come scrivere codice per gestire diversi livelli di API in fase di esecuzione e come gestire i livelli API durante la creazione o l'utilizzo di librerie Android. Ha anche fornito un elenco completo che mette in relazione i livelli API con i numeri di versione di Android (ad esempio Android 4.4), i nomi delle versioni di Android (ad esempio Kitkat) e i codici di versione della build di Xamarin.Android.