Balon

Balon memudahkan pengguna untuk melihat dan berpartisipasi dalam percakapan.

Balon tertanam dalam sistem Notifikasi. Fitur tersebut mengambang di atas konten aplikasi lain dan mengikuti pengguna ke mana pun mereka menavigasi. Balon dapat diperluas untuk menampilkan fungsionalitas dan informasi aplikasi, serta dapat diciutkan saat tidak digunakan.

Saat perangkat terkunci atau mode layar always-on aktif, balon akan ditampilkan seperti notifikasi pada umumnya.

Balon adalah fitur yang dapat dipilih untuk tidak digunakan. Saat aplikasi menampilkan balon untuk pertama kalinya, dialog izin akan muncul dan menawarkan dua pilihan:

  • Blokir semua balon dari aplikasi - notifikasi tidak diblokir, tetapi tidak akan ditampilkan sebagai balon
  • Izinkan semua balon dari aplikasi - semua notifikasi yang dikirim dengan BubbleMetaData akan muncul sebagai balon

Bubble API

Balon dibuat melalui Notification API, sehingga Anda mengirimkan notifikasi seperti biasa. Jika ingin notifikasi ditampilkan sebagai balon, Anda harus melampirkan sejumlah data tambahan ke notifikasi tersebut.

Tampilan balon yang diperluas dibuat dari aktivitas yang Anda pilih. Aktivitas tersebut perlu dikonfigurasi agar ditampilkan dengan baik sebagai balon. Aktivitas harus dapat diubah ukurannya dan disematkan. Jika tidak memiliki persyaratan ini maka akan ditampilkan sebagai notifikasi.

Kode berikut menunjukkan cara menerapkan balon sederhana:

<activity
  android:name=".bubbles.BubbleActivity"
  android:theme="@style/AppTheme.NoActionBar"
  android:label="@string/title_activity_bubble"
  android:allowEmbedded="true"
  android:resizeableActivity="true"
/>

Jika aplikasi Anda menampilkan beberapa balon dengan jenis yang sama, seperti beberapa percakapan chat dengan kontak berbeda, aktivitas tersebut harus dapat meluncurkan beberapa instance. Pada perangkat yang menjalankan Android 10, notifikasi tidak akan ditampilkan sebagai balon kecuali Anda secara eksplisit menetapkan documentLaunchMode ke "always". Mulai Android 11, Anda tidak perlu secara eksplisit karena sistem secara otomatis menetapkan semua percakapan' documentLaunchMode ke "always".

Untuk mengirim balon, ikuti langkah-langkah berikut:

Kotlin

// Create bubble intent
val target = Intent(context, BubbleActivity::class.java)
val bubbleIntent = PendingIntent.getActivity(context, 0, target, 0 /* flags */)
val category = "com.example.category.IMG_SHARE_TARGET"

val chatPartner = Person.Builder()
    .setName("Chat partner")
    .setImportant(true)
    .build()

// Create sharing shortcut
val shortcutId = generateShortcutId()
val shortcut =
   ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(setOf(category))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.name)
       .build()

// Create bubble metadata
val bubbleData = Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
    .setDesiredHeight(600)
    .build()

// Create notification, referencing the sharing shortcut
val builder = Notification.Builder(context, CHANNEL_ID)
    .setContentIntent(contentIntent)
    .setSmallIcon(smallIcon)
    .setBubbleMetadata(bubbleData)
    .setShortcutId(shortcutId)
    .addPerson(chatPartner)

Java

// Create bubble intent
Intent target = new Intent(mContext, BubbleActivity.class);
PendingIntent bubbleIntent =
    PendingIntent.getActivity(mContext, 0, target, 0 /* flags */);

private val CATEGORY_TEXT_SHARE_TARGET =
    "com.example.category.IMG_SHARE_TARGET"

Person chatPartner = new Person.Builder()
        .setName("Chat partner")
        .setImportant(true)
        .build();

// Create sharing shortcut
private String shortcutId = generateShortcutId();
ShortcutInfo shortcut =
   new ShortcutInfo.Builder(mContext, shortcutId)
       .setCategories(Collections.singleton(CATEGORY_TEXT_SHARE_TARGET))
       .setIntent(Intent(Intent.ACTION_DEFAULT))
       .setLongLived(true)
       .setShortLabel(chatPartner.getName())
       .build();

// Create bubble metadata
Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
        .setDesiredHeight(600)
        .build();

