استهداف مواد العرض حسب البلد

ما هو المقصود باستهداف مواد العرض حسب البلد؟

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

مثل ميزة "عرض المواد في Play"، تتوفّر ميزة الاستهداف حسب البلد على الإصدار 4.1 من نظام التشغيل Android (المستوى 16 من واجهة برمجة التطبيقات) والإصدارات الأحدث. أمّا على الأجهزة التي تعمل بالإصدار 4.4 من نظام التشغيل Android (المستوى 19 لواجهة برمجة التطبيقات) أو الإصدارات الأقدم، فسيتم إرسال مجموعة البلدان التلقائية بغض النظر عن الموقع الجغرافي للمستخدم.

رحلة المطوّر

على مستوى عالٍ، لدمج الاستهداف حسب البلد في لعبتك الحالية، اتّبِع الخطوات التالية:

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

Gradle هو نظام التصميم الموصى به لألعاب Java والألعاب الأصلية. بالنسبة إلى الألعاب التي تم إنشاؤها باستخدام Gradle، اتّبِع الخطوات التالية لضبط نظام الإنشاء لإنشاء حِزم APK للتطبيقات القابلة للنشر على جميع الأجهزة (AAB) مع إتاحة ميزة الاستهداف حسب البلد.

إذا كنت بصدد تصدير لعبتك إلى Gradle ثم إنهاء عملية الإنشاء هناك، ننصحك باتّباع التعليمات التالية (مثل ألعاب Unity التي تم تصديرها إلى Gradle)).

إعداد استهداف مواد العرض حسب البلد في تطبيقك

دمج ميزة "عرض المواد في Play" في لعبتك (إذا لم يسبق لك إكمالها)

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

Gradle

بالنسبة إلى الألعاب التي تم إنشاؤها باستخدام Gradle، استخدِم التعليمات التالية لإنشاء حِزم مواد العرض باستخدام Gradle، ثم اتّبِع التعليمات لدمج استرداد حِزم مواد العرض في لعبتك:

• Java
• المدمَجة مع المحتوى
• ألعاب Unity التي تم تصديرها إلى Gradle
  • استخدِم مكتبات Java من خلال واجهة JNI (مثل المكتبة المضمّنة في Unity).

إنشاء أدلة خاصة بمجموعة بلدان معيّنة

في حال استخدام Gradle

ستقسّم الآن مواد العرض بين مجموعات البلدان (20 مجموعة كحدّ أقصى) التي ستحدّدها في وقت لاحق. أنشئ الأدلة المستهدفة من خلال أخذ أدلة حِزم مواد العرض الحالية التي تم إنشاؤها في الخطوة الأخيرة، وإضافة اللاحقة "‎ #countries_latam" أو "‎#countries_na" وغيرها إلى المجلد المناسب (كما هو موضّح أدناه). عند استخدام حِزم مواد العرض في لعبتك، لن تحتاج إلى الإشارة إلى المجلدات باستخدام اللاحقة (بمعنى آخر، تتم إزالة اللاحقة تلقائيًا أثناء عملية الإنشاء).

بعد الخطوة السابقة، قد يبدو هذا كالتالي:

...
.../level1/src/main/assets/character-textures#countries_latam/
.../level1/src/main/assets/character-textures#countries_na/
.../level1/src/main/assets/character-textures/
...

عند الوصول إلى الملفات ضمن المجلد، يمكنك استخدام المسار نفسه بدون إضافة أيّ لاحقة (في هذا المثال، يمكنني الإشارة إلى المسار باسم level1/assets/character-textures/ بدون أيّ لاحقات).

إنشاء مجموعة حزمات تطبيق Android

Gradle

في ملف build.gradle الخاص بمشروعك، اضبط الاعتماديات للحصول على الإصدارات أدناه (أو الإصدارات الأحدث) لكل من المكوّن الإضافي لنظام Gradle المتوافق مع Android وbundletool:

buildscript {
  dependencies {
    classpath 'com.android.tools.build:gradle:8.1.0-alpha01'
    classpath "com.android.tools.build:bundletool:1.14.0"
    ...
  }
  ...
}

ستحتاج أيضًا إلى تحديث إصدار Gradle إلى 8.0 أو إصدار أحدث. يمكنك تعديل هذا الخيار في gradle/wrapper/gradle-wrapper.properties ضمن مشروعك.

distributionUrl=https://services.gradle.org/distributions/gradle-8.0-rc-1-all.zip

أخيرًا، عليك استخدام مكتبة Play Asset Delivery Library. إذا كنت لا تزال تستخدم مكتبة Play Core Library الموحّدة، عليك تحديثها إلى الإصدار 1.8.3 أو إصدار أحدث. ننصحك بالتبديل إلى "مكتبة عرض مواد في Play" والتحديث إلى أحدث إصدار إذا أمكن.

