Mengonfigurasi pengiriman bersyarat

Pengiriman bersyarat memungkinkan Anda menetapkan persyaratan konfigurasi perangkat tertentu agar modul fitur otomatis didownload selama penginstalan aplikasi. Misalnya, Anda dapat mengonfigurasi agar modul fitur yang mencakup fungsi augmented reality (AR) disediakan saat menginstal aplikasi di perangkat yang mendukung AR saja.

Mekanisme pengiriman ini saat ini mendukung pengontrolan download modul selama proses penginstalan aplikasi berdasarkan konfigurasi perangkat berikut:

Jika perangkat tidak memenuhi semua persyaratan yang Anda tentukan, modul tidak akan didownload pada saat penginstalan aplikasi. Namun, di lain waktu, aplikasi Anda dapat meminta untuk mendownload modul secara on demand menggunakan Play Core SDK.

Sebelum memulai, pastikan Anda menggunakan Android Studio 3.5 atau yang lebih tinggi. Bagian berikut menunjukkan cara menambahkan dukungan untuk pengiriman bersyarat ke modul fitur.

Menambahkan modul baru dengan opsi pengiriman bersyarat

Cara termudah untuk membuat modul fitur baru dengan pengiriman bersyarat adalah melalui wizard New Module, sebagai berikut:

  1. Untuk membuka dialog New Module, pilih File > New > New Module dari panel menu.
  2. Pada dialog New Module, pilih Dynamic Feature Module, lalu klik Next.
  3. Konfigurasi modul Anda seperti biasa, lalu klik Next.

  4. Pada bagian Module Download Options, lakukan langkah-langkah berikut:

    1. Tentukan Module title menggunakan maksimal 50 karakter. Platform tersebut menggunakan judul ini untuk mengidentifikasi modul kepada pengguna saat, misalnya, mengonfirmasi apakah pengguna ingin mendownload modul atau tidak. Karena alasan ini, modul dasar aplikasi Anda harus menyertakan judul modul sebagai resource string, yang dapat Anda terjemahkan. Saat membuat modul menggunakan Android Studio, IDE akan menambahkan resource string ke modul dasar dan memasukkan entri berikut dalam manifes modul fitur:

      <dist:module
    ...
    dist:title="@string/feature_title">
</dist:module>

    2. Pada menu dropdown di bagian Install-time inclusion, pilih Only include module at app install for devices with specified features, yang akan membuat modul yang disertakan bersama aplikasi Anda pada saat penginstalan aplikasi, hanya pada perangkat dengan konfigurasi tertentu yang dapat Anda tentukan, seperti fitur perangkat atau negara. Android Studio memasukkan kode berikut ke dalam manifes modul untuk merefleksikan pilihan Anda:

      <dist:module ... >
  <dist:delivery>
      <dist:install-time>
          <dist:conditions>
              <!-- If you specify conditions, as described in the steps
                   below, the IDE includes them here. -->
          </dist:conditions>
      </dist:install-time>
  </dist:delivery>
</dist:module>

    3. Jika Anda ingin membatasi download otomatis modul ke negara tertentu atau level API minimum, klik Finish untuk menyelesaikan pembuatan modul, lalu baca bagian tentang cara menentukan syarat berdasarkan negara atau level API minimum. Jika tidak, klik + device feature untuk menambahkan fitur yang diperlukan perangkat untuk mendownload modul pada saat penginstalan.

    4. Di samping device-feature, pilih salah satu opsi berikut dari menu dropdown dan tentukan nilainya:

      • Name: Memungkinkan Anda menentukan fitur hardware atau software yang diperlukan perangkat untuk mendownload modul pada saat penginstalan. Fitur yang didukung pengiriman bersyarat sama dengan fitur yang tercantum sebagai konstanta FEATURE_* oleh PackageManager. Jika Anda memilih opsi ini, mulai ketikkan bagian mana pun dari nilai konstanta fitur, misalnya "bluetooth", pada kolom di samping dropdown, lalu pilih salah satu saran yang ditampilkan.
      • OpenGL ES Version: Memungkinkan Anda menentukan versi OpenGL ES yang diperlukan perangkat untuk mendownload modul pada saat penginstalan. Jika Anda memilih opsi ini, mulai ketikkan nomor versinya, misalnya "0x00030001", pada kolom di samping menu dropdown, lalu pilih salah satu saran yang ditampilkan.

    5. Jika Anda ingin menambahkan beberapa syarat berdasarkan fitur perangkat yang tersedia, klik + device feature untuk setiap syarat fitur perangkat yang ingin Anda tentukan.

    6. Centang kotak di sebelah Fusing jika Anda ingin modul ini tersedia untuk perangkat yang menjalankan Android 4.4 (level API 20) atau yang lebih rendah dan termasuk dalam multi-APK. Artinya, Anda dapat mengaktifkan perilaku on demand untuk modul ini dan menonaktifkan penggabungan untuk menghilangkannya dari perangkat yang tidak mendukung download dan penginstalan APK terpisah. Android Studio memasukkan kode berikut ke dalam manifes modul untuk merefleksikan pilihan Anda:

      <dist:module ...>
    <dist:fusing dist:include="true | false" />
</dist:module>

  5. Setelah selesai mengonfigurasi opsi download modul, klik Finish.

