Usa burbujas para permitir que los usuarios participen en conversaciones

Las burbujas permiten que los usuarios vean las conversaciones y participen en ellas con mayor facilidad.

Las burbujas están integradas en el sistema de notificaciones. Flotan sobre otro contenido de la app y siguen al usuario a donde vaya. Los usuarios pueden expandir las burbujas para revelar la información y las funciones de la app, y contraerlas cuando no las estén usando.

Cuando el dispositivo está bloqueado o la pantalla siempre activa está activa, las burbujas aparecen como notificaciones normalmente.

Las burbujas se pueden inhabilitar. Cuando aparece la primera burbuja de una app, un diálogo de permisos ofrece dos opciones:

• Bloquea todas las burbujas de tu app. Las notificaciones no se bloquean, pero nunca aparecen como burbujas.
• Permite todas las burbujas de tu app. Todas las notificaciones que se envíen con BubbleMetaData aparecerán como burbujas.

La API de burbujas

Las burbujas se crean mediante la API de notificaciones, por lo que debes enviar la notificación como siempre. Si quieres que tu notificación se muestre como una burbuja, adjunta datos adicionales a ella.

La vista expandida de una burbuja se crea a partir de una actividad que elijas. Configura la actividad para que se muestre correctamente como una burbuja. Se debe poder cambiar de tamaño y se debe poder incorporar. En cambio, si falta alguno de estos requisitos, se mostrará como una notificación.

En el siguiente código, se demuestra cómo implementar una burbuja sencilla:

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

Si tu app muestra varias burbujas del mismo tipo, como varias conversaciones de chat con diferentes contactos, la actividad debe poder iniciar varias instancias. En los dispositivos que ejecutan Android 10 y versiones anteriores, las notificaciones no se muestran como burbujas, a menos que configures documentLaunchMode en "always" de forma explícita. A partir de Android 11, no necesitas establecer este valor de forma explícita, ya que el sistema establece automáticamente el documentLaunchMode de todas las conversaciones en "always".

Para enviar una burbuja, sigue estos pasos:

1. Crea una notificación como lo haces normalmente.
2. Llama a BubbleMetadata.Builder(PendingIntent, Icon) o BubbleMetadata.Builder(String) para crear un objeto BubbleMetadata.
3. Usa setBubbleMetadata() para agregar los metadatos a la notificación.
4. Si la orientas a Android 11 o versiones posteriores, asegúrate de que la notificación o los metadatos de la burbuja hagan referencia a un acceso directo de uso compartido.

Estos pasos se muestran en el siguiente ejemplo:

// 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)

// 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);

Si la app está en primer plano cuando se envía una burbuja, se ignora la importancia y la burbuja siempre se muestra, a menos que el usuario bloquee las burbujas o las notificaciones de la app.

Cómo crear una burbuja expandida

Puedes configurar tu burbuja para presentarla en estado expandido automáticamente. Recomendamos usar esta funcionalidad únicamente si el usuario realiza una acción que genera una burbuja, como presionar un botón para iniciar un nuevo chat. En este caso, también tiene sentido suprimir la notificación inicial enviada cuando se crea una burbuja.

Existen métodos que puedes usar para establecer marcas que habiliten estos comportamientos: setAutoExpandBubble() y setSuppressNotification().

En el siguiente ejemplo, se muestra cómo configurar una burbuja para que se presente automáticamente en un estado expandido:

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

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

Ciclo de vida del contenido del cuadro

Cuando se expande un cuadro, la actividad del contenido pasa por el ciclo de vida del proceso normal, que hace que la aplicación se convierta en un proceso en primer plano, si aún no es así.

Cuando se contrae o descarta el cuadro, se destruye la actividad. Esto puede provocar que el proceso se almacene en caché y, luego, se finalice, dependiendo de si la app tiene otros componentes en primer plano en ejecución.

Cuándo aparecen las burbujas

A fin de reducir las interrupciones para el usuario, las burbujas solo aparecen en determinadas circunstancias.

Si una app está orientada a Android 11 o versiones posteriores, la notificación no aparecerá como una burbuja, a menos que cumpla con los requisitos de conversación. Si una app se orienta a Android 10 o versiones anteriores, la notificación aparece como un cuadro solo si se cumplen una o más de las siguientes condiciones:

• La notificación usa MessagingStyle y tiene agregado un Person.
• La notificación proviene de una llamada a Service.startForeground, tiene un category de CATEGORY_CALL y tiene un Person agregado.
• La app está en primer plano cuando se envía la notificación.

Si no se cumple ninguna de estas condiciones, se muestra la notificación en lugar de una burbuja.

Prácticas recomendadas

• Envía una notificación como cuadro solo si es importante; por ejemplo, cuando forma parte de una comunicación en curso o si el usuario solicita explícitamente un cuadro para el contenido. Las burbujas usan espacio de la pantalla y cubren otro contenido de la app.
• Asegúrate de que la burbuja también funcione como una notificación normal. Cuando el usuario inhabilita el cuadro, se muestra una notificación como una notificación normal.
• La funcionalidad debe ser lo más específica y liviana posible. Los procesos que se inician desde una burbuja, como las actividades y los diálogos, aparecen dentro del contenedor. Esto significa que un cuadro puede presentar una pila de tareas. Las cosas pueden complicarse si hay mucha funcionalidad o navegación dentro de la burbuja.
• Llama a super.onBackPressed cuando anules onBackPressed en la actividad de la burbuja. De lo contrario, es posible que la burbuja no se comporte correctamente.

Cuando una burbuja contraída recibe un mensaje actualizado, aparece un ícono de insignia para indicar que hay un mensaje no leído. Cuando el usuario abra el mensaje en la app asociada, sigue estos pasos:

• Actualiza BubbleMetadata para suprimir la notificación. Llama a BubbleMetadata.Builder.setSuppressNotification(). Esto quita el ícono de insignia para indicar que el usuario interactuó con el mensaje.
• Establece Notification.Builder.setOnlyAlertOnce() en true para suprimir el sonido o la vibración que acompaña a la actualización de BubbleMetadata.

App de ejemplo

La app de ejemplo Personas es una app de conversación simple que usa burbujas. A modo de demostración, esta app usa chatbots. En aplicaciones reales, solo las personas, no los bots, deben usar las burbujas.