Insignias para íconos de apps

La API de App Badging permite que las apps web instaladas establezcan una insignia en todo 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 de marca.
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 app, que se muestra en un lugar específico del sistema operativo asociado con la app (como la biblioteca o la pantalla principal).

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

Las insignias suelen ser más fáciles de usar que las notificaciones y se pueden actualizar con una frecuencia mucho mayor, 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 para 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 el procesamiento de una imagen o un video)
  • Juegos, para indicar que se requiere una acción del jugador (p.ej., en el 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 su lugar, 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 en 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.
  3. Ábrelo como una AWP instalada. Ten en cuenta que debe estar ejecutándose como una AWP instalada (en la barra de tareas o en la estación de carga).
  4. Haz clic en el botón Configurar 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 sin formato (o alguna otra marca según corresponda a la plataforma). Configurar number en 0 es lo mismo que llamar a clearAppBadge().
  • clearAppBadge(): Quita la insignia de la app.

Ambas devuelven promesas vacías que puedes usar para el manejo de errores.

La insignia se puede configurar 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 trabajador de servicio), llama a lo siguiente:

// 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, este solo muestra un punto en lugar de un valor numérico.

No supongas nada sobre cómo el usuario-agente muestra la insignia. Algunos usuarios-agentes pueden tomar un número como "4000" y reescribirlo como "99+". Si saturas la insignia por tu cuenta (por ejemplo, si la estableces en "99"), el signo "+" no aparecerá. No importa el número real, solo llama a setAppBadge(unreadCount) y deja que el usuario-agente se encargue de mostrarlo según corresponda.

Si bien la API de App Badging en Chrome requiere una app instalada, no debes realizar llamadas a la API de Badging según el estado de instalación. Solo llama a la API cuando exista, ya que otros navegadores podrían mostrar la insignia en otros lugares. Si funciona, funciona. De lo contrario, simplemente no lo hará.

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

También puedes establecer la insignia de la app en segundo plano con el service worker. Hazlo 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 periódicamente el servidor, que se podría usar para obtener un estado actualizado, y llame a navigator.setAppBadge().

Sin embargo, la frecuencia con la que se llama a la sincronización no es del todo 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 trabajadores de servicio, que pueden ejecutar código JavaScript incluso cuando no se está ejecutando una página en primer plano. Por lo tanto, un envío 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 de aplicación. Esto es adecuado para algunos casos de uso (por ejemplo, mostrar una notificación cuando se actualiza la insignia), pero hace imposible actualizar la insignia de forma sutil sin mostrar una notificación.

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

Combinación de ambos

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

Comentarios

El equipo de Chrome quiere conocer tus experiencias 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?

Denuncia 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 un error en https://new.crbug.com. Asegúrate de incluir la mayor cantidad de detalles posible, instrucciones simples para la reproducción y establece Components en UI>Browser>WebAppInstalls. Glitch es ideal para compartir reproducciones rápidas y fáciles.

Cómo mostrar compatibilidad con la API

¿Planeas usar la API de App Bauting en tu sitio? Tu asistencia pública ayuda al equipo de Chrome a priorizar funciones y les muestra a otros proveedores de navegadores la importancia de admitirlas.

Vínculos útiles

Foto hero de Prateek Katyal en Unsplash