Version Code: چیست، شناسه عددی و به‌روزرسانی‌ها

Version Code در اندروید چیست

Version Code — یک عدد صحیح از نوع Integer است که به هر ساخت برنامه اندروید تخصیص داده می‌شود. بر خلاف Version Name، Version Code به کاربر نمایش داده نمی‌شود و صرفاً توسط سیستم عامل و Google Play برای مقایسه نسخه‌ها در زمان نصب به‌روزرسانی استفاده می‌شود.

فرمت Version Code

Version Code باید یک عدد صحیح مثبت در بازه 1 تا 2100000000 باشد. هر ساخت بعدی باید Version Code شدیداً بزرگتر از قبلی داشته باشد. اگر توسعه‌دهنده ساختی با Version Code 5 منتشر کرده باشد، انتشار بعدی می‌تواند 6، 7 یا هر عدد بزرگتر از 5 را استفاده کند، اما نه 4 و نه مجدداً 5.

تاریخچه طراحی

Google تقسیم به Version Code و Version Name را همراه با انتشار Android SDK در سال 2007 معرفی کرد. Version Code به عنوان یک شناسه ماشینی برای مقایسه خودکار نسخه‌ها طراحی شد، در حالی که Version Name برچسبی قابل خوانش برای انسان است. چنین تقسیمی به توسعه‌دهنده اجازه می‌دهد نسخه را دلبخواه نام‌گذاری کند، در حالی که ترتیب سختگیرانه به‌روزرسانی را از طریق کد عددی حفظ کند.

نسخه‌بندی از طریق Version Code چگونه کار می‌کند

مکانیزم مقایسه Version Code در سیستم عامل اندروید و فروشگاه Google Play ساخته شده است. در هر انتشار، Google Play بررسی می‌کند که آیا Version Code ساخت جدید بزرگتر از کد نسخه نصب‌شده است. اگر شرط برقرار نشود، انتشار با خطا رد می‌شود.

فرآیند بررسی به‌روزرسانی

وقتی دستگاه برای بررسی به‌روزرسانی به Google Play مراجعه می‌کند، سرور Version Code برنامه نصب‌شده را با حداکثر موجود در فروشگاه مقایسه می‌کند. اگر کد روی سرور بزرگتر باشد — دانلود و نصب به‌روزرسانی آغزان می‌شود. کاربر Version Name تعیین‌شده توسط توسعه‌دهنده را می‌بیند، اما تصمیم درباره به‌روزرسانی بر اساس Version Code گرفته می‌شود.

افزایش Version Code

توسعه‌دهندگان از راهبردهای مختلفی برای افزایش Version Code استفاده می‌کنند. سادهترین روش — افزایش به اندازه 1 در هر ساخت. برای خط لوله CI/CD اغلباً از timestamp یا شماره ساخت استفاده می‌شود: 2026070301 (سال-ماه-روز-شماره). مهم است که کد به صورت مونوتون افزایش یابد و در ساخت‌های مختلف و ترک‌های Google Play تکرار نشود.

• افزایش مونوتون — افزایش به اندازه 1 در هر commit به شاخه release
• فرمت timestamp — 20260703 برای ساخت‌های روزانه، 2026070301 برای چند ساخت در روز
• SemVer در اعداد — 100010000 برای نسخه 1.1.0 (major 1, minor 1, patch 0)
• شماره ساخت — استفاده از BUILD_NUMBER از سیستم CI (Jenkins, GitHub Actions)

تفاوت‌های Version Code و Version Name

Version Code و Version Name — دو فیلد مستقل در build.gradle هستند که کارکردهای مختلفی دارند. 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 ثابت بماند. به عنوان مثال، اگر توسعه‌دهنده یک باگ حراج را در یک ساخت hotfix بدون تغییر کارکرد برطرف کند. Version Name 2.0.0 باقی می‌ماند و Version Code از 5 به 6 تغییر می‌کند. Google Play چنین به‌روزرسانی را به درستی مدیریت می‌کند.

