Versione dell'app

Il controllo delle versioni è un componente fondamentale della strategia di upgrade e manutenzione delle app. Il controllo delle versioni è importante perché:

• Gli utenti devono disporre di informazioni specifiche sulla versione dell'app installata sui loro dispositivi e sulle versioni di upgrade disponibili per l'installazione.
• Altre app, incluse quelle che pubblichi come suite, devono eseguire query sul sistema per conoscere la versione della tua app e determinare la compatibilità e identificare le dipendenze.
• I servizi in cui pubblichi le tue app potrebbero anche dover interrogare la tua app per la sua versione in modo da poterla mostrare agli utenti. Un servizio di pubblicazione potrebbe anche dover controllare la versione dell'app per determinare la compatibilità e stabilire le relazioni di upgrade/downgrade.

Il sistema Android utilizza le informazioni sulla versione dell'app per proteggere dai downgrade. Il sistema non utilizza le informazioni sulla versione dell'app per imporre restrizioni agli upgrade o alla compatibilità delle app di terze parti. La tua app deve applicare eventuali restrizioni di versione e informare gli utenti.

Il sistema Android applica la compatibilità della versione del sistema, come espresso dall'impostazione minSdk nei file di build. Questa impostazione consente a un'app di specificare l'API di sistema minima con cui è compatibile. Per ulteriori informazioni sui requisiti delle API, consulta la sezione Specificare i requisiti del livello API (versione SDK).

I requisiti di controllo delle versioni variano a seconda dei progetti. Tuttavia, molti sviluppatori considerano il versioning semantico una buona base per una strategia di controllo delle versioni.

Impostare le informazioni sulla versione dell'app

Per definire le informazioni sulla versione della tua app, imposta i valori per le impostazioni della versione nei file di build Gradle:

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...
    

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...
      

Impostazioni della versione

Definisci i valori per entrambe le impostazioni della versione disponibili: versionCode e versionName.

versionCode

Un numero intero positivo utilizzato come numero di versione interno. Questo numero consente di determinare se una versione è più recente di un'altra. I numeri più alti indicano le versioni più recenti. Questo non è il numero di versione mostrato agli utenti; questo numero è impostato dall'impostazione versionName. Il sistema Android utilizza il valore versionCode per proteggere dai downgrade impedendo agli utenti di installare un APK con un valore versionCode inferiore a quello della versione attualmente installata sul dispositivo.

Il valore è un numero intero positivo in modo che altre app possano valutarlo in modo programmatico, ad esempio per verificare una relazione di upgrade o downgrade. Puoi impostare il valore su qualsiasi numero intero positivo. Tuttavia, assicurati che ogni release successiva della tua app utilizzi un valore maggiore.

Nota:il valore massimo consentito da Google Play per versionCode è 2100000000.

Non puoi caricare un APK sul Play Store con un versionCode che hai già utilizzato per una versione precedente.

Nota:in alcune situazioni, potresti voler caricare una versione della tua app con un versionCode inferiore rispetto alla versione più recente. Ad esempio, se pubblichi più APK, potresti avere intervalli versionCode preimpostati per APK specifici. Per saperne di più sull'assegnazione dei valori versionCode per più APK, vedi Assegnazione dei codici di versione.

In genere, rilasci la prima versione dell'app con versionCode impostato su 1, poi aumenti in modo monotono il valore a ogni release, indipendentemente dal fatto che si tratti di una release principale o secondaria. Ciò significa che il valore di versionCode non corrisponde necessariamente alla versione di rilascio dell'app visibile all'utente. Le app e i servizi di pubblicazione non devono mostrare questo valore della versione agli utenti.

versionName

Una stringa utilizzata come numero di versione mostrato agli utenti. Questa impostazione può essere specificata come stringa non elaborata o come riferimento a una risorsa stringa.

Il valore è una stringa che ti consente di descrivere la versione dell'app come una stringa <major>.<minor>.<point> o come qualsiasi altro tipo di identificatore di versione assoluto o relativo. versionName è l'unico valore mostrato agli utenti.

Definisci i valori della versione

Puoi definire i valori predefiniti per queste impostazioni includendoli nel blocco defaultConfig {}, nidificato all'interno del blocco android {} del file build.gradle o build.gradle.kts del modulo. Puoi poi ignorare questi valori predefiniti per le diverse versioni della tua app definendo valori separati per singoli tipi di build o varianti del prodotto. Il seguente file mostra le impostazioni versionCode e versionName nel blocco defaultConfig {}, nonché il blocco productFlavors {}.

