Menampilkan aktivitas yang sedang berlangsung

Perangkat Wear OS sering digunakan untuk pengalaman yang berjalan lama, seperti melacak olahraga. Hal ini menimbulkan tantangan pengalaman pengguna: jika pengguna memulai tugas, lalu keluar ke tampilan jam, bagaimana cara mereka kembali? Kembali ke aplikasi menggunakan peluncur bisa sulit, terutama saat bepergian, sehingga menimbulkan gesekan yang tidak perlu.

Solusinya adalah memasangkan notifikasi berkelanjutan dengan OngoingActivity. Hal ini memungkinkan perangkat menampilkan informasi tentang aktivitas yang berjalan lama di seluruh antarmuka pengguna, sehingga mengaktifkan fitur seperti ikon yang dapat diketuk di bagian bawah tampilan jam. Hal ini membuat pengguna mengetahui tugas latar belakang, dan menyediakan cara sekali ketuk untuk kembali ke aplikasi.

Ongoing Activity juga membuat aplikasi Anda tetap terlihat lebih lama, sehingga mencegah sistem kembali ke tampilan jam setelah periode tidak aktif. Untuk mengetahui informasi selengkapnya, lihat Membuat aplikasi tetap terlihat di Wear.

Misalnya, di aplikasi olahraga ini, informasi dapat muncul di tampilan jam pengguna sebagai ikon lari yang dapat diketuk:

Gambar 1. Indikator aktivitas.

Notifikasi berkelanjutan juga menampilkan informasi di bagian Terbaru peluncur aplikasi global. Hal ini memberikan tempat praktis lain bagi pengguna untuk melihat status tugas mereka dan berinteraksi kembali dengan aplikasi:

Gambar 2. Peluncur global.

Berikut ini adalah situasi yang tepat untuk menggunakan notifikasi berkelanjutan yang terikat dengan Aktivitas Berkelanjutan:

Gambar 3. Timer: Aktif menghitung waktu mundur, dan berakhir saat timer dijeda atau dihentikan.

Gambar 4. Navigasi belokan demi belokan: Menginformasikan rute ke tujuan. Berakhir saat pengguna mencapai tujuan atau menghentikan navigasi.

Gambar 5. Media: Memutar musik sepanjang sesi. Berakhir seketika setelah pengguna menjeda sesi.

Wear akan otomatis membuat Aktivitas Berkelanjutan untuk aplikasi media.

Lihat codelab Aktivitas Berkelanjutan untuk mengetahui contoh detail cara membuat Aktivitas Berkelanjutan untuk jenis aplikasi lain.

Penyiapan

Untuk mulai menggunakan Ongoing Activity API di aplikasi, tambahkan dependensi berikut ke file build.gradle aplikasi:

dependencies {
  implementation "androidx.wear:wear-ongoing:1.1.0"
  implementation "androidx.core:core:1.18.0"
}

Membuat Aktivitas Berkelanjutan

Proses ini terdiri dari tiga langkah:

1. Buat standar NotificationCompat.Builder dan konfigurasikan sebagai berkelanjutan.
2. Buat dan konfigurasi objek OngoingActivity, dengan meneruskan pembuat notifikasi ke objek tersebut.
3. Terapkan Aktivitas Berkelanjutan ke pembuat notifikasi dan posting notifikasi yang dihasilkan.

Membuat dan mengonfigurasi notifikasi

Mulailah dengan membuat NotificationCompat.Builder. Langkah utamanya adalah memanggil setOngoing(true) untuk menandainya sebagai notifikasi berkelanjutan. Anda juga dapat menetapkan properti notifikasi lainnya pada tahap ini, seperti ikon kecil dan kategori.

// Create a PendingIntent to pass to the notification builder
val pendingIntent =
    PendingIntent.getActivity(
        this,
        0,
        Intent(this, AlwaysOnActivity::class.java).apply {
            flags = Intent.FLAG_ACTIVITY_SINGLE_TOP
        },
        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
    )

val notificationBuilder = NotificationCompat.Builder(this, CHANNEL_ID)
    .setContentTitle("Always On Service")
    .setContentText("Service is running in background")
    .setSmallIcon(R.drawable.animated_walk)
    // Category helps the system prioritize the ongoing activity
    .setCategory(NotificationCompat.CATEGORY_WORKOUT)
    .setContentIntent(pendingIntent)
    .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
    .setOngoing(true) // Important!
AlwaysOnService.kt

Membuat OngoingActivity

Selanjutnya, buat instance OngoingActivity menggunakan pembuatnya. OngoingActivity.Builder memerlukan Context, ID notifikasi, dan NotificationCompat.Builder yang Anda buat pada langkah sebelumnya.

