Membuat pengguna Wear OS berinteraksi dengan cara baru menggunakan Ongoing Activity API

1. Pengantar

Tonton animasi di atas (demo Aktivitas Berkelanjutan). Catatan: GIF animasi hanya bergerak dalam satu waktu. Jika Anda melewatkannya, muat ulang halaman.

Dari tampilan jam, Anda akan melihat ikon animasi muncul (untuk timer). Ikon ini akan meluncurkan aplikasi yang mengaktifkan timer jika diketuk oleh pengguna.

Aktivitas Berkelanjutan adalah fitur baru di Wear OS yang memungkinkan Notifikasi Berkelanjutan muncul di platform tambahan dalam antarmuka pengguna Wear OS, yang memungkinkan pengguna untuk lebih berinteraksi dengan aktivitas yang berjalan lama.

OngoingActivity tidak terkait dengan Activity yang digunakan bersama Fragment. Aktivitas, jika terkait dengan OngoingActivity, digunakan sebagai istilah yang lebih umum.

Ongoing Notification biasanya digunakan untuk menunjukkan bahwa Notifikasi memiliki tugas latar belakang yang secara aktif dijalankan pengguna (misalnya, memutar musik) atau tertunda dengan cara tertentu sehingga memenuhi perangkat (misalnya, download file, operasi sinkronisasi, atau koneksi jaringan aktif).

Misalnya, pengguna Wear OS dapat menggunakan aplikasi timer untuk mengatur waktu acara, lalu keluar dari aplikasi tersebut untuk memulai tugas tertentu lainnya (meninjau cuaca, memulai olahraga, dll.).

Saat pengguna keluar dari aplikasi timer, aplikasi tersebut umumnya akan beralih ke Ongoing Notification yang terkait dengan tugas tertentu di latar belakang (layanan, pengelola alarm, dll.) untuk terus memberikan informasi kepada pengguna tentang waktu yang tersisa pada timer.

Pengguna dapat melihat Notifikasi untuk update dan berinteraksi dengan Notifikasi tersebut.

Namun, untuk melihat Notifikasi, pengguna masih harus menggeser ke dalam baki notifikasi di bawah tampilan jam dan menemukan Notifikasi yang tepat, yang tidak senyaman platform lainnya.

Dengan Ongoing Activity API, aplikasi dapat menampilkan informasi ke berbagai platform baru yang nyaman di Wear OS agar pengguna tetap berinteraksi.

Untuk aplikasi Timer, informasi dapat muncul di tampilan jam pengguna sebagai ikon yang dapat diketuk (indikator aktivitas di bagian bawah screenshot):

Aplikasi Timer juga dapat muncul di bagian Recents (Terbaru) peluncur aplikasi global yang mencantumkan semua Aktivitas Berkelanjutan:

Peluncur Global

Saat menggunakan Ongoing Activity, informasi aplikasi akan muncul di platform baru, tetapi Notifikasi asli tidak akan muncul lagi di baki Notifikasi.

Yang terutama, Anda hanya perlu menambahkan sekitar 10 baris kode untuk melakukannya.

Ongoing Activity hanya berfungsi di Android API level 30 dan yang lebih baru. Jika tidak, fitur tersebut akan diabaikan dan muncul sebagai Ongoing Notification normal.

Yang akan Anda pelajari

• Membuat dan menyesuaikan Ongoing Activity
• Mengaitkan Ongoing Activity ke Ongoing Notification
• Menguji Ongoing Activity di perangkat/emulator
• Menambahkan interaksi ke Ongoing Activity Anda (ketuk)

Yang akan Anda buat

Anda akan memperpanjang Walk Tracking App yang sudah ada dengan Ongoing Activity khusus yang menampilkan Walking Points untuk jalan kaki aktif di tampilan jam utama dan di bagian Terbaru peluncur aplikasi.

Bagian Terbaru adalah bagian dari aplikasi yang baru-baru ini digunakan di bagian atas peluncur aplikasi.

Prasyarat

• Pemahaman dasar tentang pengembangan Android
• Pemahaman dasar tentang Kotlin dan coroutine

