Badging API: límites de notificaciones PWA

Una insignia de una PWA puede responder «hay trabajo pendiente» sin abrir un diálogo de permisos, pero no es un canal de entrega ni un permiso. BotBrowser puede repetir una página autorizada que llama a navigator.setAppBadge() y navigator.clearAppBadge() y registrar la rama de capacidad visible; no puede añadir soporte de Badging API, entregar Web Push ni demostrar que un conteo privado sea seguro. Para el flujo que llega por un worker, consulta ciclo de vida y privacidad de Web Push; para contenido compartido, entrada PWA con Web Share Target trata otro límite.

TL;DR

• setAppBadge() solicita un número o un punto en el acceso directo de la app; clearAppBadge() elimina ese estado.
• Una insignia es una pista de presentación. No pide permiso de notificaciones, no despierta un worker, no entrega push y no confirma que alguien leyó el trabajo.
• Usa un conteo útil y limitado. Reduce valores grandes, evita identificadores y categorías sensibles, y limpia cuando el trabajo correspondiente queda realmente reconocido.
• Detecta navigator.setAppBadge y navigator.clearAppBadge; si faltan, ofrece una alternativa honesta dentro de la app.
• Mantén separados badge, Notification, PushManager y registros de entrega del servidor.

Contents

• Definir el contrato de la insignia
• Elegir números, puntos y momentos de limpieza
• Construir una alternativa no compatible
• Separar insignias, push y notificaciones
• Minimizar conteos y verificar límites
• Practical conclusion

Definir el contrato de la insignia

La especificación W3C Badging expone setAppBadge() y clearAppBadge() en Navigator. Apuntan a la representación de la aplicación en un lanzador o selector de tareas, no a un elemento DOM. El sistema operativo puede mostrar un número, un punto o nada según instalación, navegador y preferencias. Una promesa resuelta significa que el navegador aceptó la solicitud, no que el lanzador pintó unos píxeles concretos.

Un número debe resumir trabajo pendiente que la persona puede realizar. navigator.setAppBadge(3) no crea tres notificaciones ni demuestra que llegaron tres mensajes. navigator.setAppBadge() sin argumento solicita una insignia no numérica. Usa el punto cuando el número es incierto o revela demasiado. Las referencias MDN de setAppBadge() y clearAppBadge() describen el contrato, pero no garantizan el mismo dibujo en cada plataforma.

Asigna un solo propietario al estado. La página, el worker y una tarea de sincronización no deben inventar conteos desde instantáneas diferentes. Guarda solo source, countKind, count, updatedAt, revision y outcome; nunca títulos, ids o cuerpos privados. Rechaza una actualización antigua que podría volver a mostrar 4 después de que otra pestaña limpió el badge.

Elegir números, puntos y momentos de limpieza

Un número como 7 es útil cuando guía una decisión. Un contador de reintentos internos o de eventos ocultos no es trabajo de usuario. Limita el valor a 99 y cambia a un punto o a una etiqueta propia 99+ en la interfaz. El límite reduce precisión innecesaria y evita que el lanzador parezca roto. La guía de Chrome sobre Badging ilustra el caso PWA, no la semántica de tu producto.

Limpia con una transición de estado, no con un temporizador. Llama a clearAppBadge() después de que la acción representada fue reconocida o de que una escritura autorizada confirmó el nuevo estado. Abrir una bandeja no siempre equivale a leerla. Si se leen dos de cinco elementos, calcula 3 desde el estado autoritativo; no restes dos de una caché cuando otro dispositivo pudo añadir trabajo.

Una llamada tardía puede revivir un badge viejo. Centraliza las decisiones o conserva una revisión monotónica. Si el origen está desconectado, conserva el último valor con su frescura o muestra un estado offline dentro de la app; no afirmes que el trabajo desapareció. En logout, cambio de cuenta o pérdida de autorización, limpia el badge y elimina el estado local de esa cuenta.

async function applyBadge(state) {
  const { revision, count, acknowledged, supported } = state;
  if (!supported || typeof navigator.setAppBadge !== 'function') {
    return { revision, outcome: 'unsupported', fallback: 'in-app-status' };
  }
  if (acknowledged || count === 0) {
    if (typeof navigator.clearAppBadge !== 'function') {
      return { revision, outcome: 'clear-unsupported', fallback: 'in-app-status' };
    }
    await navigator.clearAppBadge();
    return { revision, outcome: 'cleared' };
  }
  if (state.countKind === 'dot') {
    await navigator.setAppBadge();
    return { revision, outcome: 'dot' };
  }
  const bounded = Math.min(Math.max(0, count), 99);
  await navigator.setAppBadge(bounded);
  return { revision, outcome: 'number', count: bounded };
}

