Penargetan perangkat untuk modul bersyarat

Apa itu Penargetan Perangkat untuk Modul Bersyarat?

Penargetan Perangkat memungkinkan Anda mengirimkan modul fitur bersyarat ke perangkat berdasarkan hardware-nya. Misalnya, Anda dapat memilih untuk hanya mengirim fitur tertentu ke perangkat kelas atas dan tidak mengirimkannya ke perangkat yang tidak dapat menggunakan fitur ini (misalnya menghemat ruang di perangkat ini). Cara ini dibuat berdasarkan konsep modul fitur di Play Feature Delivery. Seperti yang akan Anda lihat di bawah, Anda memiliki kemampuan untuk menentukan kriteria penargetan (untuk saat ini berdasarkan RAM, model perangkat tertentu, atau fitur sistem yang tersedia), dan menargetkan modul ke grup perangkat tertentu.

Perjalanan Developer

Pada level tinggi, untuk mengintegrasikan penargetan perangkat ke dalam aplikasi yang ada, Anda perlu melakukan langkah-langkah berikut:

  1. Kembangkan fitur yang ingin dikirimkan hanya ke serangkaian perangkat berdasarkan hardware-nya.
    • Terapkan fitur ini sebagai modul fitur.
    • Tentukan di bagian syarat modul AndroidManifest.xml ke grup perangkat mana tujuan pengirimannya.
  2. Buat konfigurasi Penargetan Perangkat, sehingga Play tahu cara mengirimkan modul fitur Anda ke perangkat pengguna
    • Siapkan Google Play Developer API (jika belum selesai), yang akan Anda gunakan untuk mengirim konfigurasi DT ke Play
    • Ikuti langkah-langkah untuk membuat konfigurasi DT
  3. Upload AAB Anda ke Play, lalu uji untuk memastikan semuanya dikonfigurasi dengan benar

Dokumen ini menjelaskan cara menambahkan Penargetan Perangkat untuk pengiriman bersyarat menggunakan Plugin Android Gradle.

Membuat modul fitur bersyarat dengan Penargetan Perangkat

Menambahkan modul fitur ke dalam aplikasi

Play Feature Delivery memungkinkan Anda mengirimkan fitur tertentu secara bersyarat atau didownload secara on demand. Anda dapat membaca ringkasannya di sini. Dengan Penargetan Perangkat, Anda dapat mengirimkan fitur secara bersyarat ke perangkat yang ditetapkan ke grup yang disediakan.

Untuk menggunakan DT pada pengiriman bersyarat, Anda harus menggunakan bundletool versi 1.7.0 dan yang lebih baru. Untuk itu, Anda harus menentukan versi bundletool secara eksplisit untuk Plugin Android Gradle. Ini dapat dilakukan di bagian buildscript file build.gradle root:

buildscript {
  dependencies {
    classpath "com.android.tools.build:bundletool:1.7.0"
    ...
  }
  ...
}

Untuk membuat modul fitur, gunakan petunjuk ini untuk memodularisasi aplikasi Android.

Setelah pengembangan fitur selesai, Anda dapat menentukan syarat pengiriman berdasarkan Penargetan Perangkat di AndroidManifest.xml fitur. Anda perlu menyediakan syarat grup perangkat di dalam dist:conditions dari elemen dist:module. Informasi umum tentang syarat tersedia di sini. Untuk grup perangkat, syarat baru tersedia di mana Anda dapat menentukan semua grup yang harus dikirimkan oleh fitur ini:

<dist:device-groups>
  <dist:device-group dist:name="..." />
  <dist:device-group dist:name="..." />
  ...
</dist:device-groups>

Sebagai contoh, misalnya Anda telah menentukan grup perangkat yang bernama _my_group1 (Anda akan mempelajari cara menentukannya di bagian Membuat Konfigurasi Penargetan Perangkat di bawah). Jika modul fitur hanya boleh dikirimkan ke perangkat yang berada dalam cakupan perangkat _my_group1, AndroidManifest.xml akan terlihat seperti berikut:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

Untuk fitur yang menargetkan _my_group1 dan _my_group2, AndroidManifest.xml akan terlihat seperti berikut:

