Marketing Version: چیست، تفاوت با Build Number و نصب

Marketing Version چیست

Marketing Version — یک رشته معنایی است که نسخه برنامه را برای کاربر نهایی نمایش می‌دهد. در iOS با کلید CFBundleShortVersionString و در Android با پارامتر versionName تنظیم می‌شود.

اصطلاح «Marketing Version» به طور رسمی در Xcode استفاده می‌شود: در رابط تنظیمات target فیلد «Marketing Version» نام دارد و در Info.plist با CFBundleShortVersionString مطابقت دارد. در Android معادل آن versionName است، هرچند این اصطلاح کمتر استفاده می‌شود.

طبق Apple Developer Documentation (2025)، Marketing Version باید حداکثر از سه عدد تشکیل شده باشد که با نقطه جدا شده‌اند، بدون فاصله و کاراکترهای خاص. هر عدد نباید از 255 تجاوز کند.

Marketing Version را طوری انتخاب کنید که اهمیت تغییرات را منعکس کند: به‌روزرسانی‌های major برای تغییرات اساسی، minor برای قابلیت‌های جدید.

تفاوت با Build Number داخلی

Marketing Version اساساً از Build Number از نظر هدف متفاوت است: اولی کاربر را مطلع می‌کند، دومی — بیلد را برای فروشگاه شناسایی می‌کند. Build Number می‌تواند بدون تغییر Marketing Version افزایش یابد.

به عنوان مثال، هنگام رفع یک باگ بحرانی در نسخه منتشر شده، تیم می‌تواند برنامه را با همان Marketing Version (1.2.0) اما با Build Number افزایش یافته (از 15 به 16) بازسازی کند. کاربر همان نسخه را می‌بیند، اما فروشگاه می‌فهمد که بیلد جدیدتر است.

این انعطاف‌پذیری به توسعه‌دهندگان اجازه می‌دهد بدون اطلاع کاربران از تغییر نسخه، رفع‌ایفا را منتشر کنند.

Marketing Version در کجا نمایش داده می‌شود

Marketing Version در چند نقطه کلیدی تعامل کاربر با برنامه نمایش داده می‌شود. در فروشگاه برنامه در کارت برنامه، در توضیحات به‌روزرسانی و در تاریخچه نسخه‌ها قابل مشاهده است.

روی دستگاه Marketing Version در تنظیمات سیستم (بخش «درباره برنامه» یا «برنامه‌ها»)، در دیالوگ‌های به‌روزرسانی از طریق App Store یا Google Play، و همچنین داخل خود برنامه در صفحه «درباره» نمایش داده می‌شود.

یک Marketing Version قابل فهم به کاربر کمک می‌کند تا به‌روز بودن نسخه نصب شده را ارزیابی کرده و درباره به‌روزرسانی تصمیم بگیرد.

Marketing Version در iOS

در iOS Marketing Version در Xcode از طریق فیلد «Marketing Version» در برگه General تنظیمات target تنظیم می‌شود. مقدار در Info.plist به عنوان CFBundleShortVersionString ذخیره می‌شود.

فرمت نسخه به شدت توسط اپل تنظیم می‌شود: رشته باید شامل یک تا سه عدد باشد که با نقطه جدا شده‌اند (مثلاً 1، 1.2 یا 1.2.3). حداکثر طول — 18 کاراکتر. هر عدد از 255 تجاوز نمی‌کند.

طبق Apple App Store Review Guidelines (2025)، App Store Connect اجازه آپلود بیلدی را نمی‌دهد که Marketing Version آن بیش از یک مقدار major یا minor با نسخه منتشر شده قبلی تفاوت داشته باشد — این از کاربران در برابر به‌روزرسانی‌های از دست رفته محافظت می‌کند.

برای مدیریت Marketing Version از خط فرمان از agvtool استفاده کنید — این کار یکپارچه‌سازی با سیستم‌های CI/CD را ساده می‌کند و همگام‌سازی با Build Number را تضمین می‌کند.

Marketing Version در Android

در Android Marketing Version با پارامتر versionName در فایل build.gradle تنظیم می‌شود. برخلاف iOS، Android محدودیت‌های سختی بر فرمت رشته نسخه اعمال نمی‌کند.

versionName می‌تواند هر کاراکتری داشته باشد: حروف، اعداد، خط تیره و نقطه. Google Play این رشته را در کارت برنامه و در لیست به‌روزرسانی‌ها نمایش می‌دهد، اما آن را از نظر مطابقت با هیچ قالبی بررسی نمی‌کند.

با این حال Google Play توصیه می‌کند برای یکپارچگی از فرمت معنایی Major.Minor.Patch پیروی کنید. این کار درک نسخه را برای کاربران ساده می‌کند و امکان تجزیه و تحلیل خودکار به‌روزرسانی‌ها را فراهم می‌کند.

versionName را طوری مشخص کنید که به وضوح نوع انتشار — به‌روزرسانی major، minor یا patch — را منعکس کند. این به کاربران کمک می‌کند تا اهمیت تغییرات را سریع ارزیابی کنند.

تولید پویای versionName

versionName در Android می‌تواند به صورت پویا بر اساس تگ‌های Git یا متغیرهای CI/CD تولید شود. این کار فرآیند نسخه‌بندی را ساده می‌کند و ناسازگاری‌های بین مخزن و بیلد را از بین می‌برد.

روش معمول — خواندن تگ Git (مثلاً v2.1.0) و استفاده از مقدار آن به عنوان versionName. اگر تگ وجود نداشته باشد، می‌توان نسخه را بر اساس تاریخ و شماره commit تولید کرد.

