Halaman ini diterjemahkan oleh Cloud Translation API.

Penargetan Aset menurut Negara

Apa itu Penargetan Aset menurut Negara?

Penargetan aset menurut negara memungkinkan Anda mengirim versi yang berbeda (seperti resolusi) dari aset yang sama ke perangkat berdasarkan negara tempat pengguna berada. Misalnya, Anda dapat memilih untuk mengirim aset yang disesuaikan ke berbagai negara tempat aplikasi Anda tersedia, semua tanpa menyebabkan peningkatan pada ukuran game secara menyeluruh dengan hanya mengirimkan aset yang diperlukan ke perangkat pengguna. Cara ini dibuat berdasarkan konsep paket aset di Play Asset Delivery. Seperti yang akan Anda lihat di bawah, Anda dapat menentukan kriteria penargetan dengan maksimum 20 set negara. Dalam konteks ini, negara perangkat biasanya ditentukan oleh alamat penagihan pengguna yang terdaftar di akun Google Play.

Seperti Play Asset Delivery, penargetan menurut negara mendukung Android 4.1 (API level 16) dan yang lebih tinggi. Namun, pada perangkat yang menjalankan Android 4.4 (API level 19) atau yang lebih lama, set negara default akan dikirimkan, terlepas dari lokasi pengguna.

Perjalanan Developer

Pada level yang tinggi, untuk mengintegrasikan penargetan menurut negara ke dalam game yang sudah ada, ikuti langkah-langkah berikut:

Integrasikan penargetan menurut negara (dan dengan demikian juga Play Asset Delivery) dalam game
- Integrasikan Play Asset Delivery ke dalam game (jika Anda belum melakukannya)
- Pisahkan aset Anda menjadi paket aset
- Gabungkan kode dan aset Anda untuk artefak Android App Bundle final yang akan diupload ke Play.
Buat konfigurasi Penargetan Perangkat sehingga Play tahu cara mengirimkan aset Anda ke perangkat pengguna.
- Siapkan Google Play Developer API (jika belum selesai), yang akan Anda gunakan untuk mengirimkan konfigurasi penargetan ke Play.
- Ikuti langkah-langkah untuk membuat konfigurasi penargetan.
Upload AAB Anda ke Play, lalu uji untuk memastikan semuanya dikonfigurasi dengan benar

Gradle adalah sistem build yang direkomendasikan untuk game Java dan native. Untuk game yang dibangun menggunakan Gradle, ikuti langkah-langkah berikut untuk mengonfigurasi sistem build guna membangun AAB dengan dukungan penargetan negara.

Jika Anda mengekspor game ke Gradle, lalu menyelesaikan build di sana, sebaiknya ikuti petunjuk berikut (misalnya, game Unity yang diekspor ke Gradle)).

Menyiapkan penargetan aset menurut negara dalam aplikasi Anda

Mengintegrasikan Play Asset Delivery ke dalam game (jika belum selesai)

Dengan Play Asset Delivery (PAD), Anda dapat mengirimkan aset game secara dinamis pada waktu penginstalan atau runtime, dan Anda dapat membaca ringkasannya di sini. Dengan penargetan menurut negara, Play akan mengirimkan konten paket aset berdasarkan konfigurasi set negara yang Anda tentukan untuk berbagai lokasi pengguna. Sebaiknya ikuti panduan di bawah ini dan integrasikan PAD ke dalam game (yaitu buat paket aset, implementasikan pengambilan dalam game Anda), lalu ubah kode project untuk mengaktifkan penargetan menurut negara.

Gradle

Untuk game yang di-build dengan Gradle, gunakan petunjuk ini untuk mem-build paket aset dengan Gradle, lalu ikuti petunjuk untuk mengintegrasikan pengambilan paket aset dalam game:

Java
Native
Game Unity yang diekspor ke Gradle
- Gunakan library Java melalui JNI (seperti library yang di-build di dalam Unity).

Membuat direktori khusus set negara

Jika menggunakan Gradle

Sekarang Anda akan membagi aset di antara set negara (maks. 20) yang akan Anda tentukan nanti. Buat direktori penargetan Anda dengan mengambil direktori paket aset yang ada yang dibuat di langkah terakhir, dan pasca-perbaikan folder yang sesuai (seperti yang dijelaskan di bawah) dengan #countries_latam, #countries_na, dll. Saat menggunakan paket aset dalam game, Anda tidak perlu menangani folder dengan postfix (dengan kata lain, postfix akan otomatis dihilangkan selama proses build).

Setelah langkah sebelumnya, tampilannya mungkin seperti ini:

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

