<uses-sdk>

Google Play utilizza gli attributi <uses-sdk> dichiarati nel file manifest dell'app per filtrare l'app dai dispositivi che non soddisfano i requisiti di versione della piattaforma. Prima di impostare questi attributi, assicurati di comprendere i filtri di Google Play.

:
<uses-sdk android:minSdkVersion="integer"
          android:targetSdkVersion="integer"
          android:maxSdkVersion="integer" />
contenute in:
<manifest>
description:

Consente di esprimere la compatibilità di un'applicazione con una o più versioni della piattaforma Android mediante un numero intero a livello di API. Il livello API espresso da un'applicazione viene confrontato con il livello API di un determinato sistema Android, che può variare in base ai dispositivi Android.

Nonostante il nome, questo elemento viene utilizzato per specificare il livello API, non il numero di versione del software development kit (SDK) o della piattaforma Android. Il livello API è sempre un singolo numero intero. Non puoi ricavare il livello API dal numero di versione Android associato. Ad esempio, non è uguale alla versione principale o alla somma delle versioni principali e secondarie.

Leggi anche il documento sul controllo delle versioni delle applicazioni.

:
android:minSdkVersion
Un numero intero che indica il livello API minimo richiesto per l'esecuzione dell'applicazione. Il sistema Android impedisce all'utente di installare l'applicazione se il livello API del sistema è inferiore al valore specificato in questo attributo. Dichiara sempre questo attributo.

Attenzione: se non dichiari questo attributo, il sistema presuppone un valore predefinito di "1", che indica che la tua applicazione è compatibile con tutte le versioni di Android. Se non è corretto e non hai dichiarato il valore minSdkVersion corretto, l'applicazione, se installata su un sistema con un livello API incompatibile, si arresta in modo anomalo durante il runtime quando tenta di accedere alle API non disponibili. Per questo motivo, assicurati di dichiarare il livello API appropriato nell'attributo minSdkVersion.

android:targetSdkVersion
Un numero intero che indica il livello API target dell'applicazione. Se non viene configurato, il valore predefinito equivale a quello indicato a minSdkVersion.

Questo attributo indica al sistema che hai testato rispetto alla versione di destinazione e il sistema non abilita alcun comportamento di compatibilità per mantenere la compatibilità dell'app con la versione di destinazione. L'applicazione può ancora essere eseguita sulle versioni precedenti (fino a minSdkVersion).

Per via dell'evoluzione di Android a ogni nuova versione, alcuni comportamenti e persino aspetti visivi possono cambiare. Tuttavia, se il livello API della piattaforma è superiore a quello dichiarato da targetSdkVersion dell'app, il sistema può attivare comportamenti di compatibilità in modo che l'app continui a funzionare come previsto. Puoi disabilitare questi comportamenti di compatibilità specificando targetSdkVersion in modo che corrisponda al livello API della piattaforma su cui è in esecuzione.

Ad esempio, l'impostazione di questo valore su "11" o superiore consente al sistema di applicare il tema predefinito Holo alla tua app quando viene eseguita su Android 3.0 o versioni successive e disattiva anche la modalità di compatibilità dello schermo su schermi più grandi, poiché il supporto del livello API 11 supporta implicitamente schermi più grandi.

Esistono molti comportamenti di compatibilità che il sistema può attivare in base al valore impostato per questo attributo. Molti di questi comportamenti sono descritti dalle versioni della piattaforma corrispondenti nel riferimento Build.VERSION_CODES.

Per gestire la tua applicazione insieme a ogni release di Android, aumenta il valore di questo attributo in modo che corrisponda al livello API più recente, quindi testa accuratamente la tua applicazione sulla versione della piattaforma corrispondente.

Introdotta in: livello API 4

android:maxSdkVersion
Un numero intero che indica il livello API massimo su cui è progettata l'esecuzione dell'applicazione.

In Android 1.5, 1.6, 2.0 e 2.0.1, il sistema controlla il valore di questo attributo durante l'installazione di un'applicazione e durante la riconvalida dell'applicazione dopo un aggiornamento di sistema. In entrambi i casi, se l'attributo maxSdkVersion dell'applicazione è inferiore al livello API utilizzato dal sistema stesso, il sistema non consente l'installazione dell'applicazione. In caso di nuova convalida dopo l'aggiornamento del sistema, questa operazione rimuove di fatto l'applicazione dal dispositivo.

Per illustrare in che modo questo attributo può influire sulla tua applicazione dopo gli aggiornamenti di sistema, considera il seguente esempio:

Su Google Play viene pubblicata un'applicazione con la dichiarazione maxSdkVersion="5" nel manifest. Un utente sul cui dispositivo è in esecuzione Android 1.6 (livello API 4) scarica e installa l'app. Dopo alcune settimane, l'utente riceve un aggiornamento di sistema over-the-air ad Android 2.0 (livello API 5). Dopo aver installato l'aggiornamento, il sistema controlla il valore maxSdkVersion dell'applicazione e lo riconvalida correttamente.

L'applicazione funziona normalmente. Tuttavia, qualche tempo dopo, il dispositivo riceve un altro aggiornamento di sistema, questa volta ad Android 2.0.1 (livello API 6). Dopo l'aggiornamento, il sistema non può più riconvalidare l'applicazione perché il livello API (6) del sistema è superiore al massimo supportato dall'applicazione (5). Il sistema impedisce che l'applicazione sia visibile all'utente, rimuovendola in effetti dal dispositivo.

Avviso: non è consigliabile dichiarare questo attributo. Innanzitutto, non è necessario impostare l'attributo come mezzo per bloccare il deployment dell'applicazione sulle nuove versioni della piattaforma Android non appena vengono rilasciate. Le nuove versioni della piattaforma sono state progettate per essere completamente compatibili con le versioni precedenti. L'applicazione funziona correttamente sulle nuove versioni, a condizione che utilizzi solo API standard e segua le best practice per lo sviluppo. In secondo luogo, in alcuni casi la dichiarazione dell'attributo può comportare la rimozione dell'applicazione dai dispositivi degli utenti dopo un aggiornamento del sistema a un livello API superiore. La maggior parte dei dispositivi su cui è probabile che la tua applicazione venga installata ricevono aggiornamenti di sistema periodici over-the-air, quindi valuta il loro effetto sull'applicazione prima di impostare questo attributo.

Introdotta in: livello API 4

Alcune versioni di Android (a partire da Android 2.0.1) non controllano o applicano l'attributo maxSdkVersion durante l'installazione o la nuova convalida. Tuttavia, Google Play continua a utilizzare l'attributo come filtro quando si presentano agli utenti applicazioni disponibili per il download.
introdotto in:
Livello API 1

Che cos'è il livello API?

Il livello API è un valore intero che identifica in modo univoco la revisione dell'API framework offerta da una versione della piattaforma Android.

La piattaforma Android fornisce un'API framework che le applicazioni possono utilizzare per interagire con il sistema Android sottostante. L'API framework è composta da:

  • Un insieme principale di pacchetti e classi
  • Un insieme di elementi e attributi XML per dichiarare un file manifest
  • Un insieme di elementi e attributi XML per la dichiarazione e l'accesso alle risorse
  • Un insieme di intent
  • Un insieme di autorizzazioni che le applicazioni possono richiedere, così come applicazioni delle autorizzazioni incluse nel sistema

Ogni versione successiva della piattaforma Android può includere aggiornamenti all'API Android Application Framework che fornisce.

Gli aggiornamenti all'API Framework sono progettati in modo che la nuova API rimanga compatibile con le versioni precedenti dell'API. In altre parole, la maggior parte delle modifiche nell'API è cumulativa e introduce funzionalità nuove o sostitutive. Poiché viene eseguito l'upgrade di alcune parti dell'API, le parti sostituite meno recenti sono deprecate, ma non vengono rimosse, in modo che le applicazioni esistenti possano continuare a utilizzarle.

In un numero molto ridotto di casi, parti dell'API vengono modificate o rimosse, anche se in genere queste modifiche sono necessarie solo per supportare la solidità delle API e la sicurezza delle applicazioni o del sistema. Tutte le altre parti dell'API delle revisioni precedenti vengono riportate senza modifiche.

L'API framework fornita da una piattaforma Android viene specificata utilizzando un identificatore intero chiamato livello API. Ogni versione della piattaforma Android supporta esattamente un livello API, sebbene il supporto sia implicito per tutti i livelli API precedenti (fino al livello API 1). La versione iniziale della piattaforma Android forniva il livello API 1, mentre le versioni successive hanno incrementato il livello API.

La tabella seguente specifica il livello API supportato da ogni versione della piattaforma Android. Per informazioni sul numero relativo di dispositivi su cui è in esecuzione ogni versione, consulta la dashboard di distribuzione.

