استهداف الأجهزة للوحدات الشرطية

ما المقصود بميزة استهداف الأجهزة للوحدات الشرطية؟

يتيح لك استهداف الأجهزة تقديم وحدات ميزات مشروطة للأجهزة استنادًا إلى معدّاتها. على سبيل المثال، يمكنك اختيار تقديم بعض الميزات للأجهزة المتطورة فقط وعدم تقديمها إلى الأجهزة التي يتعذر عليها استخدام هذه الميزة (أي توفير مساحة على هذه الأجهزة). ويعتمد هذا على مفهوم وحدات الميزات في عرض الميزات في Play. وكما ترى أدناه، لديك القدرة على تحديد معايير الاستهداف (تعتمد حاليًا على ذاكرة الوصول العشوائي (RAM) أو طُرز أجهزة محددة أو ميزات النظام المتاحة) واستهداف الوحدات لمجموعات أجهزة محددة.

رحلة مطوّر البرامج

لكي تتمكّن من دمج استهداف الأجهزة في تطبيقك الحالي، يجب اتّخاذ الخطوات التالية:

  1. طوّر ميزة تريد تقديمها لمجموعة فقط من الأجهزة استنادًا إلى أجهزتها.
    • نفِّذ هذه الميزة باعتبارها وحدة ميزات.
    • حدِّد في قسم شروط الوحدة في ملف AndroidManifest.xml مجموعات الأجهزة التي يجب إرسال النموذج إليها.
  2. أنشئ إعدادات "استهداف الأجهزة"، حتى يعرف Play كيفية تسليم وحدات الميزات إلى أجهزة المستخدمين.
    • عليك إعداد واجهة برمجة تطبيقات Google Play Developer API (إذا لم تكن قد أكملتها)، وهي الطريقة التي ستستخدمها لإرسال إعدادات DT إلى Play.
    • اتّبِع الخطوات لإنشاء إعدادات DT.
  3. حمِّل ملف AAB إلى Play واختبِر إعداداته للتأكّد من أنّه تم ضبط إعداداته بشكل صحيح.

يصف هذا المستند كيفية إضافة استهداف الأجهزة من أجل التسليم المشروط باستخدام المكوّن الإضافي Android Gradle.

إنشاء وحدة ميزة شرطية باستخدام ميزة "استهداف الأجهزة"

إضافة وحدة ميزات إلى التطبيق

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

لاستخدام DT للتسليم المشروط، عليك استخدام الإصدار 1.7.0 من bundletool أو الإصدارات الأحدث. لتنفيذ هذا الإجراء، عليك تحديد إصدار bundletool بشكلٍ واضح لمكوّن Android Gradle الإضافي. يمكن تنفيذ ذلك في قسم إنشاء ملف build.gradle الجذر:

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

لإنشاء وحدة ميزة، اتّبِع التعليمات التالية لتقسيم تطبيق Android إلى وحدات.

بعد اكتمال تطوير الميزة، يمكنك تحديد شروط العرض استنادًا إلى "استهداف الأجهزة" في AndroidManifest.xml للعنصر. يجب توفير شرط لمجموعة أجهزة داخل العنصر dist:conditions من dist:module. تتوفّر معلومات عامة حول الشروط هنا. بالنسبة إلى مجموعات الأجهزة، تتوفّر شروط جديدة تتيح لك تحديد جميع المجموعات التي يجب تسليم هذه الميزة إليها:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

لنفترض على سبيل المثال أنك قد حددت مجموعة أجهزة باسم _my_group1 (ستتعرف على كيفية تحديدها في القسم إنشاء إعداد استهداف الأجهزة أدناه). إذا كان يجب تسليم وحدة الميزة إلى الأجهزة التي تنتمي إلى أجهزة _my_group1 فقط، يجب أن يظهر AndroidManifest.xml الخاص بها على النحو التالي:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

بالنسبة إلى الميزة التي تستهدف كلاً من _my_group1 و _my_group2، تظهر علامة AndroidManifest.xml على النحو التالي:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
            <dist:device-group dist:name="my_group_2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

وبعد الانتهاء، يمكنك إنشاء مجموعة حزمات تطبيق Android (AAB).

الاختبار المحلي

