Membuat kartu Setelan Cepat kustom untuk aplikasi Anda

Setelan Cepat adalah kartu yang ditampilkan di panel Setelan Cepat, yang mewakili tindakan, yang dapat diketuk pengguna untuk menyelesaikan tugas berulang dengan cepat. Aplikasi Anda dapat menyediakan kartu kustom kepada pengguna melalui class TileService, dan menggunakan objek Tile untuk melacak status kartu. Misalnya, Anda dapat membuat kartu yang memungkinkan pengguna mengaktifkan atau menonaktifkan VPN yang disediakan oleh aplikasi Anda.

Gambar 1. Panel Setelan Cepat dengan kartu VPN diaktifkan dan dinonaktifkan.

Catatan: Panduan ini hanya membahas kartu non-Wear: Kartu Setelan Cepat tidak memiliki hubungan dengan kartu yang ditentukan dalam Wear OS. Untuk kartu Wear OS, lihat Panduan Kartu WearOS.

Memutuskan kapan harus membuat kartu

Sebaiknya buat kartu untuk fungsi tertentu yang Anda harapkan sering diakses atau memerlukan akses cepat (atau keduanya) oleh pengguna. Kartu yang paling efektif adalah kartu yang sesuai dengan kedua kualitas ini, yang memberikan akses cepat ke tindakan yang sering dilakukan.

Misalnya, Anda dapat membuat kartu untuk aplikasi kebugaran yang memungkinkan pengguna memulai sesi olahraga dengan cepat. Namun, kami tidak merekomendasikan pembuatan kartu untuk aplikasi yang sama yang memungkinkan pengguna meninjau seluruh histori latihan mereka.

Gambar 2. Contoh kartu yang direkomendasikan versus yang tidak direkomendasikan untuk aplikasi kebugaran.

Untuk membantu meningkatkan visibilitas dan kemudahan penggunaan kartu, sebaiknya hindari praktik tertentu:

• Hindari penggunaan kartu untuk meluncurkan aplikasi. Sebagai gantinya, gunakan pintasan aplikasi atau peluncur standar.

• Hindari penggunaan kartu untuk tindakan pengguna satu kali. Gunakan pintasan aplikasi atau notifikasi sebagai gantinya.

• Hindari membuat terlalu banyak kartu. Sebaiknya gunakan maksimum dua per aplikasi. Gunakan pintasan aplikasi.

• Hindari penggunaan kartu yang menampilkan informasi, tetapi tidak interaktif bagi pengguna. Gunakan notifikasi atau widget sebagai gantinya.

Membuat kartu

Untuk membuat kartu, Anda harus membuat ikon kartu yang sesuai terlebih dahulu, lalu membuat dan mendeklarasikan TileService di file manifes aplikasi.

Catatan: Membuat TileService untuk aplikasi Anda tidak akan menambahkannya ke panel Setelan Cepat pengguna. TileService Anda bertindak sebagai antarmuka dengan kartu hanya setelah pengguna menambahkannya.

Contoh Setelan Cepat memberikan contoh cara membuat dan mengelola kartu.

Membuat ikon kustom

Anda harus menyediakan ikon kustom, yang ditampilkan di kartu di panel Setelan Cepat. (Anda akan menambahkan ikon ini saat mendeklarasikan TileService, yang dijelaskan di bagian berikutnya.) Ikon harus berwarna putih solid dengan latar belakang transparan, berukuran 24 x 24 dp, dan dalam bentuk VectorDrawable.

Gambar 3. Contoh vektor drawable.

Buat ikon yang secara visual mengisyaratkan tujuan kartu Anda. Hal ini membantu pengguna mengidentifikasi apakah kartu Anda sesuai dengan kebutuhan mereka. Misalnya, Anda dapat membuat ikon stopwatch untuk kartu aplikasi kebugaran yang memungkinkan pengguna memulai sesi olahraga.

Membuat dan mendeklarasikan TileService

Buat layanan untuk kartu Anda yang memperluas class TileService.

class MyQSTileService : TileService() {

    // Called when the user adds your tile.
    override fun onTileAdded() {
        super.onTileAdded()
    }
    // Called when your app can update your tile.
    override fun onStartListening() {
        super.onStartListening()
    }

    // Called when your app can no longer update your tile.
    override fun onStopListening() {
        super.onStopListening()
    }

    // Called when the user taps on your tile in an active or inactive state.
    override fun onClick() {
        super.onClick()
    }
    // Called when the user removes your tile.
    override fun onTileRemoved() {
        super.onTileRemoved()
    }
}
QuickSettingsTilesSnippets.kt

