Version Name: جوهر ومعنى المعلمة والإعداد

ما هو Version Name

Version Name هو سلسلة دلالية تحدد إصدار التطبيق للمستخدم. على عكس المعرفات التقنية للإصدارات، تحمل هذه المعلمة عبئًا معنويًا: يمكن للمستخدم تقييم مدى اختلاف التحديث الجديد عن السابق.

يظهر Version Name في بطاقة التطبيق على Google Play و App Store، وفي قسم "حول التطبيق" على الجهاز، وكذلك في حوارات التحديث النظامية. يحدده المطورون في ملفات تكوين المشروع قبل بناء الإصدار النهائي.

وفقًا لـ Semantic Versioning 2.0 (2023)، يُستخدم تنسيق Major.Minor.Patch في 78% من التطبيقات المحمولة. يتغير الإصدار الرئيسي مع تغييرات API غير المتوافقة، والإصدار الثانوي مع إضافة وظائف جديدة، والتصحيح مع إصلاح الأخطاء.

استخدم Version Name للتواصل مع المستخدم: يجب أن يفهم فورًا مدى أهمية التحديث المقدم — رئيسي أو ثانوي أو تصحيحي.

هيكل الإصدار الدلالي

يتكون الإصدار الدلالي من ثلاثة أرقام مفصولة بنقاط: Major.Minor.Patch. كل مكون من هذه المكونات مسؤول عن مستوى معين من التغييرات في التطبيق.

يزداد الإصدار الرئيسي (Major) عند إدخال تغييرات جذرية تكسر التوافق العكسي. يضيف الإصدار الثانوي (Minor) وظائف جديدة دون كسر الوظائف الحالية. يحتوي التصحيح (Patch) على إصلاحات للأخطاء فقط.

على سبيل المثال، الإصدار 3.2.1 يعني: الإصدار الرئيسي الثالث، التحديث الثانوي الثاني، التصحيح الأول. هذا النظام مفهوم لكل من المطورين والمستخدمين.

أين يظهر Version Name

Version Name مرئي للمستخدم في عدة أماكن رئيسية. في متجر التطبيقات، يظهر في رأس بطاقة التطبيق وفي قائمة التحديثات. على الجهاز، يظهر في إعدادات النظام تحت قسم "حول التطبيق".

على Google Play، يظهر Version Name أسفل اسم التطبيق ويؤثر على قرار المستخدم بالتحديث. في App Store، تظهر سلسلة الإصدار في نفس المكان عند عرض صفحة التطبيق.

وفقًا لبحث Apptentive (2024)، يتحقق 67% من المستخدمين من إصدار التطبيق قبل التحديث، والدلالات الواضحة تزيد من معدل التثبيت بنسبة 23%.

Version Name على Android

على Android، يتم تعيين Version Name بواسطة المعامل versionName في ملف build.gradle (على مستوى الوحدة). هذا المعامل عبارة عن سلسلة ويمكن أن يحتوي على أي أحرف، بما في ذلك النقاط والواصلات والحروف.

يتم تعريف المعامل داخل كتلة android.defaultConfig جنبًا إلى جنب مع المعامل الإلزامي versionCode. لا يفرض Android قيودًا على تنسيق السلسلة، لكن Google Play يوصي باستخدام التنسيق الدلالي.

وفقًا لـ Android Developers (2025)، يستخدم Google Play versionName للعرض في واجهة المتجر ولكنه لا يحلل محتواه برمجيًا — فقط versionCode يؤثر على منطق التحديث.

حدد Version Name بتنسيق Major.Minor.Patch وقم بمزامنته مع الوسم في نظام التحكم في الإصدارات لتحديد الإصدار بشكل لا لبس فيه.

خصائص versionName في Gradle

يسمح Gradle بتعيين versionName بشكل ثابت في build.gradle أو ديناميكيًا عبر نصوص البناء. التوليد الديناميكي مفيد للبناءات الليلية التلقائية وخطوط أنابيب CI/CD.

في build.gradle، يمكن استخدام متغيرات البيئة أو معاملات سطر الأوامر أو استدعاءات نصوص shell لتشكيل versionName. النهج النموذجي هو قراءة الإصدار من ملف version.properties.

هذه المرونة تسمح للفرق بأتمتة عملية تحديد الإصدارات والقضاء على الخطأ البشري أثناء التحضير للإصدار.

Version Name على iOS

على iOS، يتم تعيين Version Name بواسطة المفتاح CFBundleShortVersionString في ملف Info.plist. هذه معلمة إلزامية لنشر التطبيق على App Store، وهي مقيدة كنوع سلسلة.

على عكس Android، يتحقق App Store Connect من تنسيق Version Name ويتطلب مطابقته لنمط من الأرقام المفصولة بنقاط. الحد الأقصى لطول السلسلة هو 18 حرفًا، ولا يمكن أن يتجاوز كل مكون من مكونات الإصدار 255.

وفقًا لـ توثيق مطوري Apple (2025)، يستخدم App Store CFBundleShortVersionString لعرض الإصدار في واجهة المتجر وفي حوارات النظام على جهاز المستخدم.