Construir una alternativa no compatible

Comprueba ambos métodos en tiempo de uso:

const canBadge = 'setAppBadge' in Navigator.prototype && 'clearAppBadge' in Navigator.prototype;

Un contexto seguro, modo instalado, versión del navegador, integración del sistema o política administrada pueden cambiar el resultado. La guía MDN de Badging API documenta disponibilidad, pero no permite fingir una insignia del lanzador modificando el icono de otra aplicación.

Cuando falta la API, muestra el mismo estado acotado dentro de la app: un conteo accesible, un título actualizado o una marca visible. Conserva la semántica de limpieza. No uses Web Push como alternativa: push necesita suscripción, worker, permisos y servidor, y no garantiza ejecución en segundo plano. Un resultado compacto como { "capability": "absent", "fallback": "in-app-status" } basta para soporte; no guardes el texto de una conversación.

Separar insignias, push y notificaciones

Notification pide permiso para una notificación del sistema; Badging API no abre ese diálogo. Web Push es una oportunidad de entrega a un worker, no un estado de badge. Notification de MDN, Push API y la guía Push de MDN describen superficies diferentes.

Superficie	Solicita	No demuestra	Propietario
Badging API	número o punto local	píxeles, entrega, lectura	estado coordinado
Notification	permiso y pantalla de sistema	atención o lectura	página o worker
Web Push	oportunidad de entrega	hora de llegada o estado	push y worker

Un push puede actualizar un registro minimizado y una página activa puede reconciliar el badge. El número debe venir del estado no leído autoritativo, no de la cantidad de eventos push. No limpies por mostrar una notificación; limpia después de la acción y escritura que representan el trabajo.

Minimizar conteos y verificar límites

Un número en un lock screen o una captura es una divulgación. Prefiere un punto, un bucket (1, 2-5, 6-20) o un máximo visible. Calcula el agregado después de autorizar y antes de la llamada. Nunca pases un id de usuario o conversación como argumento; la API recibe un número, no una razón.

const record = { fixtureId: 'badge-boundary-01', countKind: 'bounded', count: 3, revision: 18, outcome: 'pending' };
try {
  if (typeof navigator.setAppBadge !== 'function') record.outcome = 'unsupported';
  else if (record.count === 0 && typeof navigator.clearAppBadge === 'function') {
    await navigator.clearAppBadge();
    record.outcome = 'cleared';
  } else if (record.count > 0) {
    await navigator.setAppBadge(Math.min(record.count, 99));
    record.outcome = 'number-requested';
  } else record.outcome = 'clear-unsupported';
} catch (error) {
  record.outcome = error.name === 'NotAllowedError' ? 'policy-error' : 'api-error';
}

Repite el fixture con métodos presentes, ausentes, después de reconocer trabajo y tras una promesa rechazada. Conserva browserVersion, context, revision, countKind y outcome, sin datos de cuenta. BotBrowser puede capturar estas ramas en un contexto autorizado; no puede forzar el dibujo del lanzador, conceder permisos, entregar push ni certificar que un conteo real sea inocuo. Compara el primer campo que cambia después de una actualización del navegador, manifest o worker.

{
  "fixtureId": "badge-boundary-01",
  "context": "installed-pwa",
  "revision": 18,
  "countKind": "bounded",
  "requestedCount": 3,
  "outcome": "number-requested"
}

Fuentes públicas

• Especificación W3C Badging
• MDN: Badging API
• MDN: Navigator.setAppBadge()
• MDN: Navigator.clearAppBadge()
• Chrome Developers: Badging API
• MDN: Notification
• W3C Push API
• MDN: Push API
• MDN: PWA installation
• BotBrowser: consistencia de automatización

Practical conclusion

Usa setAppBadge() para un número o punto limitado y clearAppBadge() cuando el estado fue reconocido o reconciliado. Detecta ambos métodos, conserva una alternativa accesible y guarda solo capacidad, revisión y resultado. Badge, permiso de notificación y entrega Web Push son superficies independientes. BotBrowser puede repetir la máquina de estados sintética, pero el lanzador y la decisión de privacidad quedan fuera. Define primero el propietario del conteo y el evento de limpieza, y repite el fixture tras cada cambio del navegador o worker.