ننصحك باختبار حزمة التطبيق محليًا قبل المتابعة للتأكُّد من إعداد كل شيء بشكل صحيح. باستخدام bundletool يمكنك إنشاء تطبيقك واختباره محليًا، مع تحديد مجموعة الأجهزة الصحيحة بشكل صريح. ستستخدم أولاً build-apks لإنشاء مجموعة من ملفات .APK، ثم تنشر تطبيقك على جهاز متصل باستخدام install-apks. يمكنك أيضًا تحديد المجموعات التي ترغب في تثبيتها عن طريق علامة device-groups. يمكنك العثور على مزيد من المعلومات حول طريقة الاختبار المحلي هذه هنا. تجدر الإشارة إلى أنّه لم يتم تعديل هذه الصفحة بعد في DT، وبالتالي لا تحتوي على علامة device-groups.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

بدلاً من ذلك: يمكنك أيضًا استخدام extract-apks لاستخراج مجموعة من حِزم APK لجهاز معيّن (باستخدام get-device-spec إلى جانب تحديد مجموعات الأجهزة لهذا الجهاز).

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool extract-apks --apks=/path/to/existing_APK_set.apks --output-dir=/path/to/device_specific_APK_set.apks --device-spec=/path/to/device-spec.json

إنشاء إعدادات استهداف الأجهزة من خلال Google Play Developer API

بدء استخدام Google Play Developer API (إذا لم تكن قد أكملتها بعد)

لضبط إعدادات "استهداف الأجهزة" (تحديد مجموعات الأجهزة)، ستحتاج إلى استخدام Android Publisher API لتحميل الإعدادات إلى Google Play. يمكنك الاطّلاع على مزيد من المعلومات حول واجهة برمجة التطبيقات على الرابط أعلاه، وهناك بعض الخطوات التي عليك اتّباعها للبدء:

  1. إنشاء (إذا لزم الأمر) وربط مشروع واجهة برمجة التطبيقات بحسابك على Google Play Console
  2. إعداد برنامج عميل الوصول إلى واجهة برمجة التطبيقات

يمكنك العثور على مرجع واجهة برمجة التطبيقات هنا. وفي وقت لاحق، إذا اخترت تحميل تصميمك عبر واجهة برمجة التطبيقات، ستستخدم طرق Edits. بالإضافة إلى ذلك، يُستحسن مراجعة هذه الصفحة قبل استخدام واجهة برمجة التطبيقات.

استخدام واجهة برمجة التطبيقات Device Targeting Configuration API

يمكنك استخدام طلب البيانات من واجهة برمجة التطبيقات التالي لإنشاء إعداد استهداف الأجهزة:

إنشاء إعداد استهداف الأجهزة

طلب HTTP POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
مَعلمات المسار لا ينطبق
نص الطلب ضبط استهداف الأجهزة
نص الاستجابة ضبط استهداف الأجهزة
كائن تهيئة استهداف الأجهزة
{
  device_groups: [
    {
      name: string,
      device_selectors: [
        {
          device_ram : {
            min_bytes: integer
            max_bytes: integer
          },
          included_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          excluded_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          required_system_features: [
            {
              name: string
            }
          ],
          forbidden_system_features: [
            {
              name: string
            }
          ]
        }
      ]
    }
  ]
}

الحقول:

  • device_tier_config_id (عدد صحيح): رقم التعريف المقابل لإعدادات استهداف الجهاز هذه

  • device_groups (كائن): تعريفات المجموعات

    • name (سلسلة): اسم مجموعة الأجهزة (رقم تعريف سلسلة تحدِّده)
    • device_selectors (كائن): متطلبات الجهاز لانتماء الجهاز إلى هذه المجموعة
    • device_ram (كائن): متطلبات ذاكرة الوصول العشوائي للجهاز
      • min_bytes (عدد صحيح): الحد الأدنى المطلوب لذاكرة الوصول العشوائي (RAM) (بالبايت)
      • max_bytes (عدد صحيح): الحد الأقصى لذاكرة الوصول العشوائي المطلوبة (بالبايت)
    • included_device_ids (كائن): طُرز الأجهزة التي سيتم تضمينها في أداة الاختيار هذه (بحد أقصى 10000 رقم تعريف الجهاز لكل مجموعة). يجب أن يكون الجهاز ضمن هذه القائمة لمطابقة أداة الاختيار. ويُعدّ هذا شرطًا ضروريًا ولكنه غير كافٍ لمطابقة أداة الاختيار الكاملة (انظر الملاحظة أدناه حول دمج المتطلبات في أداة الاختيار).
      • build_brand (سلسلة): الشركة المصنّعة للجهاز
      • build_device (سلسلة): رمز طراز الجهاز
    • excluded_device_ids (كائن): طُرز الأجهزة التي سيتم استبعادها في أداة الاختيار هذه (بحد أقصى 10,000 رقم تعريف الجهاز لكل مجموعة). لن يتطابق جهاز من هذه القائمة مع أداة الاختيار حتى إذا كانت تتطابق مع جميع المتطلبات الأخرى في أداة الاختيار.
      • build_brand (سلسلة): الشركة المصنّعة للجهاز
      • build_device (سلسلة): رمز طراز الجهاز

    • required_system_features (كائن): الميزات التي يجب تضمينها على الجهاز بواسطة أداة الاختيار هذه (بحد أقصى 100 ميزة لكل مجموعة). يجب أن يتضمّن الجهاز جميع ميزات النظام في هذه القائمة لمطابقة أداة الاختيار. ويُعدّ هذا شرطًا ضروريًا ولكنّه غير كافٍ لمطابقة أداة الاختيار الكاملة (اطّلِع على الملاحظة أدناه بشأن دمج المتطلبات في أداة الاختيار).

      مرجع ميزات النظام

      • name (سلسلة): ميزة نظام

    • forbidden_system_features (كائن): الميزات التي لا يجب تضمينها على الجهاز من خلال أداة الاختيار هذه (بحد أقصى 100 ميزة لكل مجموعة). وإذا كان الجهاز يحتوي على أي من ميزات النظام في هذه القائمة، لن يتطابق مع أداة الاختيار، حتى إذا كانت تتطابق مع جميع المتطلبات الأخرى في أداة الاختيار.

      مرجع ميزات النظام

      • name (سلسلة): ميزة نظام

