Ülkeye Göre Öğe Hedefleme

Ülkeye göre öğe hedefleme nedir?

Ülkeye göre öğe hedefleme, kullanıcının bulunduğu ülkeye bağlı olarak cihazlara aynı öğenin farklı sürümlerini (çözümler gibi) yayınlamanıza olanak tanır. Örneğin, uygulamanızın kullanıma sunulduğu farklı ülkelere, özelleştirilmiş öğeler sunmayı seçebilirsiniz. Üstelik tüm bunları, yalnızca gerekli öğeleri kullanıcıların cihazlarına sunarak toplam oyun boyutunda herhangi bir artış olmadan yapabilirsiniz. Bu özellik, Play Asset Delivery'deki öğe paketi kavramına dayanır. Aşağıda göreceğiniz gibi, hedefleme ölçütlerini en fazla 20 ülke grubuyla tanımlayabilirsiniz. Bu bağlamda cihaz ülkesi genellikle kullanıcının Google Play hesabına kayıtlı fatura adresi tarafından belirlenir.

Play Asset Delivery gibi ülkeye göre hedefleme de Android 4.1 (API düzeyi 16) ve sonraki sürümleri destekler. Ancak Android 4.4 (API düzeyi 19) veya daha eski sürümleri çalıştıran cihazlarda, varsayılan ülke grubu kullanıcı konumundan bağımsız olarak yayınlanır.

Geliştirici Yolculuğu

Genel olarak, ülkeye göre hedeflemeyi mevcut oyununuza entegre etmek için aşağıdaki adımları uygulayın:

1. Oyununuza ülkeye göre hedeflemeyi (ve buna bağlı olarak Play Asset Delivery'i) entegre edin
   • Play Asset Delivery'yi oyununuza entegre edin (henüz yapmadıysanız)
   • Öğelerinizi öğe paketlerine bölme
   • Play'e yükleyeceğiniz son Android App Bundle yapısı için kodunuzu ve öğelerinizi birlikte paketleyin.
2. Play'in öğelerinizi kullanıcı cihazlarına nasıl yayınlayacağını bilmesi için cihaz hedefleme yapılandırmanızı oluşturun.
   • Hedefleme yapılandırmalarını Play'e göndermek için kullanacağınız Google Play Developer API'yi (henüz tamamlanmadıysa) ayarlayın.
   • Hedefleme yapılandırmasını oluşturma adımlarını uygulayın.
3. AAB'nizi Play'e yükleyin ve her şeyin doğru şekilde yapılandırıldığından emin olmak için test edin

Gradle, Java ve yerel oyunlar için önerilen derleme sistemidir. Gradle kullanılarak oluşturulan oyunlarda, AAB'nizi ülke hedefleme desteğiyle oluşturmak için derleme sistemini yapılandırmak üzere aşağıdaki adımları uygulayın.

Oyununuzu Gradle'a aktarıp derleme işlemini orada tamamlarsanız aşağıdaki talimatları uygulamanızı öneririz (ör. Unity oyunları (Gradle'a aktarılan)).

Uygulamanızda ülkeye göre öğe hedeflemeyi ayarlama

Play Asset Delivery'yi oyununuza entegre etme (henüz tamamlanmadıysa)

Play Asset Delivery (PAD), oyun öğelerinizi yükleme sırasında veya çalışma zamanında dinamik olarak yayınlamanıza olanak tanır. Bu konuyla ilgili genel bilgileri buradan okuyabilirsiniz. Ülkeye göre hedefleme özelliği sayesinde Play, öğe paketlerinizin içeriğini farklı kullanıcı konumları için belirttiğiniz ülke grubu yapılandırmalarına göre sunar. Aşağıdaki talimatları uygulayarak PAD'yi oyununuza entegre etmeniz (ör. öğe paketleri oluşturun, oyununuzda getirme işlemini uygulayın) ve ardından proje kodunu ülkeye göre hedeflemeyi etkinleştirecek şekilde değiştirmeniz önerilir.

Gradle

Gradle ile oluşturulan oyunlarda Gradle ile öğe paketlerinizi oluşturmak için şu talimatları uygulayın, ardından öğe paketi alımını oyununuza entegre etme talimatlarını uygulayın:

• Java
• Yerel
• Gradle'a aktarılan Unity oyunları
  • JNI aracılığıyla Java kitaplıklarını (ör. Unity'de yerleşik olan) kullanın.

Ülkeye özgü dizinler oluşturma

Gradle kullanıyorsanız

Artık öğelerinizi daha sonra tanımlayacağınız ülke grupları (maks. 20) arasında böleceksiniz. Son adımda oluşturulan mevcut öğe paketi dizinlerini alarak ve uygun klasörü (aşağıda açıklandığı gibi) #countries_latam, #countries_na vb. ile son ekleyerek hedeflenen dizinlerinizi oluşturun. Oyununuzda öğe paketlerini kullanırken klasörleri son eke göre adlandırmanız gerekmez (yani son ek, derleme işlemi sırasında otomatik olarak kaldırılır).

Önceki adımdan sonra bu durum aşağıdaki gibi görünebilir:

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

Klasördeki dosyalara erişirken, son ek olmadan aynı yolu kullanabilirsiniz (bu örnekte, son ek olmadan level1/assets/character-textures/ olarak atıfta bulunacağım).

Android App Bundle oluşturma

Gradle

Projenizin build.gradle dosyasında, bağımlılıkları Android Gradle eklentisi ve bundletool için aşağıdaki sürümlere (veya daha yeni sürümlere) sahip olacak şekilde yapılandırın:

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

Ayrıca gradle sürümünüzü 8.0 veya sonraki bir sürüme güncellemeniz gerekir. Bunu projeniz içinde gradle/wrapper/gradle-wrapper.properties bölümünde güncelleyebilirsiniz.

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

Son olarak Play Asset Delivery Kitaplığı'nı kullanmanız gerekir. Monolitik Play Core Kitaplığı'nı kullanmaya devam ediyorsanız 1.8.3 veya sonraki bir sürüme güncelleyin. Play Asset Delivery kitaplığına geçmenizi ve mümkünse en son sürüme güncelleme yapmanızı öneririz.

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

Ana uygulama modülünün build.gradle dosyasında ülke hedefleme bölme özelliğini etkinleştirin:

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

Son olarak Android App Bundle'ınızı (AAB) derleyebilirsiniz.

• Android Studio
• CLI

Bundletool

Paketinizi bundletool ile derleyin ve AAB'nizi özelleştirme adımında BundleConfig.pb dosyanıza aşağıdakileri ekleyin.

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

Yerel test

Devam etmeden önce, her şeyin doğru şekilde ayarlandığından emin olmak için uygulama paketinizi yerel olarak test etmeniz önerilir. bundletool (1.14.0 veya sonraki sürümler) ile uygulamanızı yerel olarak derleyip test ederek doğru ülkeyi açıkça belirtirsiniz. Önce build-apks kullanarak bir .apks dosyası grubu oluşturur, ardından install-apks kullanarak uygulamanızı bağlı bir cihaza dağıtırsınız. country-set işaretçisini kullanarak hangi ülke grubunun yüklenmesini istediğinizi de belirtebilirsiniz. Bu yerel test yöntemi hakkında daha fazla bilgiyi burada bulabilirsiniz (bu sayfanın ülkeye göre hedefleme için henüz güncellenmediğini ve bu nedenle country-set işaretinin eksik olduğunu lütfen unutmayın).

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

Alternatif olarak: Belirli bir cihaza ait APK grubunu ayıklamak için extract-apks'ı da kullanabilirsiniz. Ancak bu cihazın ülkesini belirtirken get-device-spec kullanmanın --local-testing işaretiyle birlikte çalışmayacağı anlamına gelir. Bu durumda hızlı takip veya isteğe bağlı öğe paketlerini test edemezsiniz.

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 aracılığıyla Cihaz Hedefleme Yapılandırması Oluşturma

Google Play Developer API'yi kullanmaya başlama (henüz tamamlanmadıysa)

Hedeflemeyi ülkeye göre yapılandırmak (ör. ülke gruplarınızı tanımlamak) için yapılandırmanızı Google Play'e yüklemek amacıyla Android Publisher API'yi kullanmanız gerekir. API hakkında daha fazla bilgiyi yukarıdaki bağlantıda bulabilirsiniz. Başlamak için uygulamanız gereken birkaç adım vardır:

1. API projenizi oluşturun (gerekirse) ve Google Play Console'unuza bağlayın.
2. API Erişim İstemcisi kurma.

API referansını buradan bulabilirsiniz. Daha sonra derlemenizi API üzerinden yüklemeyi seçerseniz düzenleme yöntemlerini kullanacaksınız. Ayrıca, API'yi kullanmadan önce bu sayfayı incelemenizi öneririz.

Cihaz Hedefleme Yapılandırma API'sini kullanma

Cihaz hedefleme yapılandırmanızı oluşturmak için aşağıdaki API çağrısını kullanabilirsiniz:

Cihaz Hedefleme Yapılandırması Oluşturma

HTTP isteği	POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Yol parametreleri	Yok
İstek Gövdesi	Cihaz Hedefleme Yapılandırması
Yanıt Metni	Cihaz Hedefleme Yapılandırması

Cihaz Hedefleme Yapılandırma Nesnesi

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

Alanlar:

• device_confid_id (tam sayı): Bu cihaz hedefleme yapılandırmasına karşılık gelen kimlik.
• user_country_sets (nesne): Ülke grubu tanımları
  • ad (dize): Ülke grubunun adı (tanımladığınız bir dize kimliği).
  • country_codes (dize): Bu ülke grubuna ait ülkeler (biçim: ISO 3166-1 alpha-2).

Cihaz Hedefleme Yapılandırmanızı Google Play'e yüklemeden önce aşağıdaki talimatları uygulayarak doğrulayabilirsiniz.

Kimliğe göre cihaz hedefleme yapılandırmasını alma

Aşağıdaki çağrıyı kullanarak kimliğe göre belirli bir cihaz hedefleme yapılandırmasını alabilirsiniz:

HTTP isteği	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}
Yol parametreleri	Yok
İstek Gövdesi	Yok
Yanıt Metni	Cihaz Hedefleme Yapılandırması