Versione piattaformaLivello APICODICE_VERSIONENotes
Android 14 34 UPSIDE_DOWN_CAKE Caratteristiche principali della piattaforma
Android 13 33 TIRAMISU Caratteristiche principali della piattaforma
Android 12 32 S_V2 Caratteristiche principali della piattaforma
31 S Caratteristiche principali della piattaforma
Android 11 30 R Caratteristiche principali della piattaforma
Android 10 29 Q Caratteristiche principali della piattaforma
Android 9 28 P Caratteristiche principali della piattaforma
Android 8.1 27 O_MR1 Caratteristiche principali della piattaforma
Android 8.0 26 O Caratteristiche principali della piattaforma
Android 7.1.1
Android 7.1
25 N_MR1 Caratteristiche principali della piattaforma
Android 7.0 24 N Caratteristiche principali della piattaforma
Android 6.0 23 M Caratteristiche principali della piattaforma
Android 5.1 22 LOLLIPOP_MR1 Caratteristiche principali della piattaforma
Android 5.0 21 LOLLIPOP
Android 4,4 W 20 KITKAT_WATCH Lollipop solo per i dispositivi indossabili
Android 4.4 19 KITKAT Caratteristiche principali della piattaforma
Android 4.3 18 JELLY_BEAN_MR2 Caratteristiche principali della piattaforma
Android 4.2, 4.2.2 17 JELLY_BEAN_MR1 Caratteristiche principali della piattaforma
Android 4.1, 4.1.1 16 JELLY_BEAN Caratteristiche principali della piattaforma
Android 4.0.3, 4.0.4 15 ICE_CREAM_SANDWICH_MR1 Caratteristiche principali della piattaforma
Android 4.0, 4.0.1, 4.0.2 14 ICE_CREAM_SANDWICH
Android 3.2 13 HONEYCOMB_MR2
Android 3.1.x 12 HONEYCOMB_MR1 Caratteristiche principali della piattaforma
Android 3.0.x 11 HONEYCOMB Caratteristiche principali della piattaforma
Android 2.3.4
Android 2.3.3
10 GINGERBREAD_MR1 Caratteristiche principali della piattaforma
Android 2.3.2
Android 2.3.1
Android 2.3
9 GINGERBREAD
Android 2.2.x 8 FROYO Caratteristiche principali della piattaforma
Android 2.1.x 7 ECLAIR_MR1 Caratteristiche principali della piattaforma
Android 2.0.1 6 ECLAIR_0_1
Android 2.0 5 ECLAIR
Android 1.6 4 DONUT Caratteristiche principali della piattaforma
Android 1.5 3 CUPCAKE Caratteristiche principali della piattaforma
Android 1.1 2 BASE_1_1
Android 1.0 1 BASE

Utilizzi del livello API in Android

L'identificatore del livello API ha un ruolo chiave nel garantire la migliore esperienza possibile a utenti e sviluppatori di applicazioni:

  • Consente alla piattaforma Android di descrivere la revisione massima dell'API framework che supporta.
  • Consente alle applicazioni di descrivere la revisione dell'API framework che richiedono.
  • Consente al sistema di negoziare l'installazione delle applicazioni sul dispositivo dell'utente in modo che non vengano installate applicazioni non compatibili con la versione.

Ogni versione della piattaforma Android archivia internamente l'identificatore del livello API, nel sistema Android stesso.

Le applicazioni possono utilizzare un elemento manifest fornito dall'API framework (<uses-sdk>) per descrivere i livelli minimo e massimo delle API in base ai quali possono essere eseguite, nonché il livello API preferito che sono progettate per supportare. L'elemento offre tre attributi chiave:

  • android:minSdkVersion: il livello API minimo su cui può essere eseguita l'applicazione. Il valore predefinito è "1".
  • android:targetSdkVersion: il livello API su cui è progettata per essere eseguita l'applicazione. In alcuni casi, ciò consente all'applicazione di utilizzare elementi manifest o comportamenti definiti nel livello API target, anziché essere limitata all'utilizzo solo di quelli definiti per il livello API minimo.
  • android:maxSdkVersion: il livello API massimo su cui può essere eseguita l'applicazione. Importante: leggi le informazioni su questo attributo in questa pagina prima di utilizzarlo.

Ad esempio, per specificare il livello API di sistema minimo richiesto da un'applicazione per essere eseguita, l'applicazione include nel manifest un elemento <uses-sdk> con un attributo android:minSdkVersion. Il valore di android:minSdkVersion è il numero intero corrispondente al livello API della prima versione della piattaforma Android in cui può essere eseguita l'applicazione.

