Guía definitiva de la API de Notificaciones de JavaScript

Introducción a la API de Notificaciones

La API de Notificaciones permite que una aplicación web muestre mensajes a nivel del sistema operativo fuera de la pestaña del navegador — los pequeños avisos emergentes que el sistema operativo muestra en la esquina de la pantalla. Como aparecen incluso cuando el usuario ha cambiado a otra pestaña o aplicación, las notificaciones son una forma directa de mostrar información urgente: un nuevo mensaje de chat, una subida completada, un recordatorio de calendario.

Esta página cubre el ciclo de vida completo: comprobar que la API está disponible, pedir permiso al usuario, crear y personalizar notificaciones, reaccionar a los clics, y mostrar notificaciones desde un service worker para que sigan funcionando después de que la página se cierre. Termina con las reglas que impiden que las notificaciones se vuelvan molestas.

Algunos aspectos importantes antes de la primera línea de código:

• Las notificaciones requieren una concesión de permiso explícita por parte del usuario. No puedes mostrar ninguna hasta que el permiso sea granted.
• Solo funcionan en un contexto seguro (https://, o http://localhost durante el desarrollo).
• El aspecto y el comportamiento de una notificación los controla el sistema operativo, no tu CSS. Tú proporcionas el contenido; el SO decide cómo renderizarlo.

Comprobación del soporte

Siempre detecta la función antes de usar la API, para que el código se degrade de forma elegante en entornos que no la tienen (navegadores más antiguos, algunas vistas web embebidas y renderizado en el servidor):

if ('Notification' in window) {
  // The Notifications API is available
} else {
  console.log('This browser does not support notifications.');
}

Comprender los permisos

El estado del permiso reside en la propiedad estática Notification.permission y es uno de tres valores de tipo string:

• 'granted' — el usuario ha permitido las notificaciones; puedes mostrarlas.
• 'denied' — el usuario las ha bloqueado; las llamadas para mostrar una notificación se ignoran silenciosamente.
• 'default' — el usuario aún no ha decidido, lo que se trata como 'denied' hasta que preguntes.

Solicita permiso con Notification.requestPermission(). Devuelve una promesa que se resuelve con el string del permiso resultante:

Notification.requestPermission().then((permission) => {
  console.log('Permission:', permission); // 'granted', 'denied', or 'default'
});

Un patrón robusto comprueba el estado actual primero y solo solicita permiso cuando la decisión aún es 'default':

async function ensurePermission() {
  if (Notification.permission === 'granted') {
    return true;
  }
  if (Notification.permission === 'denied') {
    return false; // can't re-prompt; the user must change it in browser settings
  }
  const permission = await Notification.requestPermission();
  return permission === 'granted';
}

La forma basada en promesas se combina de forma natural con async/await y la API de Promise en general.

Crear y mostrar notificaciones

Una vez que el permiso es granted, construye una notificación con el constructor Notification. El primer argumento es el título (obligatorio); el segundo es un objeto de opciones opcional.

if (Notification.permission === 'granted') {
  new Notification('Hello, world!', {
    body: 'Here is the body of the notification.',
    icon: '/icon-192.png'
  });
}

La notificación aparece en el momento en que se crea el objeto — no necesitas llamar a un método "show" por separado.

Opciones comunes

El objeto de opciones acepta muchos campos. Los más útiles:

new Notification('New message', {
  body: 'You have 1 unread message from Alex.',
  icon: '/icon-192.png',
  tag: 'chat-alex',          // replacing an earlier "Alex" notification
  data: { conversationId: 42 },
  requireInteraction: true
});

Evitar el spam de notificaciones con tag

La opción tag es la forma más sencilla de evitar acumular duplicados. Si llegan tres mensajes de la misma persona, reutilizar un tag significa que el usuario ve una única notificación actualizada en lugar de tres:

function notifyUnread(count) {
  new Notification('Inbox', {
    body: `You have ${count} unread messages.`,
    tag: 'inbox-count' // each call updates the same notification
  });
}

Eventos de notificación

Una instancia de Notification lanza eventos a los que puedes suscribirte. El más importante es click, que se lanza cuando el usuario activa la notificación:

const notification = new Notification('Interactive Notification', {
  body: 'Click me to do something',
  icon: '/icon-192.png'
});

notification.onclick = (event) => {
  event.preventDefault();    // stop the browser's default focus behavior
  window.open('https://example.com', '_blank');
  notification.close();      // remove the notification once handled
};

Otros eventos disponibles son show (mostrada), error (error al mostrar) y close (descartada). También puedes adjuntar manejadores con addEventListener — consulta el manejo de eventos en el DOM para el patrón general.

Cerrar notificaciones mediante programación

Llama a close() para descartar una notificación tú mismo — útil para eliminar un aviso de "descargando…" una vez que la descarga termina:

const note = new Notification('Downloading…', { tag: 'download' });

// later, when the work is done:
setTimeout(() => note.close(), 4000);

Notificaciones silenciosas

Establece silent: true para mostrar una notificación sin sonido ni vibración — apropiado para actualizaciones ambientales de baja prioridad:

new Notification('Silent Notification', {
  body: 'This is a silent notification.',
  silent: true
});

Notificaciones desde un service worker

El constructor Notification simple solo funciona mientras una página está abierta. Para entregar notificaciones cuando tu sitio está en segundo plano — o en respuesta a un mensaje push del servidor — muéstralas desde un service worker usando ServiceWorkerRegistration.showNotification():

// In the page: ask the service worker to show a notification
navigator.serviceWorker.ready.then((registration) => {
  registration.showNotification('Background-capable notification', {
    body: 'This can be shown even after the tab is closed.',
    icon: '/icon-192.png',
    actions: [
      { action: 'open', title: 'Open' },
      { action: 'dismiss', title: 'Dismiss' }
    ]
  });
});

Las notificaciones del service worker también admiten botones de acción (el array actions), que el constructor simple no admite. Gestiona los clics dentro del propio service worker:

// In the service worker (sw.js)
self.addEventListener('notificationclick', (event) => {
  event.notification.close();
  if (event.action === 'open') {
    event.waitUntil(clients.openWindow('/inbox'));
  }
});

Esta ruta del service worker es la que impulsa el verdadero push web: un servidor envía un mensaje, la Push API despierta al service worker, y el worker llama a showNotification().

Soporte de navegadores y advertencias

• Solo en contexto seguro. Las notificaciones necesitan HTTPS (o localhost). No funcionarán en páginas http:// simples.
• El permiso es persistente. Una vez que un usuario elige 'denied', no puedes solicitarlo de nuevo desde JavaScript — debe cambiarlo en la configuración de sitios del navegador. No sigas preguntando.
• iOS Safari históricamente no admitía notificaciones web; el soporte llegó solo para sitios añadidos a la pantalla de inicio como PWA. Siempre detecta la función.
• La apariencia la controla el SO. No dependas de un tamaño, posición o estilo específicos — céntrate en un texto claro y breve.

Mejores prácticas

Para que las notificaciones sean una función que los usuarios agradezcan en lugar de silenciar:

• Solicita en contexto, tras un gesto. Pide permiso cuando el usuario acabe de hacer algo que haga que las notificaciones sean obviamente útiles (por ejemplo, activar alertas), nunca en la primera carga.
• Respeta un "no". Si el permiso es 'denied', detente. No es técnicamente posible solicitar permiso de nuevo, y la insistencia en la interfaz erosiona la confianza.
• Sé oportuno y relevante. Envía solo notificaciones que el usuario realmente querría en ese momento.
• Úsalas con moderación. Agrupa con tag, consolida cuando puedas, y reserva las notificaciones para lo que es verdaderamente importante — el exceso de notificaciones entrena a los usuarios a ignorarte o bloquearte.
• Haz que los clics sean significativos. Un clic debería llevar al usuario directamente al contenido relevante, no solo a tu página de inicio.

Conclusión

La API de Notificaciones de JavaScript permite que las aplicaciones web lleguen a los usuarios con mensajes oportunos a nivel del sistema — tanto mientras una página está abierta como, a través de un service worker, después de que se haya cerrado. El flujo de trabajo es coherente: detectar la función, solicitar permiso en respuesta a un gesto del usuario, luego crear notificaciones con el constructor Notification (o showNotification() en un worker) y responder a los eventos de clic. Combinado con un uso disciplinado y moderado, las notificaciones se convierten en una función que los usuarios mantienen habilitada en lugar de apresurarse a desactivar.

Práctica