דף זה תורגם על ידי Cloud Translation API.

טירגוט נכסים לפי מדינה

מהו טירגוט נכסים לפי מדינה?

טירגוט של נכסים לפי מדינה מאפשר להציג גרסאות שונות (למשל רזולוציות) של אותו נכס למכשירים בהתאם למדינה שבו המשתמש נמצא. לדוגמה, אפשר לבחור להציג מודעות נכסים למדינות שונות שבהן האפליקציה זמינה – והכול בלי הגדלה של גודל המשחק הכולל על ידי אספקת הנכסים החיוניים למשתמשים מכשירים. הגישה הזו מתבססת על חבילות נכסים ב-Play Asset Delivery. כפי שמוצג בהמשך, אפשר להגדיר את הקריטריונים לטירגוט עם 20 מדינות לכל היותר למשימות. בהקשר הזה, המדינה של המכשיר בדרך כלל נקבעים לפי הכתובת לחיוב של המשתמש שרשומה ב-Google חשבון Play.

בדומה להעברת נכסים ב-Play, טירגוט לפי מדינה תומך ב-Android 4.1 (רמת API) 16) ומעלה. עם זאת, במכשירים שבהם פועלת גרסת Android 4.4 (רמת API 19) ומטה, המדינה שמוגדרת כברירת מחדל נשלחת ללא קשר למיקום המשתמש.

התהליך למפתחים

ברמה גבוהה, כדי לשלב טירגוט לפי מדינה במשחק הקיים שלכם, פועלים לפי השלבים הבאים:

שילוב של טירגוט לפי מדינה (וכתוצאה מכך, Play Asset Delivery) בתוך המשחק
- משלבים Play Asset Delivery במשחק (אם עוד לא עשיתם זאת) כבר עשית זאת)
- מחלקים את הנכסים לחבילות נכסים
- עליכם לארוז את הקוד והנכסים שלכם יחד כדי ליצור את פריט מידע שנוצר בקובץ Android App Bundle שיעלה ל-Play.
יצירת הגדרה של טירגוט לפי מכשיר כדי שמערכת Play תדע איך לשלוח את הנכסים שלכם למכשירים של המשתמשים.
- להגדיר את Google Play Developer API (אם עדיין לא השלמתם אותו), שבו תשתמש כדי לשלוח את הגדרות הטירגוט ל-Play.
- מבצעים את השלבים ליצירת הגדרת הטירגוט.
צריך להעלות את קובץ ה-AAB ל-Play ולבדוק אם הכול תקין הוגדר כראוי

Gradle היא מערכת ה-build המומלצת למשחקים Java ולמשחקים נייטיב. במשחקים שנוצרו באמצעות Gradle, צריך לבצע את השלבים הבאים כדי להגדיר את מערכת ה-build כדי ליצור AAB בעזרת תמיכה בטירגוט לפי מדינה.

אם מייצאים את המשחק ל-Gradle ואז מסיימים את ה-build שם, מומלץ לפעול לפי ההוראות הבאות (לדוגמה: משחקי Unity יוצאו אל Gradle)).

הגדרת טירגוט של נכסים לפי מדינה באפליקציה

שילוב של Play Asset Delivery במשחק (אם עדיין לא השלמתם אותו)

באמצעות Play Asset Delivery (PAD) אפשר להעביר באופן דינמי את הרכיבים של המשחק בזמן ההתקנה או בזמן הריצה, וניתן גם לקרוא סקירה כללית בנושא. ב- שמטרגטת לפי מדינה, מערכת Play תספק את התוכן של חבילות הנכסים שלך בהגדרות של המדינה שבחרת עבור מיקומי משתמש שונים. מומלץ לפעול לפי ההנחיות שבהמשך ולשלב את PAD המשחק שלך (למשל, יצירת חבילות נכסים, הטמעת אחזור במשחק), ולאחר מכן לשנות את קוד הפרויקט כדי לאפשר טירגוט לפי מדינה.

גרדל

במשחקים שנוצרו באמצעות Gradle, צריך לפעול לפי ההוראות הבאות עבור פיתוח חבילות נכסים באמצעות Gradle ואז פועלים לפי ההוראות לשילוב האחזור של חבילת הנכסים בתוך המשחק:

Java
מודעות מותאמות
משחקי Unity יוצאו אל Gradle
- שימוש בספריות Java באמצעות ה-JNI (למשל זה שמובנה ב-Unity).

יצירת ספריות ספציפיות לפי מדינה

אם משתמשים ב-Gradle

עכשיו תפצלו את הנכסים בין קבוצות המדינות (עד 20) אגדיר מאוחר יותר. כדי ליצור את הספריות המטורגטות, משתמשים בפקודה הקיימות ספריות של חבילות נכסים שנוצרו בשלב האחרון, ולאחר תיקון התיקייה המתאימה (כפי שמתואר בהמשך) עם #countries_latam, #countries_na, וכו' כשמשתמשים בחבילות הנכסים במשחק, לא צריך לעשות כתובות תיקיות לפי Postfix (במילים אחרות, התיקון מפרסום) בתהליך ה-build).