این روش تضمین می‌کند که versionName همیشه با وضعیت کد منبع مطابقت دارد و نیاز به به‌روزرسانی دستی ندارد.

تفاوت Marketing Version با Build Number

Marketing Version و Build Number — دو پارامتر مستقل هستند که وظایف متفاوتی را حل می‌کنند. Marketing Version کاربر را مطلع می‌کند و Build Number از نظر فنی بیلد را شناسایی می‌کند.

تفاوت کلیدی — یکتایی. Build Number باید برای هر بیلد یکتا باشد. Marketing Version می‌تواند تکرار شود: چندین بیلد از یک نسخه Marketing Version یکسان اما Build Number متفاوت دارند.

طبق Google Play Policy (2025)، اگر دو APK با Marketing Version یکسان اما Build Number متفاوت آپلود شوند، Google Play هر دو را به عنوان بیلدهای مختلف از یک نسخه می‌پذیرد. برای App Store نیز قانون مشابهی اعمال می‌شود.

به خاطر داشته باشید: Build Number — برای ماشین‌ها، Marketing Version — برای انسان‌ها. اولی را خودکار کنید و دومی را با دقت برنامه‌ریزی کنید.

استراتژی‌های نسخه‌بندی

انتخاب استراتژی نسخه‌بندی به نوع برنامه، مخاطب و فرآیند انتشار بستگی دارد. سه طرح اصلی — معنایی، تقویمی و ترکیبی — بیشتر سناریوها را پوشش می‌دهند.

نسخه معنایی (SemVer) از فرمت Major.Minor.Patch استفاده می‌کند و به طور دقیق مشخص می‌کند که چه زمانی کدام مؤلفه افزایش یابد. این برای برنامه‌های با API عمومی و یکپارچه‌سازی پیچیده ایده‌آل است.

طبق semver.org (2023)، نسخه 2.0.0 از مشخصات SemVer در 89% پروژه‌های موبایل متن‌باز استفاده می‌شود و توسط تمام مدیران بسته پشتیبانی می‌شود.

نسخه‌بندی تقویمی

نسخه‌بندی تقویمی (CalVer) از تاریخ انتشار به عنوان نسخه استفاده می‌کند — مثلاً 25.06 برای ژوئن 2025. این رویکرد در برنامه‌های با به‌روزرسانی‌های مکرر محبوب است.

CalVer اطلاعاتی درباره اهمیت تغییرات ندارد، اما تازگی نسخه را به خوبی نشان می‌دهد. کاربر بلافاصله می‌فهمد که نسخه 25.06 جدیدتر از 25.03 است.

اگر برنامه شما مرتباً به‌روزرسانی می‌شود و برای کاربران تازگی داده‌ها مهم‌تر از حجم تغییرات است، نسخه‌بندی تقویمی را انتخاب کنید.

توصیه‌های انتخاب

برای MVP و استارتاپ‌ها نسخه معنایی ساده بدون patch (Major.Minor) مناسب است. برای محصولات بالغ با پشتیبانی طولانی — SemVer کامل. برای برنامه‌های با انتشار مداوم — CalVer.

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

اشتباهات در انتخاب Marketing Version

اشتباه رایج — حذف مؤلفه نسخه هنگام انتقال به خط major جدید. مثلاً بعد از نسخه 1.9.9، نسخه بعدی باید 2.0.0 باشد نه 1.10.0. این کار معنایی را نقض می‌کند و کاربران را سردرگم می‌کند.

مشکل رایج دیگر ناسازگاری Marketing Version در کد و فروشگاه برنامه است. همیشه قبل از ارسال بیلد برای بررسی، مطابقت versionName در build.gradle با نسخه مشخص شده در Google Play Console یا App Store Connect را بررسی کنید.

نمونه‌های تنظیم Marketing Version

نمونه‌های کد نشان می‌دهند که چگونه Marketing Version را در هر دو پلتفرم تنظیم کرده و به‌روزرسانی آن را خودکار کنید.

تنظیم versionName در Android Gradle

در Android versionName در build.gradle تنظیم می‌شود. مقدار می‌تواند ثابت باشد یا از متغیر محیطی خوانده شود.

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

// خواندن نسخه از تگ Git
def getVersionNameFromGit = {
    def tag = "git describe --tags".execute().
        text.trim()
    return tag.startsWith("v") ? tag.substring(1) : tag
}

versionName از تگ Git استخراج می‌شود که مطابقت بین نسخه در مخزن و در برنامه ساخته شده را تضمین می‌کند.

مدیریت Marketing Version در Xcode

در iOS Marketing Version از طریق Xcode یا agvtool تنظیم می‌شود. دستور زیر یک نسخه بازاریابی جدید تنظیم می‌کند.

# تنظیم Marketing Version
xcrun agvtool new-marketing-version 2.1.0

# افزایش خودکار
xcrun agvtool next-marketing-version

agvtool به طور خودکار Info.plist را به‌روزرسانی می‌کند و نسخه را بین تمام targetهای پروژه Xcode همگام‌سازی می‌کند.

Fastlane برای هر دو پلتفرم

Fastlane به شما امکان می‌دهد Marketing Version را در هر دو پلتفرم از یک اسکریپت مدیریت کنید که پشتیبانی از پروژه‌های چندپلتفرمی را ساده می‌کند.

# تنظیم نسخه بازاریابی
increment_version_number(
    version_number: "2.1.0"
)

# افزایش خودکار نسخه فرعی
increment_version_number(
    bump_type: "minor"
)

Fastlane روی هر دو پلتفرم کار می‌کند و توسط اکثر سرویس‌های CI/CD پشتیبانی می‌شود.