إصدار تطبيقك

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

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

يستخدم نظام 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. يحدّد هذا الملف أيضًا نكهتَين للمنتج، هما: "إصدار تجريبي" و "كامل". بما أنّ نكهة المنتج "الإصدار التجريبي" تحدّد 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، يُرجى الاطّلاع على ضبط نُسخ الإصدار.