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

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

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

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

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

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

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

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

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

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

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

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

Gradle

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

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

יצירת ספריות ספציפיות לקבוצות של מדינות

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

עכשיו תצטרכו לפצל את הנכסים בין קבוצות המדינות (עד 20) שתגדירו בהמשך. כדי ליצור את הספריות המטורגטות, צריך לקחת את הספריות הקיימות של חבילות הנכסים שנוצרו בשלב האחרון, ולהוסיף לספרייה המתאימה את הסיומת #countries_latam,‏ #countries_na וכו' (כפי שמתואר בהמשך). כשמשתמשים בחבילות הנכסים במשחק, לא צריך להתייחס לספריות לפי הסיומת (כלומר, הסיומת מוסרת באופן אוטומטי במהלך תהליך ה-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/ ללא תוספות פוסט).

יצירה של קובץ Android App Bundle

Gradle

בקובץ 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. אם אתם עדיין משתמשים בספריית הליבה המונוליטית של Google Play, עליכם לעדכן אותה לגרסה 1.8.3 ואילך. אם אפשר, מומלץ לעבור לספריית Play Asset Delivery ולעדכן לגרסה האחרונה.

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

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

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

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

• Android Studio
• CLI

Bundletool

יוצרים את החבילה באמצעות 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. אפשר לקרוא מידע נוסף על ה-API בקישור שלמעלה. יש כמה שלבים שצריך לבצע כדי להתחיל:

1. יוצרים (אם צריך) ומקשרים את פרויקט ה-API ל-Google Play Console.
2. הגדרת לקוח גישה ל-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 ההגדרות האחרונות של טירגוט לפי מכשיר בעזרת הקריאה הבאה (או לציין עשר הגדרות באופן אופטימלי באמצעות פרמטר השאילתה page_token):

בקשת HTTP	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
פרמטרים של נתיב	לא רלוונטי
פרמטרים של שאילתות	page_token (אופציונלי) – משמש לציון קבוצה ספציפית של 10 DTC. האפשרות הזו שימושית אם יצרת יותר מ-10 המרות DTC, וברצונך לראות המרות 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, מוסיפים את מזהה ה-config לפרמטר של השאילתה 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 העדכנית תוחל על חבילת האפליקציות.

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

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

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

• המפתח שתואם ללקוח ה-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