Quando l'utente tenta di installare un'applicazione o quando riconvalida un'applicazione dopo un aggiornamento di sistema, il sistema Android controlla prima gli attributi <uses-sdk> nel file manifest dell'applicazione e confronta i valori con il proprio livello API interno. Il sistema consente di iniziare l'installazione solo se vengono soddisfatte le seguenti condizioni:

  • Se viene dichiarato un attributo android:minSdkVersion, il suo valore è inferiore o uguale al numero intero a livello di API del sistema. Se non viene dichiarato, il sistema presuppone che l'applicazione richieda il livello API 1.
  • Se viene dichiarato un attributo android:maxSdkVersion, il suo valore è uguale o superiore al numero intero a livello di API del sistema. Se non viene dichiarato, il sistema presuppone che l'applicazione non abbia un livello API massimo. Leggi la descrizione di questo attributo per ulteriori informazioni su come viene gestito dal sistema.

Quando viene dichiarato nel manifest di un'applicazione, un elemento <uses-sdk> potrebbe avere il seguente aspetto:

<manifest>
  <uses-sdk android:minSdkVersion="5" />
  ...
</manifest>

Il motivo principale per cui un'applicazione dichiara un livello API in android:minSdkVersion è comunicare al sistema Android che utilizza le API che sono state introdotte nel livello API specificato.

Se in qualche modo l'applicazione viene installata su una piattaforma con un livello API inferiore, si arresta in modo anomalo in fase di runtime quando tenta di accedere ad API che non esistono. Il sistema impedisce questo risultato impedendo l'installazione dell'applicazione se il livello API più basso richiesto è superiore a quello della versione della piattaforma sul dispositivo di destinazione.

Considerazioni sullo sviluppo

Le seguenti sezioni forniscono informazioni relative al livello API che devi prendere in considerazione durante lo sviluppo della tua applicazione.

Compatibilità con il forwarding delle applicazioni

Le app Android sono in genere compatibili con le nuove versioni della piattaforma Android.

Poiché quasi tutte le modifiche all'API Framework sono cumulative, un'applicazione Android sviluppata utilizzando una determinata versione dell'API, come specificato dal relativo livello API, è compatibile con le versioni successive della piattaforma Android e con livelli API superiori. L'applicazione può essere eseguita su tutte le versioni successive della piattaforma Android, tranne che in casi isolati in cui l'applicazione utilizza una parte dell'API che in seguito viene rimossa per qualche motivo.

La compatibilità diretta è importante perché molti dispositivi Android ricevono aggiornamenti di sistema OTA (over-the-air). L'utente potrebbe installare e utilizzare l'applicazione e poi ricevere un aggiornamento OTA a una nuova versione della piattaforma Android. Una volta installato l'aggiornamento, l'applicazione viene eseguita in una nuova versione di runtime dell'ambiente, che però conserva le funzionalità API e di sistema da cui dipende l'applicazione.

Le modifiche sotto l'API, ad esempio quelle nel sistema sottostante stesso, possono influire sulla tua applicazione quando viene eseguita nel nuovo ambiente. In qualità di sviluppatore dell'applicazione, è importante capire l'aspetto e il comportamento dell'applicazione in ciascun ambiente del sistema.

Per aiutarti a testare la tua applicazione su varie versioni della piattaforma Android, l'SDK Android include più piattaforme che puoi scaricare. Ogni piattaforma include un'immagine di sistema compatibile che puoi eseguire in una durata di visualizzazione media per testare l'applicazione.

Compatibilità con le versioni precedenti dell'applicazione

Le app Android non sono necessariamente compatibili con le versioni precedenti della piattaforma Android rispetto alla versione in base alla quale sono state compilate.

Ogni nuova versione della piattaforma Android può includere nuove API framework, ad esempio quelle che consentono alle applicazioni di accedere a nuove funzionalità della piattaforma o sostituiscono le parti dell'API esistenti. Le nuove API sono accessibili alle applicazioni quando vengono eseguite sulla nuova piattaforma e anche quando vengono eseguite su versioni successive della piattaforma, come specificato dal livello API. Tuttavia, poiché le versioni precedenti della piattaforma non includono le nuove API, le applicazioni che utilizzano le nuove API non possono essere eseguite su quelle piattaforme.

Sebbene non sia probabile che venga eseguito il downgrade a una versione precedente della piattaforma per un dispositivo Android, è importante capire che sul campo ci sono molti dispositivi con versioni precedenti della piattaforma. Anche tra i dispositivi che ricevono aggiornamenti OTA, alcuni potrebbero essere in ritardo e non ricevere aggiornamenti per un periodo di tempo significativo.

Seleziona una versione della piattaforma e un livello API

Durante lo sviluppo dell'applicazione, scegli la versione della piattaforma in base alla quale compili l'applicazione. In generale, compila l'applicazione rispetto alla versione più bassa possibile della piattaforma supportata dall'applicazione.