Deklarasikan TileService di file manifes aplikasi Anda. Tambahkan nama dan label TileService Anda (hingga 18 karakter untuk android:label), ikon kustom yang Anda buat di bagian sebelumnya, dan izin yang sesuai.

 <!-- 18-character limit for android:label. -->
 <service
     android:name=".MyQSTileService"
     android:exported="true"
     android:label="@string/my_default_tile_label"
     android:icon="@drawable/my_default_icon_label"
     android:permission="android.permission.BIND_QUICK_SETTINGS_TILE">
     <intent-filter>
         <action android:name="android.service.quicksettings.action.QS_TILE" />
     </intent-filter>
 </service>

Mengelola TileService

Setelah membuat dan mendeklarasikan TileService dalam manifes aplikasi, Anda harus mengelola statusnya.

TileService adalah layanan terikat. TileService Anda terikat saat diminta oleh aplikasi atau jika sistem perlu berkomunikasi dengannya. Siklus proses layanan terikat biasanya berisi empat metode callback berikut: onCreate(), onBind(), onUnbind(), dan onDestroy(). Metode ini dipanggil oleh sistem setiap kali layanan memasuki fase siklus proses baru.

Penting: TileService Anda akan tetap melalui siklus proses Service yang biasa. Namun, TileService berbeda dari sebagian besar layanan terikat lainnya karena berisi metode siklus proses yang spesifik untuk TileService yang harus direspons oleh aplikasi Anda.

Ringkasan siklus proses TileService

Selain callback yang mengontrol siklus proses layanan terikat, Anda harus mengimplementasikan metode lain yang spesifik untuk siklus proses TileService. Metode ini dapat dipanggil di luar onCreate() dan onDestroy() karena metode siklus proses Service dan metode siklus proses TileService dipanggil dalam dua thread asinkron terpisah.

Siklus proses TileService berisi metode berikut, yang dipanggil oleh sistem setiap kali TileService Anda memasuki fase siklus proses baru:

• onTileAdded(): Metode ini hanya dipanggil saat pengguna menambahkan kartu Anda untuk pertama kalinya, dan jika pengguna menghapus dan menambahkan kartu Anda lagi. Ini adalah waktu terbaik untuk melakukan inisialisasi satu kali. Namun, hal ini mungkin tidak memenuhi semua inisialisasi yang diperlukan.

  Catatan: onTileAdded() tidak dipanggil setiap kali kartu dibuat. Misalnya, onTileAdded() tidak dipanggil saat perangkat dimulai ulang atau dinyalakan jika kartu telah ditambahkan dan tidak dihapus sebelum perangkat dimatikan.

• onStartListening() dan onStopListening(): Metode ini dipanggil setiap kali aplikasi Anda mengupdate kartu, dan sering dipanggil. TileService tetap terikat antara onStartListening() dan onStopListening(), sehingga aplikasi Anda dapat mengubah kartu dan mengirim update.

• onTileRemoved(): Metode ini hanya dipanggil jika pengguna menghapus kartu Anda.

Perhatian: Fase ini mungkin tidak terjadi secara berurutan. onTileAdded() hanya dapat dipanggil sekali saat kartu Anda ditambahkan oleh pengguna ke panel Setelan Cepat. onStartListening() dan onStopListening() dapat dipanggil beberapa kali selama siklus proses TileService. onTileRemoved() tidak akan pernah dipanggil jika pengguna tidak menghapus kartu Anda dari panel Setelan Cepat.

Pilih mode mendengarkan

TileService Anda memproses dalam mode aktif atau mode nonaktif. Sebaiknya gunakan mode aktif, yang harus Anda deklarasikan dalam manifes aplikasi. Jika tidak, TileService adalah mode standar dan tidak perlu dideklarasikan.

Jangan berasumsi bahwa TileService Anda akan aktif di luar pasangan metode onStartListening() dan onStopListening().

Mode aktif (direkomendasikan)

Gunakan mode aktif untuk TileService yang memproses dan memantau statusnya dalam prosesnya sendiri. TileService dalam mode aktif terikat untuk onTileAdded(), onTileRemoved(), peristiwa ketuk, dan saat diminta oleh proses aplikasi.

Sebaiknya gunakan mode aktif jika TileService Anda diberi tahu saat status kartu harus diupdate oleh prosesnya sendiri. Ubin aktif membatasi beban pada sistem karena tidak harus terikat setiap kali panel Setelan Cepat terlihat oleh pengguna.

