تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

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

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

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

جرس

بالنسبة إلى الألعاب التي تم إنشاؤها باستخدام 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"

جرس

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

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

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

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

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

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

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

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

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

أداة الحزمة

أنشِئ حزمتك باستخدام bundletool وأثناء خطوة تخصيص تنسيق AAB، أضِف ما يلي إلى ملف BundleConfig.pb.

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

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

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

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

استخدام واجهة برمجة التطبيقات 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 (كائن): تعريفات مجموعة البلدان
- name (سلسلة): اسم مجموعة البلدان (رقم تعريف سلسلة تحدِّده).
- country_codes (سلسلة): البلدان التي تنتمي إلى مجموعة البلد هذه (التنسيق: ISO 3166-1 alpha-2).

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

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

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

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

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

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

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

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

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