Mengonfigurasi aplikasi Wear OS untuk Push Tampilan Jam

Watch Face Push memungkinkan aplikasi Anda mengelola tampilan jam di perangkat Wear OS. Hal ini mencakup menambahkan, mengupdate, dan menghapus tampilan jam, serta menyetel tampilan jam aktif. Konfigurasikan aplikasi Wear OS Anda untuk menggunakan Watch Face Push API.

Penyiapan

Sertakan dependensi yang diperlukan:

implementation("androidx.wear.watchface:watchface-push:1.3.0-alpha07")

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 = WatchFacePushManager(context)

WatchFacePushManager menyediakan akses ke semua metode untuk berinteraksi dengan Watch Face Push.

Menggunakan slot

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

Saat mengupdate atau menghapus tampilan jam, slotId digunakan untuk mengidentifikasi tampilan jam tempat operasi akan dilakukan.

Mencantumkan tampilan jam

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

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

Hal ini memungkinkan Anda menentukan apakah slot tersedia, atau apakah menambahkan tampilan jam lain memerlukan penggantian tampilan jam yang ada. Daftar ini juga memberi Anda detail tentang tampilan jam yang diinstal. 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, seperti yang 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.
}

Mengupdate tampilan jam

Dengan mengupdate tampilan jam, Anda dapat mengganti konten slot tertentu dengan paket baru. Tindakan 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.
}

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

Memeriksa apakah tampilan jam Anda aktif

Menentukan apakah marketplace Anda telah menetapkan tampilan jam aktif atau belum penting dalam memastikan pengguna memiliki pengalaman yang lancar: Jika marketplace sudah menetapkan tampilan jam aktif, maka jika pengguna ingin memilih tampilan jam lain, mereka hanya perlu mengganti tampilan jam saat ini melalui aplikasi marketplace agar tindakan ini dapat diterapkan. Namun, jika marketplace tidak memiliki tampilan jam aktif yang ditetapkan, aplikasi ponsel harus menawarkan panduan lebih lanjut kepada pengguna. Lihat bagian aplikasi ponsel untuk mengetahui detail selengkapnya tentang cara menangani pengalaman pengguna ini.

Untuk menentukan apakah marketplace telah menyetel tampilan jam aktif:

Menyediakan tampilan jam default

Watch Face Push menawarkan kemampuan untuk menginstal tampilan jam default saat aplikasi marketplace Anda diinstal. Tindakan ini tidak akan otomatis menetapkan tampilan jam default tersebut sebagai 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

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

Menetapkan tampilan jam aktif

Push Tampilan Jam menyediakan cara bagi aplikasi marketplace untuk menyetel tampilan jam aktif.

Artinya, aplikasi dapat menyetel tampilan jam aktif ke tampilan jam yang dimiliki marketplace jika tampilan jam aktif saat ini tidak dimiliki marketplace. Perhatikan bahwa jika marketplace sudah memiliki tampilan jam aktif, mengubahnya menjadi 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).

Menetapkan tampilan jam sebagai aktif

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

watchFacePushManager.setWatchFaceAsActive(slotId)

Setelah cara ini digunakan, aplikasi ponsel Anda akan 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 minor 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 yang berbeda, dengan semua yang 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 dari varian berikut yang diinstal:

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

Pertimbangan

Pertimbangan penting saat menerapkan Watch Face Push di aplikasi Anda mencakup berfokus pada konsumsi daya, penyimpanan dalam cache, mengupdate tampilan jam yang dipaketkan, 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 digunakan langsung oleh pengguna). Hal ini mencakup:
    • Meminimalkan pengaktifan aplikasi dari aplikasi telepon
    • Meminimalkan berjalannya tugas WorkManager
  2. Menjadwalkan pelaporan analisis untuk saat smartwatch sedang diisi dayanya:
    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 dayanya dan menggunakan Wi-Fi:
    1. Sebaiknya periksa versi tampilan jam yang diinstal dan update secara otomatis. Sekali lagi, gunakan batasan requiresCharging dan jenis jaringan UNMETERED untuk requiresNetworkType.
    2. Saat 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 ini berlaku untuk tempat marketplace mungkin menawarkan tampilan jam hari ini; download terlebih dahulu saat smartwatch sedang diisi dayanya.
  4. Jangan menjadwalkan tugas untuk memeriksa tampilan jam yang aktif:
    1. Memeriksa secara berkala apakah marketplace Anda masih memiliki tampilan jam yang aktif dan tampilan jam mana yang menghabiskan baterai. Hindari pendekatan ini.
  5. Jangan gunakan notifikasi di smartwatch:
    1. Jika aplikasi Anda menggunakan notifikasi, fokuskan notifikasi tersebut di ponsel, tempat tindakan pengguna membuka aplikasi ponsel untuk melanjutkan perjalanan. Pastikan hal ini tidak dihubungkan ke aplikasi smartwatch menggunakan setLocalOnly.

Menyimpan ke cache

Dalam contoh marketplace kanonis, tampilan jam ditransfer dari ponsel ke smartwatch. Koneksi ini biasanya merupakan koneksi Bluetooth, yang dapat cukup lambat.

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

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

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

Mengupdate tampilan jam yang dipaketkan

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

Untuk menangani situasi ini, aplikasi marketplace Anda harus memproses tindakan siaran MY_PACKAGE_REPLACED dan memeriksa kebutuhan untuk mengupdate tampilan jam yang dipaketkan dari aset paket.

Tampilan jam default representatif

Tampilan jam default adalah cara yang bagus 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 hal ini, kembalikan tampilan jam ke tampilan jam default menggunakan updateWatchFace. Hal ini membantu pengguna menemukan tampilan jam Anda dan menyetelnya dari galeri.
  • Buat tampilan jam default 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.