// مثال: version name تغییر نمی‌کند، code افزایش می‌یابد
android {
    defaultConfig {
        versionCode 6  // 5 بود — hotfix بدون قابلیت‌های جدید
        versionName "2.0.0"  // تغییر نکرد
    }
}

// بررسی نسخه‌ها در runtime
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("کد: $code، نام: $name")

تنظیمات Version Code در build.gradle

تنظیمات Version Code در فایل build.gradle ماژول برنامه انجام می‌شود. فیلد versionCode یک عدد صحیح می‌پذیرد و در بلوک defaultConfig قرار می‌گیرد. برای ساخت‌های مختلف flavour می‌توان مقادیر خود را از طریق فیلد 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 های مختلف برای پیکربندی‌های مختلف استفاده کنید: نسخه دمو، نسخه جداگانه برای تبلت‌ها. اگر در پروژه از flavors استفاده شود، Version Code نهایی از عدد پایه و افزایش مخصوص flavour تشکیل می‌شود. Google Play هر ترکیب را به طور مستقل پیگیری می‌کند.

خودکارسازی افزایش از طریق CI

در خط لوله‌های CI/CD (GitHub Actions، GitLab CI، Jenkins) Version Code اغلباً به صورت خودکار بر اساس شماره ساخت یا تاریخ تولید می‌شود. این خطاهای انسانی در به‌روزرسانی دستی را از بین می‌برد. اسکریپت Version Code فعلی را از build.gradle می‌خواند، آن را افزایش می‌دهد و قبل از شروع ساخت برمی‌گرداند.

// افزایش خودکار 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
    }
}

قوانین Version Code برای انتشار در Google Play

Google Play قوانین سختگیرانه‌ای برای Version Code در انتشار و به‌روزرسانی برنامه‌ها دارد. نقض این قوانین منجر به رد ساخت یا عدم امکان انتشار به‌روزرسانی می‌شود. توسعه‌دهنده باید محدودیت‌ها و راهبردهای مدیریت کد را در تمامی مراحل چرخه عمر درک کند.

قاعده افزایش مونوتون

Google Play اجازه آپلود APK یا AAB که Version Code آن کوچکتر یا مساوی نسخه منتشرشده است را نمی‌دهد. این قاعده برای هر ترک (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 استفاده می‌کند، نمی‌توان ساختی با کد 10 را به production منتقل کرد، حتی اگر production آن را ندیده باشد.

• Monotonous increment — هر ساخت در ترک Version Code بزرگتر از قبلی در همان ترک دارد
• Cross-track awareness — در ارتقاء بین ترک‌ها، Version Code به صورت متوالی افزایش می‌یابد
• Internal testing — ترک آزمایش داخلی از همان قوانین مونوتونیته استفاده می‌کند
• Multiple APKs — فرمت قدیمی انتشار برای هر APK به Version Code منحصربه‌فرد نیاز داشت

خطاها در تعیین Version Code

رایج‌ترین خطا — تطابق Version Code در ساخت‌های مختلف آپلودشده به یک ترک. Google Play خطای APK_VERSION_CODE_ALREADY_EXISTS را برمی‌گرداند. خطای دیگر — تجاوز از حداکثر مقدار 2100000000 که منجر به خطای کامپایل می‌شود. برای جلوگیری از تعارض‌ها، از تولید خودکار کد در سیستم CI با پیوند به شماره ساخت یا تاریخ ساخت استفاده کنید.

همچنین توسعه‌دهندگان اغلباً اشتباه می‌کنند و Version Code را در ساخت hotfix برای ترک جایگزین افزایش نمی‌دهند. اگر production کد 15 را داشته باشد و ترک alpha در 14 باقی مانده باشد، در ارتقاء alpha به production، Google Play ساخت را رد می‌کند زیرا کد آن از production فعلی کوچک‌تر است. مونوتونیته کد را در همه ترک‌ها به طور همزمان نظارت کنید — برای این کار استفاده از یک فایل version.properties واحد که تمامی ترک‌ها مقدار فعلی را از آن می‌خوانند راحت است.