Google Play utilizza gli attributi <uses-sdk> dichiarati nel file manifest dell'app per filtrare l'app dai dispositivi che non soddisfano i requisiti della versione della piattaforma. Prima di impostare questi attributi, assicurati di aver compreso i filtri di Google Play.
- Sintassi:
<uses-sdk android:minSdkVersion="integer" android:targetSdkVersion="integer" android:maxSdkVersion="integer" />
- contenuto in:
<manifest>- description:
Consente di esprimere la compatibilità di un'applicazione con una o più versioni della piattaforma Android tramite un numero intero del livello API. Il livello API espresso da un'applicazione viene confrontato con il livello API di un determinato sistema Android, che può variare tra i diversi 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 dedurre il livello API dal numero di versione di Android associato. Ad esempio, non è la stessa della versione principale o della somma delle versioni principale e secondaria.
Non è possibile specificare che un'app ha come target o richiede una versione secondaria dell'SDK.
Leggi anche il documento sul controllo delle versioni delle applicazioni.
- attributi:
-
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 "1", che indica che la tua applicazione è compatibile con tutte le versioni di Android. Se non lo è e non hai dichiarato l'elemento
minSdkVersionappropriato, l'applicazione 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'attributominSdkVersion. android:targetSdkVersion- Un numero intero che indica il livello API scelto come target dall'applicazione. Se non viene impostato, il valore predefinito è uguale a quello assegnato a
minSdkVersion.Questo attributo informa il sistema che hai eseguito i test con la versione di destinazione e il sistema non attiva alcun comportamento di compatibilità per mantenere la compatibilità con le versioni successive dell'app con la versione di destinazione. L'applicazione è ancora in grado di funzionare su 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 alla versione dichiarata dall'attributo
targetSdkVersiondella tua app, il sistema può attivare comportamenti di compatibilità in modo che l'app continui a funzionare come previsto. Puoi disattivare questi comportamenti di compatibilità specificandotargetSdkVersionin modo che corrisponda al livello API della piattaforma su cui è in esecuzione.Ad esempio, l'impostazione di questo valore su "11" o su un valore 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 quando viene eseguita su schermi più grandi, perché il supporto per il 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 mantenere l'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 l'applicazione sulla versione della piattaforma corrispondente.
Introdotto in: livello API 4
- Un numero intero che indica il livello API massimo su cui l'applicazione è progettata per essere eseguita.
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 nuova convalida dell'applicazione dopo un aggiornamento di sistema. In entrambi i casi, se l'attributo
maxSdkVersiondell'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 di sistema, l'applicazione viene effettivamente rimossa dal dispositivo.Per illustrare in che modo questo attributo può influire sulla tua applicazione dopo gli aggiornamenti di sistema, considera il seguente esempio:
Un'applicazione che dichiara
maxSdkVersion="5"nel suo manifest viene pubblicata su Google Play. Un utente con un dispositivo su cui è installato 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 l'installazione dell'aggiornamento, il sistema controlla ilmaxSdkVersiondell'applicazione e lo convalida nuovamente con successo.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 del sistema (6) è ora superiore al livello massimo supportato dall'applicazione (5). Il sistema impedisce all'utente di visualizzare l'applicazione, rimuovendola di fatto dal dispositivo.
Avviso: sconsigliamo di dichiarare questo attributo. Innanzitutto, non è necessario impostare l'attributo per bloccare il deployment della tua applicazione su nuove versioni della piattaforma Android man mano che vengono rilasciate. Per progettazione, le nuove versioni della piattaforma sono completamente compatibili con le versioni precedenti. La tua applicazione funziona correttamente sulle nuove versioni, a condizione che utilizzi solo API standard e segua le best practice di sviluppo. In secondo luogo, in alcuni casi la dichiarazione dell'attributo può comportare la rimozione dell'applicazione dai dispositivi degli utenti dopo un aggiornamento di sistema a un livello API superiore. La maggior parte dei dispositivi su cui è probabile che venga installata la tua applicazione riceve aggiornamenti di sistema periodici over-the-air, quindi considera il loro effetto sulla tua applicazione prima di impostare questo attributo.
Introdotto in: livello API 4
Alcune versioni di Android (oltre ad Android 2.0.1) non controllano o applicano l'attributomaxSdkVersiondurante l'installazione o la nuova convalida. Tuttavia, Google Play continua a utilizzare l'attributo come filtro quando presenta agli utenti le applicazioni disponibili per il download.
- introdotta in:
- Livello API 1
Che cos'è il livello API?
Il livello API è un valore intero che identifica in modo univoco la revisione dell'API del framework offerta da una versione della piattaforma Android.
La piattaforma Android fornisce un'API del framework che le applicazioni possono utilizzare per interagire con il sistema Android sottostante. L'API del framework è costituita da:
- Un insieme di base di pacchetti e classi
- Un insieme di elementi e attributi XML per la dichiarazione di un file manifest
- Un insieme di elementi e attributi XML per dichiarare e accedere alle risorse
- Un insieme di intent
- Un insieme di autorizzazioni che le applicazioni possono richiedere, nonché le applicazioni delle autorizzazioni incluse nel sistema
Ogni versione successiva della piattaforma Android può includere aggiornamenti all'API del framework delle app per Android che fornisce.
Gli aggiornamenti all'API del framework sono progettati in modo che la nuova API rimanga compatibile con le versioni precedenti. In altre parole, la maggior parte delle modifiche all'API sono additive e introducono funzionalità nuove o sostitutive. Man mano che viene eseguito l'upgrade delle parti dell'API, le parti precedenti sostituite vengono ritirate, ma non rimosse, in modo che le applicazioni esistenti possano continuare a utilizzarle.
In un numero molto ridotto di casi, alcune parti dell'API vengono modificate o rimosse, anche se in genere queste modifiche sono necessarie solo per supportare la robustezza dell'API e la sicurezza dell'applicazione o del sistema. Tutte le altre parti dell'API delle revisioni precedenti vengono riportate senza modifiche.
L'API del 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, anche se il supporto è implicito per tutti i livelli API precedenti (fino al livello API 1). La release iniziale della piattaforma Android ha fornito il livello API 1 e le release successive hanno incrementato il livello API. Le API introdotte o ritirate negli SDK di anteprima pre-release che non hanno raggiunto la stabilità della piattaforma sono contrassegnate come "API in fase di sviluppo" anziché con un numero di livello API.
La tabella seguente specifica il livello API supportato da ogni versione della piattaforma Android. Per informazioni sul numero relativo di dispositivi che eseguono ciascuna versione, consulta la dashboard di distribuzione.
API in fase di sviluppo
Nella documentazione di riferimento dell'API Android, le API aggiunte o ritirate in un SDK pre-release sono contrassegnate con "API in fase di sviluppo" anziché con un numero di livello API. Questa etichetta si applica alle notifiche "Aggiunta in" e "Ritirata in" finché l'SDK non raggiunge la stabilità della piattaforma e non riceve un livello API principale o secondario finale. Le API in fase di sviluppo hanno le seguenti caratteristiche:
- Stato di anteprima pre-release: l'aggiunta o la deprecazione dell'API fa parte di una release SDK di anteprima beta o canary attiva prima della finalizzazione del livello API.
- Nessuna garanzia di stabilità: a differenza delle API rilasciate (che hanno un livello API permanente e sono compatibili con le versioni precedenti), le API in fase di sviluppo potrebbero cambiare firma, essere rinominate o essere rimosse completamente tra le release dell'SDK in anteprima.
Controlla la presenza di API in fase di sviluppo in fase di runtime (PREVIEW_SDK_INT)
Poiché le API in fase di sviluppo possono cambiare o scomparire tra le versioni di anteprima, non utilizzare mai un controllo maggiore o uguale a (>=) per proteggere le chiamate alle API non rilasciate. Un'API presente nell'anteprima 1 potrebbe essere modificata o eliminata nell'anteprima 2.
Le app che sperimentano le funzionalità in anteprima devono invece verificare l'uguaglianza rigorosa (==) del valore Build.VERSION.PREVIEW_SDK_INT con la revisione esatta dell'anteprima con cui è stata compilata l'app:
- Nelle build e nelle release di produzione finali,
Build.VERSION.PREVIEW_SDK_INTè sempre0. - Nelle build di anteprima,
PREVIEW_SDK_INTè univoco per ogni release.
Utilizzi del livello API in Android
L'identificatore del livello API svolge un ruolo chiave nel garantire la migliore esperienza possibile per gli utenti e gli sviluppatori di applicazioni:
- Consente alla piattaforma Android di descrivere la revisione massima dell'API del framework che supporta.
- Consente alle applicazioni di descrivere la revisione dell'API del 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 memorizza internamente l'identificatore del livello API, nel sistema Android stesso.
Le applicazioni possono utilizzare un elemento manifest fornito dall'API del framework, <uses-sdk>, per descrivere i livelli API minimo e massimo in cui 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 l'applicazione può essere eseguita. Il valore predefinito è "1".android:targetSdkVersion: il livello API su cui è progettata l'esecuzione dell'applicazione. In alcuni casi, ciò consente all'applicazione di utilizzare elementi o comportamenti del file manifest definiti nel livello API target, anziché essere limitata a utilizzare solo quelli definiti per il livello API minimo.android:maxSdkVersion: il livello API massimo su cui l'applicazione può essere eseguita. Importante: prima di utilizzare questo attributo, leggi le informazioni relative riportate in questa pagina.
Ad esempio, per specificare il livello API di sistema minimo richiesto da un'applicazione per l'esecuzione, l'applicazione include nel proprio manifest un elemento <uses-sdk> con un attributo android:minSdkVersion. Il valore di android:minSdkVersion è l'intero corrispondente al livello API della versione meno recente della piattaforma Android in cui l'applicazione può essere eseguita.
Quando l'utente tenta di installare un'applicazione o quando convalida nuovamente 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 l'avvio dell'installazione solo se sono soddisfatte queste condizioni:
- Se viene dichiarato un attributo
android:minSdkVersion, il suo valore è minore o uguale al numero intero del livello 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 maggiore del numero intero del livello 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 saperne di più su come viene gestito dal sistema.
Se dichiarato nel file 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 API introdotte nel livello API specificato.
Se l'applicazione viene installata in qualche modo 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 non consentendo 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 sezioni seguenti forniscono informazioni relative al livello API che devi considerare durante lo sviluppo della tua applicazione.
Compatibilità con le versioni successive dell'applicazione
Le app per Android sono generalmente compatibili con le nuove versioni della piattaforma Android.
Poiché quasi tutte le modifiche all'API del framework sono additive, un'app per 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, ad eccezione di casi isolati in cui l'applicazione utilizza una parte dell'API che viene successivamente rimossa per qualche motivo.
La compatibilità con le versioni successive è importante perché molti dispositivi Android ricevono aggiornamenti di sistema over-the-air (OTA). L'utente potrebbe installare la tua applicazione e utilizzarla correttamente, per 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 runtime dell'ambiente, che però dispone ancora delle funzionalità API e di sistema da cui dipende l'applicazione.
Le modifiche al di sotto dell'API, ad esempio quelle nel sistema sottostante, possono influire sulla tua applicazione quando viene eseguita nel nuovo ambiente. In qualità di sviluppatore di applicazioni, è importante che tu comprenda l'aspetto e il comportamento dell'applicazione in ogni ambiente di 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 un AVD per testare la tua applicazione.
Compatibilità con le versioni precedenti delle applicazioni
Le app per Android non sono necessariamente compatibili con le versioni della piattaforma Android precedenti a quella con cui sono state compilate.
Ogni nuova versione della piattaforma Android può includere nuove API del framework, ad esempio quelle che consentono alle applicazioni di accedere a nuove funzionalità della piattaforma o di sostituire parti di 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 le utilizzano non possono essere eseguite su queste piattaforme.
Sebbene sia improbabile che un dispositivo Android venga sottoposto a downgrade a una versione precedente della piattaforma, è importante tenere presente che è probabile che sul campo siano presenti molti dispositivi che eseguono versioni precedenti della piattaforma. Anche tra i dispositivi che ricevono aggiornamenti OTA, alcuni potrebbero subire ritardi e non ricevere un aggiornamento per un periodo di tempo significativo.
Seleziona una versione della piattaforma e un livello API
Quando sviluppi l'applicazione, scegli la versione della piattaforma con cui compilarla. In generale, compila l'applicazione con la versione più bassa possibile della piattaforma supportata dall'applicazione.
Puoi determinare la versione più bassa possibile della piattaforma compilando l'applicazione con target di build progressivamente più bassi. Dopo aver determinato la versione più bassa, crea un AVD utilizzando la versione della piattaforma e il livello API corrispondenti e testa completamente l'applicazione. Assicurati di dichiarare un attributo android:minSdkVersion nel manifest dell'applicazione e di impostare il relativo valore sul livello API della versione della piattaforma.
Dichiara un livello API minimo
Se crei un'applicazione che utilizza API o funzionalità di sistema introdotte nell'ultima versione della piattaforma, imposta l'attributo android:minSdkVersion sul livello API dell'ultima versione della piattaforma. In questo modo, gli utenti possono installare la tua applicazione solo se sui loro dispositivi è in esecuzione una versione compatibile della piattaforma Android. A sua volta, questo aiuta a garantire che la tua applicazione possa funzionare correttamente sui loro dispositivi.
Se la tua applicazione utilizza API introdotte nell'ultima versione della piattaforma, ma
non dichiara un attributo android:minSdkVersion,
funziona correttamente sui dispositivi con l'ultima versione della piattaforma, ma
non sui dispositivi con versioni precedenti della piattaforma. In quest'ultimo caso, l'applicazione si arresta in modo anomalo in fase di runtime quando tenta di utilizzare API che non esistono nelle versioni precedenti.
Esegui test con livelli API più elevati
Dopo aver compilato l'applicazione, assicurati di testarla sulla piattaforma specificata nell'attributo android:minSdkVersion dell'applicazione. Per farlo, crea un AVD che utilizzi la versione della piattaforma richiesta dalla tua applicazione. Inoltre, per verificare la compatibilità con le versioni successive, 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, inclusa l'ultima versione, e fornisce uno strumento di aggiornamento che puoi utilizzare per scaricare altre versioni della piattaforma, se necessario.
Per accedere all'updater, utilizza lo strumento a riga di comando android, che si trova nella directory <sdk>/tools. Puoi avviare l'updater dell'SDK eseguendo android sdk. Puoi anche fare doppio clic sul file android.bat (Windows) o android (OS X/Linux).
Per eseguire l'applicazione con versioni diverse della piattaforma nell'emulatore, crea un AVD per ogni versione della piattaforma che vuoi testare. Per saperne di più sugli AVD, consulta Crea e gestisci dispositivi virtuali. Se utilizzi un dispositivo fisico per i test, assicurati di conoscere il livello API della piattaforma Android su cui viene eseguito. Consulta la tabella in 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 mostrare la documentazione solo per le parti dell'API effettivamente accessibili alla tua applicazione, in base al livello API specificato nell'attributo android:minSdkVersion del file manifest.
Per utilizzare i filtri, seleziona dal menu il livello API specificato dalla tua applicazione. Le API introdotte in un livello API successivo vengono quindi disattivate e i relativi contenuti vengono mascherati, poiché non sono accessibili alla tua applicazione.
Il filtro per livello API nella documentazione non fornisce una visualizzazione delle novità o delle funzionalità introdotte in ogni livello API. Fornisce un modo per visualizzare l'intera API associata a un determinato livello API, escludendo gli elementi API introdotti nei livelli API successivi.
Per tornare alla visualizzazione della documentazione completa, seleziona REL nella parte superiore del menu dei livelli API. Per impostazione predefinita, il filtro per livello API è disattivato, in modo da poter visualizzare l'API del framework completa, indipendentemente dal livello API.
La documentazione di riferimento per i singoli elementi dell'API specifica il livello API in cui ogni elemento viene introdotto o ritirato. Il livello API per pacchetti e classi è specificato come "Aggiunto nel livello API" e, se applicabile, "Ritirato nel livello API" nell'angolo in alto a destra dell'area dei contenuti di ogni pagina della documentazione. Il livello API per i membri della classe è specificato nelle intestazioni della descrizione dettagliata, nel margine destro. Per le aggiunte o le deprecazioni di API pre-release che non hanno raggiunto la stabilità della piattaforma, in queste posizioni viene visualizzato "API in fase di sviluppo" anziché un numero di livello API.