Metode TileService.requestListeningState() statis dapat dipanggil untuk meminta memulai status pemrosesan dan menerima callback ke onStartListening().

Anda dapat mendeklarasikan mode aktif dengan menambahkan META_DATA_ACTIVE_TILE ke file manifes aplikasi.

<service ...>
    <meta-data android:name="android.service.quicksettings.ACTIVE_TILE"
       android:value="true" />
    ...
</service>

Mode nonaktif

Mode non-aktif adalah mode standar. TileService berada dalam mode non-aktif jika terikat setiap kali kartu Anda terlihat oleh pengguna. Artinya, TileService Anda dapat dibuat dan diikat lagi pada waktu di luar kendalinya. Tata letak ini juga dapat dilepaskan dan dihancurkan saat pengguna tidak melihat kartu.

Aplikasi Anda menerima callback ke onStartListening() setelah pengguna membuka panel Setelan Cepat. Anda dapat memperbarui objek Tile sebanyak yang Anda inginkan antara onStartListening() dan onStopListening().

Perhatian: Jika Anda menggunakan mode non-aktif, bukan mode aktif, TileService Anda mungkin terikat setiap kali pengguna membuka panel Setelan Cepat.

Anda tidak perlu mendeklarasikan mode non-aktif: jangan tambahkan META_DATA_ACTIVE_TILE ke file manifes aplikasi Anda.

Ringkasan status kartu

Setelah pengguna menambahkan kartu Anda, kartu tersebut akan selalu ada dalam salah satu status berikut.

• STATE_ACTIVE: Menunjukkan status aktif atau diaktifkan. Pengguna dapat berinteraksi dengan kartu Anda saat dalam status ini.

  Misalnya, untuk kartu aplikasi kebugaran yang memungkinkan pengguna memulai sesi olahraga berwaktu, STATE_ACTIVE berarti pengguna telah memulai sesi olahraga dan timer sedang berjalan.

• STATE_INACTIVE: Menunjukkan status nonaktif atau dijeda. Pengguna dapat berinteraksi dengan kartu Anda saat dalam status ini.

  Untuk menggunakan contoh kartu aplikasi kebugaran lagi, kartu di STATE_INACTIVE berarti pengguna belum memulai sesi olahraga, tetapi dapat melakukannya jika mereka mau.

• STATE_UNAVAILABLE: Menunjukkan status tidak tersedia untuk sementara. Pengguna tidak dapat berinteraksi dengan kartu Anda saat dalam status ini.

  Misalnya, kartu di STATE_UNAVAILABLE berarti kartu tersebut saat ini tidak tersedia untuk pengguna karena alasan tertentu.

  Perhatian: Gunakan STATE_UNAVAILABLE untuk kartu yang saat ini tidak tersedia, tetapi dapat diubah menjadi tersedia nanti. Jika komponen tidak akan pernah tersedia lagi untuk pengguna, teruskan COMPONENT_ENABLED_STATE_DISABLED ke setComponentEnabledSetting().

Sistem hanya menetapkan status awal objek Tile Anda. Anda menetapkan status objek Tile selama sisa siklus prosesnya.

Sistem dapat memberi tint pada ikon dan latar belakang kartu untuk mencerminkan status objek Tile Anda. Objek Tile yang ditetapkan ke STATE_ACTIVE adalah yang paling gelap, dengan STATE_INACTIVE dan STATE_UNAVAILABLE yang semakin terang. Nuansa warna yang tepat bergantung pada produsen dan versi.

Gambar 4. Contoh kartu yang diwarnai untuk mencerminkan status kartu (masing-masing status aktif, tidak aktif, dan tidak tersedia).

Memperbarui kartu

Anda dapat memperbarui kartu setelah menerima callback ke onStartListening(). Bergantung pada mode kartu, kartu Anda dapat diperbarui setidaknya sekali hingga menerima callback ke onStopListening().

Dalam mode aktif, Anda dapat memperbarui kartu tepat satu kali sebelum menerima callback ke onStopListening(). Dalam mode non-aktif, Anda dapat memperbarui kartu sebanyak yang Anda inginkan antara onStartListening() dan onStopListening().

Catatan: Mode aktif memungkinkan Anda mengupdate kartu, terlepas dari apakah kartu terlihat oleh pengguna atau tidak.

Anda dapat mengambil objek Tile dengan memanggil getQsTile(). Untuk memperbarui kolom tertentu pada objek Tile, panggil metode berikut:

• setContentDescription()
• setIcon()
• setLabel()
• setState()
• setStateDescription()
• setSubtitle()

Catatan: Ikon dan label yang ditetapkan dalam file manifes aplikasi Anda adalah nilai default yang ditampilkan pada kartu di panel Setelan Cepat. Namun, Anda dapat memanggil metode setIcon() dan setLabel() saat memperbarui kartu untuk menetapkan kolom ke nilai baru.

Anda harus memanggil updateTile() untuk memperbarui kartu setelah selesai menetapkan kolom objek Tile ke nilai yang benar. Tindakan ini akan membuat sistem mengurai data kartu yang diperbarui dan memperbarui UI.

data class StateModel(val enabled: Boolean, val label: String, val icon: Icon)

override fun onStartListening() {
    super.onStartListening()
    val state = getStateFromService()
    qsTile.label = state.label
    qsTile.contentDescription = state.label
    qsTile.state = if (state.enabled) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.icon = state.icon
    qsTile.updateTile()
}
QuickSettingsTilesSnippets.kt

Menangani ketukan

Pengguna dapat mengetuk kartu Anda untuk memicu tindakan jika kartu Anda berada di STATE_ACTIVE atau STATE_INACTIVE. Sistem kemudian akan memanggil callback onClick() aplikasi Anda.

Setelah menerima callback ke onClick(), aplikasi Anda dapat meluncurkan dialog atau aktivitas, memicu pekerjaan latar belakang, atau mengubah status kartu.

var counter = 0
override fun onClick() {
    super.onClick()
    counter++
    qsTile.state = if (counter % 2 == 0) Tile.STATE_ACTIVE else Tile.STATE_INACTIVE
    qsTile.label = "Clicked $counter times"
    qsTile.contentDescription = qsTile.label
    qsTile.updateTile()
}
QuickSettingsTilesSnippets.kt

Meluncurkan dialog

showDialog() menciutkan panel Setelan Cepat dan menampilkan dialog. Gunakan dialog untuk menambahkan konteks ke tindakan Anda jika memerlukan input tambahan atau izin pengguna.

Catatan: isLocked() memeriksa apakah layar kunci pengguna ditampilkan. Jika isLocked() menampilkan nilai benar (true), showDialog() tidak akan menampilkan dialog yang terlihat karena dimuat di bawah layar kunci.

Meluncurkan aktivitas

startActivityAndCollapse() memulai aktivitas sambil menciutkan panel. Aktivitas berguna jika ada informasi yang lebih mendetail untuk ditampilkan daripada dalam dialog, atau jika tindakan Anda sangat interaktif.

Jika aplikasi Anda memerlukan interaksi pengguna yang signifikan, aplikasi hanya boleh meluncurkan aktivitas sebagai upaya terakhir. Sebagai gantinya, pertimbangkan untuk menggunakan dialog atau tombol.

Mengetuk lama kartu akan menampilkan layar Info Aplikasi untuk pengguna. Untuk mengganti perilaku ini dan meluncurkan aktivitas untuk menyetel preferensi, tambahkan <intent-filter> ke salah satu aktivitas Anda dengan ACTION_QS_TILE_PREFERENCES.

Mulai Android API 28, PendingIntent harus memiliki Intent.FLAG_ACTIVITY_NEW_TASK:

if (Build.VERSION.SDK_INT >= 28) {
    intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK)
}
QuickSettingsTilesSnippets.kt

Atau, Anda dapat menambahkan flag di AndroidManifest.xml di bagian Activity tertentu.

Menandai kartu sebagai dapat diaktifkan/dinonaktifkan

Sebaiknya tandai kartu Anda sebagai dapat diaktifkan/dinonaktifkan jika kartu tersebut berfungsi terutama sebagai tombol dua status (yang merupakan perilaku kartu yang paling umum). Hal ini membantu memberikan informasi tentang perilaku kartu ke sistem operasi dan meningkatkan aksesibilitas secara keseluruhan.

Tetapkan metadata TOGGLEABLE_TILE ke true untuk menandai kartu Anda sebagai dapat diaktifkan/dinonaktifkan.

<service ...>
  <meta-data android:name="android.service.quicksettings.TOGGLEABLE_TILE"
    android:value="true" />
</service>

Hanya melakukan tindakan yang aman di perangkat yang terkunci dengan aman

Kartu Anda dapat ditampilkan di atas layar kunci pada perangkat yang terkunci. Jika kartu berisi informasi sensitif, periksa nilai isSecure() untuk menentukan apakah perangkat dalam status aman, dan TileService Anda harus mengubah perilakunya.