2. Mempersiapkan

Pada langkah ini, Anda akan menyiapkan lingkungan dan mendownload project awal.

Yang akan Anda butuhkan

• Android Studio
• Emulator Wear OS (level API >= 30)
• Ongoing Activity hanya tersedia di API level 30 atau yang lebih baru
• Baru menggunakan emulator? Berikut cara menyiapkannya.

Mendownload kode

Jika sudah menginstal git, Anda dapat menjalankan perintah di bawah ini untuk meng-clone kode dari repositori ini. Untuk memeriksa apakah git sudah diinstal, ketik git --version di terminal atau command line dan pastikan git dijalankan dengan benar.

git clone https://github.com/android/codelab-ongoing-activity.git
cd ongoing-activity

Jika tidak memiliki git, Anda dapat mengklik tombol berikut untuk mendownload semua kode untuk codelab ini:

Download ZIP

Direktori sampel berisi kode start dan finished untuk codelab ini. Pada tampilan Project di sebelah kiri Android Studio, Anda akan menemukan dua modul.

• start – kode awal untuk project ini; Anda akan membuat perubahan pada kode ini untuk menyelesaikan codelab
• finished – kode lengkap untuk codelab ini; digunakan untuk memeriksa pekerjaan Anda

Anda dapat menjalankan modul mana pun di Android Studio kapan saja dengan mengubah konfigurasi run di toolbar.

Membuka project di Android Studio

1. Di jendela Welcome to Android Studio, pilih Open
2. Pilih folder [Download Location]
3. Setelah Android Studio mengimpor project, uji apakah Anda dapat menjalankan modul start dan finished di emulator Wear OS atau perangkat fisik.
4. Modul start akan terlihat seperti screenshot di bawah ini. Di sinilah Anda akan melakukan semua pekerjaan Anda.

Coba aplikasi dengan memulai olahraga jalan kaki. Anda akan melihat bahwa Anda mulai memperoleh poin setiap ~3 detik. (Aplikasi menggunakan data tiruan, jadi Anda tidak perlu benar-benar berjalan kaki.)

Coba geser keluar dari aplikasi. Jika Anda menuju bagian bawah tampilan jam ke baki navigasi, temukan Ongoing Notification yang terus melacak poin jalan kaki Anda.

Setelah diketuk, tampilannya akan terlihat seperti ini:

Jangan ragu untuk berhenti berjalan kaki.

Pada akhir codelab ini, informasi jalan kaki yang sama akan muncul di tampilan jam dan di bagian Terbaru pada peluncur aplikasi global.

Aplikasi yang muncul di tampilan jam (lihat Indikator Aktivitas di bagian bawah):

Aplikasi yang muncul di bagian Recents (Terbaru) di Peluncur aplikasi:

Mempelajari kode awal

Dalam modul start:

• build.gradle berisi konfigurasi aplikasi dasar. Ini mencakup dependensi yang diperlukan untuk membuat Ongoing Activity.
• manifest > AndroidManifest.xml menyertakan bagian yang diperlukan untuk menandainya sebagai aplikasi Wear OS.
• java > ... > data > WalkingWorkoutsRepository.kt ditautkan ke class WalkingWorkoutsDataStore.kt untuk menyimpan poin jalan kaki dan status olahraga jalan kaki. Jangan khawatir tentang detailnya. Anda tidak akan perlu meninjau class tersebut untuk codelab ini.
• java > ... > MainApplication.kt membuat singleton repositori. Jangan khawatir tentang detailnya. Anda tidak akan perlu meninjau class tersebut untuk codelab ini.
• java > ... > ForegroundOnlyWalkingWorkoutService.kt berisi kode untuk memulai dan menghentikan olahraga jalan kaki. Jika olahraga aktif dan pengguna keluar dari aplikasi, olahraga akan melepas ikatan dari Aktivitas dan memulai Ongoing Notification untuk terus memberikan informasi kepada pengguna tentang poin olahraganya (menggunakan data tiruan). Di sinilah kita akan menambahkan kode Ongoing Activity (dekat kode Notifikasi).
• java > ... > MainActivity.kt berisi UI bagi pengguna untuk memulai/menghentikan olahraga jalan kaki. Aktivitas ini terikat ke layanan di atas untuk memungkinkannya menangani semua tugas olahraga.
• java > ... > MainViewModel.kt adalah ViewModel sederhana untuk menangani kode non-UI di MainActivity.kt. Jangan khawatir tentang detailnya. Anda tidak akan perlu meninjau class tersebut untuk codelab ini.

