برنامه خود را نسخه کنید

نسخه سازی یک جزء حیاتی از استراتژی ارتقا و نگهداری برنامه شما است. نسخه سازی مهم است زیرا:

• کاربران باید اطلاعات خاصی در مورد نسخه برنامه نصب شده بر روی دستگاه هایشان و نسخه های ارتقا یافته موجود برای نصب داشته باشند.
• سایر برنامه‌ها - از جمله سایر برنامه‌هایی که به صورت مجموعه منتشر می‌کنید - برای تعیین سازگاری و شناسایی وابستگی‌ها، باید نسخه برنامه شما را از سیستم پرس و جو کنند.
• سرویس‌هایی که برنامه(های) خود را در آنها منتشر می‌کنید نیز ممکن است نیاز داشته باشند برنامه شما را برای نسخه آن جستجو کنند تا بتوانند نسخه را به کاربران نمایش دهند. ممکن است یک سرویس انتشاراتی برای تعیین سازگاری و ایجاد روابط ارتقا/کاهش، نیاز به بررسی نسخه برنامه داشته باشد.

سیستم Android از اطلاعات نسخه برنامه شما برای محافظت در برابر کاهش رتبه استفاده می کند. سیستم از اطلاعات نسخه برنامه برای اعمال محدودیت در ارتقا یا سازگاری برنامه های شخص ثالث استفاده نمی کند. برنامه شما باید هر گونه محدودیت نسخه را اعمال کند و آنها را به کاربران اطلاع دهد.

سیستم Android سازگاری نسخه سیستم را اعمال می کند، همانطور که توسط تنظیمات minSdk در فایل های ساخت بیان شده است. این تنظیم به برنامه اجازه می‌دهد حداقل API سیستمی را که با آن سازگار است مشخص کند. برای اطلاعات بیشتر درباره الزامات API، به مشخص کردن سطح API (نسخه SDK) الزامات مراجعه کنید.

الزامات نسخه سازی بین پروژه های مختلف متفاوت است. با این حال، بسیاری از توسعه دهندگان Semantic Versioning را مبنای خوبی برای استراتژی نسخه سازی می دانند.

اطلاعات نسخه برنامه را تنظیم کنید

برای تعریف اطلاعات نسخه برای برنامه خود، مقادیری را برای تنظیمات نسخه در فایل های ساخت Gradle تنظیم کنید:

    android {
      namespace 'com.example.testapp'
      compileSdk 33

      defaultConfig {
          applicationId "com.example.testapp"
          minSdk 24
          targetSdk 33
          versionCode 1
          versionName "1.0"
          ...
      }
      ...
    }
    ...
    

    android {
      namespace = "com.example.testapp"
      compileSdk = 33

      defaultConfig {
          applicationId = "com.example.testapp"
          minSdk = 24
          targetSdk = 33
          versionCode = 1
          versionName = "1.0"
          ...
      }
      ...
    }
    ...
      

تنظیمات نسخه

مقادیر را برای هر دو تنظیمات نسخه موجود تعریف کنید: versionCode و versionName .

versionCode

یک عدد صحیح مثبت که به عنوان شماره نسخه داخلی استفاده می شود. این عدد کمک می کند تا مشخص شود که آیا یک نسخه جدیدتر از نسخه دیگر است یا خیر، با اعداد بالاتر نشان دهنده نسخه های جدیدتر است. این شماره نسخه نمایش داده شده به کاربران نیست. این عدد توسط تنظیمات versionName تنظیم می شود. سیستم Android از مقدار versionCode استفاده می‌کند تا با جلوگیری از نصب یک APK با versionCode پایین‌تر از نسخه‌ای که در حال حاضر روی دستگاه آن‌ها نصب شده، در برابر کاهش رتبه‌بندی محافظت کند.

این مقدار یک عدد صحیح مثبت است تا برنامه‌های دیگر بتوانند آن را به صورت برنامه‌نویسی ارزیابی کنند—مثلاً برای بررسی یک رابطه ارتقا یا کاهش رتبه. می توانید مقدار را روی هر عدد صحیح مثبت تنظیم کنید. با این حال، مطمئن شوید که هر نسخه متوالی برنامه شما از ارزش بیشتری استفاده می کند.

توجه: بیشترین مقداری که Google Play برای versionCode اجازه می دهد 2100000000 است.

نمی‌توانید APK را با versionCode قبلاً برای نسخه قبلی استفاده کرده‌اید، در فروشگاه Play آپلود کنید.