dependencies {
  implementation 'com.google.android.play:asset-delivery:2.0.1'
  ...
}

في ملف build.gradle الخاص بوحدة التطبيق الرئيسية، فعِّل تقسيم استهداف البلدان:

android {
  bundle {
    countrySet {
      enableSplit true
    }
    ...
  }
  ...
}

أخيرًا، يمكنك إنشاء مجموعة حزمات تطبيقات Android (AAB).

• استوديو Android
• واجهة سطر الأوامر

Bundletool

أنشئ حِزمك باستخدام أداة bundletool، وأضِف ما يلي إلى ملف BundleConfig.pb أثناء خطوة تخصيص حِزم APK المُعدّة للنشر (AAB):

{
  ...
  "optimizations": {
    "splitsConfig": {
      "splitDimension": [
      ...
      {
        "value": "COUNTRY_SET",
        "negate": false,
        "suffixStripping": {
          "enabled": true,
        }
      }],
    }
  }
}

الاختبار على الجهاز

قبل المتابعة، ننصحك باختبار حِزمة تطبيقك على الجهاز للتأكّد من أنّ كل الإعدادات صحيحة. باستخدام IDE bundletool (الإصدار 1.14.0 أو الإصدارات الأحدث)، يمكنك إنشاء تطبيقك واختباره محليًا، مع تحديد البلد الصحيح صراحةً. عليك استخدام build-apks أولاً لإنشاء مجموعة من ملفات .apks، ثم نشر تطبيقك على جهاز متصل باستخدام install-apks. يمكنك أيضًا تحديد مجموعة البلدان التي تريد تثبيت التطبيق فيها باستخدام العلامة country-set. يمكنك الاطّلاع على مزيد من المعلومات حول طريقة الاختبار المحلي هذه هنا (يُرجى العِلم أنّه لم يتم تعديل هذه الصفحة بعد لاستهداف البلدان، وبالتالي لا تظهر فيها country-set).

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testing
bundletool install-apks --apks=/path/to/app.apks --country-set=latam

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

bundletool get-device-spec --output=/path/to/device-spec.json --country-set=latam
bundletool 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. إعداد عميل للوصول إلى واجهة برمجة التطبيقات

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

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

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

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

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

عنصر إعدادات استهداف الأجهزة

{
  "user_country_sets": [
    {
      "name": "latam",
      "country_codes": [
        "AR",
        "BR",
        ...
      ]
    },
    {
      "name": "sea",
      "country_codes": [
        "VN",
        "TW",
        ...
      ]
    }
  ]
}

الحقول:

• ‫device_confid_id (عدد صحيح): المعرّف المقابل لإعدادات استهداف هذا الجهاز.
• user_country_sets (object): تعريفات مجموعة البلدان
  • ‫name (سلسلة): اسم مجموعة البلدان (معرّف سلسلة تحدّده).
  • country_codes (سلسلة): البلدان التي تنتمي إلى مجموعة البلدان هذه (التنسيق: ISO 3166-1 alpha-2).

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

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

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

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

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

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

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

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

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

باستخدام bundletool print-device-targeting-config، يمكنك التحقّق من صحة ملف JSON.

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

باستخدام bundletool evaluate-device-targeting-config، يمكنك تقييم مجموعة البلدان التي تتطابق مع جهاز معيّن. يمكنك تقديم بلد المستخدم من خلال العلامة --country-code.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device --country-code=AR

تحميل "مجموعة حزمات تطبيق 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 على حِزمة تطبيقك.

التأكّد من تسليم مواد العرض الصحيحة

استخدِم الطريقة التالية لضمان عدم إرسال سوى مواد العرض الصحيحة إلى الجهاز.

adb shell pm path {packageName}

من المفترض أن يظهر لك شيء مثل:

package:{...}/base.apk
package:{...}/split_config.en.apk
package:{...}/split_config.xxhdpi.apk
package:{...}/split_main_asset.apk
package:{...}/split_main_asset.config.countries_latam.apk

مساعد

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

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

• المفتاح المقابل لعميل واجهة برمجة التطبيقات
• اسم حزمة تطبيقك

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

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPOST -H "Content-Type: application/json" -d "{ "user_country_sets": [ { "name": "latam", "country_codes": [ "AR", "BR" ] }, { "name": "sea", "country_codes": [ "VN", "TW" ] } ] }" 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، مع تحديد إعداد استهداف الأجهزة كمَعلمة طلب بحث. إذا كان الطلب ناجحًا، سيظهر لك رمز الإصدار و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="{deviceTargetingConfigID}"

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

curl -H "$(oauth2l header --json $HOME/{apiKey} androidpublisher)" -XPUT -H "Content-Type: application/json" -d "{ releases: [{status: '{status}'</code>, <code><strong>versionCodes</strong></code>: <code>['{versionCode}']</code> <code><strong>}]}</strong></code>" <code>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