Mengonfigurasi aplikasi Wear OS untuk Push Tampilan Jam

Watch Face Push memungkinkan aplikasi Anda mengelola tampilan jam di perangkat Wear OS. Hal ini mencakup penambahan, pembaruan, dan penghapusan tampilan jam, serta penyetelan tampilan jam aktif. Konfigurasi aplikasi Wear OS Anda untuk menggunakan Watch Face Push API.

Penyiapan

Sertakan dependensi yang diperlukan:

implementation("androidx.wear.watchfacepush:watchfacepush:1.0.0-alpha01")

Tambahkan kode berikut ke AndroidManifest.xml Anda:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <!-- Required to use the Watch Face Push API.  -->
    <uses-permission android:name="com.google.wear.permission.PUSH_WATCH_FACES" />

    <!-- Required to be able to call the setWatchFaceAsActive() method. -->
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />

</manifest>

Mendapatkan referensi ke instance pengelola

Dapatkan instance WatchFacePushManager:

val manager = WatchFacePushManagerFactory.createWatchFacePushManager(context)

WatchFacePushManager menyediakan akses ke semua metode untuk berinteraksi dengan Pengiriman Tampilan Jam.

Bekerja dengan slot

Konsep utama saat menggunakan Watch Face Push adalah slot. Slot adalah cara untuk mengatasi tampilan jam terinstal yang termasuk dalam aplikasi Anda. Sistem menetapkan jumlah maksimum slot yang dapat dimiliki marketplace; dengan Wear OS 6, batasnya adalah 1.

Saat memperbarui atau menghapus tampilan jam, slotId digunakan untuk mengidentifikasi tampilan jam yang akan dioperasikan.

Mencantumkan tampilan jam

Untuk mencantumkan kumpulan tampilan jam yang diinstal, gunakan listWatchFaces():

val response = watchFacePushManager.listWatchFaces()
val installedList = response.installedWatchFaceDetails
val remainingSlots = response.remainingSlots

Dengan demikian, Anda dapat menentukan apakah slot tersedia, atau apakah penambahan tampilan jam lain memerlukan penggantian tampilan jam yang ada. Daftar ini juga memberi Anda detail tentang tampilan jam yang terinstal. Misalnya, untuk memeriksa apakah paket tampilan jam tertentu telah diinstal:

suspend fun isInstalled(packageName: String) = watchFacePush.listWatchFaces()
    .installedWatchFaceDetails.any { it.packageName == packageName }

Menambahkan tampilan jam

Jika ada slot yang tersedia, sebagaimana ditentukan oleh respons listWatchFaces, metode addWatchFace() harus digunakan:

try {
    // Supply the validation token along with the watch face package data itself.
    val slot = watchFacePushManager.addWatchFace(parcelFileDescriptor, token)
    Log.i(TAG, "${slot.packageName} (${slot.versionCode}) added in slot ${slot.slotId}")
} catch (e: AddWatchFaceException) {
    // Something went wrong adding the watch face.
}

Catatan: Jangan menyimpan nilai slotId atau memperlakukannya sebagai persisten. Status dapat berubah di luar aplikasi Anda; misalnya, pengguna dapat menghapus aplikasi tampilan jam Anda melalui UI sistem. Selalu dapatkan status saat ini segera sebelum operasi berbasis slot apa pun.

Mengupdate tampilan jam

Mengupdate tampilan jam memungkinkan Anda mengganti konten slot tertentu dengan paket baru. Hal ini dapat berupa mengupgrade tampilan jam yang sama ke versi yang lebih baru atau mengganti tampilan jam sepenuhnya dengan tampilan jam lain.

// Replacing the com.example.watchfacepush.green watch face with
// com.example.watchfacepush.red.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.updateWatchFace(slotId, redParcelFileDesc, redValidationToken)
} catch (e: UpdateWatchFaceException) {
    // Something went wrong updating the watch face.
}

Menghapus tampilan jam

Untuk menghapus tampilan jam:

// Remove the com.example.watchfacepush.green watch face.
val slotId = watchFacePushManager.listWatchFaces().installedWatchFaceDetails.
    firstOrNull { it.packageName == "com.example.watchfacepush.green" }?.slotId

try {
    watchFacePushManager.removeWatchFace(slotId)
} catch (e: RemoveWatchFaceException) {
    // Something went wrong removing the watch face.
}