توجه: در برخی شرایط، ممکن است بخواهید نسخه ای از برنامه خود را با versionCode پایین تر از آخرین نسخه آپلود کنید. برای مثال، اگر چندین APK منتشر می‌کنید، ممکن است محدوده‌های versionCode از پیش تنظیم شده برای APK‌های خاص داشته باشید. برای اطلاعات بیشتر درباره تخصیص مقادیر versionCode برای چندین APK، به اختصاص کدهای نسخه مراجعه کنید.

به طور معمول، شما اولین نسخه برنامه خود را با versionCode روی 1 منتشر می کنید، سپس به طور یکنواخت ارزش را با هر نسخه افزایش می دهید، صرف نظر از اینکه نسخه نسخه اصلی یا فرعی باشد. این بدان معنی است که مقدار versionCode لزوماً شبیه نسخه انتشار برنامه نیست که برای کاربر قابل مشاهده است. برنامه‌ها و سرویس‌های انتشار نباید این مقدار نسخه را به کاربران نشان دهند.

versionName

رشته ای که به عنوان شماره نسخه نمایش داده شده به کاربران استفاده می شود. این تنظیم را می توان به عنوان یک رشته خام یا به عنوان یک مرجع به یک منبع رشته تعیین کرد.

مقدار یک رشته است تا بتوانید نسخه برنامه را به عنوان یک رشته <major>.<minor>.<point> یا هر نوع دیگری از شناسه نسخه مطلق یا نسبی توصیف کنید. versionName تنها مقداری است که به کاربران نمایش داده می شود.

مقادیر نسخه را تعریف کنید

می‌توانید مقادیر پیش‌فرض را برای این تنظیمات با قرار دادن آن‌ها در بلوک defaultConfig {} که در داخل بلوک android {} فایل build.gradle یا build.gradle.kts ماژول شما قرار دارد، تعریف کنید. سپس می‌توانید این مقادیر پیش‌فرض را برای نسخه‌های مختلف برنامه خود با تعریف مقادیر جداگانه برای انواع ساخت‌ها یا طعم‌های محصول لغو کنید. فایل زیر تنظیمات versionCode و versionName در بلوک defaultConfig {} و همچنین بلوک productFlavors {} را نشان می دهد.

سپس این مقادیر در طی فرآیند ساخت در فایل مانیفست برنامه شما ادغام می شوند.

    android {
        ...
        defaultConfig {
            ...
            versionCode 2
            versionName "1.1"
        }
        productFlavors {
            demo {
                ...
                versionName "1.1-demo"
            }
            full {
                ...
            }
        }
    }
    

    android {
        ...
        defaultConfig {
            ...
            versionCode = 2
            versionName = "1.1"
        }
        productFlavors {
            create("demo") {
                ...
                versionName = "1.1-demo"
            }
            create("full") {
                ...
            }
        }
    }
    

در بلوک defaultConfig {} این مثال، مقدار versionCode نشان می‌دهد که APK فعلی حاوی نسخه دوم برنامه است و رشته versionName مشخص می‌کند که به عنوان نسخه 1.1 برای کاربران ظاهر می‌شود. این فایل همچنین دو طعم محصول "دمو" و "فول" را تعریف می کند. از آنجایی که طعم محصول "دمو" versionName به عنوان "1.1-demo" تعریف می کند، ساخت "نسخه نمایشی" به جای مقدار پیش فرض از این versionName استفاده می کند. بلوک طعم محصول "کامل" versionName تعریف نمی کند، بنابراین از مقدار پیش فرض "1.1" استفاده می کند.

توجه: اگر برنامه شما نسخه برنامه را مستقیماً در عنصر <manifest> تعریف می‌کند، مقادیر نسخه در فایل ساخت Gradle تنظیمات موجود در مانیفست را لغو می‌کند. علاوه بر این، تعریف این تنظیمات در فایل های ساخت Gradle به شما امکان می دهد مقادیر مختلفی را برای نسخه های مختلف برنامه خود تعیین کنید. برای انعطاف بیشتر و جلوگیری از بازنویسی احتمالی هنگام ادغام مانیفست، این ویژگی ها را از عنصر <manifest> حذف کنید و به جای آن تنظیمات نسخه خود را در فایل های ساخت Gradle تعریف کنید.

چارچوب Android یک API ارائه می دهد تا به شما امکان می دهد اطلاعات نسخه مربوط به برنامه خود را از سیستم پرس و جو کنید. برای به دست آوردن اطلاعات نسخه، از روش PackageManager.getPackageInfo(java.lang.String, int) استفاده کنید.