Cihaz Hedefleme Yapılandırmalarının listesini al

Aşağıdaki çağrıyı kullanarak son 10 cihaz hedefleme yapılandırmasını alabilirsiniz (veya page_token sorgu parametresini kullanarak onlu bir grup belirtebilirsiniz):

HTTP isteği	GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs
Yol parametreleri	Yok
Sorgu parametreleri	page_token (isteğe bağlı): Belirli bir 10 DTC grubunu belirtmek için kullanılır. Bu, 10'dan fazla DTC oluşturduysanız ve en son 10'dan önce oluşturulan DTC'leri görmek istiyorsanız kullanışlıdır.
İstek Metni	Yok
Yanıt Metni	Cihaz Hedefleme Yapılandırmalarının Listesi sayfa_jetonu

Cihaz Hedefleme Yapılandırmanızı Doğrulama

bundletool, cihaz hedefleme yapılandırmanızı Play'e yüklemeden önce amaçladığınız şekilde çalıştığını doğrulamanıza yardımcı olan iki komut içerir.

bundletool print-device-targeting-config ile JSON dosyanızın söz dizimi açısından doğru olup olmadığını doğrulayabilirsiniz.

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

bundletool evaluate-device-targeting-config ile belirli bir cihazla hangi ülke grubunun eşleşeceğini değerlendirebilirsiniz. Kullanıcının ülkesini --country-code işareti aracılığıyla sağlayabilirsiniz.

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

Android App Bundle'ınızı Google Play'e yükleme

API aracılığıyla

Android App Bundle'ınızı Google Play'e yüklemek ve belirli bir cihaz hedefleme yapılandırmasını derlemenize bağlamak için Google Play Developer API'yi kullanabilirsiniz.

Düzenleme yöntemlerine genel bir bakış ve Google Play Console'da farklı kanallarda yayınlamayla ilgili daha ayrıntılı örnekler bulabilirsiniz (Son bağlantıda, sayfada listelenen APK uyumlu API yerine AAB uyumlu API'leri kullanmanız gerekir). Derlemenizin cihaz hedefleme yapılandırmasını belirtmek için edits.bundle.upload yöntemini çağırırken aşağıdaki gibi yapılandırma kimliğini deviceTierConfigId sorgu parametresine eklersiniz:

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

Google Play Console aracılığıyla

Android uygulama paketinizi yüklemek için buradaki talimatları uygulayabilirsiniz. En son DTC yapılandırması uygulama paketinize uygulanır.

Doğru öğelerin yayınlandığını doğrulama

Cihaza yalnızca doğru öğelerin yayınlandığından emin olmak için aşağıdaki yöntemi kullanın

adb shell pm path {packageName}

Aşağıdakine benzer bir şey görürsünüz:

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

Yardımcı

Curl kullanarak Hızlı Başlangıç

Aşağıda, yeni bir cihaz hedefleme yapılandırması oluşturma ve Edits API'yi kullanarak yeni bir düzenleme oluşturma, yeni bir AAB yükleme (belirli bir cihaz hedefleme yapılandırmasıyla ilişkilendirme), kanal/sürüm yapılandırmasını ayarlama ve düzenlemeyi kaydetme örneği (curl komut satırı aracı kullanılarak) verilmiştir. (Böylece değişikliği herkese açık hale getirmiş olursunuz). Aşağıdakilerin konumunu bilmeniz gerekir:

• API istemcinize karşılık gelen anahtar
• Uygulamanızın paket adı

Öncelikle bir cihaz hedefleme yapılandırması oluşturun ve başarılı bir aramadan sonra alacağınız deviceTierConfigId değerini not edin.

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

Düzenleme başlatın: Düzenleme için bir kimlik ve geçerlilik bitiş zamanı alırsınız. Sonraki aramalar için kimliği kaydedin.

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

Cihaz hedefleme yapılandırmasını sorgu parametresi olarak belirterek AAB'yi yükleyin. Çağrı başarılı olursa derlemenin sürüm kodunu, sha1'ini ve sha256'sını görürsünüz. Sonraki arama için sürüm kodunu kaydedin.

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'yi istediğiniz kanala atayın (test için dahili test kanalını kullanmanız önerilir ancak farklı kanallar hakkında daha fazla bilgiyi buradan edinebilirsiniz). Burada, sürüm notları olmadan basit bir kullanıma sunma işlemi gerçekleştiriyoruz ancak aşamalı kullanıma sunma, sürüm taslakları ve sürüm notları hakkında daha fazla bilgi edinmek için bu sayfayı okuyabilirsiniz. Publisher API'yi ilk kez kullanıyorsanız bunu taslak sürüm olarak oluşturmanızı ve her şeyin doğru yapılandırıldığından emin olmak için sürümü Google Play Console'da tamamlamanızı öneririz.

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}

Değişiklikleri kaydetme (Bu işlem, tüm değişikliklerin Play'de yayınlanmasını sağlayacağından istenen kanala dikkatli bir şekilde ilerleyin)

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