Version Code: その概要、数値識別子、アップデット

AndroidにおけるVersion Codeとは

Version CodeはInteger型の整数で、Androidアプリケーションの各ビルドに割り当てられます。Version Nameとは異なり、Version Codeはユーザーに表示されず、オペレーティングシステムとGoogle Playがアップデートインストール時にバージョンを比較するためにのみ使用されます。

Version Codeの形式

Version Codeは1から2100000000の範囲の正の整数でなければなりません。後続の各ビルドは、前回より厳密に大きいVersion Codeを持つ必要があります。開発者がVersion Code 5のビルドをリリースした場合、次の公開では6、7、または5より大きい任意の数値を使用できますが、4や再び5は使用できません。

起源の歴史

Googleは2007年のAndroid SDKリリースとともにVersion CodeとVersion Nameの分割を導入しました。Version Codeは自動バージョン比較のためのマシン識別子として設計され、Version Nameは人間が読めるラベルとして設計されました。この分割により、開発者はバージョンに任意の名前を付けつつ、数値コードによる厳格なアップデート順序を維持できます。

Version Codeによるバージョニングの仕組み

Version Codeの比較メカニズムはAndroidオペレーティングシステムとGoogle Playストアに組み込まれています。公開のたびに、Google Playは新しいビルドのVersion Codeがインストール済みバージョンのコードより大きいことを確認します。条件が満たされない場合、公開はエラーで拒否されます。

アップデート確認プロセス

デバイスがアップデートを確認するためにGoogle Playに接続すると、サーバーはインストール済みアプリケーションのVersion Codeとストアで利用可能な最大値を比較します。サーバー上のコードが大きい場合、アップデートのダウンロードとインストールが開始されます。ユーザーは開発者が指定したVersion Nameを表示しますが、アップデートの判断はVersion Codeに基づいて行われます。

Version Codeの増分

開発者はVersion Codeを増やすためにさまざまな戦略を適用します。最も簡単なのは、ビルドごとに1ずつ増やすことです。CI/CDパイプラインでは、タイムスタンプやビルド番号がよく使用されます：2026070301（年-月-日-番号）。コードが単調に増加し、異なるビルドやGoogle Playトラック間で重複しないことが重要です。

• 単調増加 — リリースブランチへのコミットごとに1ずつ増加
• タイムスタンプ形式 — 日次ビルドの場合は20260703、1日に複数ビルドの場合は2026070301
• 数値でのSemVer — バージョン1.1.0の場合は100010000（major 1、minor 1、patch 0）
• ビルド番号 — CIシステム（Jenkins、GitHub Actions）のBUILD_NUMBERを使用

Version CodeとVersion Nameの違い

Version CodeとVersion Nameはbuild.gradle内の2つの独立したフィールドで、異なる機能を果たします。Version Codeはシステム用の内部識別子であり、Version Nameはユーザー向けのマーケティングラベルです。これらは互いに独立して変更できます。

ユーザー向けのVersion Name

Version Nameはアプリケーション設定、Google Play、アップデートダイアログに表示される文字列です。開発者は任意の形式（1.0.0、2.3.1-beta、3.0-rc1など）を指定できます。Version Nameは文字列バージョンの比較には使用されません — Google Playは常にVersion Codeに依存します。

乖離のシナリオ

Version Codeが増加してもVersion Nameが同じままである状況が可能です。例えば、開発者が機能を変更せずにホットフィックスビルドで重大なバグを修正する場合です。Version Nameは2.0.0のまま、Version Codeは5から6に変わります。Google Playはこのようなアップデートを正しく処理します。

// 例: version nameは変更されず、コードが増加する
android {
    defaultConfig {
        versionCode 6  // 以前は5 — 新機能のないホットフィックス
        versionName "2.0.0"  // 変更なし
    }
}

// ランタイムでのバージョン確認
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

build.gradleでのVersion Code設定