يمكنك العثور على التنسيق الصحيح للشركة المصنّعة للجهاز ورمز الطراز باستخدام قائمة الأجهزة على Google Play Console عن طريق اتّباع إحدى الطريقتَين التاليتَين:

  • فحص الأجهزة الفردية باستخدام قائمة الأجهزة، والعثور على رمز الشركة المصنّعة والطراز في المواقع الجغرافية كما هو موضّح في المثال أدناه (بالنسبة إلى هاتف Google Pixel 4a، تكون الشركة المصنّعة هي "Google" ورمز الطراز هو "سمك الشمس")"

    صفحة pixel 4a في قائمة الأجهزة

    صفحة pixel 4a في قائمة الأجهزة

  • تنزيل ملف CSV للأجهزة المتوافقة، واستخدام Manufacturer وModel Code للحقلين build_brand وbuild_device على التوالي.

على سبيل المثال، تتطابق المجموعة التالية مع جميع الأجهزة التي تضمّ ذاكرة وصول عشوائي بسعة أكثر من 4 غيغابايت، باستثناء هاتف Pixel 5 (google redfin) بما في ذلك Pixel 3 (Google Blueline الذي يتضمّن ذاكرة وصول عشوائي أقل من 4 غيغابايت).

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

يمكنك قراءته على النحو التالي:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

يمكنك اتّباع التعليمات الواردة أدناه للتحقّق من صحة ضبط استهداف الأجهزة قبل تحميله إلى Google Play.

الحصول على إعداد استهداف الأجهزة حسب رقم التعريف

يمكنك استرداد تهيئة استهداف أجهزة معينة عن طريق رقم التعريف باستخدام المكالمة التالية:

طلب HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
مَعلمات المسار لا ينطبق
نص الطلب لا ينطبق
نص الاستجابة ضبط استهداف الأجهزة

الحصول على قائمة بإعدادات استهداف الأجهزة

يمكنك الحصول على آخر 10 إعدادات لاستهداف الأجهزة وفقًا للاستدعاء التالي (أو تحديد مجموعة من عشرة إعدادات على النحو الأمثل باستخدام مَعلمة طلب البحث page_token):

طلب HTTP GEThttps://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
مَعلمات المسار لا ينطبق
مَعلمات طلب البحث page_token (اختيارية) - تُستخدَم لتحديد مجموعة معيّنة مكونة من 10 وحدات DTC. يكون هذا الإجراء مفيدًا إذا كنت قد أنشأت أكثر من 10 رموز DTC، وتريد الاطّلاع على رموز DTC التي تم إنشاؤها قبل أحدث 10 رموز DTC.
نص الطلب لا ينطبق
نص الاستجابة قائمة بإعدادات استهداف الأجهزة

page_token

التحقّق من إعدادات استهداف الأجهزة

يتضمّن bundletool أمرَين يساعدك في التحقّق من عمل إعدادات استهداف الأجهزة على النحو المطلوب قبل تحميلها إلى Play.

باستخدام bundletool print-device-targeting-config، يمكنك التحقّق من صحة بنية ملف JSON وعرض مجموعات أجهزتك بتنسيق يمكن قراءته بسهولة.