الزامات سطح API (نسخه SDK) را مشخص کنید

اگر برنامه شما به حداقل نسخه خاصی از پلتفرم Android نیاز دارد، می توانید آن نسخه مورد نیاز را به عنوان تنظیمات سطح API در فایل build.gradle یا build.gradle.kts برنامه مشخص کنید. در طول فرآیند ساخت، این تنظیمات در فایل مانیفست برنامه شما ادغام می شوند. مشخص کردن الزامات سطح API تضمین می‌کند که برنامه شما فقط می‌تواند روی دستگاه‌هایی نصب شود که نسخه سازگار پلتفرم Android را اجرا می‌کنند.

توجه: اگر الزامات سطح API را مستقیماً در فایل مانیفست برنامه خود مشخص کنید، تنظیمات مربوطه در فایل های ساخت، تنظیمات فایل مانیفست را لغو می کند. علاوه بر این، تعریف این تنظیمات در فایل های ساخت Gradle به شما امکان می دهد مقادیر مختلفی را برای نسخه های مختلف برنامه خود تعیین کنید. برای انعطاف‌پذیری بیشتر و جلوگیری از بازنویسی احتمالی هنگام ادغام مانیفست، این ویژگی‌ها را از عنصر <uses-sdk> حذف کنید و به‌جای آن تنظیمات سطح API خود را در فایل‌های ساخت Gradle تعریف کنید.

دو تنظیمات سطح API موجود است:

• minSdk - حداقل نسخه پلتفرم Android که برنامه روی آن اجرا می شود، که توسط شناسه سطح API پلت فرم مشخص شده است.
• targetSdk - سطح API، متصل به ثابت <SDK_INT> ، که برنامه برای اجرا بر روی آن طراحی شده است. در برخی موارد، این به برنامه اجازه می دهد تا از عناصر یا رفتارهای مانیفست تعریف شده در سطح API هدف استفاده کند، نه اینکه فقط به استفاده از مواردی که برای حداقل سطح API تعریف شده اند محدود شود.

نمی توان مشخص کرد که یک برنامه یک نسخه کوچک SDK را هدف قرار می دهد یا به آن نیاز دارد. برای فراخوانی ایمن API های جدیدی که به نسخه SDK اصلی یا فرعی بالاتری نسبت به minSdkVersion نیاز دارند، می توانید با استفاده از ثابت SDK_INT_FULL ، از یک بلوک کد با بررسی انتشار جزئی یا اصلی محافظت کنید.

if (SDK_INT_FULL >= VERSION_CODES_FULL.[MAJOR or MINOR RELEASE]) {
  // Use APIs introduced in a major or minor SDK version
}

برای مشخص کردن الزامات سطح API پیش‌فرض در یک فایل build.gradle یا build.gradle.kts ، یک یا چند مورد از تنظیمات سطح API را به بلوک defaultConfig{} که در داخل بلوک android {} قرار دارد، اضافه کنید. همچنین می‌توانید این مقادیر پیش‌فرض را برای نسخه‌های مختلف برنامه خود با افزودن تنظیمات برای ساخت انواع یا طعم‌های محصول لغو کنید.

فایل زیر تنظیمات پیش‌فرض minSdk و targetSdk را در بلوک defaultConfig {} مشخص می‌کند و minSdk برای یک طعم محصول لغو می‌کند:

android {
    ...
    defaultConfig {
        ...
        minSdk 21
        targetSdk 33
    }
    productFlavors {
        main {
            ...
        }
        afterNougat {
            ...
            minSdk 24
        }
    }
}

android {
    ...
    defaultConfig {
        ...
        minSdk = 21
        targetSdk = 33
    }
    productFlavors {
        create("main") {
            ...
        }
        create("afterNougat") {
            ...
            minSdk = 24
        }
    }
}

هنگام آماده شدن برای نصب برنامه، سیستم مقدار این تنظیمات را بررسی می کند و آنها را با نسخه سیستم مقایسه می کند. اگر مقدار minSdk بیشتر از نسخه سیستم باشد، سیستم از نصب برنامه جلوگیری می کند.

اگر این تنظیمات را مشخص نکنید، سیستم فرض می‌کند که برنامه شما با تمام نسخه‌های پلتفرم سازگار است. این معادل تنظیم minSdk به 1 است.

برای اطلاعات بیشتر، ببینید سطح API چیست؟ . برای تنظیمات ساخت Gradle، به پیکربندی انواع ساخت مراجعه کنید.