<manifest ...>
  ...
  <dist:module dist:title="...">
    <dist:delivery>
      <dist:install-time>
        <dist:conditions>
          <dist:device-groups>
            <dist:device-group dist:name="my_group_1"/>
            <dist:device-group dist:name="my_group_2"/>
          </dist:device-groups>
          ...
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
  </dist:module>
  ...
</manifest>

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

Pengujian Lokal

Sebelum melanjutkan, sebaiknya Anda menguji app bundle secara lokal untuk memastikan semuanya telah disiapkan dengan benar. Dengan bundletool, Anda mem-build dan menguji aplikasi secara lokal, yang secara eksplisit menentukan grup perangkat yang benar. Pertama-tama, Anda akan menggunakan build-apks untuk membuat serangkaian file .apk, lalu men-deploy aplikasi ke perangkat yang terhubung menggunakan install-apks. Anda juga dapat menentukan grup mana yang ingin diinstal melalui tanda device-groups. Anda dapat menemukan informasi metode pengujian lokal ini selengkapnya di sini. Perhatikan bahwa halaman ini belum diperbarui untuk DT sehingga flag device-groups tidak ada.

bundletool build-apks --bundle=/path/to/app.aab --output=/path/to/app.apks --local-testingbundletool install-apks --apks=/path/to/app.apks --device-groups=my_group_1,my_group_2

Atau: Anda juga dapat menggunakan extract-apks untuk mengekstrak serangkaian APK untuk perangkat tertentu (menggunakan get-device-spec serta menentukan grup perangkat untuk perangkat ini).

bundletool get-device-spec --output=/path/to/device-spec.json --device-groups=my_group_1,my_group_2bundletool 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 Perangkat (menentukan grup perangkat), Anda harus menggunakan Android Publisher API untuk mengupload konfigurasi ke Google Play. Anda dapat membaca tentang API ini selengkapnya pada link di atas - ada beberapa langkah yang harus Anda ikuti untuk memulai:

  1. Buat (jika diperlukan) dan tautkan project API Anda ke Konsol Google Play
  2. Siapkan Klien Akses API

Anda dapat menemukan referensi API di sini. Nantinya, 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
{
  device_groups: [
    {
      name: string,
      device_selectors: [
        {
          device_ram : {
            min_bytes: integer
            max_bytes: integer
          },
          included_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          excluded_device_ids: [
            {
              build_brand: string,
              build_device: string
            }
          ],
          required_system_features: [
            {
              name: string
            }
          ],
          forbidden_system_features: [
            {
              name: string
            }
          ]
        }
      ]
    }
  ]
}

Kolom:

  • device_tier_config_id (bilangan bulat): ID yang berkaitan dengan konfigurasi penargetan perangkat ini

  • device_groups (objek): Penentuan grup

    • name (string): Nama grup perangkat (ID string yang Anda tentukan)
    • device_selectors (objek): Persyaratan perangkat untuk perangkat yang termasuk dalam grup ini.
    • device_ram (objek): Persyaratan RAM perangkat
      • min_bytes (bilangan bulat): RAM minimum yang diperlukan (dalam byte)
      • max_bytes (bilangan bulat): RAM maksimum yang diperlukan (dalam byte)
    • included_device_ids (objek): Model perangkat yang akan disertakan dalam pemilih ini (maks. 10.000 device_ids per grup). Perangkat harus ada dalam daftar ini agar cocok dengan pemilih. Syarat untuk mencocokkan pemilih penuh ini diperlukan, tetapi tidak memadai (lihat catatan di bawah tentang menggabungkan persyaratan dalam pemilih).
      • build_brand (string): Produsen perangkat
      • build_device (string): Kode model perangkat
    • excluded_device_ids (objek): Model perangkat untuk dikecualikan dalam pemilih ini (maks. 10.000 device_id per grup). Perangkat dari daftar ini tidak akan cocok dengan pemilih meskipun cocok dengan semua persyaratan lain dalam pemilih.
      • build_brand (string): Produsen perangkat
      • build_device (string): Kode model perangkat

    • required_system_features (objek): Fitur yang diperlukan perangkat agar disertakan oleh pemilih ini (maks. 100 fitur per grup). Perangkat harus memiliki semua fitur sistem dalam daftar ini agar cocok dengan pemilih. Syarat untuk mencocokkan pemilih penuh ini diperlukan, tetapi tidak memadai (lihat catatan di bawah tentang menggabungkan persyaratan dalam pemilih).

      Referensi fitur sistem

      • name (string): Fitur sistem

    • forbidden_system_features (objek): Fitur yang mana perangkat tidak boleh disertakan oleh pemilih ini (maks. 100 fitur per grup). Jika perangkat memiliki salah satu fitur sistem dalam daftar ini, perangkat tidak akan cocok dengan pemilih, meskipun cocok dengan semua persyaratan lain dalam pemilih.

      Referensi fitur sistem

      • name (string): Fitur sistem