3. Meninjau aplikasi

Aplikasi ini sudah menjadi aplikasi Walking Workout yang berfungsi.

Seperti yang telah Anda lihat di langkah sebelumnya, Anda dapat meluncurkan aplikasi dan memulai/menghentikan olahraga jalan kaki. Seiring waktu berlalu selama olahraga aktif, Anda akan memperoleh poin jalan kaki.

Poin direset untuk setiap olahraga jalan kaki yang baru.

Jika keluar dari aplikasi saat olahraga aktif, Anda dapat menggeser ke bawah untuk melihat Ongoing Notification yang terus memberikan informasi tentang progres kepada Anda.

Dari Notifikasi tersebut, Anda dapat menghentikan olahraga dari Notifikasi atau membuka aplikasi.

Biasanya, Anda akan menghitung poin jalan kaki berdasarkan data lokasi dan sensor dengan algoritma eksklusif. Dalam kasus ini, kita hanya meniru data untuk memudahkan segala sesuatu.

Bagaimana caranya?

MainActivity membuat antarmuka pengguna, menautkan ke ViewModel untuk info terbaru tentang status olahraga/poin jalan kaki, dan mengikat ke layanan.

Saat olahraga dimulai atau dihentikan, MainActivity akan memanggil metode mulai atau berhenti yang setara di Layanan untuk menangani banyaknya kesulitan dalam melacak olahraga.

Jika pengguna keluar, MainActivity hanya akan melepas ikatan dari layanan.

Sebagian besar keajaiban terjadi di ForegroundOnlyWalkingWorkoutService. Ini adalah class yang memulai/menghentikan olahraga dan menyimpan setiap perubahan status atau poin jalan kaki ke repositori.

Layanan juga beralih ke layanan latar depan dan mengikat diri ke Ongoing Notification jika pengguna keluar dari MainActivity saat sesi berlangsung.

Ongoing Notification berfungsi untuk melacak aktivitas olahraga dan terikat dengan layanan di atas sebagai Layanan Latar Depan.

Jangan khawatir jika Anda tidak memahami semua detailnya. Hal yang penting adalah memahami bahwa ini adalah aplikasi yang berfungsi dengan Notifikasi yang sudah dibuat. Kami hanya ingin memperpanjang Notifikasi agar terlihat di lebih banyak platform dengan Ongoing Activity.

Kode Notifikasi tersebut ada di ForegroundOnlyWalkingWorkoutService, dan di sinilah Anda melakukan semua pekerjaan untuk codelab ini.

4. Membuat Ongoing Activity

Meninjau dependensi

Pada langkah ini, kita tidak akan melakukan coding. Sebagai gantinya, kita akan meninjau dependensi Ongoing Activity.

Buka file app/build.gradle dalam modul start, lalu telusuri "TODO: Review dependencies for Ongoing Activity".

Isi file akan terlihat seperti berikut:

Langkah 1

    // TODO: Review dependencies for Ongoing Activity.
    implementation libs.androidx.wear.ongoing
    // Includes LocusIdCompat and new Notification categories for Ongoing Activity.
    implementation libs.androidx.core.ktx

Dependensi pertama diwajibkan untuk menggunakan Ongoing Activity API Wear OS.

Dependensi kedua adalah mendapatkan fitur terbaru Notification API yang mendukung berbagai fitur yang digunakan bersama dengan Ongoing Activity. Dua fitur berikut dapat diterapkan pada Ongoing Notification, dan karena itu juga dapat diterapkan pada Ongoing Activity:

• Category - Android menggunakan beberapa kategori yang telah ditentukan sebelumnya di seluruh sistem untuk menentukan apakah akan mengganggu pengguna dengan notifikasi tertentu bila pengguna mengaktifkan mode Jangan Ganggu. Category akan menentukan prioritas Ongoing Activity di tampilan jam. Kategori baru ditambahkan baru-baru ini untuk mendukung Wear.
• LocusId - Locus adalah konsep baru yang diperkenalkan di Android 10 (API Level 29) dan memungkinkan sistem Android menghubungkan status antar-subsistem seperti pengambilan konten, pintasan, dan notifikasi. Jika memiliki beberapa peluncur, Anda dapat menggunakan ID locus untuk mengaitkan Ongoing Activity dengan Shortcut dinamis tertentu agar muncul dengan benar di bagian Terbaru peluncur aplikasi.

Meninjau kode Ongoing Notification

Pada langkah ini, kita tidak akan melakukan coding apa pun. Sebagai gantinya, kita hanya akan meninjau kode Notifikasi.

Buka file ForegroundOnlyWalkingWorkoutService.kt dalam modul start, lalu telusuri "TODO: Review Notification builder code".

Isi file akan terlihat seperti berikut:

Langkah 2

// TODO: Review Notification builder code.
val notificationBuilder = notificationCompatBuilder
    .setStyle(bigTextStyle)
    .setContentTitle(titleText)
    .setContentText(mainText)
    .setSmallIcon(R.mipmap.ic_launcher)
    .setDefaults(NotificationCompat.DEFAULT_ALL)
    // Makes Notification an Ongoing Notification (a Notification with a background task).
    .setOngoing(true)
    // Android uses some pre-defined system-wide categories to determine whether to
    // disturb the user with a given notification when the user has enabled Do Not Disturb
    // mode. The Category determines the priority of the Ongoing Activity and new
    // categories were added recently to support Wear
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .addAction(
        R.drawable.ic_walk, getString(R.string.launch_activity),
        activityPendingIntent
    )
    .addAction(
        R.drawable.ic_cancel,
        getString(R.string.stop_walking_workout_notification_text),
        servicePendingIntent
    )

// TODO: Create an Ongoing Activity.
// SKIP TODO FOR REVIEW STEP

return notificationBuilder.build()

Tinjau kode di atas dan baca komentar (lewati bagian TODO karena akan dibahas pada langkah berikutnya).

Ada jauh lebih banyak kode Notifikasi di atas bagian ini yang menyiapkan semuanya untuk builder ini.

Namun, untuk codelab ini, kita hanya perlu fokus pada panggilan setOngoing() dan setCategory() di builder notifikasi.

Category akan membantu Wear OS menentukan prioritas Notifikasi untuk tampilan jam.

Panggilan setOngoing() membuat Notifikasi kita menjadi Ongoing Notification, yaitu Notifikasi dengan tugas latar belakang yang digunakan pengguna untuk berinteraksi secara aktif, misalnya melacak olahraga jalan kaki.

Kita membuat Notifikasi ini saat pengguna memiliki olahraga jalan kaki yang aktif dan keluar dari MainActivity.

Membuat Ongoing Activity

Ongoing Activity harus dikaitkan dengan Ongoing Notification. Kita memiliki Ongoing Notification, jadi sekarang mari kita buat Ongoing Activity.

Telusuri "TODO: Create an Ongoing Activity" dan ganti baris "// SKIP TODO FOR REVIEW STEP" dengan kode di bawah ini.

Langkah 4

// TODO: Create an Ongoing Activity.
val ongoingActivityStatus = Status.Builder()
    // Sets the text used across various surfaces.
    .addTemplate(mainText)
    .build()

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // Sets icon that will appear on the watch face in active mode. If it isn't set,
        // the watch face will use the static icon in active mode.
        .setAnimatedIcon(R.drawable.animated_walk)
        // Sets the icon that will appear on the watch face in ambient mode.
        // Falls back to Notification's smallIcon if not set. If neither is set,
        // an Exception is thrown.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap/touch event, so users can re-enter your app from the
        // other surfaces.
        // Falls back to Notification's contentIntent if not set. If neither is set,
        // an Exception is thrown.
        .setTouchIntent(activityPendingIntent)
        // In our case, sets the text used for the Ongoing Activity (more options are
        // available for timers and stop watches).
        .setStatus(ongoingActivityStatus)
        .build()

