إصدار تطبيقك

يُعد تحديد الإصدارات أحد العناصر المهمة في استراتيجية ترقية تطبيقك وصيانته. وتُعدّ عملية تحديد الإصدارات مهمة للأسباب التالية:

  • يحتاج المستخدمون إلى معلومات محدّدة حول إصدار التطبيق الذي تم تثبيته على أجهزتهم وإصدارات الترقية المتاحة للتثبيت.
  • تحتاج التطبيقات الأخرى، بما في ذلك التطبيقات الأخرى التي تنشرها كحزمة، إلى طلب بحث من النظام عن إصدار تطبيقك لتحديد التوافق وتحديد التبعيات.
  • قد تحتاج الخدمات التي تنشر تطبيقاتك من خلالها أيضًا إلى طلب معرفة إصدار التطبيق لتتمكن من عرض الإصدار للمستخدمين. قد تحتاج خدمة النشر أيضًا إلى التحقق من إصدار التطبيق لتحديد التوافق وإنشاء علاقات الترقية/الرجوع إلى إصدار سابق.

يستخدم نظام Android معلومات إصدار تطبيقك للحماية من الرجوع إلى إصدار سابق. ولا يستخدم النظام معلومات إصدار التطبيق لفرض قيود على ترقيات التطبيقات التابعة لجهات خارجية أو توافقها. يجب أن يفرض تطبيقك أي قيود على الإصدار وإعلام المستخدمين بها.

يفرض نظام Android توافق إصدار النظام، كما هو موضّح في الإعداد minSdk في ملفات الإصدار. يتيح هذا الإعداد للتطبيق تحديد الحدّ الأدنى لواجهة برمجة تطبيقات النظام التي يكون متوافقًا معها. لمزيد من المعلومات حول متطلبات واجهة برمجة التطبيقات، يمكنك الاطّلاع على تحديد متطلبات مستوى واجهة برمجة التطبيقات.

تختلف متطلبات تحديد الإصدارات باختلاف المشاريع. ومع ذلك، يعتبر العديد من المطوّرين أنّ تحديد الإصدارات الدلالية أساسًا مناسبًا لاستراتيجية تحديد الإصدارات.

ضبط معلومات إصدار التطبيق

لتحديد معلومات إصدار تطبيقك، عليك ضبط قيم لإعدادات الإصدار في ملفات إصدار Gradle كما يلي:

رائع

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

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

Kotlin

    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 إلى "متجر Play" باستخدام versionCode سبق أن استخدمتها في إصدار سابق.

ملاحظة: في بعض الحالات، قد تحتاج إلى تحميل إصدار من تطبيقك يحتوي على 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 {
                ...
            }
        }
    }
    

Kotlin

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

في المجموعة defaultConfig {} من هذا المثال، تشير القيمة versionCode إلى أنّ حزمة APK الحالية تحتوي على الإصدار الثاني من التطبيق، وتحدّد سلسلة versionName أنّه سيظهر للمستخدمين كالإصدار 1.1. يحدّد هذا الملف أيضًا نوعَي منتج، "إصدار تجريبي" و "كامل". بما أنّ صيغة المنتج "demo" تحدّد versionName على أنّها "1.1-demo"، تستخدم النسخة "التجريبية" هذه versionName بدلاً من القيمة التلقائية. لا تحدّد مجموعة نكهة المنتج "الكاملة" السمة versionName، لذا فهي تستخدم القيمة التلقائية "1.1".

ملاحظة: إذا كان تطبيقك يحدّد إصدار التطبيق مباشرةً في العنصر <manifest>، ستلغي قيم الإصدار في ملف إصدار Gradle الإعدادات في البيان. بالإضافة إلى ذلك، يتيح لك تحديد هذه الإعدادات في ملفات إصدار Gradle تحديد قيم مختلفة للإصدارات المختلفة من تطبيقك. للحصول على قدر أكبر من المرونة وتجنُّب إمكانية الكتابة عند دمج البيان، عليك إزالة هذه السمات من العنصر <manifest> وتحديد إعدادات الإصدار في ملفات إصدار Gradle بدلاً من ذلك.

