使用气泡让用户参与对话

气泡让用户可以轻松查看并参与对话。

图 1. 聊天气泡。

气泡内置于通知系统中。它们悬浮在其他应用内容之上，并随用户一起移动。用户可以展开气泡以显示应用内容并与之互动，还可以在不使用气泡时将其收起。

当设备处于锁定状态或“显示屏始终开启”功能启用时，气泡的显示方式和常规通知相同。

气泡是一种可以选择停用的功能。在应用显示其第一个气泡时，系统会显示一个权限对话框，其中提供两个选项：

• 屏蔽来自您的应用的所有气泡。通知不会被屏蔽，但永远不会显示为气泡。
• 允许来自您的应用的所有气泡。使用 BubbleMetaData 发送的所有通知都会显示为气泡。

Bubble API

气泡是使用 Notification API 创建的，因此您可以照常发送通知。如果您希望通知显示为气泡，请向其中附加额外的数据。

气泡的展开视图是根据您选择的 activity 创建的。将 activity 配置为正确显示为气泡。此 activity 必须可以调整大小且是嵌入式的。如果它不满足其中任何一项要求，都会显示为通知。

以下代码演示了如何实现气泡：

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

如果您的应用显示多个相同类型的气泡（例如与不同联系人的多个聊天对话），则相应 activity 必须能够启动多个实例。在搭载 Android 10 及更低版本的设备上，除非您将 documentLaunchMode 明确设置为 "always"，否则通知不会显示为气泡。从 Android 11 开始，您无需明确设置此值，因为系统会自动将所有对话的 documentLaunchMode 设置为 "always"。

如需发送气泡，请按照以下步骤操作：

1. 按照常规方式创建通知。
2. 调用 BubbleMetadata.Builder(PendingIntent, Icon) 或 BubbleMetadata.Builder(String) 以创建 BubbleMetadata 对象。
3. 使用 setBubbleMetadata() 将元数据添加到通知中。
4. 如果以 Android 11 或更高版本为目标平台，请确保对话泡元数据或通知引用共享快捷方式。
5. 修改您的应用，使其不取消显示为气泡的通知。 如需检查通知 activity 是否以气泡形式启动，请调用 Activity#isLaunchedFromBubble()。取消通知会从屏幕上移除气泡。打开气泡会自动隐藏与其关联的通知。

这些步骤如以下示例所示：

Kotlin

// Create a 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 a 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 a bubble metadata.
val bubbleData = Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
    .setDesiredHeight(600)
    .build()

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

Java

// Create a 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 a 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 a bubble metadata.
Notification.BubbleMetadata bubbleData =
    new Notification.BubbleMetadata.Builder(bubbleIntent,
            Icon.createWithResource(context, R.drawable.icon))
        .setDesiredHeight(600)
        .build();

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

注意 ：首次发送显示气泡的通知时，请确保使用具有 IMPORTANCE_MIN 或更高级别的通知渠道。

如果应用在发送气泡时位于前台，系统会忽略重要性并始终显示气泡，除非用户屏蔽来自应用的气泡或通知。

创建展开的气泡

您可以将气泡配置为自动以展开状态显示。我们建议您仅在用户执行会导致显示气泡的操作（例如点按按钮以开始新的聊天）时才使用此功能。在这种情况下，还有必要禁止显示在创建气泡时发送的初始通知。

您可以使用以下方法设置启用这些行为的标志：setAutoExpandBubble() 和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();

气泡内容生命周期

如果展开气泡，内容 activity 会完成常规进程生命周期，这会使应用成为前台进程（如果应用尚未在前台运行）。

当气泡被收起或关闭时，系统会销毁该 activity。这可能会导致系统缓存进程，并在之后将其终止，具体取决于应用是否有其他前台组件正在运行。

何时显示气泡

为减少对用户的干扰，气泡仅在特定情况下显示。

如果应用以 Android 11 或更高版本为目标平台，那么除非通知符合对话要求，否则将不会显示为气泡。如果应用以 Android 10 或更低版本为目标平台，则只有在满足以下一个或多个条件时，通知才会显示为气泡：

• 通知使用 MessagingStyle，并添加了 Person。
• 通知来自对 Service.startForeground 的调用，category 为 CATEGORY_CALL，并添加了 Person。
• 发送通知时，应用在前台运行。

如果上述条件均不满足，系统就会显示通知而不显示气泡。

注意： Android 10 不支持开箱即用气泡。 若要看到对话泡显示方式，您需要启用开发者选项，在“设置”菜单中搜索“对话泡”，然后启用“对话泡”设置。

从气泡启动 activity

当气泡启动新 activity 时，新 activity 将在同一任务和同一气泡窗口中启动，或在新的全屏任务中启动，并收起启动它的气泡。

如需在气泡所在的同一任务中启动新 activity，请执行以下操作： 1. 在启动 intent、activity.startActivity(intent) 和 1 时使用 activity 上下文。请勿在 intent 上设置 FLAG_ACTIVITY_NEW_TASK 标志。

否则，新任务中会启动新 activity，并且气泡会收起。

请注意，气泡代表特定对话，因此在气泡内启动的 activity 应与该对话相关。此外，在气泡内启动 activity 会增加气泡的任务堆栈，并且可能会使用户体验变得复杂，尤其是在导航方面。

最佳做法

• 仅当通知非常重要时（例如，属于持续性通信的一部分，或者用户明确要求将内容显示为气泡）才以气泡形式发送通知。气泡会占用屏幕空间，并遮挡其他应用内容。
• 确保您的气泡通知也可以作为一般通知使用。当用户停用气泡通知时，气泡通知会显示为一般通知。
• 在气泡 activity 中替换 onBackPressed 时调用 super.onBackPressed。否则，气泡可能会无法正常运行。

当收起的气泡收到更新的消息时，气泡会显示一个标志图标，表示有未读消息。当用户在关联的应用中打开该消息时，请按以下步骤操作：

• 更新 BubbleMetadata 以抑制通知的显示。调用 BubbleMetadata.Builder.setSuppressNotification()。 这会移除标志图标，以表示用户与消息互动过。
• 将 Notification.Builder.setOnlyAlertOnce() 设置为 true 可禁止涉及 BubbleMetadata 更新的声音或振动。

示例应用

People 示例应用是一个使用气泡的对话式应用。出于演示目的，此应用使用聊天机器人。在真实的应用中，请使用气泡显示人类发送的消息。