Questi valori vengono poi uniti nel file manifest della tua app durante il processo di build.

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }
    

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }
    

Nel blocco defaultConfig {} di questo esempio, il valore versionCode indica che l'APK attuale contiene la seconda release dell'app e la stringa versionName specifica che verrà visualizzata dagli utenti come versione 1.1. Questo file definisce anche due varianti del prodotto, "demo" e "full". Poiché la variante di prodotto "demo" definisce versionName come "1.1-demo", la build "demo" utilizza questo versionName anziché il valore predefinito. Il blocco "full" del prodotto non definisce versionName, quindi utilizza il valore predefinito "1.1".

Nota:se la tua app definisce la versione dell'app direttamente nell'elemento <manifest>, i valori della versione nel file di build Gradle ignorano le impostazioni nel manifest. Inoltre, la definizione di queste impostazioni nei file di build Gradle ti consente di specificare valori diversi per versioni diverse della tua app. Per una maggiore flessibilità ed evitare potenziali sovrascritture quando il manifest viene unito, rimuovi questi attributi dall'elemento <manifest> e definisci le impostazioni della versione nei file di build Gradle.

Il framework Android fornisce un'API che consente di eseguire query sul sistema per ottenere informazioni sulla versione della tua app. Per ottenere informazioni sulla versione, utilizza il metodo PackageManager.getPackageInfo(java.lang.String, int).

Specificare i requisiti del livello API (versione dell'SDK)

Se la tua app richiede una versione minima specifica della piattaforma Android, puoi specificare questo requisito di versione come impostazioni del livello API nel file build.gradle o build.gradle.kts dell'app. Durante la procedura di build, queste impostazioni vengono unite al file manifest dell'app. La specifica dei requisiti relativi al livello API garantisce che la tua app possa essere installata solo su dispositivi che eseguono una versione compatibile della piattaforma Android.

Nota:se specifichi i requisiti del livello API direttamente nel file manifest della tua app, le impostazioni corrispondenti nei file di build sostituiranno quelle nel file manifest. Inoltre, la definizione di queste impostazioni nei file di build Gradle ti consente di specificare valori diversi per versioni diverse della tua app. Per una maggiore flessibilità ed evitare potenziali sovrascritture durante l'unione del manifest, rimuovi questi attributi dall'elemento <uses-sdk> e definisci le impostazioni del livello API nei file di build Gradle.

Sono disponibili due impostazioni del livello API:

• minSdk: la versione minima della piattaforma Android su cui verrà eseguita l'app, specificata dall'identificatore del livello API della piattaforma.
• targetSdk: il livello API, collegato alla costante <SDK_INT>, su cui è progettata l'app. In alcuni casi, ciò consente all'app di utilizzare elementi o comportamenti del manifest definiti nel livello API di destinazione, anziché essere limitata all'utilizzo solo di quelli definiti per il livello API minimo.

Non è possibile specificare che un'app ha come target o richiede una versione secondaria dell'SDK. Per chiamare in modo sicuro nuove API che richiedono una versione principale o secondaria dell'SDK superiore a minSdkVersion, puoi proteggere un blocco di codice con un controllo per una release secondaria o principale utilizzando la costante SDK_INT_FULL.

if (SDK_INT_FULL >= VERSION_CODES_FULL.[MAJOR or MINOR RELEASE]) {
  // Use APIs introduced in a major or minor SDK version
}

Per specificare i requisiti del livello API predefinito in un file build.gradle o build.gradle.kts, aggiungi una o più impostazioni del livello API al blocco defaultConfig{}, nidificato all'interno del blocco android {}. Puoi anche sostituire questi valori predefiniti per diverse versioni della tua app aggiungendo le impostazioni ai tipi di build o alle varianti di prodotto.

Il seguente file specifica le impostazioni predefinite minSdk e targetSdk nel blocco defaultConfig {} e sostituisce minSdk per una variante del prodotto:

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

Durante la preparazione dell'installazione dell'app, il sistema controlla il valore di queste impostazioni e lo confronta con la versione del sistema. Se il valore minSdk è maggiore della versione del sistema, il sistema impedisce l'installazione dell'app.

Se non specifichi queste impostazioni, il sistema presuppone che la tua app sia compatibile con tutte le versioni della piattaforma. Equivale a impostare minSdk su 1.

Per saperne di più, vedi Che cos'è il livello API? Per le impostazioni di build di Gradle, vedi Configurare le varianti di build.