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 altre che pubblichi come suite, devono chiedere al sistema la versione dell'app per determinare la compatibilità e identificare le dipendenze.
  • I servizi in cui pubblichi le tue app potrebbero anche dover eseguire una query per conoscere la versione dell'app per poterne mostrare la versione agli utenti. Un servizio di pubblicazione potrebbe anche dover controllare la versione dell'app per determinare la compatibilità e stabilire 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 applicare limitazioni relative agli upgrade o alla compatibilità di app di terze parti. L'app deve applicare eventuali limitazioni di versione e informare gli utenti in merito.

Il sistema Android applica la compatibilità della versione del sistema, come indicato dall'impostazione minSdk nei file di build. Questa impostazione consente a un'app di specificare l'API di sistema minima con cui è compatibile. Per maggiori informazioni sui requisiti delle API, consulta la pagina Specificare i requisiti relativi ai livelli API.

I requisiti di controllo delle versioni variano tra progetti diversi. Tuttavia, molti sviluppatori considerano il controllo delle versioni semantico una buona base per una strategia di controllo delle versioni.

Impostare le informazioni sulla versione dell'app

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

Trendy

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

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

Kotlin

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

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

Impostazioni versione

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

versionCode
Un numero intero positivo utilizzato come numero di versione interno. Questo numero aiuta a determinare se una versione è più recente di un'altra, con numeri più alti che 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 gli utenti dai downgrade impedendo agli utenti di installare un APK con un valore versionCode inferiore alla versione attualmente installata sul dispositivo.

Il valore è un numero intero positivo che consente alle altre app di 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 dell'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 alcuni casi potresti voler caricare una versione dell'app con un valore inferiore a versionCode 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 di valori versionCode per più APK, consulta Assegnare i codici di versione.

In genere, rilasci la prima versione dell'app con versionCode impostato su 1, per poi aumentare monotonicamente il valore a ogni release, a prescindere dal fatto che la release sia principale o secondaria. Ciò significa che il valore versionCode non assomiglia necessariamente alla versione di release dell'app visibile all'utente. Le app e i servizi di pubblicazione non devono mostrare questo valore di 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 per consentirti di descrivere la versione dell'app come 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 includendole nel blocco defaultConfig {}, nidificato all'interno del blocco android {} del file build.gradle o build.gradle.kts del tuo modulo. Puoi quindi eseguire l'override di questi valori predefiniti per le diverse versioni dell'app definendo valori separati per singoli tipi di build o versioni di prodotto. Il seguente file mostra le impostazioni versionCode e versionName nel blocco defaultConfig {}, nonché nel blocco productFlavors {}.

Questi valori vengono quindi uniti nel file manifest dell'app durante il processo di creazione.

Trendy

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

Kotlin

    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 corrente contiene la seconda release dell'app, mentre la stringa versionName specifica che verrà mostrata agli utenti come versione 1.1. Questo file definisce anche due versioni di prodotto, "demo" e "full". Poiché la versione del prodotto "demo" definisce versionName come "1.1-demo", la build "demo" utilizza questo versionName anziché il valore predefinito. Il blocco delle versioni di prodotto "completo" non definisce versionName, quindi utilizza il valore predefinito "1.1".

Nota: se l'app definisce la versione dell'app direttamente nell'elemento <manifest>, i valori della versione nel file di build Gradle sovrascrivono le impostazioni nel file manifest. Inoltre, la definizione di queste impostazioni nei file di build Gradle ti consente di specificare valori diversi per le diverse versioni dell'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 ti consente di eseguire query sul sistema per ottenere informazioni sulla versione dell'app. Per ottenere informazioni sulla versione, usa il metodo PackageManager.getPackageInfo(java.lang.String, int).

Specificare i requisiti dei livelli API

Se la tua app richiede una versione minima specifica della piattaforma Android, puoi specificare tale requisito di versione come impostazioni a livello di API nel file build.gradle o build.gradle.kts dell'app. Durante il processo di compilazione, queste impostazioni vengono unite nel file manifest dell'app. Se specifichi i requisiti relativi ai livelli API, ti assicuri che la tua app possa essere installata solo su dispositivi che eseguono una versione compatibile della piattaforma Android.

Nota: se specifichi i requisiti relativi ai livelli API direttamente nel file manifest dell'app, le impostazioni corrispondenti nei file di build sostituiranno le impostazioni del file manifest. Inoltre, la definizione di queste impostazioni nei file di build Gradle ti consente di specificare valori diversi per le diverse versioni dell'app. Per una maggiore flessibilità ed evitare potenziali sovrascritture quando il manifest viene unito, rimuovi questi attributi dall'elemento <uses-sdk> e definisci le impostazioni a livello di API nei file di build Gradle.

Sono disponibili due impostazioni a livello di 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 su cui è progettata l'esecuzione dell'app. In alcuni casi, ciò consente all'app 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.

Per specificare i requisiti predefiniti per i livelli API in un file build.gradle o build.gradle.kts, aggiungi una o più impostazioni a livello di API al blocco defaultConfig{}, nidificate all'interno del blocco android {}. Puoi anche eseguire l'override di questi valori predefiniti per diverse versioni dell'app aggiungendo le impostazioni per creare tipi o versioni di prodotto.

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

Trendy

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

Kotlin

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

Durante la preparazione all'installazione dell'app, il sistema controlla il valore di queste impostazioni e le 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 ulteriori informazioni, consulta la sezione Che cos'è il livello API?. Per le impostazioni della build Gradle, consulta l'articolo Configurare le varianti della build.