Ülkeye Göre Öğe Hedefleme

Ülkeye Göre Öğe Hedefleme nedir?

Ülkeye göre öğe hedefleme, cihazlara kullanıcının bulunduğu ülkeye bağlı olarak aynı öğenin farklı sürümlerini (çözünürlükler gibi) sunmanıza olanak tanır. Örneğin, uygulamanızın kullanıma sunulduğu farklı ülkelere, özelleştirilmiş öğeler göndermeyi seçebilirsiniz. Üstelik tüm bunları, kullanıcıların cihazlarına yalnızca gerekli öğeleri sunarak genel oyun boyutunda herhangi bir artış olmadan yapabilirsiniz. Bu uygulama, Play Öğe Teslimi'ndeki öğe paketi kavramını temel alır. Aşağıda gösterildiği gibi, en fazla 20 ülke grubu içeren hedefleme ölçütleri tanımlayabilirsiniz. Bu bağlamda, cihazın ülkesi genellikle kullanıcının Google Play hesabında kayıtlı fatura adresine göre 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 önceki sürümleri çalıştıran cihazlarda varsayılan ülke ayarı, kullanıcının 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. Ülkeye (ve buna bağlı olarak Play Asset Delivery) hedeflemeyi oyununuza entegre edin
   • Play Asset Delivery'yi oyununuza entegre edin (henüz yapmadıysanız)
   • Öğelerinizi öğe paketlerine bölün
   • Play'e yükleyeceğiniz son Android App Bundle yapısı için kodunuzu ve öğelerinizi bir araya getirin.
2. Play'in öğelerinizi kullanıcı cihazlarına nasıl yayınlayacağını bilmesi için Cihaz Hedefleme yapılandırmanızı oluşturun.
   • Google Play Developer API'yi ayarlayın (daha önce tamamlanmadıysa). Hedefleme yapılandırmalarını Play'e göndermek için bunu kullanacaksınız.
   • Hedefleme yapılandırmasını oluşturma adımlarını tamamlayın.