Jika tindakan kartu aman dilakukan saat terkunci, gunakan startActivity() untuk meluncurkan aktivitas di atas layar kunci.

Jika tindakan kartu tidak aman, gunakan unlockAndRun() untuk meminta pengguna membuka kunci perangkat mereka. Jika berhasil, sistem akan mengeksekusi objek Runnable yang Anda teruskan ke metode ini.

Mengategorikan kartu Anda

Untuk meningkatkan pengalaman pengguna di Setelan Cepat, Anda dapat mengategorikan kartu. Sistem mengatur kartu ke dalam kategori seperti Konektivitas, Tampilan, dan Privasi. Sistem menggunakan kategori ini untuk mengurutkan dan mengelompokkan kartu dalam mode edit Setelan Cepat, sehingga memudahkan pengguna untuk menemukan dan mengelolanya.

Penerapan

Untuk menentukan kategori TileService, tambahkan kolom metadata ke deklarasi layanan dalam file AndroidManifest.xml:

• Di AndroidManifest.xml, dalam elemen <service> untuk TileService, tambahkan elemen <meta-data>.
• android:name: Tetapkan nilai ini ke android.service.quicksettings.TILE_CATEGORY.
• android:value: Tetapkan salah satu konstanta kategori yang telah ditentukan, seperti android.service.quicksettings.CATEGORY_CONNECTIVITY atau android.service.quicksettings.CATEGORY_DISPLAY.

Seperti yang ditunjukkan dalam contoh berikut:

<service
    android:name=".MyConnectivityTileService"
    [...]
    >
    <meta-data android:name="android.service.quicksettings.TILE_CATEGORY"
        android:value="android.service.quicksettings.CATEGORY_CONNECTIVITY" />
</service>

API ini menyediakan serangkaian kategori yang telah ditentukan untuk dipilih. Kategori ini ditentukan sebagai konstanta string dalam class TileService.

Jika kategori tidak ditentukan, sistem akan otomatis menetapkan kategori default:

• Dari aplikasi sistem: Untuk kartu yang merupakan bagian dari aplikasi sistem.
• Dari aplikasi yang Anda instal: Untuk kartu dari aplikasi yang diinstal pengguna.

Meskipun perangkat Google Pixel menggunakan kategori di Setelan Cepat, OEM dapat menggunakan atau mengabaikan informasi kategori ini di UI sistem masing-masing.

Meminta pengguna untuk menambahkan kartu Anda

Untuk menambahkan kartu Anda secara manual, pengguna harus mengikuti beberapa langkah:

1. Geser ke bawah untuk membuka panel Setelan Cepat.
2. Ketuk tombol edit.
3. Men-scroll semua kartu di perangkatnya hingga menemukan kartu Anda.
4. Tahan kartu, lalu tarik ke daftar kartu aktif.

Pengguna juga dapat memindahkan atau menghapus kartu Anda kapan saja.

Mulai Android 13, Anda dapat menggunakan metode requestAddTileService() untuk memudahkan pengguna menambahkan kartu ke perangkat. Metode ini meminta pengguna untuk menambahkan kartu Anda secara cepat langsung ke panel Setelan Cepat mereka. Perintah ini menyertakan nama aplikasi, label yang diberikan, dan ikon.

Gambar 5. Dialog API Penempatan Setelan Cepat.

public void requestAddTileService (
  ComponentName tileServiceComponentName,
  CharSequence tileLabel,
  Icon icon,
  Executor resultExecutor,
  Consumer<Integer> resultCallback
)

Callback berisi informasi tentang apakah kartu ditambahkan atau tidak, tidak ditambahkan, apakah sudah ada, atau apakah terjadi error.

Gunakan pertimbangan Anda saat memutuskan kapan dan seberapa sering akan meminta pengguna. Sebaiknya panggil requestAddTileService() hanya dalam konteks, seperti saat pengguna melakukan Interaksi Pertama dengan fitur yang difasilitasi kartu Anda.

Sistem dapat memilih untuk berhenti memproses permintaan untuk ComponentName tertentu jika telah ditolak oleh pengguna beberapa kali sebelumnya. Pengguna ditentukan dari Context yang digunakan untuk mengambil layanan ini: harus cocok dengan pengguna saat ini.

Catatan: Sebaiknya panggil requestAddTileService() untuk meningkatkan visibilitas kartu dan mengurangi beban pengguna untuk menambahkan kartu Anda ke panel Setelan Cepat.