PWA Storefront Pack

Guía completa de instalación, configuración y uso de PWA Storefront Pack: el plugin que convierte su tienda WooCommerce en una Progressive Web App instalable, con modo sin conexión y notificaciones push VAPID nativas (sin Firebase, sin OneSignal, sin suscripción mensual).

Descripción general y principio

PWA Storefront Pack añade a su WooCommerce tres bloques independientes pero complementarios:

• Web App Manifest — sus clientes pueden instalar su tienda en la pantalla de inicio como una app nativa real (icono, splash screen, modo standalone sin barra de direcciones).
• Service Worker — caché inteligente de páginas y recursos, página sin conexión personalizable, exclusiones automáticas de zonas sensibles (carrito, checkout, mi cuenta).
• Notificaciones push VAPID — implementación completa del protocolo Web Push en PHP puro: ECDSA P-256, JWT ES256, cifrado aes128gcm. Su servidor habla directamente con los servicios push de los navegadores.

Requisitos

• WordPress 6.0 o superior
• WooCommerce 7.0 o superior
• PHP 7.4 o superior con la extensión openssl (activada por defecto en todos los hostings)
• HTTPS obligatorio — los navegadores rechazan registrar un Service Worker o gestionar notificaciones push sobre HTTP (excepto en localhost para desarrollo)

Instalación

1. Descargue el archivo pwa-storefront-pack.zip desde su cuenta DataFirefly.
2. En WordPress, vaya a Plugins → Añadir nuevo → Subir plugin.
3. Seleccione el ZIP y haga clic en Instalar ahora, después Activar.
4. Al activar, el plugin crea tres tablas SQL (wp_pwasp_subscriptions, wp_pwasp_push_log, wp_pwasp_stock_waitlist) y genera automáticamente su par de claves VAPID.
5. Vaya a WooCommerce → PWA Storefront para configurar.

Configuración general

La pestaña General centraliza la identidad de su aplicación:

• Enable PWA — interruptor principal. Desactive para retirar temporalmente el manifest y el Service Worker sin desinstalar el plugin.
• App name — nombre completo mostrado durante la instalación y en el splash screen (ej. «Mi Tienda Oficial»).
• Short name — etiqueta corta bajo el icono de la pantalla de inicio, limitada a 12 caracteres por convención Android.
• Theme color — color de la barra de direcciones y del selector de tareas (recomendado: su color de marca principal).
• Background color — fondo del splash screen durante la carga de la app (normalmente blanco o muy claro).

URLs de los endpoints

El plugin sirve dos endpoints críticos:

• https://su-sitio.com/pwasp-manifest.json — el Web App Manifest
• https://su-sitio.com/pwasp-service-worker.js — el Service Worker

Manifest

La pestaña Manifest controla el comportamiento de la app instalada:

• Display mode — standalone por defecto (recomendado, experiencia tipo app). Otras opciones: fullscreen, minimal-ui, browser.
• Orientation — any, portrait o landscape. En móvil, portrait suele ser la más adaptada para tiendas.
• Start URL — ruta donde la app se abre al lanzarse. Por defecto /. Puede apuntar a /tienda para abrir directamente el catálogo.
• Scope — ámbito de URLs controlado por la app. Generalmente /. Restrínjalo solo si la PWA se usa únicamente en una subcarpeta.
• Categories — pistas para las app stores web (Chrome, Edge). Ejemplo: shopping,business.
• Shortcuts — active para generar accesos rápidos Tienda / Carrito / Mi cuenta accesibles mediante pulsación larga en el icono de la pantalla de inicio.

Iconos de la aplicación

La pestaña Icons permite asociar sus iconos desde la biblioteca de medios de WordPress. Se gestionan cinco formatos:

• Icon 192×192 (any purpose) — obligatorio. Usado en Android, en los resultados del motor de búsqueda.
• Icon 512×512 (any purpose) — obligatorio. Icono del splash screen al lanzamiento.
• Maskable 192×192 — opcional. Con margen de seguridad interno del 10 % para iconos adaptativos Android (formas redondas, cuadradas, lágrima).
• Maskable 512×512 — opcional. Mismo principio para el splash screen.
• Apple Touch Icon 180×180 — para iOS. Cuadrado, sin esquinas redondeadas (iOS las añade automáticamente).

Mientras no haya iconos configurados, el plugin utiliza iconos por defecto incluidos (marca DataFirefly). Reemplácelos antes de pasar a producción.

Modo sin conexión y estrategia de caché

La pestaña Offline & Cache configura el comportamiento del Service Worker:

Estrategias

• Network first (recomendado) — el navegador intenta la red primero, luego retrocede al caché si offline. Máxima frescura de precios y stock.
• Cache first — el caché responde inmediatamente, la red actualiza en segundo plano. Más rápido pero puede mostrar precios ligeramente obsoletos.

Las estrategias solo se aplican a las páginas HTML. Los otros tipos de recursos tienen estrategias fijas óptimas:

• CSS / JS / fuentes → cache-first (solo cambian con actualizaciones de versión)
• Imágenes de producto → stale-while-revalidate (visualización inmediata desde caché, refresco en segundo plano)

Alcance del caché

Tres casillas permiten activar/desactivar el caché por tipo:

• Cache HTML pages — páginas de producto, categoría, portada, entradas
• Cache CSS / JS / fonts — el esqueleto de su tema
• Cache images — visuales de producto, imágenes de entradas de blog

Página sin conexión

Dos opciones:

• Usar la pantalla por defecto — pantalla minimalista integrada en el plugin (icono, mensaje, botón Reintentar), con los colores de su marca.
• Usar una página personalizada — seleccione una página WordPress existente. Se pre-cacheará en la instalación del Service Worker y se servirá en caso de fallo de red.

Banner de instalación

La pestaña Install Banner controla la promoción de la instalación:

• Delay (page views) — número de páginas vistas antes de mostrarse. 3 por defecto: el usuario ha manifestado un interés mínimo sin ser hostigado desde la primera visita.
• Banner title / text / CTA / Dismiss — textos totalmente personalizables, traducibles vía .pot.

Comportamiento:

• En Chrome, Edge, Opera, Samsung Internet: el banner aparece cuando el navegador señala que el sitio es instalable (beforeinstallprompt). Un clic en el CTA muestra el diálogo nativo de instalación.
• En iOS Safari: el banner muestra automáticamente las instrucciones «Toque Compartir, después Añadir a pantalla de inicio» (Apple no ofrece API de instalación programática).
• Descarte memorizado 7 días — si el usuario cierra el banner, no reaparece en una semana.
• Detección automática — si la app ya está instalada (modo standalone detectado), el banner ya no se muestra.

Notificaciones push: las claves VAPID

Las notificaciones push usan el protocolo VAPID (Voluntary Application Server Identification), estándar W3C. Al activar el plugin, se genera automáticamente un par de claves ECDSA P-256:

• Clave pública — compartida con los navegadores de los suscriptores (vía JavaScript). 65 bytes, codificada base64url.
• Clave privada — nunca se transmite, sirve para firmar cada envío. 32 bytes.

La pestaña Push Notifications muestra su clave pública en claro y el número de suscripciones activas. Puede copiarla para eventuales pruebas externas.

Regeneración de claves

El botón Regenerate keys genera un par nuevo. Esta operación es destructiva:

VAPID subject

Campo VAPID subject: dirección de contacto en formato mailto:usted@ejemplo.com o https://ejemplo.com/contacto. Algunos servicios push (Mozilla en particular) la usan para contactarle en caso de abuso detectado desde su servidor. Precompletado con el email admin de WordPress.

Opt-in prompt y RGPD

La sección Opt-in prompt configura la pre-invitación mostrada antes del diálogo nativo de permiso:

• Show opt-in prompt — activa la pre-invitación personalizada. Recomendado: el diálogo nativo solo tiene una tasa de rechazo alta y bloquea toda nueva solicitud durante 30 días.
• GDPR consent required — nunca muestra el diálogo nativo sin clic explícito del usuario en su CTA. Requerido en Europa para ser conforme RGPD.
• Delay (seconds) — espera antes de mostrarse. 10 segundos por defecto: dejar al usuario explorar antes de solicitar el permiso.
• Prompt title / text / CTA / Dismiss — textos totalmente personalizables.

Disparadores automáticos

El plugin trae tres automatizaciones conectadas directamente a los hooks WooCommerce. Cada una es activable independientemente.

Estado de pedido

Hook: woocommerce_order_status_changed.
El cliente identificado (no los invitados) recibe una notificación en cada transición de estado de su pedido. Título: «Pedido #1042 actualizado». Cuerpo: «Estado: Enviado». Clic → página de seguimiento del pedido.

La notificación usa una tag única por pedido (order-1042): las actualizaciones sucesivas reemplazan la anterior en lugar de acumularse.

Nuevo pedido (admin)

Hook: woocommerce_new_order.
Todos los usuarios con rol administrator o shop_manager y suscritos a las push reciben una notificación en cada nuevo pedido. Título: «Nuevo pedido recibido». Cuerpo: «Pedido #1042 — 189,00 €». Clic → pantalla de edición del pedido.

La URL admin es HPOS-aware: si su WooCommerce usa High-Performance Order Storage, el enlace apunta al nuevo esquema (admin.php?page=wc-orders). Si no, al antiguo (post.php?post=X).

Vuelta a stock

Hooks: woocommerce_product_set_stock y woocommerce_variation_set_stock.
Cuando un producto pasa de «agotado» a «en stock», el plugin envía una notificación a todos los visitantes que se habían añadido a su lista de espera. Título: «¡De vuelta en stock!». Cuerpo: «Sneakers cuero premium edición limitada está de nuevo disponible». Imagen del producto como vista previa si disponible.

Cada entrada se marca notified_at tras el envío exitoso, para evitar duplicados si el stock oscila.

Compositor de broadcast

Menú: WooCommerce → PWA Broadcast. Interfaz para enviar una notificación manual a todos los suscriptores activos (campañas de marketing, anuncios, etc.).

Campos:

• Title — título de la notificación (100 caracteres máx. recomendados)
• Message — cuerpo de la notificación (200 caracteres máx. recomendados)
• Open URL — página donde el usuario aterriza al hacer clic (por defecto la portada)
• Image URL — imagen grande mostrada en la notificación (Android únicamente, iOS no la muestra)

Una vista previa en tiempo real muestra el renderizado aproximado de la notificación a la derecha de la pantalla.

Dos botones:

• Send broadcast — envío a todos los suscriptores activos (confirmación requerida)
• Send test to me — envío únicamente a sus propias suscripciones. Útil para validar el renderizado antes de un broadcast masivo.

Lista de espera vuelta a stock (API JavaScript)

Para permitir a los visitantes inscribirse en la lista de espera de un producto agotado, llame desde su tema:

window.PWASP.addToWaitlist(productId)
  .then(result => {
    if (result.success) {
      alert('¡Será notificado en cuanto vuelva al stock!');
    }
  });

Comportamiento:

1. Si el usuario aún no está suscrito a las push, se abre el diálogo nativo de permiso.
2. Una vez registrada la suscripción en el servidor, la entrada se añade a la lista de espera del producto.
3. Al detectar la vuelta a stock, una push se envía automáticamente.

Puede llamar esta API desde cualquier botón personalizado o vía un mu-plugin enganchado a woocommerce_single_product_summary.

Otras APIs JS expuestas

// Suscribir manualmente (por ejemplo desde un botón personalizado)
window.PWASP.subscribePush();

// Cancelar suscripción (botón «Cancelar suscripción»)
window.PWASP.unsubscribePush();

API REST

El plugin expone seis endpoints bajo el namespace pwasp/v1:

• POST /wp-json/pwasp/v1/subscribe — registra una suscripción. Cuerpo: objeto PushSubscription del navegador.
• POST /wp-json/pwasp/v1/unsubscribe — elimina una suscripción. Cuerpo: { endpoint: "..." }.
• POST /wp-json/pwasp/v1/test — envío de prueba al usuario actual (auth requerida, capability manage_woocommerce).
• POST /wp-json/pwasp/v1/broadcast — difusión a todos los suscriptores (auth requerida).
• POST /wp-json/pwasp/v1/regenerate-vapid — regenera las claves VAPID (auth requerida).
• POST /wp-json/pwasp/v1/waitlist — añade a una lista de espera. Cuerpo: { subscription_id, product_id }.

Autenticación: nonce WordPress X-WP-Nonce para los endpoints públicos, capability manage_woocommerce para los endpoints admin.

Compatibilidad y casos particulares

HPOS (High-Performance Order Storage)

El plugin declara formalmente su compatibilidad HPOS a WooCommerce vía FeaturesUtil::declare_compatibility. Verá la casilla marcada en WooCommerce → Ajustes → Avanzado → Características.

Plugins de caché

Añada las siguientes exclusiones en su plugin de caché:

• /pwasp-manifest.json
• /pwasp-service-worker.js

Algunos plugins (WP Rocket, LiteSpeed) también ofrecen una opción para no cachear los archivos JavaScript de Service Worker — actívela si está disponible.

iOS y Safari

Soporte por versión:

• iOS 16.4 y superior — instalación vía «Añadir a pantalla de inicio» y notificaciones push (solo para PWA instaladas)
• iOS 15 y 16.3 — instalación posible, notificaciones push no disponibles
• iOS 14 e inferior — instalación posible, ninguna notificación

En iOS, las push solo funcionan si el usuario ha instalado antes la PWA en su pantalla de inicio. Es una restricción de Apple, no del plugin.

Subcarpetas y multisite

El plugin funciona en WordPress instalado en la raíz (ejemplo.com) o en una subcarpeta (ejemplo.com/tienda/). Los endpoints se resuelven dinámicamente vía home_url(). En multisite, active el plugin por sitio — cada sitio tendrá su propio par de claves VAPID y su propia base de suscriptores.

Solución de problemas

«El Service Worker no está registrado»

1. Compruebe que su sitio está bien en HTTPS (https:// y no http://).
2. Abra la consola del navegador (F12 → pestaña Aplicación → Service Workers). ¿Hay algún mensaje de error?
3. Pruebe la URL https://su-sitio.com/pwasp-service-worker.js en una pestaña. El archivo debe devolver JavaScript, no una página 404 ni la portada de WordPress.
4. Si es 404: vaya a Ajustes → Enlaces permanentes y haga clic en Guardar cambios para refrescar las reglas de reescritura.

«Las notificaciones no llegan»

1. Compruebe en WooCommerce → PWA Subscribers que su suscripción está bien listada y en estado active.
2. Use el botón Send test to me en el compositor de broadcast. ¿Recibe la notificación?
3. Si no: el diálogo de permiso puede haber sido rechazado. En Chrome: abra el candado en la barra de direcciones → Notificaciones → Permitir.
4. En Windows/macOS: compruebe que Chrome/Firefox no está en modo «No molestar».

«La regeneración de claves VAPID ha fallado»

Causa probable: la extensión PHP openssl no está disponible en su hosting, o la generación de claves ECDSA está bloqueada. Compruebe vía un archivo phpinfo.php que la sección openssl está presente y que la curva prime256v1 es soportada. Contacte con su hosting si es necesario.

Desinstalación

Eliminación vía Plugins → Plugins instalados → Borrar:

• Las tres tablas SQL se eliminan
• Las opciones del plugin se eliminan
• Las tareas cron programadas se cancelan
• Los iconos subidos a la biblioteca de medios permanecen (pueden usarse en otros sitios)

Soporte

Para cualquier pregunta o anomalía, abra un ticket desde su cuenta DataFirefly. Respuesta en 24 h laborables.