Perhatikan bahwa plugin Android Gradle tidak mendukung lint yang berjalan dari modul fitur dinamis. Menjalankan lint dari modul aplikasi yang sesuai akan menjalankan lint pada modul fitur dinamisnya dan menyertakan semua masalah dalam laporan lint aplikasi.

Menambahkan opsi pengiriman bersyarat ke modul fitur yang sudah ada

Anda dapat dengan mudah menambahkan opsi pengiriman bersyarat ke modul fitur yang sudah ada melalui manifes modul. Namun, Anda harus terlebih dahulu mempelajari kompatibilitas opsi pengiriman bersyarat dengan opsi pengiriman lain yang mungkin telah Anda aktifkan.

Untuk memulai, Anda harus memigrasikan manifes ke elemen <dist:delivery> baru. Cuplikan kode di bawah ini menunjukkan contoh sintaksis lama:

<!-- This is the old syntax. -->
<dist:module
  dist:title="@string/feature_title" dist:onDemand="true">
  <dist:fusing dist:include="true"/>
</dist:module>

Opsi pengiriman di atas sekarang ditetapkan sebagai berikut.

<dist:module
  dist:title="@string/feature_title">
  <dist:delivery>
      <dist:on-demand/>
  </dist:delivery>
  <dist:fusing dist:include="true"/>
</dist:module>

Selanjutnya, Anda dapat menyertakan opsi pengiriman bersyarat berdasarkan fitur perangkat, sebagai berikut.

<dist:module
    dist:title="@string/feature_title">
    <dist:delivery>
      <dist:on-demand/>
      <dist:install-time>
        <dist:conditions>
          <!-- Requires that the device support AR to download the module at
          app install-time.  -->
          <dist:device-feature dist:name="android.hardware.camera.ar"/>
        </dist:conditions>
      </dist:install-time>
    </dist:delivery>
    <dist:fusing dist:include="true"/>
</dist:module>

Bagian di bawah ini membahas opsi lain untuk pengiriman bersyarat, misalnya berdasarkan negara atau level API minimum.

Kompatibilitas dengan opsi download modul lainnya

Karena modul fitur menawarkan banyak opsi untuk mengonfigurasi cara setiap fitur dikirimkan ke perangkat pengguna, Anda perlu memahami bagaimana opsi pengiriman bersyarat dipengaruhi oleh setelan lainnya. Tabel berikut merangkum kompatibilitas pengiriman bersyarat dengan opsi download modul lainnya.

Opsi download modul Kompatibilitas dengan pengiriman bersyarat
Fusing (<dist:fusing dist:include="true"/>) Jika modul menyetel opsi ini ke benar (true), Google Play tidak mematuhi opsi pengiriman bersyarat yang Anda tetapkan saat men-deploy aplikasi ke perangkat yang menjalankan level API 19 atau yang lebih rendah. Artinya, modul fitur yang memungkinkan penggabungan selalu disertakan pada saat penginstalan untuk perangkat yang menjalankan level API 19 atau lebih rendah.
Diaktifkan secara instan (<dist:module dist:instant="true"/>) Opsi pengiriman bersyarat tidak didukung untuk modul fitur yang mendukung akses instan.
On demand (<dist:on-demand/>) Secara default, jika Anda menentukan opsi pengiriman bersyarat, modul tersebut juga tersedia on demand.

Menentukan syarat berdasarkan negara

Pengiriman bersyarat juga memungkinkan Anda menentukan negara mana yang ingin Anda kecualikan (atau sertakan) ketika mendownload modul pada saat penginstalan aplikasi. Penentuan syarat ini dapat berguna ketika, misalnya, modul Anda mengimplementasikan metode pembayaran yang tidak tersedia di wilayah tertentu.

Dalam konteks ini, negara perangkat biasanya ditentukan oleh alamat penagihan pengguna yang terdaftar di akun Google Play.

Jika ingin menentukan negara untuk modul Anda, sertakan hal berikut dalam manifes modul fitur.

<dist:conditions>
   <!-- Set to "true" to specify countries to exclude from downloading
   this module at app install-time. By default, modules are available
   for download to all user countries. -->
  <dist:user-countries dist:exclude="true">
    <!-- Specifies the two-letter  CLDR country code for regions that should
    not download the module at app install-time. -->
    <dist:country dist:code="CN"/>
    <dist:country dist:code="HK"/>
  </dist:user-countries>
</dist:conditions>

Menentukan syarat untuk level API

Penentuan syarat berdasarkan level API pada perangkat dapat berguna jika modul fitur bergantung pada API yang hanya tersedia dalam versi platform Android tertentu.

Untuk menetapkan syarat berdasarkan level API minimum atau maksimum, sertakan baris berikut dalam manifes modul fitur Anda.

<dist:conditions>
    <!-- Specifies the minimum API level that the device must satisfy
         in order to download your module at app install-time. The API level you
         specify must be greater or equal to the module's own minSdkVersion. -->
   <dist:min-sdk dist:value="21"/>
    <!-- Specifies the maximum API level that the device cannot exceed
         in order to download your module at app install-time. The API level you
         specify must be less than or equal to the module's own maxSdkVersion. -->
   <dist:max-sdk dist:value="24"/>
</dist:conditions>