Version Codeの設定はアプリケーションモジュールのbuild.gradleファイルで行います。versionCodeフィールドは整数を受け入れ、defaultConfigブロックの一部です。異なるflavorビルドでは、プロダクト設定のversionCodeフィールドを通じてカスタム値を設定できます。

基本設定

// build.gradle.kts — Kotlin DSL
android {
    defaultConfig {
        applicationId "com.example.app"
        versionCode 15
        versionName "2.1.0"
    }

    flavorDimensions +"version"
    productFlavors {
        create("demo") {
            versionCode 1015
        }
        create("full") {
            versionCode 2015
        }
    }
}

Product flavorsを使用すると、異なる設定（デモ版、タブレット用の別バージョン）に異なるVersion Codeを使用できます。プロジェクトでflavorが使用されている場合、最終的なVersion Codeは基本数値とflavor固有の増分から構成されます。Google Playは各組み合わせを独立して追跡します。

CIによる増分の自動化

CI/CDパイプライン（GitHub Actions、GitLab CI、Jenkins）では、Version Codeはビルド番号や日付に基づいて自動生成されることがよくあります。これにより、手動アップデート時の人為的エラーが排除されます。スクリプトはbuild.gradleから現在のVersion Codeを読み取り、それを増分し、ビルド開始前に書き戻します。

// Version Codeの自動増分
import java.util.Properties
import java.io.FileInputStream

val versionProps = Properties()
versionProps.load(FileInputStream("version.properties"))

val versionCode = versionProps.getProperty("VERSION_CODE").toInt() + 1
versionProps.setProperty("VERSION_CODE", versionCode.toString())

android {
    defaultConfig {
        versionCode = versionCode
    }
}

Google Play公開におけるVersion Codeの特性

Google Playにはアプリの公開と更新に関するVersion Codeの厳格なルールがあります。これらのルールに違反すると、ビルドが拒否されたり、アップデートをリリースできなくなったりします。開発者はライフサイクルのすべての段階における制限とコード管理戦略を理解する必要があります。

単調増加ルール

Google Playは、Version Codeが現在公開されているもの以下であるAPKまたはAABのアップロードを許可しません。このルールは各トラック（production、beta、alpha）に独立して適用されます。productionにVersion Code 10のビルドがアップロードされ、alphaにコード5のビルドがある場合、alphaトラックは6、7、8、9に更新できますが、productionは10のままです。

トラック間の移行

ビルドをalphaからbeta、そしてproductionに昇格させる際、Version Codeは各段階で増加する必要があります。alphaバージョンのコードが10の場合、betaは11、productionは12を使用できます。alphaがすでに10を使用している場合、productionがまだそのコードを見たことがなくても、コード10のビルドをproductionにリリースすることはできません。

• 単調増加 — トラック内の各ビルドは、同じトラック内の前回より大きいVersion Codeを持つ
• クロストラック認識 — トラック間の昇格時に、Version Codeは順次増加する
• 内部テスト — 内部テストトラックも同じ単調性ルールを使用する
• 複数APK — 古い公開形式ではAPKごとに一意のVersion Codeが必要だった

Version Code指定時のエラー

最も一般的なエラーは、同じトラックにアップロードされた異なるビルドでのVersion Codeの一致です。Google PlayはAPK_VERSION_CODE_ALREADY_EXISTSエラーを返します。もう一つのエラーは、最大値2100000000を超えることで、コンパイルエラーが発生します。競合を避けるには、CIシステムでビルド番号またはビルド日付に紐づいた自動コード生成を使用してください。

開発者はまた、代替トラック用のホットフィックスリリースをビルドする際にVersion Codeを増やさないという間違いをよく犯します。productionのコードが15でalphaトラックが14のままの場合、alphaをproductionに昇格させると、Google Playはそのコードが現在のproductionコードより小さいためビルドを拒否します。すべてのトラックでコードの単調性を同時に監視してください — これには、すべてのトラックが現在値を読み取る単一のversion.propertiesファイルを使用すると便利です。