Konfigurasikan properti utama yang akan ditampilkan di platform UI baru:

• Ikon animasi dan statis: Menyediakan ikon yang ditampilkan di tampilan jam dalam mode aktif dan standby.
• Intent sentuh: PendingIntent yang membawa pengguna kembali ke aplikasi Anda saat mereka mengetuk ikon Aktivitas Berkelanjutan. Anda dapat menggunakan kembali pendingIndent yang dibuat pada langkah sebelumnya.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // Sets the icon that appears on the watch face in active mode.
        .setAnimatedIcon(R.drawable.animated_walk)
        // Sets the icon that appears on the watch face in ambient mode.
        .setStaticIcon(R.drawable.ic_walk)
        // Sets the tap target to bring the user back to the app.
        .setTouchIntent(pendingIntent)
        .build()
AlwaysOnService.kt

Menerapkan ke notifikasi dan memposting

Langkah terakhir adalah menautkan OngoingActivity dengan notifikasi, lalu mempostingnya. Metode ongoingActivity.apply() mengubah pembuat notifikasi asli, menambahkan data yang diperlukan sehingga sistem dapat menampilkannya di platform tambahan. Setelah menerapkannya, Anda dapat membuat dan memposting notifikasi seperti biasa.

// This call modifies notificationBuilder to include the ongoing activity data.
ongoingActivity.apply(applicationContext)

// Post the notification.
startForeground(NOTIFICATION_ID, notificationBuilder.build())
AlwaysOnService.kt

Menambahkan teks status dinamis ke peluncur

Kode sebelumnya menambahkan ikon yang dapat diketuk ke tampilan jam. Untuk memberikan pembaruan real-time yang lebih lengkap di bagian Terbaru peluncur, buat objek Status dan lampirkan ke OngoingActivity. Jika Anda tidak memberikan Status kustom, sistem akan menggunakan teks konten notifikasi secara default (ditetapkan menggunakan setContentText()). Untuk menampilkan teks dinamis, gunakan Status.Builder. Anda dapat menentukan string template dengan placeholder dan menyediakan objek Status.Part untuk mengisi placeholder tersebut. Status.Part dapat bersifat dinamis, seperti stopwatch atau timer.

Contoh berikut menunjukkan cara membuat status yang menampilkan "Run for [a stopwatch timer]":

// Define a template with placeholders for the activity type and the timer.
val statusTemplate = "#type# for #time#"

// Set the start time for a stopwatch.
// Use SystemClock.elapsedRealtime() for time-based parts.
val runStartTime = SystemClock.elapsedRealtime()

val ongoingActivityStatus = Status.Builder()
    // Sets the template string.
    .addTemplate(statusTemplate)
    // Fills the #type# placeholder with a static text part.
    .addPart("type", Status.TextPart("Run"))
    // Fills the #time# placeholder with a stopwatch part.
    .addPart("time", Status.StopwatchPart(runStartTime))
    .build()
AlwaysOnService.kt

Terakhir, tautkan Status ini ke OngoingActivity dengan memanggil setStatus() di OngoingActivity.Builder.

val ongoingActivity =
    OngoingActivity.Builder(applicationContext, NOTIFICATION_ID, notificationBuilder)
        // ...
        // Add the status to the OngoingActivity.
        .setStatus(ongoingActivityStatus)
        .build()
AlwaysOnService.kt

Penyesuaian tambahan

Selain Status, Anda dapat menyesuaikan Aktivitas atau notifikasi Berkelanjutan dengan cara berikut. Namun, penyesuaian ini mungkin tidak digunakan, berdasarkan penerapan OEM.

Notifikasi Berkelanjutan

• Kumpulan kategori menentukan prioritas Aktivitas Berkelanjutan.
  • CATEGORY_CALL: panggilan suara atau video yang masuk atau permintaan komunikasi sinkron yang serupa
  • CATEGORY_NAVIGATION: peta atau navigasi belokan demi belokan
  • CATEGORY_TRANSPORT: kontrol transmisi media untuk pemutaran
  • CATEGORY_ALARM: alarm atau timer
  • CATEGORY_WORKOUT: olahraga
  • CATEGORY_LOCATION_SHARING: kategori berbagi lokasi sementara
  • CATEGORY_STOPWATCH: stopwatch

Aktivitas Berkelanjutan

• Ikon animasi: vektor hitam putih, sebaiknya dengan latar belakang transparan. Ditampilkan di tampilan jam dalam mode aktif. Jika ikon animasi tidak disediakan, ikon notifikasi default akan digunakan. Ikon notifikasi default berbeda untuk setiap aplikasi.

