Has implementado manifest.json, registrado el Service Worker, realizado pruebas y todo funciona.
Sin embargo, una semana después, los usuarios ven una versión obsoleta del sitio, Google indexa páginas incorrectas
y las analíticas muestran la mitad de las visitas reales.
Spoiler: el 90% de estos problemas son consecuencia de errores típicos en la integración de PWA que son fáciles de evitar si se conocen de antemano.
⚡ En resumen
- ✅ El almacenamiento en caché de HTML es el error más peligroso: los usuarios ven contenido desactualizado y usted ni siquiera lo sabe.
- ✅ El Service Worker puede bloquear las actualizaciones: sin una estrategia de activación correcta, el código antiguo vive para siempre.
- ✅ PWA en iOS tiene limitaciones únicas: Safari limpia la caché tras 7 días de inactividad.
- 🎯 Obtendrá: 8 análisis detallados con el formato "Escenario → Problema → Solución" y código listo para cada situación.
- 👇 A continuación: ejemplos reales, fragmentos de código y lista de verificación.
📚 Contenido del artículo
🎯 Error 1. Caché de páginas HTML (el error más peligroso)
Caché de HTML dinámico
Si el Service Worker almacena en caché páginas HTML bajo la estrategia Cache First, los usuarios se quedan estancados
permanentemente en la versión antigua del sitio. No verán nuevos productos, promociones ni correcciones de errores
hasta que limpien manualmente la caché del navegador.
Almacenar en caché CSS y JS es correcto. Almacenar HTML con Cache First es el camino hacia actualizaciones invisibles.
📋 Escenario
Ha desplegado una PWA para una tienda online. El Service Worker almacena todas las respuestas, incluidas las páginas HTML,
utilizando la estrategia Cache First: primero consulta la caché y solo si no existe, recurre a la red.
Una semana después, actualiza el catálogo de productos, cambia los precios y añade un banner promocional. Pero los usuarios
que ya visitaron el sitio anteriormente siguen viendo la versión antigua.
❌ Problema
La estrategia Cache First para HTML significa que el navegador ni siquiera intenta verificar si existe una versión
más reciente en el servidor. Siempre entrega lo que ya está en la caché. Para recursos estáticos (fuentes,
iconos, librerías) es ideal. Para HTML que cambia, es una catástrofe.
El usuario no ve las actualizaciones, no ve nuevos productos e incluso podría realizar un pedido
de un artículo que ya no está en stock.
✅ Estrategia correcta
Utilice Network First para las páginas HTML: primero se realiza la solicitud al servidor
y solo si la red no está disponible, se muestra la versión cacheada. Así, el usuario siempre recibe
contenido fresco, y la caché sirve únicamente como respaldo para el modo offline.
self.addEventListener('fetch', event => {const url = new URL(event.request.url);
// Recursos estáticos — Cache First (cambian rara vez)
if (url.pathname.match(/.(css|js|png|jpg|woff2)$/)) {
event.respondWith(
caches.match(event.request)
.then(cached => cached || fetch(event.request))
);
return;
}
// Páginas HTML — Network First (siempre contenido fresco)
event.respondWith(
fetch(event.request)
.then(response => {
if (response.ok) {
const clone = response.clone();
caches.open('html-cache').then(cache =>
cache.put(event.request, clone)
);
}
return response;
})
.catch(() => caches.match(event.request))
);
});
Principio clave: separe la caché en dos tipos. Estáticos (CSS, JS, imágenes) —
Cache First con versiones mediante el nombre de la caché. HTML y API — Network First, para asegurar que
los datos estén siempre actualizados.
🎯 El Service Worker bloquea las actualizaciones de página
Service Worker desactualizado
Sin skipWaiting() y una estrategia de activación adecuada, el nuevo Service Worker espera
a que el usuario cierre todas las pestañas del sitio. Esto puede tardar días o semanas; durante todo ese tiempo,
sigue funcionando la versión antigua con posibles errores.
Ha implementado una corrección para un error crítico, pero los usuarios no la reciben porque el antiguo Service Worker sigue "en guardia".
📋 Escenario
Ha encontrado y corregido un error grave en la caché: a algunos usuarios se les mostraba la página
de perfil de otra persona. Ha desplegado el nuevo sw.js con la corrección. Sin embargo, la nueva versión
del Service Worker no se activa: permanece en estado "waiting" hasta que se cierren todas las pestañas con su
sitio web. Los usuarios que mantienen la pestaña abierta constantemente pueden no recibir la actualización durante semanas.
❌ Problema
Por defecto, el navegador no activa un nuevo Service Worker mientras el antiguo esté gestionando al menos una
pestaña abierta. Esto se hace por estabilidad, para que la lógica de caché no cambie repentinamente durante la sesión del usuario.
Pero en la práctica, esto significa que las actualizaciones críticas se quedan atascadas en la cola.
En dispositivos móviles la situación es peor: Safari en iOS puede mantener una PWA "viva" en segundo plano
durante un tiempo prolongado.
✅ Estrategia correcta
Añada skipWaiting() al evento install: esto obliga al nuevo Service Worker
a activarse inmediatamente sin esperar al cierre de pestañas. Y clients.claim() en el evento
activate garantiza que las páginas ya abiertas pasen de inmediato bajo el control del nuevo SW.
Adicionalmente, versione la caché para que los datos antiguos se eliminen automáticamente.
const CACHE_NAME = 'my-app-v3'; // Cambie la versión en cada despliegueself.addEventListener('install', event => {
// No esperamos al cierre de pestañas — activamos inmediatamente
self.skipWaiting();
event.waitUntil(
caches.open(CACHE_NAME)
.then(cache => cache.addAll(STATIC_ASSETS))
);
});
self.addEventListener('activate', event => {
event.waitUntil(
caches.keys().then(keys =>
Promise.all(
// Eliminamos todas las versiones antiguas de la caché
keys.filter(key => key !== CACHE_NAME)
.map(key => caches.delete(key))
)
).then(() => {
// Tomamos el control de todas las pestañas abiertas
return self.clients.claim();
})
);
});
Consejo: Automatice el cambio de versión de la caché. La opción más sencilla es usar
un timestamp o el hash del commit de Git como parte del nombre de la caché. Así, nunca olvidará actualizar la versión
después de un despliegue.
🎯 Error 3. La PWA intercepta la navegación (error de enrutamiento)
Service Worker intercepta rutas ajenas
Si el Service Worker está registrado en el directorio raíz sin filtrado de rutas, interceptará solicitudes al panel de administración, endpoints de API, webhooks y servicios de terceros. Esto provoca errores de autorización, respuestas incorrectas e interfaces bloqueadas.
El administrador no puede entrar al panel de control porque el Service Worker le entrega la página de inicio cacheada en lugar de /admin/login.
📋 Escenario
Tiene un sitio con la parte pública en / y un panel de administración en /admin. El Service Worker está registrado con scope: "/" y cachea todas las solicitudes GET. El administrador accede a /admin/dashboard, pero en lugar del panel, ve la versión cacheada de la página de inicio. O peor aún: las solicitudes de API a /api/webhook de un sistema de pagos son interceptadas por el SW y devuelven HTML en lugar de JSON.
❌ Problema
Por defecto, el Service Worker intercepta todas las solicitudes dentro de su alcance (scope). Si el alcance es la raíz /, procesa absolutamente todo: páginas de cliente, panel de administración, REST API, webhooks y descargas de archivos. Sin un filtrado explícito de rutas, esto genera un comportamiento impredecible, especialmente en páginas autorizadas donde el caché podría mostrar datos de otro usuario.
✅ Estrategia correcta
Defina claramente en el manejador fetch qué rutas debe procesar el Service Worker y cuáles debe ignorar. La regla es simple: todo lo que no sea contenido público para el cliente debe pasar directamente al servidor sin intervención del SW.
self.addEventListener('fetch', event => {const url = new URL(event.request.url);
// Omitimos todo lo que no requiere caché
if (event.request.method !== 'GET') return;
if (url.pathname.startsWith('/api/')) return;
if (url.pathname.startsWith('/admin')) return;
if (url.pathname.startsWith('/webhook')) return;
if (url.pathname.startsWith('/login')) return;
if (url.pathname.startsWith('/register')) return;
if (url.pathname.startsWith('/logout')) return;
// Páginas autorizadas — no cachear
if (url.pathname.startsWith('/dashboard')) return;
if (url.pathname.startsWith('/profile')) return;
if (url.pathname.startsWith('/payment')) return;
// Audio y archivos grandes — no cachear
if (url.pathname.startsWith('/audio')) return;
if (url.pathname.startsWith('/upload')) return;
// Solo contenido público — Network First
event.respondWith(
fetch(event.request)
.then(response => {
if (response.ok) {
const clone = response.clone();
caches.open('public-cache').then(c => c.put(event.request, clone));
}
return response;
})
.catch(() => caches.match(event.request))
);
});
Principio de "Lista Blanca": en lugar de pensar en qué excluir, es mejor definir qué cachear exactamente. Las páginas públicas (inicio, blog, catálogo, FAQ) se cachean; todo lo demás se ignora. Es más seguro que intentar prever todas las rutas prohibidas.
🎯 SPA-navegación sin eventos pageview
La analítica pierde datos
En una Single Page Application (SPA), las transiciones entre páginas ocurren sin recargar el navegador. Google Analytics y otros sistemas solo registran la carga inicial, mientras que las transiciones posteriores son invisibles. Pierde entre el 60% y 80% de los datos reales sobre el comportamiento del usuario.
Según la analítica tiene 1,000 visitas al día. En realidad son 5,000. Pero no lo sabe porque la SPA se "come" los pageviews.
📋 Escenario
Lanzó su PWA como una SPA en React o Vue. El usuario entra en la página principal y Google Analytics registra un pageview. Luego navega al catálogo, abre un producto y lee reseñas, pero todo sucede sin recargar la página (enrutamiento del lado del cliente). GA no registra ninguna de estas acciones. En su informe aparece 1 visita en lugar de 4.
❌ Problema
Google Analytics clásico registra un pageview al cargar la página, cuando el navegador realiza una solicitud completa al servidor. En una SPA esto no ocurre: JavaScript cambia la URL mediante el History API y sustituye el contenido sin recargar. Consecuencias: embudos de conversión incorrectos, subestimación de páginas populares e incapacidad para evaluar la eficacia del contenido o campañas publicitarias.
✅ Estrategia correcta
Monitoree los cambios de URL a través del History API y envíe manualmente un pageview en cada transición. Para Google Analytics 4 (GA4), use el evento page_view. En aplicaciones de servidor (Thymeleaf / Spring Boot) donde cada página es una solicitud completa, este problema es menos relevante, pero si usa navegación AJAX o htmx, verifíquelo.
// Para SPA: rastreamos cada cambio de ruta// React Router, Vue Router o navegación manual
function trackPageView(path) {
gtag('event', 'page_view', {
page_path: path,
page_title: document.title
});
}
// Opción 1: escuchar popstate (botones "atrás/adelante")
window.addEventListener('popstate', () => {
trackPageView(window.location.pathname);
});
// Opción 2: interceptar pushState
const originalPushState = history.pushState;
history.pushState = function() {
originalPushState.apply(this, arguments);
trackPageView(arguments[2]); // el tercer argumento es la URL
};
// Opción 3: para React Router (en el componente raíz)
useEffect(() => {
trackPageView(location.pathname);
}, [location.pathname]);
Importante: si su PWA se basa en renderizado del lado del servidor (Thymeleaf, Django, Laravel) y cada página es una solicitud HTTP independiente, este error no le afecta. GA funcionará correctamente por defecto. El problema es específico de frameworks SPA (React, Vue, Angular).
🎯 Problemas con la URL canonical
Duplicación de páginas en el índice de Google
Una PWA puede crear múltiples versiones de una misma página: ?source=pwa, ?utm_source=homescreen, con o sin barra final (trailing slash). Google las indexa como páginas distintas, diluyendo el peso SEO y creando duplicados en los resultados de búsqueda.
Una sola página: tres URLs en el índice de Google. Su tráfico SEO se divide en tres en lugar de concentrarse en una.
📋 Escenario
En el manifest.json indicó "start_url": "/?source=pwa" para medir cuántas personas acceden desde la PWA instalada. Además, marketing añadió etiquetas UTM para campañas. Como resultado, la misma página de inicio es accesible en /, /?source=pwa y /?utm_source=homescreen. Google detecta tres páginas diferentes con el mismo contenido.
❌ Problema
Los robots de búsqueda indexan la URL completa con todos sus parámetros. Sin una etiqueta canonical correcta, Google no sabe cuál es la versión principal. Puede elegir cualquiera de ellas o penalizarlas como duplicados. Es un problema clásico de "dilución" de autoridad SEO, crítico para sitios donde cada página es un punto de entrada potencial desde buscadores.
✅ Estrategia correcta
Indique siempre la URL canonical sin parámetros de seguimiento. En manifest.json puede mantener el parámetro para analítica, pero en la página, el canonical debe apuntar a la URL limpia. Asegúrese de que el canonical sea idéntico para versiones con y sin barra final.
<!-- En CADA página del sitio --><link rel="canonical" href="[https://example.com/catalog](https://example.com/catalog)">
<!-- Incluso si la URL real es: -->
<!-- [https://example.com/catalog?source=pwa](https://example.com/catalog?source=pwa) -->
<!-- [https://example.com/catalog?utm_source=homescreen](https://example.com/catalog?utm_source=homescreen) -->
<!-- [https://example.com/catalog/](https://example.com/catalog/) (con trailing slash) -->
<!-- manifest.json — aquí el parámetro es válido para analítica -->
{
"start_url": "/?source=pwa"
}
<!-- Ejemplo en Thymeleaf -->
<link rel="canonical" th:href="${pageSEO.canonicalUrl}">
<!-- Controlador Spring Boot -->
// El canonical siempre va sin parámetros
String canonical = "[https://kazkiua.com](https://kazkiua.com)" + request.getRequestURI();
seo.setCanonicalUrl(canonical); // sin ?source=pwa
Verificación: abra Google Search Console → Páginas → Excluidas → "Duplicada sin etiqueta canónica". Si ve sus páginas con parámetros allí, el canonical está mal configurado.
🎯 Olvido de HTTPS en el subdominio
El Service Worker no se registra sin HTTPS
El Service Worker funciona exclusivamente bajo HTTPS (con la única excepción de localhost). Si su subdominio (api.example.com, cdn.example.com) opera bajo HTTP, el SW no podrá cachear recursos de esa fuente.
Dominio principal en HTTPS, pero el CDN de imágenes en HTTP. El Service Worker ignora silenciosamente todas las fotos.
📋 Escenario
Su sitio [https://example.com](https://example.com) usa HTTPS. El Service Worker está registrado y cachea las páginas. Pero las imágenes se cargan desde un CDN en [http://cdn.example.com](http://cdn.example.com) (sin SSL). Al intentar cachear estas imágenes, el SW recibe un error de contenido mixto (mixed content): el navegador bloquea solicitudes HTTP desde una página HTTPS. En modo offline, todas las imágenes desaparecen.
❌ Problema
El requisito de HTTPS se aplica no solo al dominio principal, sino a todos los recursos que se cargan en la página. El contenido mixto es bloqueado por los navegadores modernos. El Service Worker ni siquiera podrá ejecutar un fetch() hacia un recurso HTTP desde una página HTTPS. Este error es traicionero porque todo funciona con internet activo (el navegador carga la imagen directamente), pero falla en offline (el SW no puede entregar lo que no pudo cachear).
✅ Estrategia correcta
Asegúrese de que absolutamente todos los recursos (dominio principal, subdominios, CDN, APIs externas) funcionen mediante HTTPS. Use certificados gratuitos como Let's Encrypt. Para servicios de CDN (Cloudinary, AWS CloudFront, Cloudflare), el HTTPS suele estar activo por defecto; verifíquelo.
<!-- ❌ INCORRECTO: mixed content --><img src="[http://cdn.example.com/photo.jpg](http://cdn.example.com/photo.jpg)">
<script src="[http://analytics.example.com/tracker.js](http://analytics.example.com/tracker.js)"></script>
<!-- ✅ CORRECTO: todo por HTTPS -->
<img src="[https://cdn.example.com/photo.jpg](https://cdn.example.com/photo.jpg)">
<script src="[https://analytics.example.com/tracker.js](https://analytics.example.com/tracker.js)"></script>
<!-- ✅ O BIEN: URL relativa al protocolo (usa el protocolo de la página) -->
<img src="//[cdn.example.com/photo.jpg](https://cdn.example.com/photo.jpg)">
Verificación rápida: abra DevTools → Console y busque advertencias de "Mixed Content". O vaya a la pestaña Security para revisar el estado de cada recurso.
🎯 Error 7. manifest.json sin el scope correcto
La PWA "captura" URLs ajenas
El parámetro scope en manifest.json define qué URLs pertenecen a su PWA. Sin él o con un scope demasiado amplio, la PWA puede interceptar la navegación hacia servicios externos, pasarelas de pago y páginas de OAuth, rompiendo flujos críticos.
El usuario hace clic en "Pagar" y, en lugar de ir a la página de pago, ve un error porque la PWA intenta abrirla en su propia ventana.
📋 Escenario
Su PWA está instalada en la pantalla de inicio. El usuario tramita un pedido y pulsa "Pagar". El sitio redirige a [https://pay.example.com/checkout](https://pay.example.com/checkout), una pasarela externa. Sin embargo, la PWA abre esta URL en su ventana standalone en lugar de un navegador externo. La página de pago no funciona correctamente sin un entorno de navegador completo y el pago falla.
❌ Problema
Si no se especifica el scope en manifest.json, el navegador lo determina automáticamente según la ubicación del manifiesto. Esto puede provocar que la PWA considere como propias URLs que no le pertenecen. Los enlaces externos que deberían abrirse en el navegador (pagos, OAuth, redes sociales) se abren en la ventana de la PWA y, a menudo, dejan de funcionar.
✅ Estrategia correcta
Indique explícitamente el scope en manifest.json. Para la mayoría de los sitios, es "/" (la raíz de su dominio). Las URLs fuera del scope se abrirán automáticamente en el navegador externo. Para enlaces externos en su HTML, añada siempre target="_blank".
// manifest.json{
"name": "My PWA",
"short_name": "MyPWA",
"start_url": "/",
"scope": "/",
"display": "standalone",
"background_color": "#ffffff",
"theme_color": "#4f46e5"
}
// Si la PWA reside en un subdirectorio:
{
"start_url": "/app/",
"scope": "/app/"
}
// En HTML — abrimos enlaces externos en el navegador
<a href="[https://pay.example.com/checkout](https://pay.example.com/checkout)"
target="_blank"
rel="noopener noreferrer">
Pagar
</a>
<a href="[https://accounts.google.com/oauth](https://accounts.google.com/oauth)"
target="_blank"
rel="noopener noreferrer">
Iniciar sesión con Google
</a>
Regla: todo lo que salga de su dominio (pagos, OAuth, redes sociales) debe tener target="_blank". Esto garantiza la apertura en el navegador completo independientemente de la configuración del scope.
🎯 iOS Safari limpia la caché tras 7 días
Apple elimina los datos de la PWA por inactividad
Safari en iOS limpia automáticamente toda la caché de la PWA (Cache API, IndexedDB, LocalStorage) si el usuario no ha abierto la aplicación durante 7 días. Esto significa que la funcionalidad offline, los datos guardados e incluso la sesión de usuario desaparecen sin previo aviso.
El usuario abre la PWA tras una semana de vacaciones y empieza de cero: sesión cerrada, datos perdidos y caché vacía.
📋 Escenario
Ha creado una PWA para leer artículos offline. El usuario guardó 20 artículos para leer en el avión, pero su vuelo se retrasó 10 días. Cuando finalmente abre la PWA, la caché está vacía. Safari eliminó todos los datos porque la aplicación no se usó en más de una semana. Sin advertencias, solo una pantalla vacía.
❌ Problema
Apple implementó la política Intelligent Tracking Prevention (ITP), que limita el almacenamiento de datos. Para las PWA en iOS, esto implica que si no hay interacción en 7 días, Safari tiene derecho a borrar todo lo escrito por JavaScript. Esta restricción no afecta a las apps nativas de la App Store, solo a las PWA. En Android esta limitación no existe.
✅ Estrategia correcta
Es imposible evitar completamente esta restricción, ya que es una decisión de Apple a nivel de sistema operativo. Sin embargo, puede minimizar las consecuencias: no confíe en la caché del cliente como único almacenamiento, guarde los datos críticos en el servidor y, al abrir la PWA, verifique siempre la integridad de la caché, restaurándola si es necesario.
// En cada inicio de la PWA — verificamos el estado de la cachéasync function checkAndRestoreCache() {
const cache = await caches.open('my-app-v3');
const keys = await cache.keys();
if (keys.length === 0) {
console.log('Caché vacía — restaurando recursos base');
await cache.addAll(STATIC_ASSETS);
// Si hay autenticación — verificamos el token
const token = localStorage.getItem('auth_token');
if (!token) {
// El token también fue eliminado — redirigir al login
window.location.href = '/login';
}
}
}
// Ejecutar al cargar
if ('serviceWorker' in navigator) {
checkAndRestoreCache();
}
Regla de oro para iOS: la caché del cliente es una optimización de velocidad, no un almacenamiento fiable. Todo lo importante debe estar en el servidor. La caché puede desaparecer en cualquier momento y su aplicación debe estar preparada.
❓ Preguntas frecuentes (FAQ)
¿Es necesario un Service Worker si mi sitio es de servidor (Thymeleaf, Django, Laravel)?
Sí, si desea funcionalidad PWA: instalación, modo offline y carga rápida. No obstante, la estrategia será más sencilla: Network First para HTML y Cache First para estáticos. Los problemas específicos de SPA (Error 4) no le afectan.
¿Cómo compruebo si mi Service Worker funciona correctamente?
Chrome DevTools → Application → Service Workers. Aquí verá el estado (active, waiting, redundant) y podrá forzar su actualización. La pestaña Cache Storage mostrará qué hay cacheado. También puede ejecutar Lighthouse → PWA para ver una lista de problemas.
¿Se puede revocar un Service Worker si "rompe" el sitio?
Sí. Despliegue un nuevo sw.js con un manejador fetch vacío o utilice self.registration.unregister(). En casos extremos, el usuario puede eliminarlo manualmente en la configuración del navegador.
¿Afecta la PWA al SEO?
Positivamente, si está bien configurada. Mejora los Core Web Vitals, un factor de ranking en Google. Sin embargo, errores de caché en HTML (Error 1) o duplicados de canonical (Error 5) pueden perjudicar su posicionamiento.
✅ Conclusiones y lista de verificación
Al integrar PWA en mi proyecto Kazki AI —un servicio de audiocuentos personalizados para niños basado en Spring Boot— me enfrenté a la mayoría de estos errores en producción. Por eso he recopilado este material: cada escenario es fruto de mi propia experiencia o de problemas observados en colegas desarrolladores.
La conclusión principal es clara: una PWA no es solo añadir un manifest.json. Es una decisión arquitectónica que afecta al caché, la analítica, el SEO y la seguridad. En Android la experiencia es fluida; en iOS es más compleja debido a la falta de banners automáticos y la volatilidad de la caché.
El error más crítico es el uso de Cache First para HTML, ya que hace las actualizaciones invisibles para el usuario. Para Kazki AI, donde el contenido es dinámico, esto habría sido desastroso. Por ello, opté por Network First para HTML y excluí de la caché las páginas autorizadas y archivos de audio pesados.
Mi lista de verificación antes de cada despliegue de PWA:
1. Caché: HTML en Network First, estáticos en Cache First con versionado.
2. Actualización de SW: skipWaiting() + clients.claim() + nuevo nombre de caché.
3. Enrutamiento: API, administración y pagos excluidos del SW.
4. Analítica: eventos pageview manuales para cada transición (en SPA).
5. Canonical: URLs limpias sin parámetros UTM en cada página.
6. HTTPS: cifrado en todos los recursos, subdominios y CDN.
7. Scope: definición explícita del alcance y enlaces externos con target="_blank".
8. iOS: persistencia de datos críticos exclusivamente en el servidor.
Esta revisión me toma 5 minutos antes de cada release de Kazki AI, pero ahorra horas de depuración. Espero que esta guía le ayude a lanzar una PWA robusta que realmente mejore la experiencia de sus usuarios.
📖 Fuentes y enlaces útiles
Ключові слова:
PWAWorkeriOSService Worker