3. AAB'nizi Play'e yükleyin ve her şeyin doğru 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 aktardıktan sonra derlemenizi orada tamamlarsanız bu talimatları (ör. Unity oyunları Gradle'a aktarılır).

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

Play Asset Delivery'yi oyununuza entegre etme (henüz tamamlanmamışsa)

Play Asset Delivery (PAD), yükleme veya çalışma zamanında oyununuzun öğelerini dinamik olarak sunmanızı sağlar. Bununla ilgili genel bakışı buradan inceleyebilirsiniz. Ülkeye göre hedefleme kullanıldığında Play, öğe paketlerinizin içeriğini farklı kullanıcı konumları için tanımladığınız ülke ayarı yapılandırmalarına göre yayınlar. Aşağıdaki yönergeleri uygulamanız ve PAD'i oyununuza entegre etmeniz (ör. öğe paketleri oluşturma, oyununuzda alma uygulaması) 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 bu talimatları uygulayın, ardından öğe paketi alma özelliğini oyununuza entegre etme talimatlarını uygulayın:

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

Ülkeye özgü dizinler oluşturma

Gradle kullanıyorsanız

Şimdi öğelerinizi daha sonra tanımlayacağınız ülke grupları (maks. 20) arasında böleceksiniz. Hedeflenen dizinlerinizi, son adımda oluşturulan mevcut öğe paketi dizinlerini alarak oluşturun ve uygun klasörü (aşağıda açıklandığı gibi) #countries_latam, #countries_na vb. ile düzelterek yayınlayın. Oyununuzda öğe paketlerini kullanırken klasörleri postfix ile ele almanız gerekmez (başka bir deyişle, sonek, derleme işlemi sırasında otomatik olarak çıkarı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ör altındaki dosyalara eriştiğinizde, aynı yolu sonradan düzeltme olmadan kullanabilirsiniz (bu örnekte, herhangi bir son ek olmadan level1/assets/character-textures/ referans verilmiştir).

Android App Bundle oluşturma

Gradle

Projenizin build.gradle dosyasında, Android Gradle eklentisi ve bundletool için bağımlılıklarınızı aşağıdaki (veya daha yüksek bir sürüm) 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 projenizdeki gradle/wrapper/gradle-wrapper.properties bölümünden 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 kitaplığı 1.8.3 veya sonraki bir sürüme güncelleyin. Mümkünse Play Öğe Yayınlama Kitaplığı'na geçmenizi ve en son sürüme güncellemenizi ö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ölümünü etkinleştirin:

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

Son olarak, Android App Bundle'ınızı (AAB) oluşturabilirsiniz.

• Android Studio
• KSA

Paket aleti

paketinizi Bundletool ile oluşturun ve AAB'nizi özelleştirme adımındayken aşağıdaki kodu BundleConfig.pb dosyanıza ekleyin.

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

Yerel Test

Devam etmeden önce her şeyin doğru yapılandırıldığından emin olmak için uygulama paketinizi yerel olarak test etmeniz önerilir. bundletool'ı (1.14.0 veya üzeri) kullanarak uygulamanızı yerel olarak derleyip test ederek doğru ülkeyi açıkça belirtirsiniz. Öncelikle build-apks kullanarak bir .apks dosya grubu oluşturacaksınız, ardından uygulamanızı install-apks kullanarak bağlı bir cihaza dağıtacaksınız. Yüklemek istediğiniz ülke grubunu country-set işaretini kullanarak da belirtebilirsiniz. Bu yerel test yöntemi hakkında daha fazla bilgiyi burada bulabilirsiniz (bu sayfanın henüz ülkeye göre hedefleme için güncellenmediğini ve bu nedenle country-set işaretinin bulunmadığını 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 bir APK grubunu ayıklamak için extract-apks de kullanılabilir. Ancak bu cihazın ülkesini belirtmekle birlikte get-device-spec kullanmak --local-testing işaretiyle birlikte işe yaramaz. Bu nedenle hızlı takip edilen 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 tamamlanmamışsa)

Ülkeye göre hedeflemeyi yapılandırmak (ör. ülke gruplarınızı tanımlamak) için Android Yayıncı API'sini kullanarak yapılandırmanızı Google Play'e yüklemeniz gerekir. Yukarıdaki bağlantıdan API hakkında daha fazla bilgi edinebilirsiniz. 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 ayarlama.

API referansını burada bulabilirsiniz. Daha sonra derlemenizi API aracılığıyla yüklemeyi seçerseniz Düzenleme yöntemlerini kullanırsınız. Ayrıca, API'yi kullanmadan önce bu sayfayı incelemeniz önerilir.

Device Targeting Configuration API'yi 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 Metni	Cihaz Hedefleme Yapılandırması
Yanıt Gövdesi	Cihaz Hedefleme Yapılandırması

Cihaz Hedefleme Yapılandırması Nesnesi

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

Alanlar:

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

Google Play'e yüklemeden önce Cihaz Hedefleme Yapılandırmanızı doğrulamak için aşağıdaki talimatları uygulayabilirsiniz.

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 Metni	Yok
Yanıt Gövdesi	Cihaz Hedefleme Yapılandırması

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

Aşağıdaki çağrıya göre son 10 cihaz hedefleme yapılandırmasını alabilirsiniz (veya page_token sorgu parametresini kullanarak en uygun şekilde on adetlik 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ı) - 10 DTC'den oluşan belirli bir grubu belirtmek için kullanılır. Bu seçenek, 10'dan fazla DTC oluşturduysanız ve en son 10 DTC'den önce oluşturulmuş DTC'leri görmek istiyorsanız yararlı olur.
İstek Metni	Yok
Yanıt Gövdesi	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ın Play'e yüklenmeden önce amaçlandığı şekilde çalıştığını doğrulamanıza yardımcı olacak iki komut içerir.

bundletool print-device-targeting-config ile JSON dosyanızın söz diziminin doğru olduğunu doğrulayabilirsiniz.

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

bundletool evaluate-device-targeting-config ile hangi ülke grubunun belirli bir cihazla eşleşeceğini değerlendirebilirsiniz. Kullanıcının ülkesini --country-code işaretiyle belirtebilirsiniz.

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ışın yanı sıra Google Play Console'daki farklı kanallara yayınlamayla ilgili daha ayrıntılı örnekler de verilmiştir (son bağlantı için sayfada listelenen APK ile uyumlu API yerine AAB uyumlu API'leri kullanın). Derlemeniz için cihaz hedefleme yapılandırmasını belirtmek istiyorsanız edits.bundle.upload yöntemini çağırırken yapılandırma kimliğini deviceTierConfigId sorgu parametresine eklersiniz. Örneğin:

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

Google Play Console'dan

Android App Bundle'ınızı yüklemek için buradaki talimatları uygulayabilirsiniz. En son DTC yapılandırması App Bundle'ınıza uygulanır.

Doğru öğelerin teslim edildiğini doğrulama

Cihaza yalnızca doğru öğelerin teslim edildiğinden emin olmak için aşağıdaki yöntemi kullanın

adb shell pm path {packageName}

Şuna benzer bir sayfa 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'ü Kullanmaya Hızlı Başlangıç

Aşağıda, yeni bir cihaz hedefleme yapılandırması oluşturma ve yeni bir düzenleme oluşturmak, yeni bir AAB yüklemek (onu belirli bir cihaz hedefleme yapılandırmasıyla ilişkilendirmek), izleme/sürüm yapılandırmasını ayarlamak ve düzenlemeyi gerçekleştirmek için Edits API'yi kullanma ile ilgili bir örnek (komut satırı aracı curl kullanılarak) verilmiştir. (Böylece değişikliği herkese açık hale getirmiş olursunuz). Aşağıdaki konuma sahip olduğunuzdan emin olun:

• 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 size gönderilen deviceTierConfigId bilgisini 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 süresi alırsınız. Aşağıdaki çağrılar 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 ve sha256'yı görürsünüz. Sürüm kodunu bir sonraki çağrı için 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 sunum gerçekleştiriyoruz. Ancak aşamalı sunumların, taslak sürümlerin ve sürüm notlarının nasıl hazırlanacağı 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 uygulayın (Dikkatli bir şekilde devam edin; bu işlem, Play'de tüm değişikliklerin Play'de yayınlanmasına neden olur.)

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