Saat mengakses file dalam folder, Anda cukup menggunakan jalur yang sama tanpa pasca-perbaikan, (dalam contoh ini - saya akan mereferensikan sebagai level1/assets/character-textures/ tanpa postfix apa pun).

Membangun Android App Bundle

Gradle

Dalam file build.gradle project Anda, konfigurasikan dependensi agar memiliki versi di bawah ini (atau yang lebih tinggi) untuk plugin Android Gradle dan bundletool:

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

Anda juga harus mengupdate versi Gradle ke 8.0 atau yang lebih baru. Anda dapat mengupdatenya di gradle/wrapper/gradle-wrapper.properties dalam project Anda.

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

Terakhir, Anda harus menggunakan Library Play Asset Delivery jika Anda masih menggunakan Library Play Core monolitik, update library ke versi 1.8.3 atau yang lebih baru. Sebaiknya mulailah beralih ke Library Play Asset Delivery dan update ke versi terbaru jika memungkinkan.

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

Di file build.gradle modul aplikasi utama, aktifkan pembagian penargetan negara:

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

Terakhir, Anda dapat mem-build Android App Bundle (AAB).

Bundletool

Build paket Anda dengan bundletool, dan saat melakukan langkah untuk menyesuaikan AAB, tambahkan kode berikut ke file BundleConfig.pb Anda.

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

Pengujian Lokal

Sebelum melanjutkan, sebaiknya Anda menguji app bundle secara lokal untuk memastikan semuanya telah disiapkan dengan benar. Dengan bundletool (1.14.0 atau yang lebih baru), Anda mem-build dan menguji aplikasi secara lokal, yang secara eksplisit menentukan negara yang benar. Pertama-tama, Anda akan menggunakan build-apks untuk membuat serangkaian file .apks, lalu men-deploy aplikasi ke perangkat terhubung menggunakan install-apks. Anda juga dapat menentukan set negara yang ingin diinstal melalui flag country-set. Anda dapat menemukan informasi metode pengujian lokal ini selengkapnya di sini (perhatikan bahwa halaman ini belum diperbarui untuk penargetan menurut, sehingga flag country-set tidak ada).

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

Atau: Anda juga dapat menggunakan extract-apks untuk mengekstrak serangkaian APK untuk perangkat tertentu. Namun, menggunakan get-device-spec serta menentukan negara untuk perangkat ini tidak akan berhasil jika diiringi dengan flag --local-testing, yang berarti Anda tidak akan dapat menguji paket aset fast-follow atau on-demand.

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

Membuat Konfigurasi Penargetan Perangkat melalui Google Play Developer API

Memulai Google Play Developer API (jika belum selesai)

Untuk mengonfigurasi penargetan menurut negara (yaitu menentukan set negara), Anda harus menggunakan Android Publisher API untuk mengupload konfigurasi ke Google Play. Anda dapat membaca API ini selengkapnya pada link di atas - ada beberapa langkah yang harus Anda ikuti untuk memulai:

Anda dapat menemukan referensi API di sini. Nanti, jika memilih untuk mengupload build melalui API, Anda akan menggunakan metode Edits. Selain itu, sebaiknya tinjau halaman ini sebelum menggunakan API.

Menggunakan Device Targeting Configuration API

Anda dapat menggunakan panggilan API berikut untuk membuat konfigurasi penargetan perangkat:

Membuat Konfigurasi Penargetan Perangkat

Permintaan HTTP	`POST https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
Parameter jalur	T/A
Isi Permintaan	Konfigurasi Penargetan Perangkat
Isi Respons	Konfigurasi Penargetan Perangkat

Objek Konfigurasi Penargetan Perangkat

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

Kolom:

device_confid_id (bilangan bulat): ID yang sesuai dengan konfigurasi penargetan perangkat ini.
user_country_sets (objek): Penentuan set negara
- name (string): Nama set negara (ID string yang Anda tentukan).
- country_codes (string): Negara yang termasuk dalam set negara ini (format: ISO 3166-1 alpha-2).

Anda dapat mengikuti petunjuk di bawah ini untuk memvalidasi Konfigurasi Penargetan Perangkat sebelum menguploadnya ke Google Play.

Mendapatkan Konfigurasi Penargetan Perangkat menurut ID

Anda dapat mengambil konfigurasi penargetan perangkat tertentu menurut ID menggunakan panggilan berikut:

Permintaan HTTP	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs/{deviceTierConfigId}`
Parameter jalur	T/A
Isi Permintaan	T/A
Isi Respons	Konfigurasi Penargetan Perangkat

