إصدار تطبيقك

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

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

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

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

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

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

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

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

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

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

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

تحديد متطلبات مستوى واجهة برمجة التطبيقات (إصدار حزمة تطوير البرامج (SDK))

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

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

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

• ‫minSdk: هو الحد الأدنى لإصدار نظام Android الأساسي الذي سيعمل عليه التطبيق، ويتم تحديده من خلال معرّف مستوى واجهة برمجة التطبيقات للنظام الأساسي.
• ‫targetSdk: هو مستوى واجهة برمجة التطبيقات المرتبط بالثابت <SDK_INT> الذي تم تصميم التطبيق ليعمل عليه. في بعض الحالات، يتيح ذلك للتطبيق استخدام عناصر البيان أو السلوكيات المحدّدة في مستوى واجهة برمجة التطبيقات المستهدَف، بدلاً من أن يقتصر على استخدام تلك المحدّدة لمستوى واجهة برمجة التطبيقات الأدنى.

لا يمكن تحديد ما إذا كان التطبيق يستهدف إصدارًا ثانويًا من حزمة تطوير البرامج (SDK) أو يتطلّبه. لاستدعاء واجهات برمجة تطبيقات جديدة بأمان تتطلّب إصدارًا رئيسيًا أو ثانويًا من حزمة تطوير البرامج (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
}

لتحديد متطلبات مستوى واجهة برمجة التطبيقات التلقائية في ملف build.gradle أو build.gradle.kts، أضِف إعدادًا واحدًا أو أكثر من إعدادات مستوى واجهة برمجة التطبيقات إلى الحظر 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.

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