عند تحميل بناء إلى App Store Connect، تأكد من أن Version Name يتطابق مع الإصدار المذكور في المواد التسويقية — وهذا يبسط التواصل مع المستخدمين.

التكامل مع Xcode

يوفر Xcode واجهة رسومية لتغيير Version Name في إعدادات الهدف. حقل "Marketing Version" موجود في علامة التبويب General تحت قسم Identity. يتم حفظ التغييرات تلقائيًا في Info.plist.

للأتمتة، يمكن استخدام نصوص البناء في Xcode Build Phases أو أداة agvtool (Apple Generic Version Tool). تتيح agvtool إدارة الإصدارات من سطر الأوامر وتتكامل مع CI/CD.

هذا النهج مناسب بشكل خاص عند استخدام fastlane أو Jenkins للبناء والتسليم التلقائي للتطبيقات.

الاختلافات بين Version Name و Build Number

Version Name و Build Number يؤديان مهام مختلفة في عملية التطوير. Version Name هو سلسلة موجهة للمستخدم، بينما Build Number هو معرف رقمي داخلي يحدد بشكل فريد كل بناء.

Build Number (versionCode في Android، CFBundleVersion في iOS) يجب أن يزيد مع كل بناء جديد وتستخدمه متاجر التطبيقات لتحديد أي إصدار أحدث. يمكن أن يبقى Version Name دون تغيير عبر عدة بنيات لنفس الإصدار.

وفقًا لـ سياسة Google Play (2025)، يعتبر تطبيقان لهما نفس versionCode نفس الإصدار — يجب أن يكون versionCode فريدًا لكل APK. Version Name لا يشارك في هذا التحقق.

قم دائمًا بزيادة Build Number مع كل بناء وقم بتغيير Version Name فقط عندما تتغير الوظائف — وهذا يمنع التعارضات أثناء النشر.

كيفية اختيار Version Name

اختيار Version Name يعتمد على استراتيجية تحديد الإصدارات للفريق. النهج الأكثر شيوعًا هو تحديد الإصدارات الدلالي (SemVer)، ولكن توجد مخططات بديلة مثل تحديد الإصدارات التقويمي أو تحديد الإصدارات حسب تاريخ الإصدار.

يوصي Semantic Versioning 2.0 بتنسيق Major.Minor.Patch مع لاحقات اختيارية للإصدارات الأولية. للتطبيقات المحمولة، أيضًا شائع مخطط Major.Minor حيث يتم حذف إصدار التصحيح لتبسيط الفهم.

يستخدم تحديد الإصدارات التقويمي (CalVer) تاريخ الإصدار كرقم الإصدار — على سبيل المثال، 25.06 (السنة والشهر). هذا النهج مناسب للتطبيقات ذات الإصدارات المتكررة حيث لا تحمل الدلالات معنى.

توصيات لاختيار المخطط

تحديد الإصدارات الدلالي مناسب للتطبيقات ذات API العامة حيث تكون التوافقية العكسية مهمة. يفهم المستخدمون والمتكاملون التغييرات المتوقعة مع التحديثات.

تحديد الإصدارات التقويمي يُختار للتطبيقات حيث تكون حداثة الإصدار أهم من حجم التغييرات. على سبيل المثال، مجمعات الأخبار أو تطبيقات الطقس.

المخطط الهجين يجمع بين كلا النهجين: Major.Minor.RC، حيث RC هو رقم البناء لمرشح إصدار معين. هذا المخطط مناسب أثناء الاختبار التجريبي النشط.

أمثلة على تكوين Version Name

أمثلة الكود أدناه توضح كيفية تعيين Version Name على Android و iOS. لـ Android يُستخدم Gradle، لـ iOS — Xcode Build Settings مع agvtool.

تكوين versionName في Android

في Android، يتم تعيين الإصدار في ملف app/build.gradle داخل كتلة defaultConfig. يقبل المعامل versionName قيمة سلسلة.

android {
    defaultConfig {
        versionCode 3
        versionName "2.1.0"
    }
}

versionName يمكن أيضًا قراءته من ملف خارجي أو توليده ديناميكيًا باستخدام Gradle Script.

التوليد الديناميكي لـ versionName

يتكون الإصدار الديناميكي من متغيرات بيئة نظام CI/CD. هذا يضمن أن كل بناء يتلقى رقم الإصدار الصحيح.

def getVersionName = {
    return System.getenv("VERSION_NAME") ?:
            "2.1.0"
}

android {
    defaultConfig {
        versionName getVersionName()
    }
}

هذا النهج يؤتمت تحديد الإصدارات ويزيل خطر عدم التطابق بين البناء والوسم في المستودع.

تكوين CFBundleShortVersionString في iOS

في iOS، يمكن تعيين الإصدار عبر Xcode أو من خلال سطر الأوامر باستخدام agvtool.

# تعيين إصدار التسويق
xcrun agvtool new-marketing-version 2.1.0

# قراءة الإصدار الحالي
xcrun agvtool what-marketing-version

agvtool يقوم تلقائيًا بتحديث Info.plist ومزامنة الإصدار عبر جميع الأهداف في مشروع Xcode.