Nivel avanzado6 min de lectura · Publicado el

Push API: notificaciones web con Service Workers

Push API: el servidor envía el mensaje a la dirección de la suscripción, el endpoint, y el Service Worker lo recoge y muestra la notificación. Push API, con la web cerradarubentejera.com servidorendpointServiceWorkerHola
El navegador abre un apartado de correos a nombre de tu web: el endpoint. Tu servidor manda ahí el mensaje y el Service Worker, de cartero, lo recoge y muestra la notificación, aunque la web esté cerrada.

La Push API es la interfaz del navegador que permite a tu servidor enviar notificaciones push a una web, aunque el usuario la tenga cerrada, a través de un Service Worker. Piensa en un apartado de correos: el navegador abre uno a nombre de tu web y te da la dirección. Cuando tienes algo que contar, lo envías ahí, y el Service Worker, que hace de cartero, lo recoge aunque no estés en casa.

Vídeo: introducción a Service Workers y Push API

Gracias a Carlos Blé por esta introducción:

El vídeo es la grabación de una clase de Carlos Blé con la Generación K, publicada el 20 de junio de 2018 en su canal «Carlitos y sus cosas». Dura algo más de una hora y, según su descripción, trata los Service Workers y la Push API. Al ser de 2018, el código de ejemplo puede no coincidir con la sintaxis actual; los pasos de abajo están actualizados.

Las piezas

Pieza Qué hace
Service Worker Script que el navegador ejecuta en segundo plano. Recibe el evento push
PushManager.subscribe() Pide al navegador una suscripción al servicio de push
PushSubscription El resultado: un endpoint (URL única) y las claves para cifrar
Claves VAPID Par de claves de tu servidor; demuestran que el mensaje viene de ti
showNotification() Muestra la notificación cuando llega el mensaje
Flujo de la Push API en dos fases. Suscripción: en el navegador, subscribe() con la clave pública VAPID devuelve una PushSubscription, con el endpoint y las claves, y tu servidor la guarda. Envío del mensaje: el servidor llama a sendNotification() con su clave privada VAPID, el mensaje llega al servicio de push en el endpoint, el Service Worker recibe el evento push y showNotification() muestra la notificación aunque la web esté cerrada.
Sigue las flechas: la suscripción viaja del navegador a tu servidor; cada mensaje hace el camino de vuelta, del servidor al endpoint y de ahí al Service Worker.

Las notificaciones push son una de las piezas de una aplicación web progresiva (PWA).

Paso a paso

  1. Genera las claves VAPID de tu servidor.
  2. Registra el Service Worker y suscribe al usuario.
  3. Envía la suscripción a tu servidor y guárdala.
  4. Manda el mensaje desde el servidor.
  5. Muestra la notificación en el Service Worker.

1. Genera las claves VAPID

npx web-push generate-vapid-keys

Te da una clave pública (va al navegador) y una privada (se queda en el servidor).

2. Suscribe al usuario en el navegador

// Llámalo desde un clic: Firefox exige un gesto del usuario
async function suscribirse(clavePublicaVapid) {
  const registro = await navigator.serviceWorker.register("/sw.js");
  const suscripcion = await registro.pushManager.subscribe({
    userVisibleOnly: true, // Chrome y Edge lo exigen
    applicationServerKey: clavePublicaVapid,
  });

  await fetch("/suscripciones", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(suscripcion),
  });
}

3. Muestra la notificación en el Service Worker

// sw.js
self.addEventListener("push", (event) => {
  const datos = event.data?.json() ?? { titulo: "Novedades" };
  event.waitUntil(
    self.registration.showNotification(datos.titulo, { body: datos.texto })
  );
});

4. Envía el mensaje desde Node

// enviar.mjs
import * as webpush from "web-push";

webpush.setVapidDetails(
  "mailto:[email protected]",
  process.env.VAPID_PUBLICA,
  process.env.VAPID_PRIVADA
);

// La suscripción que guardaste en el paso 2
const suscripcion = JSON.parse(process.env.SUSCRIPCION);

await webpush.sendNotification(
  suscripcion,
  JSON.stringify({ titulo: "Hola", texto: "Mensaje desde el servidor" })
);

Compatibilidad

Navegador Desde Detalle
Chrome 42 Exige applicationServerKey
Edge 17 Exige applicationServerKey
Firefox 44 Desde la 72, solo tras un gesto del usuario
Safari (macOS) 16 Notificaciones desde macOS Ventura
Safari (iOS/iPadOS) 16.4 Solo en webs añadidas a la pantalla de inicio

Para quién es y lo que conviene saber

Encaja si ya manejas JavaScript asíncrono (promesas y await) y tienes una web propia a la que quieres añadir avisos: un mensaje nuevo, un pedido que cambia de estado, un recordatorio. Si buscas solo avisar mientras la página está abierta, no necesitas Push API: basta con la Notifications API o con actualizar la página.

  • Funciona solo con HTTPS (en desarrollo, localhost también vale).
  • El usuario puede negar o retirar el permiso en cualquier momento: tu web debe funcionar igual sin notificaciones.
  • En iPhone y iPad, Safari 18.4 añadió además Declarative Web Push, una variante que muestra la notificación sin necesitar un Service Worker. Por ahora es propia de WebKit.

Alternativas

  • Firebase Cloud Messaging (web): el SDK de Google se apoya en la misma Push API y te ahorra gestionar las claves y el envío, a cambio de depender de Firebase.
  • Hacerlo con web-push, como arriba: más piezas a tu cargo, pero sin depender de un servicio de terceros.

Ejemplos para practicar

Dos repositorios de ejemplo, forks de los originales:

  • Gracias a Carlos Blé: simple-push-api-example, un chat que usa la Push API (fork de carlosble/simple-push-api-example).
  • Gracias a Carlos González: sw-task-scheduler, una prueba de concepto de planificador de tareas dentro de un Service Worker (fork de cgrs/sw-task-scheduler).

Si quieres repasar la base asíncrona que hay detrás (promesas y await), mira Programación asíncrona con JavaScript, de Carlos Blé y this en JavaScript.

Fuentes

  • MDN: Push API y PushManager.subscribe(), contenido de mdn/content consultado el 7 de noviembre de 2026.
  • Tabla de compatibilidad: @mdn/browser-compat-data 8.1.8.
  • WebKit: Web Push for Web Apps on iOS and iPadOS.
  • web-push 4.0.0: README de la librería.
  • Ejecutado con Node 24.21.0 y web-push 4.0.0: npx web-push generate-vapid-keys y, con una suscripción de prueba, generateRequestDetails(), que prepara la misma petición cifrada que envía sendNotification() sin mandarla. El código del navegador y del Service Worker no se ha ejecutado; está comprobado contra MDN.
  • Título, autor, fecha (20 de junio de 2018), duración (61 min) y descripción del vídeo, comprobados en YouTube (oEmbed y ficha del vídeo).
  • WebKit, WebKit Features in Safari 18.4: Declarative Web Push en iOS y iPadOS 18.4.
  • Firebase, Get started with Firebase Cloud Messaging in Web apps.
  • Los repositorios de ejemplo (forks y originales) responden y siguen en GitHub.