• Ikon statis: ikon vektor dengan latar belakang transparan. Ditampilkan di tampilan jam dalam mode standby. Jika ikon animasi tidak disetel, ikon statis akan digunakan pada tampilan jam untuk mode aktif. Jika tidak disediakan, ikon notifikasi akan digunakan. Jika keduanya tidak ditetapkan, pengecualian akan ditampilkan. (Peluncur aplikasi masih menggunakan ikon aplikasi.)

• OngoingActivityStatus: teks biasa atau Chronometer. Ditampilkan di bagian Terbaru dari peluncur aplikasi. Jika tidak disediakan, notifikasi "teks konteks" akan digunakan.

• Intent Sentuh: PendingIntent yang digunakan untuk beralih kembali ke aplikasi jika pengguna mengetuk ikon Aktivitas Berkelanjutan. Ditampilkan di tampilan jam atau di item peluncur. Mungkin berbeda dengan intent asli yang digunakan untuk meluncurkan aplikasi. Jika tidak disediakan, intent konten notifikasi akan digunakan. Jika keduanya tidak ditetapkan, pengecualian akan ditampilkan.

• LocusId: ID yang menetapkan pintasan peluncur yang terkait dengan aktivitas berkelanjutan. Ditampilkan pada peluncur di bagian Terbaru saat aktivitas sedang berlangsung. Jika tidak disediakan, peluncur akan menyembunyikan semua item aplikasi di bagian Terbaru dari paket yang sama dan hanya menampilkan Aktivitas Berkelanjutan.

• ID Aktivitas Berkelanjutan: ID yang digunakan untuk membedakan panggilan ke fromExistingOngoingActivity() jika aplikasi memiliki lebih dari satu Aktivitas Berkelanjutan.

Memperbarui Aktivitas Berkelanjutan

Anda harus memperbarui Aktivitas Berkelanjutan untuk notifikasi yang ada saat perlu mengubah status, bukan membuat notifikasi dan Aktivitas Berkelanjutan baru. Untuk memperbarui Aktivitas Berkelanjutan dan notifikasi yang diposting, gunakan objek yang Anda buat sebelumnya, lalu panggil update() seperti ditunjukkan dalam contoh berikut:

ongoingActivity.update(context, newStatus)
AlwaysOnService.kt

Jika tidak memungkinkan untuk menyimpan referensi ke Aktivitas Berkelanjutan, ada metode statis untuk memulihkan Aktivitas Berkelanjutan. Namun, hal ini kurang disarankan:

OngoingActivity.recoverOngoingActivity(context)
    ?.update(context, newStatus)
AlwaysOnService.kt

Menghentikan Aktivitas Berkelanjutan

Setelah selesai berjalan sebagai Aktivitas Berkelanjutan, aplikasi hanya perlu membatalkan notifikasi berkelanjutan.

Anda juga dapat memilih untuk membatalkan notifikasi atau Aktivitas Berkelanjutan saat muncul di latar depan, lalu membuatnya kembali saat kembali ke latar belakang, tetapi hal ini tidak wajib.

Menjeda Aktivitas Berkelanjutan

Jika aplikasi Anda memiliki tindakan berhenti yang eksplisit, lanjutkan Aktivitas Berkelanjutan setelah tidak dijeda lagi. Untuk aplikasi tanpa tindakan berhenti yang eksplisit, akhiri aktivitas ketika dijeda.

Pertimbangan utama

Perhatikan hal-hal berikut saat menggunakan Ongoing Activity API:

• Tetapkan ikon statis untuk Aktivitas Berkelanjutan, baik secara eksplisit atau sebagai pengganti menggunakan notifikasi. Jika tidak, Anda akan mendapatkan IllegalArgumentException.

• Gunakan ikon vektor hitam putih dengan latar belakang transparan.

• Tetapkan intent sentuh untuk Aktivitas Berkelanjutan, secara eksplisit atau sebagai pengganti menggunakan notifikasi. Jika tidak, Anda akan mendapatkan IllegalArgumentException.

• Jika aplikasi Anda memiliki lebih dari satu aktivitas MAIN LAUNCHER yang dideklarasikan dalam manifes, publikasikan pintasan dinamis dan kaitkan dengan Aktivitas Berkelanjutan menggunakan LocusId.

Memublikasikan notifikasi media saat memutar media di perangkat Wear OS

Jika konten media diputar di perangkat Wear OS, publikasikan notifikasi media. Hal ini memungkinkan sistem membuat aktivitas berkelanjutan yang sesuai.

Jika Anda menggunakan Media3, notifikasi akan dipublikasikan secara otomatis. Jika Anda membuat notifikasi secara manual, notifikasi tersebut harus menggunakan MediaStyleNotificationHelper.MediaStyle, dan MediaSession yang sesuai harus memiliki aktivitas sesi yang terisi.