Anda dapat menemukan pemformatan yang benar untuk produsen dan kode model perangkat menggunakan Katalog Perangkat di Konsol Google Play, dengan salah satu dari opsi berikut:

  • Memeriksa setiap perangkat menggunakan Katalog Perangkat, dan menemukan produsen dan kode model di lokasi seperti yang ditunjukkan pada contoh di bawah ini (Untuk Google Pixel 4a, produsennya adalah “Google” dan kode modelnya adalah “sunfish”)'

    halaman pixel 4a di katalog perangkat

    halaman pixel 4a di katalog perangkat

  • Mendownload CSV perangkat yang didukung, dan menggunakan Produsen dan Kode Model untuk masing-masing kolom build_brand dan build_device.

Misalnya, grup berikut cocok dengan semua perangkat yang memiliki RAM lebih dari 4 GB, kecuali Pixel 5 (google redfin) dan termasuk Pixel 3 (Google Blueline, yang memiliki RAM kurang dari 4 GB).

device_groups: [
  {
    name: "my_group_1",
    device_selectors: [
      {
        device_ram: {
          min_bytes: 4294967296
        },
        excluded_device_ids: [
          {
            build_brand: "google",
            build_device: "redfin"
          }
        ]
      },
      {
        included_device_ids: [
          {
            build_brand: "google",
            build_device: "blueline"
          }
        ]
      }
    ]
  }
]

Anda dapat membacanya sebagai:

[ (RAM > 4GB) AND NOT (google redfin) ] OR [ (google blueline) ]

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 GEThttps://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 GEThttps://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 dan memvisualisasikan grup perangkat dalam format yang lebih mudah dibaca.

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

Dengan bundletool evaluate-device-targeting-config, Anda dapat mengevaluasi grup yang akan cocok dengan perangkat tertentu. Anda dapat menghubungkan perangkat target ke workstation dan menggunakan tanda --connected-device; atau mengompilasi file JSON dengan properti perangkat secara manual dan memberikannya melalui tanda --device-properties.

bundletool evaluate-device-targeting-config --config=mydtc.json --connected-device
bundletool evaluate-device-targeting-config --config=mydtc.json --device-properties=deviceproperties.json

File properti perangkat harus berupa file JSON yang mengikuti struktur protobuf DeviceProperties. Contoh:

{
  "ram": 2057072640,
  "device_id": {
    "build_brand":"google",
    "build_device":"redfin"
  },
  "system_features": [
    {
      "name":"android.hardware.bluetooth"
    },
    {
      "name":"android.hardware.camera"
    }
  ]
}

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). Guna menentukan konfigurasi penargetan perangkat untuk build, Anda akan menambahkan ID konfigurasi ke parameter kueri deviceTierConfigId saat memanggil 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.

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 (sehingga membuat perubahan tersebut bersifat 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 "{ device_groups: [ { name: "my_group_1", device_selectors: [ { device_ram: { min_bytes: 4294967296 }, excluded_device_ids: [ { build_brand: "google", build_device: "redfin" } ] }, { included_device_ids: [ { build_brand: "google", build_device: "blueline" } ] } ] } ] }" 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, yang menentukan konfigurasi penargetan perangkat (deviceTierConfigId) 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="{deviceTierConfigId}

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}', versionCodes: ['{versionCode}'] }]}" https://androidpublisher.googleapis.com/androidpublisher/v3/applications/{packageName}/edits/{editID}/tracks/{track}

Lakukan 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