Insignias para íconos de apps

La API de App Badging permite que las apps web instaladas establezcan una insignia para toda la aplicación en el ícono de la app.

Pete LePage

¿Qué es la API de App Badging?

Ejemplo de Twitter con ocho notificaciones y otra app que muestra una insignia de tipo bandera.
Ejemplo de Twitter con ocho notificaciones y otra app que muestra una insignia de tipo de bandera.

La API de App Badging permite que las apps web instaladas establezcan una insignia para toda la aplicación, que se muestra en un lugar específico del sistema operativo asociado con la aplicación (como la biblioteca o la pantalla principal).

Las insignias permiten notificar al usuario de forma sutil que hay actividad nueva que podría requerir su atención o indicar una pequeña cantidad de información, como un recuento de elementos no leídos.

Las insignias suelen ser más fáciles de usar que las notificaciones y se pueden actualizar con mucha más frecuencia, ya que no interrumpen al usuario. Además, como no interrumpen al usuario, no necesitan su permiso.

Posibles casos de uso

Estos son algunos ejemplos de apps que podrían usar esta API:

  • Apps de chat, correo electrónico y redes sociales, para indicar que llegaron mensajes nuevos o mostrar la cantidad de elementos no leídos
  • Apps de productividad, para indicar que se completó una tarea en segundo plano de larga duración (como renderizar una imagen o un video)
  • Juegos, para indicar que se requiere una acción del jugador (p.ej., en ajedrez, cuando es el turno del jugador).

Asistencia

La API de App Badging funciona en Windows y macOS, en Chrome 81 y Edge 81 o versiones posteriores. La compatibilidad con ChromeOS está en desarrollo y estará disponible en una versión futura. En Android, no se admite la API de Badging. En cambio, Android muestra automáticamente una insignia en el ícono de la app web instalada cuando hay una notificación no leída, al igual que con las apps para Android.

Probar

  1. Abre la demostración de la API de App Badging.
  2. Cuando se te solicite, haz clic en Instalar para instalar la app o usa el menú de Chrome para instalarla.
  3. Ábrela como una AWP instalada. Ten en cuenta que debe ejecutarse como una PWA instalada (en la barra de tareas o el dock).
  4. Haz clic en el botón Establecer o Borrar para establecer o borrar la insignia del ícono de la app. También puedes proporcionar un número para el Valor de la insignia.

Cómo usar la API de App Badging

Para usar la API de App Badging, tu app web debe cumplir con los criterios de instalabilidad de Chrome, y los usuarios deben agregarla a sus pantallas principales.

La API de Badge consta de dos métodos en navigator:

  • setAppBadge(number): Establece la insignia de la app. Si se proporciona un valor, establece la insignia en el valor proporcionado. De lo contrario, muestra un punto blanco simple (o cualquier otro indicador según corresponda a la plataforma). Configurar number en 0 es lo mismo que llamar a clearAppBadge().
  • clearAppBadge(): Quita la insignia de la app.

Ambos devuelven promesas vacías que puedes usar para el control de errores.

La insignia se puede establecer desde la página actual o desde el service worker registrado. Para configurar o borrar la insignia (en la página en primer plano o en el service worker), llama a:

// Set the badge
const unreadCount = 24;
navigator.setAppBadge(unreadCount).catch((error) => {
  //Do something with the error.
});

// Clear the badge
navigator.clearAppBadge().catch((error) => {
  // Do something with the error.
});

En algunos casos, es posible que el sistema operativo no permita la representación exacta de la insignia. En esos casos, el navegador intentará proporcionar la mejor representación para ese dispositivo. Por ejemplo, como la API de Badging no es compatible con Android, Android solo muestra un punto en lugar de un valor numérico.

No supongas nada sobre cómo el usuario-agente muestra la insignia. Algunos agentes de usuario pueden tomar un número como "4000" y reescribirlo como "99+". Si saturas la insignia tú mismo (por ejemplo, configurándola en "99"), no aparecerá el signo "+". Sin importar el número real, solo llama a setAppBadge(unreadCount) y deja que el agente de usuario se encargue de mostrarlo de forma adecuada.

Si bien la API de App Badging en Chrome requiere una app instalada, no debes hacer que las llamadas a la API de Badging dependan del estado de instalación. Solo llama a la API cuando exista, ya que otros navegadores pueden mostrar la insignia en otros lugares. Si funciona, funciona. De lo contrario, simplemente no lo hace.

Cómo establecer y borrar la insignia en segundo plano desde un service worker

También puedes configurar la insignia de la app en segundo plano con el trabajador de servicio. Puedes hacerlo a través de la sincronización periódica en segundo plano, la API de Push o una combinación de ambas.

Sincronización periódica en segundo plano

La sincronización periódica en segundo plano permite que un trabajador de servicio sondee el servidor de forma periódica, lo que se podría usar para obtener un estado actualizado y llamar a navigator.setAppBadge().

Sin embargo, la frecuencia con la que se llama a la sincronización no es perfectamente confiable y se llama a discreción del navegador.

API de Web Push

La API de Push permite que los servidores envíen mensajes a los service workers, que pueden ejecutar código JavaScript incluso cuando no se está ejecutando ninguna página en primer plano. Por lo tanto, una inserción del servidor podría actualizar la insignia llamando a navigator.setAppBadge().

Sin embargo, la mayoría de los navegadores, incluido Chrome, requieren que se muestre una notificación cada vez que se recibe un mensaje push. Esto funciona bien para algunos casos de uso (por ejemplo, mostrar una notificación cuando se actualiza el distintivo), pero imposibilita actualizar el distintivo de forma sutil sin mostrar una notificación.

Además, los usuarios deben otorgar permiso de notificación a tu sitio para recibir mensajes push.

Combinación de ambos

Si bien no es perfecta, la combinación de la API de Push y la sincronización periódica en segundo plano proporciona una buena solución. La información de alta prioridad se entrega a través de la API de Push, que muestra una notificación y actualiza la insignia. La información de menor prioridad se entrega actualizando la insignia, ya sea cuando la página está abierta o a través de la sincronización periódica en segundo plano.

Comentarios

El equipo de Chrome quiere conocer tu experiencia con la API de App Badging.

Cuéntanos sobre el diseño de la API

¿Hay algo en la API que no funciona como esperabas? ¿O faltan métodos o propiedades que necesitas para implementar tu idea? ¿Tienes alguna pregunta o comentario sobre el modelo de seguridad?

Informa un problema con la implementación

¿Encontraste un error en la implementación de Chrome? ¿O la implementación es diferente de la especificación?

  • Informa el error en https://new.crbug.com. Asegúrate de incluir la mayor cantidad de detalles posible, instrucciones sencillas para reproducir el error y configura Components como UI>Browser>WebAppInstalls.

Cómo mostrar compatibilidad con la API

¿Planeas usar la API de App Badging en tu sitio? Tu apoyo público ayuda al equipo de Chrome a priorizar funciones y muestra a otros proveedores de navegadores lo importante que es admitirlas.

Vínculos útiles

Foto de héroe de Prateek Katyal en Unsplash