Mendapatkan daftar Konfigurasi Penargetan Perangkat

Anda bisa mendapatkan 10 konfigurasi penargetan perangkat terakhir dengan panggilan berikut (atau secara optimal menentukan serangkaian sepuluh menggunakan parameter kueri page_token):

Permintaan HTTP	`GET https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/deviceTierConfigs`
Parameter jalur	T/A
Parameter kueri	page_token (opsional) - Digunakan untuk menentukan grup tertentu yang terdiri dari 10 DTC. Ini berguna jika Anda telah membuat lebih dari 10 DTC, dan ingin melihat DTC yang dibuat sebelum 10 terbaru.
Isi Permintaan	T/A
Isi Respons	Daftar Konfigurasi Penargetan Perangkat page_token

Memvalidasi Konfigurasi Penargetan Perangkat

bundletool menyertakan dua perintah yang membantu Anda memvalidasi bahwa Konfigurasi Penargetan Perangkat berfungsi sebagaimana mestinya sebelum menguploadnya ke Play.

Dengan bundletool print-device-targeting-config, Anda dapat memvalidasi bahwa file JSON secara sintaksis benar.

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

Dengan bundletool evaluate-device-targeting-config, Anda dapat mengevaluasi set negara yang akan cocok dengan perangkat tertentu. Anda dapat menyediakan negara melalui flag --country-code.

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

Mengupload Android App Bundle ke Google Play

Melalui API

Anda dapat menggunakan Google Play Developer API untuk mengupload Android App Bundle ke Google Play, dan menautkan konfigurasi Penargetan Perangkat tertentu ke build Anda.

Terdapat ringkasan umum metode Edits di sini, serta contoh yang lebih mendalam tentang merilis ke berbagai jalur di Konsol Google Play (untuk link terakhir, sebaiknya gunakan API yang kompatibel dengan AAB, bukan API yang kompatibel dengan APK, yang tercantum di halaman). Untuk menentukan konfigurasi penargetan perangkat bagi build, Anda akan menambahkan ID konfigurasi ke parameter kueri deviceTierConfigId saat memanggil metode edits.bundle.upload, seperti ini:

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

Melalui Konsol Google Play

Anda dapat mengikuti petunjuk di sini untuk mengupload Android App Bundle. Konfigurasi DTC terbaru akan diterapkan ke App Bundle Anda.

Memverifikasi aset yang benar dikirimkan

Gunakan metode berikut untuk memastikan hanya aset yang benar yang dikirim ke perangkat

adb shell pm path {packageName}

Anda akan melihat yang seperti:

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

Tambahan

Mulai Cepat menggunakan Curl

Berikut adalah contoh (menggunakan curl alat command line) membuat konfigurasi penargetan perangkat baru, dan menggunakan Edits API untuk membuat edit baru, mengupload AAB baru (mengaitkannya dengan konfigurasi penargetan perangkat tertentu), menyetel konfigurasi jalur/rilis, dan melakukan pengeditan. (yang akan menjadikan perubahan tersebut publik). Pastikan Anda memiliki lokasi:

Kunci yang sesuai dengan klien API Anda
Nama paket aplikasi Anda

Pertama, buat konfigurasi penargetan perangkat, dan catat deviceTierConfigId yang akan Anda terima setelah panggilan berhasil.

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

Mulai pengeditan - Anda akan mendapatkan ID dan expiry time pengeditan. Simpan ID untuk panggilan berikut.

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

Upload AAB, dengan menentukan konfigurasi penargetan perangkat sebagai parameter kueri - jika panggilan berhasil, Anda akan melihat kode versi, sha1, dan sha256 build. Simpan kode versi untuk panggilan berikutnya.

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}"

Tetapkan AAB ke jalur yang diinginkan (untuk pengujian, sebaiknya gunakan jalur pengujian internal, tetapi Anda dapat membaca berbagai jalur selengkapnya di sini), di sini kita melakukan peluncuran sederhana tanpa catatan rilis, tetapi Anda dapat membaca halaman ini untuk mempelajari lebih lanjut cara meluncurkan peluncuran bertahap, rilis draf, dan catatan rilis. Jika ini pertama kalinya Anda menggunakan Publisher API, sebaiknya buat ini sebagai rilis draf, dan selesaikan rilis di Konsol Google Play untuk memastikan semuanya telah dikonfigurasi dengan benar.

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}

Commit perubahan (lanjutkan dengan hati-hati, karena tindakan ini akan membuat semua perubahan ditayangkan di Play pada jalur yang diinginkan)

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