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) بدون تأثیر بر قابلیت‌های موجود، قابلیت جدیدی اضافه می‌کند. پتچ فقط شامل رفع اشتباهات است.

به عنوان مثال، نسخه 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 Developer Documentation (2025)، CFBundleShortVersionString توسط App Store برای نمایش نسخه در رابط فروشگاه و کادرهای گفتگویی سیستم روی دستگاه کاربر استفاده می‌شود.

هنگام بارگذاری ساخت به 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 Policy (2025)، دو برنامه با versionCode یکسان یک نسخه محسوب می‌شوند — versionCode باید برای هر APK منحصر به فرد باشد. Version Name در این بررسی شرکت نمی‌کند.

همواره Build Number را در هر ساخت افزایش دهید و Version Name را فقط در صورت تغییر قابلیت تغییر دهید — این از تعارض در انتشار جلوگیری می‌کند.

چگونگی انتخاب Version Name

انتخاب Version Name به استراتژی نسخه‌دهی تیم بستگی دارد. متداول‌ترین رویکرد نسخه‌دهی سمانتیک (SemVer) است، اما الگوهای جایگزینی مانند نسخه‌دهی تقویمی یا نسخه‌دهی بر اساس تاریخ انتشار نیز وجود دارند.

Semantic Versioning 2.0 فرمات Major.Minor.Patch را با پسوندهای اختیاری pre-release توصیه می‌کند. برای برنامه‌های موبایل، شما 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 هماهنگ می‌کند.