Catatan: Pertimbangkan apakah aplikasi Anda harus memanggil removeWatchFace. Sebagai gantinya, saat pengguna mengetuk untuk meng-uninstal tampilan jam melalui aplikasi marketplace Anda, Anda dapat menggantinya dengan tampilan jam default.

Hal ini akan memastikan tampilan jam Anda selalu dapat ditemukan di pemilih tampilan jam sistem, dapat menampilkan logo Anda secara jelas, dan bahkan dapat menampilkan tombol untuk meluncurkan aplikasi Marketplace Anda di ponsel.

Memeriksa apakah tampilan jam Anda aktif

Menentukan apakah marketplace Anda telah menyetel tampilan jam aktif penting untuk memastikan pengguna mendapatkan pengalaman yang lancar: Jika marketplace sudah menyetel tampilan jam aktif, pengguna hanya perlu mengganti tampilan jam saat ini melalui aplikasi marketplace agar perubahan ini diterapkan. Namun, jika marketplace tidak menyetel tampilan jam aktif, aplikasi ponsel harus menawarkan panduan lebih lanjut kepada pengguna. Lihat bagian tentang aplikasi telepon untuk mengetahui detail selengkapnya tentang cara menangani pengalaman pengguna ini.

Untuk menentukan apakah marketplace telah menyetel tampilan jam aktif, gunakan logika berikut:

val hasActiveWatchFace = watchFacePushManager.listWatchFaces()
    .installedWatchFaceDetails
    .any {
        watchFacePushManager.isWatchFaceActive(it.packageName)
    }

Peringatan: Saat memanggil updateWatchFace(), jangan panggil isWatchFaceActive() segera setelahnya karena dapat menyebabkan hasil yang tidak terduga. Mungkin perlu waktu beberapa saat hingga penggantian tampilan jam selesai.

Sebagai gantinya, tentukan terlebih dahulu apakah aplikasi yang memanggil memiliki referensi ke tampilan jam aktif seperti yang ditunjukkan dalam cuplikan sebelumnya, lalu panggil updateWatchFace(). Jika updateWatchFace() berhasil diselesaikan, Anda dapat mengasumsikan bahwa aplikasi Anda masih memiliki kontrol atas tampilan jam aktif.

Menyediakan tampilan jam default

Watch Face Push menawarkan kemampuan untuk menginstal tampilan jam default saat aplikasi marketplace Anda diinstal. Dengan sendirinya, hal ini tidak akan menyetel tampilan jam default tersebut sebagai tampilan jam aktif (lihat menyetel tampilan jam aktif), tetapi akan memastikan bahwa tampilan jam Anda tersedia di alat pilih tampilan jam sistem.

Untuk menggunakan fitur ini:

1. Dalam build aplikasi Wear OS, sertakan tampilan jam default di jalur: assets/default_watchface.apk

2. Tambahkan entri berikut ke AndroidManifest.xml Anda

   <application ...>
   <meta-data
       android:name="com.google.android.wearable.marketplace.DEFAULT_WATCHFACE_VALIDATION_TOKEN"
       android:value="@string/default_wf_token" />
   

Catatan: Pola build umum mencakup membangun default_watchface.apk sebagai bagian dari build aplikasi secara keseluruhan sebagai langkah pra-build. Anda dapat menggunakan ini untuk mengisi nilai manifes token validasi dengan membuat proses build tampilan jam default menghasilkan file XML resource Android tambahan dan menyertakan jalur resource tersebut sebagai jalur resource tambahan dalam aplikasi utama Anda. Pendekatan ini lebih sederhana daripada mencoba memanipulasi file manifes itu sendiri selama proses build.

Menyetel tampilan jam aktif

Watch Face Push menyediakan sarana bagi aplikasi marketplace untuk menyetel tampilan jam aktif.

Artinya, aplikasi dapat menyetel tampilan jam aktif ke salah satu tampilan jam yang termasuk dalam marketplace jika tampilan jam aktif saat ini tidak termasuk dalam marketplace. Perhatikan bahwa jika marketplace sudah memiliki tampilan jam aktif, perubahan ke tampilan jam lain dilakukan melalui panggilan ke updateWatchFace untuk mengganti konten slot tampilan jam dengan tampilan jam lain.

