Version Code: ما هو، المعرف الرقمي والتحديثات

ما هو Version Code في Android

Version Code هو عدد صحيح من نوع Integer يُخصص لكل بناء من تطبيق Android. على عكس Version Name، لا يظهر Version Code للمستخدم ويُستخدم exclusively من قبل نظام التشغيل و Google Play لمقارنة الإصدارات عند تثبيت التحديثات.

تنسيق Version Code

Version Code يجب أن يكون عددًا صحيحًا موجبًا في النطاق من 1 إلى 2100000000. يجب أن يكون لكل بناء لاحق Version Code أكبر strictly من السابق. إذا أصدر المطور بناءً برقم Version Code 5، يمكن للنشر التالي استخدام 6 أو 7 أو أي رقم أكبر من 5، ولكن ليس 4 وليس 5 مرة أخرى.

تاريخ النشأة

قدم Google الفصل بين Version Code و Version Name مع إصدار Android SDK في عام 2007. 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، غالبًا ما يُستخدم timestamp أو رقم البناء: 2026070301 (سنة-شهر-يوم-رقم). من المهم أن يزيد الكود monotonically ولا يتكرر بين البناءات المختلفة وقنوات Google Play.

• الزيادة الرتيبة — الزيادة بمقدار 1 مع كل commit في فرع الإصدار
• تنسيق 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 كما هو. على سبيل المثال، إذا أصلح المطور خطأً critical في بناء hotfix دون تغيير الوظائف. يبقى Version Name 2.0.0، بينما يتغير Version Code من 5 إلى 6. سيتعامل Google Play مع هذا التحديث بشكل صحيح.

// مثال: اسم الإصدار لا يتغير، الكود يزيد
android {
    defaultConfig {
        versionCode 6  // كان 5 — hotfix بدون ميزات جديدة
        versionName "2.0.0"  // لم يتغير
    }
}

// التحقق من الإصدارات في وقت التشغيل
val code = BuildConfig.VERSION_CODE
val name = BuildConfig.VERSION_NAME
println("Code: $code, Name: $name")

إعداد Version Code في build.gradle

يتم إعداد Version Code في ملف build.gradle لوحدة التطبيق. يقبل الحقل versionCode عددًا صحيحًا وهو جزء من كتلة defaultConfig. للبناءات المختلفة (flavors)، يمكن تعيين قيم مخصصة عبر الحقل 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 النهائي من الرقم الأساسي والزيادة الخاصة بالـ flavor. يتتبع 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) بشكل مستقل. إذا تم تحميل بناء برقم Version Code 10 في production وبناء برقم 5 في alpha، يمكن تحديث مسار alpha إلى 6 أو 7 أو 8 أو 9، لكن يبقى production على 10.

الترحيل بين المسارات

عند ترقية بناء من alpha إلى beta ثم إلى production، يجب أن يزيد Version Code في كل مرحلة. إذا كان إصدار alpha لديه كود 10، يمكن لـ beta استخدام 11 و production 12. لا يمكن نشر بناء برقم 10 في production إذا كان alpha يستخدم 10 بالفعل، حتى لو لم يرَ production هذا الإصدار بعد.

• الزيادة الرتيبة — كل بناء في مسار له Version Code أكبر من السابق في نفس المسار
• الوعي عبر المسارات — عند الترقية بين المسارات، يزيد Version Code بشكل تسلسلي
• الاختبار الداخلي — مسار الاختبار الداخلي يستخدم نفس قواعد الرتابة
• APK متعددة — تنسيق النشر القديم تطلب Version Code فريدًا لكل APK

أخطاء عند تحديد 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 واحد تقرأ منه جميع المسارات القيمة الحالية.