يوفّر إطار عمل Android واجهة برمجة تطبيقات تتيح لك طلب معلومات من النظام عن إصدار تطبيقك للحصول على معلومات الإصدار، وذلك باستخدام طريقة PackageManager.getPackageInfo(java.lang.String, int).

تحديد متطلبات مستوى واجهة برمجة التطبيقات

إذا كان تطبيقك يتطلّب حدًّا أدنى معيّنًا من نظام التشغيل Android الأساسي، يمكنك تحديد متطلبات الإصدار هذه كإعدادات على مستوى واجهة برمجة التطبيقات في ملف build.gradle أو ملف build.gradle.kts الخاص بالتطبيق. وأثناء عملية التصميم، يتم دمج هذه الإعدادات في ملف بيان تطبيقك. يؤدي تحديد متطلبات مستوى واجهة برمجة التطبيقات إلى ضمان عدم إمكانية تثبيت تطبيقك إلا على الأجهزة التي تعمل بإصدار متوافق من نظام Android الأساسي.

ملاحظة: إذا حددت متطلبات مستوى واجهة برمجة التطبيقات مباشرةً في ملف البيان لتطبيقك، ستؤدي الإعدادات المقابلة في ملفات الإصدار إلى إلغاء الإعدادات في ملف البيان. بالإضافة إلى ذلك، يتيح لك تحديد هذه الإعدادات في ملفات إصدار Gradle تحديد قيم مختلفة للإصدارات المختلفة من تطبيقك. للحصول على قدر أكبر من المرونة وتجنُّب إمكانية الكتابة عند دمج البيان، عليك إزالة هذه السمات من العنصر <uses-sdk> وتحديد إعدادات مستوى واجهة برمجة التطبيقات في ملفات إصدار Gradle بدلاً من ذلك.

يتوفّر إعدادان على مستوى واجهة برمجة التطبيقات:

  • minSdk — الحد الأدنى لإصدار نظام Android الأساسي الذي سيتم تشغيل التطبيق عليه، ويتم تحديده من خلال معرّف مستوى واجهة برمجة التطبيقات للنظام الأساسي.
  • targetSdk — مستوى واجهة برمجة التطبيقات الذي تم تصميم التطبيق لتشغيله وفي بعض الحالات، يسمح هذا الإجراء للتطبيق باستخدام عناصر البيان أو السلوكيات المحددة في مستوى واجهة برمجة التطبيقات المستهدف، بدلاً من الاقتصار على استخدام العناصر المحددة فقط للحد الأدنى من مستوى واجهة برمجة التطبيقات.

لتحديد متطلبات مستوى واجهة برمجة التطبيقات التلقائي في ملف build.gradle أو build.gradle.kts، أضِف إعدادًا واحدًا أو أكثر من الإعدادات على مستوى واجهة برمجة التطبيقات إلى المجموعة defaultConfig{} المدمجة داخل مجموعة android {}. يمكنك أيضًا إلغاء هذه القيم التلقائية لإصدارات مختلفة من تطبيقك من خلال إضافة الإعدادات لتحديد أنواع التصاميم أو نكهات المنتجات.

يحدّد الملف التالي الإعداد التلقائي minSdk وtargetSdk في مجموعة defaultConfig {} ويلغي الإعداد minSdk لصيغة منتج واحدة:

رائع

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

Kotlin

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

عند التحضير لتثبيت التطبيق، يتحقّق النظام من قيمة هذه الإعدادات ويقارنها بإصدار النظام. وإذا كانت القيمة minSdk أكبر من إصدار النظام، سيمنع النظام تثبيت التطبيق.

إذا لم تحدّد هذه الإعدادات، سيفترض النظام أنّ تطبيقك متوافق مع جميع إصدارات النظام الأساسي. يعادل ذلك ضبط السمة minSdk على 1.

لمزيد من المعلومات، يُرجى الاطِّلاع على ما هو مستوى واجهة برمجة التطبيقات؟. للتعرّف على إعدادات إصدار Gradle، يمكنك الاطّلاع على ضبط خيارات الإصدار.