Menyetel tampilan jam aktif adalah proses dua tahap:

1. Dapatkan Izin Android yang diperlukan untuk menyetel tampilan jam aktif.
2. Panggil metode setWatchFaceAsActive.

Mendapatkan izin untuk menyetel tampilan jam aktif

Izin yang diperlukan adalah SET_PUSHED_WATCH_FACE_AS_ACTIVE, yang harus ditambahkan ke manifes Anda:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    ...
    <uses-permission android:name="com.google.wear.permission.SET_PUSHED_WATCH_FACE_AS_ACTIVE" />
</manifest>

Karena ini adalah izin runtime, aplikasi Anda harus meminta izin ini dari pengguna saat aplikasi berjalan (pertimbangkan library Accompanist untuk membantu hal ini).

Catatan: Izin ini memiliki jumlah penolakan maksimum 1: Jika pengguna menolak permintaan, permintaan tersebut tidak dapat dilakukan lagi. Dalam hal ini, aplikasi harus mengarahkan pengguna ke setelan untuk menyesuaikan izin secara manual.

Menetapkan tampilan jam sebagai aktif

Setelah izin diberikan, panggil setWatchFaceAsActive di ID slot tampilan jam yang harus aktif:

watchFacePushManager.setWatchFaceAsActive(slotId)

Catatan: Tampilan jam aktif hanya dapat disetel dengan cara ini satu kali. Jika pengguna beralih ke tampilan jam dari developer lain, memanggil API ini untuk menyetel tampilan jam aktif kembali ke tampilan jam Anda akan memunculkan pengecualian.

Setelah cara ini digunakan, aplikasi ponsel Anda harus menawarkan panduan tentang cara menyetel tampilan jam aktif secara manual.

Membaca metadata tambahan dari APK tampilan jam

Objek WatchFaceSlot juga menyediakan cara untuk mendapatkan informasi tambahan yang dapat Anda deklarasikan di tampilan jam.

Hal ini dapat berguna terutama dalam skenario saat Anda memiliki varian kecil dari tampilan jam yang sama. Misalnya, Anda dapat menentukan tampilan jam:

• Nama paket: com.myapp.watchfacepush.mywatchface
• Versi paket: 1.0.0

Namun, tampilan jam ini mungkin hadir sebagai empat APK berbeda, yang semuanya hampir sama persis, tetapi dengan warna default yang berbeda: merah, kuning, hijau, dan biru, yang ditetapkan dalam ColorConfiguration di XML Format Tampilan Jam.

Variasi kecil ini kemudian tercermin dalam setiap empat APK:

<!-- For watch face com.myapp.watchfacepush.mywatchface -->
<property
        android:name="default_color"
        android:value="red" />

Dengan menggunakan properti kustom, aplikasi Anda dapat menentukan varian mana yang diinstal:

watchFaceDetails
    .getMetaDataValues("com.myapp.watchfacepush.mywatchface.default_color")
    .invoke()

Catatan: Dalam contoh sebelumnya, namespace harus diberikan untuk properti karena none dideklarasikan pada properti. Jika properti menyertakan titik (.), hal ini tidak diperlukan, sehingga properti bernama abc.def dapat diambil menggunakan getMetaDataValues("abc.def").

Pertimbangan

Pertimbangan penting saat menerapkan Push Tampilan Jam di aplikasi Anda mencakup berfokus pada konsumsi daya, penyiapan cache, memperbarui tampilan jam bawaan, dan menyediakan tampilan jam default yang representatif.

Daya

Pertimbangan utama untuk aplikasi apa pun yang berjalan di Wear OS adalah konsumsi daya. Untuk komponen Wear OS aplikasi marketplace Anda:

1. Aplikasi Anda harus berjalan sesedikit dan sesering mungkin (kecuali jika berinteraksi langsung dengan pengguna). Hal ini mencakup:
   • Meminimalkan membangunkan aplikasi dari aplikasi Telepon
   • Meminimalkan jalannya tugas WorkManager
2. Menjadwalkan pelaporan analisis apa pun saat smartwatch sedang diisi daya:
   1. Jika Anda ingin melaporkan statistik penggunaan dari aplikasi Wear OS atau metrik lainnya, gunakan WorkManager dengan batasan requiresCharging.