// Create notification, referencing the sharing shortcut
Notification.Builder builder =
    new Notification.Builder(mContext, CHANNEL_ID)
        .setContentIntent(contentIntent)
        .setSmallIcon(smallIcon)
        .setBubbleMetadata(bubbleData)
        .setShortcutId(shortcutId)
        .addPerson(chatPartner);

Jika aplikasi Anda berjalan di latar depan saat balon dikirim, tingkat kepentingan diabaikan dan balon akan selalu ditampilkan (kecuali jika pengguna telah memblokir balon atau notifikasi dari aplikasi Anda).

Membuat balon yang diperluas

Anda dapat mengonfigurasi balon agar otomatis ditampilkan dalam keadaan diperluas. Sebaiknya gunakan fungsi ini hanya jika pengguna melakukan tindakan yang akan menghasilkan balon, seperti mengetuk tombol untuk memulai chat baru. Dalam hal ini, sebaiknya sembunyikan notifikasi awal saat balon dibuat.

Ada beberapa metode yang dapat Anda gunakan untuk menyetel flag yang memungkinkan perilaku berikut: setAutoExpandBubble() dan setSuppressNotification().

Kotlin

val bubbleMetadata = Notification.BubbleMetadata.Builder()
    .setDesiredHeight(600)
    .setIntent(bubbleIntent)
    .setAutoExpandBubble(true)
    .setSuppressNotification(true)
    .build()

Java

Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder()
        .setDesiredHeight(600)
        .setIntent(bubbleIntent)
        .setAutoExpandBubble(true)
        .setSuppressNotification(true)
        .build();

Siklus konten balon

Jika balon diperluas, aktivitas konten akan melewati siklus proses normal, sehingga aplikasi menjadi proses latar depan (jika belum).

Jika balon diciutkan atau ditutup, aktivitas akan dihapus. Hal ini mungkin menyebabkan proses di-cache, lalu dihentikan, tergantung apakah aplikasi memiliki komponen latar depan lainnya yang sedang berjalan atau tidak.

Waktu balon muncul

Untuk mengurangi jumlah gangguan bagi pengguna, balon hanya muncul dalam kondisi tertentu.

Jika aplikasi menargetkan Android 11 atau lebih baru, notifikasi tidak akan muncul sebagai balon kecuali jika memenuhi persyaratan percakapan. Jika aplikasi menargetkan Android 10, notifikasi akan muncul sebagai balon hanya jika satu atau beberapa kondisi ini terpenuhi:

Jika tidak satu pun dari kondisi tersebut terpenuhi, notifikasi akan ditampilkan sebagai ganti balon.

Praktik terbaik

  • Balon menempati ruang layar dan menutup konten aplikasi lainnya. Sebaiknya Anda hanya mengirim notifikasi sebagai balon jika sifatnya cukup penting, seperti komunikasi berkelanjutan, atau jika pengguna secara eksplisit meminta balon untuk konten tertentu.
  • Perhatikan bahwa balon dapat dinonaktifkan oleh pengguna. Dalam hal ini, notifikasi balon akan ditampilkan sebagai notifikasi normal. Anda harus selalu memastikan notifikasi balon Anda juga berfungsi sebagai notifikasi normal.
  • Proses yang diluncurkan dari balon (seperti aktivitas dan dialog) akan muncul di dalam penampung balon. Ini berarti balon dapat memiliki tumpukan tugas. Prosesnya dapat menjadi rumit jika terdapat banyak fungsionalitas atau navigasi dalam balon Anda. Sebaiknya Anda terus mempertahankan fungsi ini sespesifik dan seringan mungkin.
  • Pastikan untuk memanggil super.onBackPressed saat mengganti onBackPressed dalam aktivitas Balon, jika tidak, balon Anda mungkin tidak akan bekerja dengan benar.
  • Saat balon yang diciutkan menerima pesan yang diperbarui, balon akan menampilkan ikon badge untuk menunjukkan pesan yang belum dibaca. Saat pengguna membuka pesan di aplikasi terkait, ikuti langkah-langkah berikut:

Contoh aplikasi

Aplikasi sampel Orang adalah aplikasi percakapan sederhana yang menggunakan balon. Untuk tujuan demonstrasi aplikasi ini menggunakan bot chat. Dalam aplikasi dunia nyata, balon seharusnya hanya digunakan untuk pesan oleh manusia, bukan bot.