// Applies any Ongoing Activity updates to the notification builder.
// This method should always be called right before you build your notification,
// since an Ongoing Activity doesn't hold references to the context.
ongoingActivity.apply(applicationContext)

Sebelum Anda membuat Ongoing Activity, pertama-tama buat Status Ongoing Activity dengan menyertakan teks yang akan muncul di berbagai platform Wear OS.

Kita menetapkan teks menggunakan .addTemplate() di Status.Builder untuk teks utama sama seperti yang digunakan untuk Notifikasi.

Anda sebenarnya dapat menyesuaikan tampilan teks (tentukan warna, ketebalan, dll.), tetapi kita akan membuat teks sederhana untuk codelab ini. Namun, jika Anda ingin mempelajari lebih lanjut, baca Panduan Ongoing Activity.

Selanjutnya, kita membuat OngoingActivity itu sendiri. Kita meneruskan konteks, ID notifikasi, dan builder notifikasi yang kita buat di atas kode ini ke dalam konstruktor OngoingActivity.Builder().

ID notifikasi dan instance NotificationCompat.Builder penting untuk mengaitkan OngoingActivity ke Ongoing Notification.

Pertama-tama, kita menetapkan ikon animasi (untuk tampilan jam dalam mode aktif) dan ikon statis (untuk tampilan jam dalam mode standby).

Selanjutnya, kita menetapkan peristiwa sentuh dan terakhir teks menggunakan objek Status yang telah kita buat sebelum menutup pernyataan dengan .build().

Ikon yang digunakan di bagian "Terbaru" peluncur aplikasi menggunakan ikon yang terkait dengan aktivitas utama/peluncur.

Antarmuka pengguna OngoingActivity disediakan menggunakan ikon dan teks Status. Peristiwa sentuh memungkinkan pengguna mengetuk kembali ke aplikasi dari tampilan jam atau bagian Terbaru peluncur aplikasi global.

Catatan: Selalu tetapkan ikon statis dan intent sentuh untuk Ongoing Activity Anda baik secara eksplisit atau sebagai penggantian menggunakannotifikasi. Jika tidak, Anda akan mendapatkan IllegalArgumentException.

Terakhir, kita memanggil apply() di Ongoing Activity dan meneruskan konteksnya. Ini adalah langkah terakhir yang menerapkan perubahan apa pun di Ongoing Activity ke builder notifikasi.

Oke, selesai.

Bila dipanggil dengan Notifikasi ini, notificationManager.notify(NOTIFICATION_ID, notification) kini akan muncul di platform baru.

Sekarang jalankan aplikasi Anda di emulator atau perangkat Wear OS baru.

Mulailah berjalan kaki dari aplikasi, lalu geser untuk keluar dari aplikasi.

Jika Anda tidak memiliki olahraga jalan kaki yang aktif, aplikasi tidak akan muncul di platform baru.

Pada tampilan jam, Anda akan melihat ikon orang berjalan kaki berukuran kecil seperti ini (tetapi dalam animasi):

Jika mengetuk ikon, Anda akan kembali ke aplikasi.

Keluar lagi dari aplikasi, lalu ketuk tombol peluncur aplikasi di perangkat Wear OS.

Anda akan melihat tampilan seperti ini:

Jika mengklik ketuk pada aplikasi jalan kaki di bagian Recents (Terbaru), Anda akan kembali lagi ke aplikasi.

5. Selamat

Selamat! Anda telah mempelajari cara membuat Ongoing Activity di Wear OS.

Ongoing Activity adalah cara yang bagus untuk mengajak pengguna berinteraksi di platform baru di Wear.

Apa selanjutnya?

Lihat codelab Wear OS lainnya:

• Membuat Kartu Wear OS pertama
• Menampilkan data ke detail tampilan jam

Bacaan lebih lanjut

• Panduan Ongoing Activity