3. Menjadwalkan update saat smartwatch sedang diisi daya dan menggunakan Wi-Fi:
   1. Anda dapat memeriksa versi tampilan jam yang terinstal dan memperbaruinya secara otomatis. Sekali lagi, gunakan batasan requiresCharging dan jenis jaringan UNMETERED untuk requiresNetworkType.
   2. Saat sedang diisi dayanya, perangkat kemungkinan memiliki akses ke Wi-Fi. Minta Wi-Fi untuk mendownload APK yang diupdate dengan cepat, dan lepaskan jaringan setelah selesai.
   3. Panduan yang sama berlaku untuk tempat marketplace dapat menawarkan tampilan jam harian; download sebelumnya saat smartwatch sedang diisi dayanya.
4. Jangan menjadwalkan tugas untuk memeriksa tampilan jam aktif:
   1. Memeriksa secara berkala apakah marketplace Anda masih memiliki tampilan jam aktif dan tampilan jam mana yang aktif akan menguras daya baterai. Hindari pendekatan ini.
5. Jangan menggunakan notifikasi di smartwatch:
   1. Jika aplikasi Anda menggunakan notifikasi, fokuskan notifikasi ini di ponsel, tempat tindakan pengguna membuka aplikasi ponsel untuk melanjutkan perjalanan. Pastikan hal ini tidak menjembatani aplikasi smartwatch menggunakan setLocalOnly.

Menyimpan ke cache

Dalam contoh marketplace kanonis, tampilan jam ditransfer dari ponsel ke smartwatch. Koneksi ini biasanya berupa koneksi Bluetooth, yang bisa sangat lambat.

Untuk memberikan pengalaman pengguna yang lebih baik dan menghemat daya transmisi ulang, pertimbangkan untuk menerapkan cache kecil di perangkat Wear OS untuk menyimpan beberapa APK.

Jika pengguna mencoba tampilan jam lain, tetapi kemudian memutuskan untuk kembali ke tampilan jam yang dipilih sebelumnya, tindakan ini akan hampir instan.

Demikian pula, ini dapat digunakan untuk melakukan pra-cache untuk tampilan jam hari ini atau skema serupa saat tampilan jam didownload saat perangkat Wear OS sedang diisi dayanya.

Mengupdate tampilan jam bawaan

Aplikasi Anda dapat menyertakan aset tampilan jam default seperti yang dijelaskan sebelumnya. Penting untuk diketahui bahwa, meskipun tampilan jam ini diinstal ke sistem saat aplikasi marketplace Anda diinstal, tampilan jam tidak akan diupdate jika versi yang lebih baru disertakan dengan update apa pun pada aplikasi marketplace Anda.

Untuk menangani situasi ini, aplikasi marketplace Anda harus memproses tindakan siaran MY_PACKAGE_REPLACED dan memeriksa apakah perlu memperbarui tampilan jam yang disertakan dari aset paket.

Tampilan jam default representatif

Tampilan jam default adalah cara yang tepat untuk membantu pengguna menemukan dan menggunakan marketplace Anda: Tampilan jam diinstal saat marketplace Anda diinstal, sehingga pengguna dapat menemukannya di galeri tampilan jam.

Beberapa pertimbangan saat menggunakan tampilan jam default:

• Jangan gunakan removeWatchFace jika pengguna memilih untuk meng-uninstal tampilan jam dari aplikasi marketplace Anda. Sebagai gantinya, dalam kasus ini, kembalikan tampilan jam ke tampilan jam default menggunakan updateWatchFace. Tindakan ini membantu pengguna menemukan tampilan jam Anda dan menyetelnya dari galeri.
• Buat tampilan jam default yang sederhana dan langsung dikenali melalui logo dan tema Anda. Hal ini membantu pengguna menemukannya di galeri tampilan jam.

• Tambahkan tombol ke tampilan jam default untuk membuka aplikasi ponsel. Hal ini dapat dilakukan dalam dua tahap:

  1. Tambahkan elemen Launch ke tampilan jam untuk meluncurkan intent menggunakan aplikasi Wear OS, misalnya:

     <Launch target="com.myapp/com.myapp.LaunchOnPhoneActivity" />

  2. Di LaunchOnPhoneActivity, luncurkan aplikasi telepon menggunakan RemoteActivityHelper.