Puoi determinare la versione della piattaforma più bassa possibile compilando l'applicazione in base a target di build successivamente inferiori. Dopo aver determinato la versione più bassa, crea una durata di visualizzazione media utilizzando la versione della piattaforma e il livello API corrispondenti, quindi testa completamente l'applicazione. Assicurati di dichiarare un attributo android:minSdkVersion nel manifest dell'applicazione e di impostarne il valore sul livello API della versione della piattaforma.

Dichiarare un livello API minimo

Se crei un'applicazione che utilizza API o funzionalità di sistema introdotte nella versione più recente della piattaforma, imposta l'attributo android:minSdkVersion sul livello API della versione più recente della piattaforma. In questo modo gli utenti potranno installare la tua applicazione solo se sui loro dispositivi è installata una versione compatibile della piattaforma Android. A sua volta, ciò aiuta a garantire che l'applicazione possa funzionare correttamente sui relativi dispositivi.

Se la tua applicazione utilizza API introdotte nell'ultima versione della piattaforma ma non dichiara un attributo android:minSdkVersion, allora viene eseguita correttamente sui dispositivi che eseguono l'ultima versione della piattaforma, ma non su dispositivi che eseguono versioni precedenti della piattaforma. Nel secondo caso, l'applicazione si arresta in modo anomalo in fase di runtime quando tenta di utilizzare API che non esistono nelle versioni precedenti.

Esegui il test rispetto a livelli API più elevati

Dopo aver compilato la tua applicazione, assicurati di testarla sulla piattaforma specificata nell'attributo android:minSdkVersion dell'applicazione. Per farlo, crea una durata di visualizzazione media che utilizzi la versione della piattaforma richiesta dalla tua applicazione. Inoltre, per verificare la compatibilità con il futuro, esegui e testa l'applicazione su tutte le piattaforme che utilizzano un livello API superiore a quello utilizzato dalla tua applicazione.

L'SDK Android include più versioni della piattaforma che puoi utilizzare, compresa la versione più recente, e fornisce uno strumento di aggiornamento che puoi usare per scaricare altre versioni della piattaforma, se necessario.

Per accedere al programma di aggiornamento, utilizza lo strumento a riga di comando android, disponibile nella directory <sdk>/tools. Puoi avviare il programma di aggiornamento dell'SDK eseguendo android sdk. Puoi anche fare doppio clic sul file android.bat (Windows) o android (OS X/Linux).

Per eseguire l'applicazione su diverse versioni della piattaforma nell'emulatore, crea una durata di visualizzazione media per ogni versione della piattaforma che vuoi testare. Per ulteriori informazioni sulla durata di visualizzazione media, consulta l'articolo Creare e gestire dispositivi virtuali. Se utilizzi un dispositivo fisico per i test, assicurati di conoscere il livello API della piattaforma Android che esegue. Consulta la tabella di questo documento per un elenco delle versioni della piattaforma e dei relativi livelli API.

Filtra la documentazione di riferimento per livello API

Le pagine della documentazione di riferimento della piattaforma Android offrono un controllo "Livello API" nell'area in alto a sinistra di ogni pagina. Puoi utilizzare il controllo per visualizzare la documentazione solo per le parti dell'API che sono effettivamente accessibili alla tua applicazione, in base al livello API specificato nell'attributo android:minSdkVersion del relativo file manifest.

Per utilizzare i filtri, seleziona dal menu il livello API specificato dall'applicazione. Le API introdotte in un livello API successivo vengono visualizzate in grigio e il loro contenuto è mascherato, dato che non sono accessibili alla tua applicazione.

Il filtro per livello API nella documentazione non fornisce una visione delle novità o di quelle introdotte in ogni livello API. Consente di visualizzare l'intera API associata a un determinato livello API, escludendo al contempo gli elementi dell'API introdotti nei livelli API successivi.

Per tornare a visualizzare la documentazione completa, seleziona REL nella parte superiore del menu del livello API. Per impostazione predefinita, il filtro a livello di API è disabilitato, in modo da poter visualizzare l'API completa del framework, indipendentemente dal livello API.

La documentazione di riferimento per i singoli elementi API specifica il livello API a cui viene introdotto ogni elemento. Il livello API per pacchetti e classi è specificato come "Aggiunto nel livello API" nell'angolo in alto a destra dell'area dei contenuti in ogni pagina della documentazione. Il livello API per i membri della classe è specificato nelle intestazioni dettagliate della descrizione, sul margine destro.