אחרי השלב הקודם, זה עשוי להיראות כך:

...
.../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/ ללא סיומות (postfix)).

פיתוח קובץ Android App Bundle

גרדל

בקובץ 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"
    ...
  }
  ...
}

צריך גם לעדכן את גרסת ה-Gradle לגרסה 8.0 ואילך. אפשר לעדכן את האפשרות הזו בgradle/wrapper/gradle-wrapper.properties בתוך הפרויקט.

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

לסיום, תצטרכו להשתמש בספרייה ב-Play Asset Delivery. אם אתם עדיין באמצעות ספריית הליבה המונולית של Play, לעדכן אותה לגרסה 1.8.3 ואילך. ההמלצות שלנו מעבר לספרייה להעברת נכסים ב-Play ועדכון לגרסה האחרונה אם אפשר.

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

בקובץ build.gradle של המודול הראשי של האפליקציה, מפעילים את חלוקת הטירגוט לפי מדינה:

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

לבסוף, אפשר ליצור קובץ Android App Bundle (AAB).

כלי Bundletool

בניית החבילה באמצעות Bundletool, וגם בשלב שבו מבצעים התאמה אישית של ה-AAB, יש להוסיף את הטקסט הבא לקובץ BundleConfig.pb שלך.

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

בדיקות מקומיות

לפני שממשיכים, מומלץ לבדוק באופן מקומי את ה-App Bundle כדי מוודאים שהכול מוגדר כמו שצריך. באמצעות 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

תחילת העבודה עם ממשק ה-API של Google Play למפתחים (אם עדיין לא השלמתם אותו)

כדי להגדיר טירגוט לפי מדינה (כלומר, הגדרת קבוצות המדינות שלכם), צריך תצטרכו להשתמש ב-Android Publisher API כדי להעלות את התצורה שלך ל-Google Play. מידע נוסף על ה-API זמין בכתובת הקישור שלמעלה – יש כמה השלבים שצריך לבצע כדי להתחיל:

יוצרים (במידת הצורך) את פרויקט ה-API ומקשרים אותו ל-Google Play Console.
Set up API Access Client (הגדרת לקוח גישה ל-API).

מידע על ה-API כאן - אם תבחרו להעלות את ה-build דרך ה-API, באמצעות שיטות עריכה. בנוסף, מומלץ לקריאת הדף הזה לפני השימוש ב-API.

שימוש ב-Device Targeting Configuration API

אפשר להשתמש בקריאה הבאה ל-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 (string): מדינות ששייכות לקבוצת המדינה הזו (בפורמט: 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 המרות דיגיטליות. האפשרות הזו שימושית אם יצרתם יותר מ-10 המרות מסוג DTC, והיית רוצה לראות אותן לפני ה-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 App Bundle ל-Google Play

דרך API

אפשר להשתמש ב-Google Play Developer API כדי להעלות את קובץ Android App Bundle ל-Google Play ולקשר הגדרה ספציפית של טירגוט לפי מכשיר את ה-build שלך.

יש סקירה כללית על שיטות העריכה, וגם דוגמאות מעמיקות יותר להשקה לטראקים השונים ב-Google Play Console (בקישור האחרון מומלץ להשתמש ממשקי API ידידותיים ל-AAB במקום API ידידותי ל-APK, שמפורטות בדף). כדי לציין את הגדרת הטירגוט למכשיר עבור של ה-build, עליך להוסיף את מזהה ההגדרה אל deviceTierConfigId של שאילתה ה-method edits.bundle.upload, כמו:

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

מ-Google Play Console

כאן אפשר למצוא את ההוראות כדי להעלות את קובץ Android App Bundle. ההגדרה האחרונה של ה-DTC תהיה הוחל על קובץ ה-App Bundle.

מתבצע אימות של הנכסים הנכונים

פועלים בשיטה הבאה כדי לוודא שנאספים רק הנכסים הנכונים למכשיר

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 של כלי שורת הפקודה) של יצירת הגדרה חדשה של טירגוט לפי מכשיר, וכן באמצעות ממשק ה-API של העריכות כדי ליצור עריכה חדשה, להעלות AAB חדש (לשייך אותו עם הגדרות טירגוט ספציפיות למכשיר), קובעים את תצורת המסלול/ההפצה את העריכה. (וכך הופכים את השינוי לגלוי לכולם). עליך להקפיד להתקין את המיקום של:

המפתח שתואם ללקוח ה-API שלכם
שם החבילה של האפליקציה

קודם כול, יוצרים הגדרת טירגוט לפי מכשיר ומעיינים הסכום 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 של ה-build. שמירה את קוד הגרסה של השיחה הבאה.

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