管理應用程式版本

版本管理是應用程式升級與維護策略的重要一環，原因如下：

  • 對於裝置上已安裝的應用程式版本和可安裝的升級版本，使用者都需要瞭解具體的相關資訊。
  • 其他應用程式 (包括您以套件形式發布的其他應用程式) 需要向系統查詢您的應用程式版本，才能判斷相容性及識別依附元件。
  • 發布應用程式所用的服務可能需要向您的應用程式查詢版本資訊，才能顯示版本給使用者查看。此外，為了判斷相容性及建立升級/降級關係，發布服務可能也會需要檢查應用程式版本。

Android 系統會利用應用程式的版本資訊防止發生降級情形，但不會將該資訊用於強制執行有關更新或第三方應用程式相容性的限制。如有任何版本限制，都必須由您的應用程式強制執行，而且應該告知使用者。

Android 系統會根據建構檔案中的 minSdkVersion 設定所示，強制執行有關「系統」版本相容性的限制。透過這項設定，應用程式可指定與本身相容的最低系統 API 版本。詳情請參閱「指定 API 級別規定」一節。

設定應用程式版本資訊

如要定義應用程式的版本資訊，請在 Gradle 建構檔案中指定版本設定值。接著，這些值會在建構程序中併入應用程式的資訊清單檔案。

注意：如果應用程式直接在 <manifest> 元素中定義應用程式版本，Gradle 建構檔案內的版本值將覆寫資訊清單中的設定。此外，藉由在 Gradle 建構檔案中定義這些設定，您可以針對應用程式的各種版本指定不同的值。為了提升靈活度，以及在資訊清單合併時避免可能的覆寫情況，您應該從 <manifest> 元素中移除這些屬性，並改為在 Gradle 建構檔案中定義版本設定。

以下列出兩種可用的設定，請務必定義這些設定的值：

  • versionCode：做為內部版本號碼的正整數。這組號碼是由下方的 versionName 設定所指定，只會用於判定哪個版本較新 (號碼越大表示版本越新)，並不會向使用者顯示。Android 系統會利用 versionCode 值防止發生降級情形，做法是以裝置上現已安裝的版本為準，禁止使用者安裝 versionCode 較低的 APK。

    這個值是正整數，因此可讓其他應用程式透過程式輔助的方式評估，例如確認升級或降級關係。您可以視需求將該值設為任何正整數，但應確保應用程式連續發布的個別版本採用依序遞增的值。如果 APK 設定先前版本用過的 versionCode，就不得上傳至 Play 商店。

    注意：在某些特定情況下，您可能會想上傳 versionCode 低於最新版本的應用程式版本，例如在即將發布多個 APK 時預先設定特定 APK 的 versionCode 範圍。如要進一步瞭解如何為多個 APK 指派 versionCode 值，請參閱「支援多個 APK」一文。

    一般而言，您會將第一個應用程式版本的 versionCode 設為 1，接著以單調遞增的方式設定後續個別版本的值，無論該版本屬於主要或次要版本皆然。也就是說，versionCode 值不一定會與使用者看到的應用程式發布版本非常相似 (詳情請見下方的 versionName)。應用程式和發布服務不應向使用者顯示這個版本值。

    警告：Google Play 允許的 versionCode 上限值為 2100000000。

  • versionName：做為使用者所見版本號碼的字串。此設定可指定為原始字串，或是字串資源的參照。

    這個值是字串，因此您可以將應用程式版本描述為 <major>.<minor>.<point> 字串，或者任何其他類型的確切或相對版本 ID。除了向使用者顯示之外，versionName 並沒有其他用途。

如要定義這類設定的預設值，請將該設定加入 defaultConfig {} 區塊，此區塊是以巢狀結構的形式置於模組 build.gradle 檔案的 android {} 區塊中。接著，您可以分別定義各建構類型或變種版本的值，藉此針對應用程式的不同版本覆寫這些預設值。下方的 build.gradle 檔案列出 defaultConfig {} 和 productFlavors {} 區塊中的 versionCode 與 versionName 設定。

Groovy

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") {
            ...
        }
    }
}

在上方示例的 defaultConfig {} 區塊中，versionCode 值表示當前 APK 含有應用程式的第二個版本，而 versionName 字串則指定該版本會向使用者顯示為第 1.1 版。此 build.gradle 檔案一併定義了「demo」和「full」這兩個變種版本。由於「demo」變種版本將 versionName 定義為「1.1-demo」，因此會採用這個 versionName，而非預設值。「full」變種版本並未定義 versionName，所以會採用預設值「1.1」。

Android 架構提供的 API 可讓您向系統查詢與應用程式相關的版本資訊。如要取得這類資訊，請使用 PackageManager 的 getPackageInfo(java.lang.String, int) 方法。

指定 API 級別規定

如果您的應用程式要規定適用的特定最低 Android 平台版本，您可以在應用程式的 build.gradle 檔案中將版本規定指定為 API 級別設定。這些設定會在建構程序中併入應用程式的資訊清單檔案。透過指定 API 級別規定，您可以確保應用程式只能安裝在搭載相容 Android 平台版本的裝置上。

注意：如果您直接在應用程式的資訊清單檔案中指定 API 級別規定，建構檔案內的對應設定將覆寫資訊清單檔案中的設定。此外，藉由在 Gradle 建構檔案中定義這些設定，您可以針對應用程式的各種版本指定不同的值。為了提升靈活度，以及在資訊清單合併時避免可能的覆寫情況，您應該從 <uses-sdk> 元素中移除這些屬性，並改為在 Gradle 建構檔案中定義 API 級別設定。

以下列出兩種可用的 API 級別設定：

  • minSdkVersion：由 Android 平台的 API 級別 ID 所指定，表示應用程式執行平台的最低版本。
  • targetSdkVersion：指定可執行應用程式的 API 級別。在某些情況下，這項設定可讓應用程式採用目標 API 級別中定義的資訊清單元素或行為，而不是限制應用程式只能採用針對最低 API 級別所定義的元素或行為。

如要在 build.gradle 檔案中指定預設的 API 級別規定，請將上述一或多項設定新增至 defaultConfig {} 區塊，此區塊是以巢狀結構的形式置於 android {} 區塊中。您也可以將這些設定新增到建構類型或變種版本，藉此針對應用程式的不同版本覆寫這些預設值。下方的 build.gradle 檔案在 defaultConfig {} 區塊中指定預設的 minSdkVersion 和 targetSdkVersion 設定，並覆寫一個變種版本的 minSdkVersion。

Groovy

android {
    ...
    defaultConfig {
        ...
        minSdkVersion 14
        targetSdkVersion 24
    }
    productFlavors {
        main {
            ...
        }
        afterLollipop {
            ...
            minSdkVersion 21
        }
    }
}

Kotlin

android {
    ...
    defaultConfig {
        ...
        minSdkVersion(14)
        targetSdkVersion(24)
    }
    productFlavors {
        create("main") {
          ...
        }
        create("afterLollipop") {
          ...
          minSdkVersion(21)
        }
    }
}

準備安裝應用程式時，系統會檢查上述設定的值，並與系統版本比較。一旦 minSdkVersion 值大於系統版本，系統就會禁止安裝應用程式。

如果您並未指定這些值，系統則會假設應用程式與所有平台版本相容。

詳情請參閱 <uses-sdk> 資訊清單元素說明文件和 API 級別文件。如要瞭解 Gradle 建構設定，請參閱「設定建構變數」一文。