bundletool print-device-targeting-config --config=mydtc.json

باستخدام bundletool evaluate-device-targeting-config، يمكنك تقييم المجموعات التي قد تتطابق مع جهاز معيّن. يمكنك إمّا توصيل الجهاز المستهدَف بمحطة العمل واستخدام العلامة --connected-device أو تجميع ملف JSON بخصائص الجهاز يدويًا وتقديمه من خلال العلامة --device-properties.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

يجب أن يكون ملف خصائص الجهاز ملف JSON يتّبع بنية النموذج الأوّلي DeviceProperties. مثلاً:

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

جارٍ تحميل "مجموعة حزمات تطبيق Android" على Google Play

عبر واجهة برمجة التطبيقات

يمكنك استخدام Google Play Developer API لتحميل مجموعة حزمات تطبيق Android إلى Google Play وربط إعدادات معيّنة لاستهداف الأجهزة بتصميمك.

يمكنك الاطّلاع على نظرة عامة على أساليب التعديلات هنا، بالإضافة إلى أمثلة أكثر تفصيلاً عن طرح الإصدار الجديد من قنوات الإصدار المختلفة في Google Play Console (بالنسبة إلى الرابط الأخير، عليك استخدام واجهات برمجة التطبيقات المتوافقة مع AAB بدلاً من واجهة برمجة التطبيقات المتوافقة مع APK المدرجة في الصفحة). لتحديد إعدادات استهداف الأجهزة لإصدارك، يجب إضافة معرّف الإعداد إلى معلمة طلب البحث deviceTierConfigId أثناء استدعاء طريقة edits.bundle.upload، على النحو التالي:

https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editId}/bundles?deviceTierConfigId="{deviceTierConfigId}"

عبر Google Play Console

يمكنك اتّباع التعليمات الواردة هنا لتحميل "مجموعة حزمات تطبيق Android". سيتمّ تطبيق أحدث إعدادات DTC على حزمة التطبيقات.

مساعد

البدء السريع باستخدام Curl

وفي ما يلي مثال (باستخدام curl لأداة سطر الأوامر) لإنشاء ضبط جديد لاستهداف جهاز، واستخدام واجهة برمجة تطبيقات "Edits" لإنشاء تعديل جديد، وتحميل تنسيق AAB جديد (ربطه بإعداد استهداف جهاز معيّن)، وإعداد إعداد قناة الإصدار/الإصدار، وتنفيذ التعديل (وبالتالي جعل التغيير متاحًا للجميع). تأكد من أن لديك موقع:

أولاً، أنشئ تهيئة لاستهداف الأجهزة، ودوِّن رقم deviceTierConfigId الذي ستتلقاه عند إجراء مكالمة ناجحة.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs

بدء تعديل - ستحصل على معرّف ووقت انتهاء صلاحية التعديل. احفظ رقم التعريف للمكالمات التالية.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits

حمِّل تنسيق AAB، مع تحديد إعداد استهداف الأجهزة (deviceTierConfigId) على أنّه مَعلمة طلب بحث. في حال نجاح الطلب، سترى رمز الإصدار وsha1 وsha256 للبنية. احفظ رمز الإصدار للمكالمة التالية.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" --data-binary @$HOME/{aabFile} -H "Content-Type: application/octet-stream" -XPOST https://androidpublisher.googleapis.com/upload/androidpublisher/v3/applications/{packageName}/edits/{editID}/bundles?deviceTierConfigId="{deviceTierConfigId}

تحديد مسار AAB للمسار المطلوب (من أجل الاختبار، يُنصح باستخدام مسار الاختبار الداخلي، ولكن يمكنك الاطّلاع على المزيد من المعلومات حول المسارات المختلفة هنا)، نجري هنا عملية طرح بسيطة بدون ملاحظات الإصدار، ولكن يمكنك قراءة هذه الصفحة لمعرفة المزيد من المعلومات حول طريقة الطرح على مراحل والإصدارات الأولية وملاحظات الإصدار. إذا كانت هذه هي المرة الأولى التي تستخدم فيها واجهة برمجة تطبيقات الناشر، نقترح عليك إنشاء هذا الإصدار كإصدار تمهيدي، وإكمال الإصدار على Google Play Console لضمان ضبط كل الإعدادات بشكل صحيح.

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

تنفيذ التغييرات (يُرجى توخي الحذر حيث سيؤدي ذلك إلى نشر جميع التغييرات على Play على المقطع الصوتي المطلوب)

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}:commit