DfPwaPush — Guía completa

DfPwaPush combina dos funciones en un solo plugin de Shopware: convierte tu storefront en una Progressive Web App instalable (manifest, service worker, página sin conexión, banner de instalación) y te permite re-enganchar a tus clientes con notificaciones Web Push totalmente autoalojadas. Sin servicio de terceros (sin Firebase, sin OneSignal), sin dependencia Composer: el cifrado Web Push (RFC 8291) y la firma VAPID (RFC 8292) están implementados de forma nativa con las extensiones OpenSSL y cURL ya exigidas por Shopware. Todos los datos de suscripción permanecen en tu servidor. Esta guía cubre la instalación, la configuración PWA y Push, la generación de claves VAPID, la creación y el envío de campañas, la ejecución en segundo plano y la resolución de problemas.

Instalación

1. Descarga el archivo DfPwaPush-1.0.2.zip desde tu cuenta DataFirefly.
2. Instálalo mediante Administración → Extensiones → Mis extensiones → Subir extensión, o copia la carpeta descomprimida DfPwaPush en custom/plugins/.
3. Ejecuta la instalación y la activación:

   bin/console plugin:refresh
   bin/console plugin:install --activate DfPwaPush
   bin/console cache:clear

4. Al instalarse, el plugin crea sus dos tablas (df_push_subscription y df_push_campaign) y registra su ScheduledTask de envío.

Requisito HTTPS

Los service workers y la API Web Push solo existen en un origen seguro. Tu tienda debe servirse por HTTPS (solo localhost es una excepción en desarrollo). En una tienda en HTTP, el plugin permanece en silencio en el front y lo registra en la consola del navegador.

Dónde encontrar el plugin en la administración

Tras la activación, aparece una entrada Campañas push en el menú Marketing de la administración. Ahí es donde creas, programas y haces seguimiento de tus campañas. Toda la configuración PWA y Push se hace en la configuración del plugin, por canal de venta, mediante Extensiones → Mis extensiones → DfPwaPush → ⋯ → Configurar.

Generación de las claves VAPID

El Web Push se basa en un par de claves VAPID (norma RFC 8292) que autentica tu servidor ante los servicios push de los navegadores. Genéralas con un comando:

bin/console df:pwa-push:vapid:generate

Las claves se escriben directamente en la configuración del plugin. Usa la opción --force para regenerarlas. También puedes pegar claves VAPID existentes en los campos de configuración.

Configuración PWA

La tarjeta PWA de la configuración (ajustable por canal de venta) controla la instalabilidad de tu tienda:

• Activar la PWA: sirve el manifest y el service worker.
• Nombre y nombre corto de la aplicación: mostrados en la pantalla de inicio una vez instalada.
• Color del tema / color de fondo: por defecto #0f172a para el tema.
• Modo de visualización: standalone, minimal-ui, fullscreen o browser.
• Iconos 192 px y 512 px: subidas PNG, imprescindibles para la instalabilidad.
• Banner de instalación: activa el aviso «Añadir a la pantalla de inicio».

Configuración Push

La tarjeta Push controla las notificaciones:

• Activar el Web Push: activa el banner de opt-in y los endpoints de suscripción. Activado por defecto.
• Clave pública / clave privada VAPID: generadas por el comando anterior.
• Asunto VAPID: una dirección mailto: o la URL de tu sitio.
• Retardo de opt-in: número de segundos antes de que aparezca el banner de autorización (8 por defecto).

El service worker y los endpoints del storefront

Todos los recursos PWA se sirven dinámicamente mediante un controlador, lo que los hace insensibles al cambio de webpack a Vite en la 6.7:

• GET /df-pwa/manifest.json — el manifest PWA, generado por canal de venta.
• GET /df-pwa/sw.js — el service worker (cabecera Service-Worker-Allowed: / para controlar todo el origen).
• GET /df-pwa/icon/{192|512} — los iconos PWA.
• GET /df-pwa/offline — la página de reserva sin conexión, cacheada por el service worker.
• POST /df-pwa/subscribe y POST /df-pwa/unsubscribe — registro y eliminación de una suscripción (XHR).

El service worker cachea la página sin conexión al instalarse, sirve una reserva para las navegaciones fallidas y muestra las notificaciones recibidas mediante el evento push con redirección al hacer clic hacia la URL de la campaña.

Crear y enviar una campaña

1. Ve a Marketing → Campañas push → Crear una campaña.
2. Rellena el título, el mensaje y, opcionalmente, una URL de destino y un icono.
3. Restringe la campaña a un canal de venta si es necesario (de lo contrario se segmenta a todos los suscriptores).
4. O bien defines una fecha de programación y guardas, o bien haces clic en Enviar ahora.

«Enviar ahora» pone la campaña en cola inmediata (estado scheduled con una fecha de envío en el momento presente); la tarea programada la procesa en los minutos siguientes. Una campaña pasa por los estados draft → scheduled → sending → sent (o failed), y la ficha muestra los contadores de envíos correctos y fallidos.

Envío en segundo plano: ScheduledTask y CLI

El envío de campañas lo gestiona la ScheduledTask df_pwa_push.send_campaigns, ejecutada cada 300 segundos. Recupera las campañas programadas vencidas y las envía por lotes. También puedes disparar el envío manualmente:

bin/console df:pwa-push:send

Web Push nativo, sin dependencia

DfPwaPush implementa la pila Web Push completa en PHP puro, sin biblioteca externa:

• VAPID / ES256 (RFC 8292): generación de claves P-256 mediante OpenSSL y firma JWT ES256 para autenticar el servidor.
• Cifrado aes128gcm (RFC 8291): ECDH efímero, derivación HKDF y cifrado AES-128-GCM del mensaje para cada suscriptor.
• Envío paralelo mediante curl_multi por lotes, con gestión de los códigos de retorno de los servicios push.

La implementación se valida byte a byte contra el vector de prueba oficial del RFC 8291, lo que garantiza la interoperabilidad con Chrome, Firefox, Edge y Safari.

Limpieza automática de suscripciones

Cuando un servicio push responde que una suscripción ya no existe (códigos HTTP 404 o 410), la suscripción correspondiente se desactiva automáticamente. Las suscripciones que fallan de forma repetida (5 fallos consecutivos) también se desactivan. Tu base de suscriptores se mantiene limpia sin intervención.

Compatibilidad iOS y Safari

FAQ y resolución de problemas

La instalación por ZIP falla con «paquete minishlink/web-push ausente». Este error afectaba a versiones anteriores. Desde la 1.0.1, el Web Push es nativo y el plugin ya no tiene ninguna dependencia Composer: la versión actual se instala en cualquier alojamiento, incluido el compartido.

No aparece nada para crear campañas en el back office. El módulo de administración está precompilado desde la 1.0.1. Tras una actualización, ejecuta bin/console assets:install && bin/console cache:clear y recarga la administración forzando la caché (Ctrl+Shift+R). La entrada está en Marketing → Campañas push.

La URL /df-pwa/manifest.json devuelve un error 500. Corregido en la 1.0.2: el método setTwig() del controlador padre se eliminó en Shopware 6.7, lo que hacía fallar todas las rutas /df-pwa/*. Actualiza a la 1.0.2 o posterior.

No pasa nada en el storefront. Abre la consola del navegador: el plugin registra cada decisión con el prefijo [DfPwaPush] (service worker registrado o no, clave VAPID ausente, permiso denegado, iOS sin PWA instalada…). Comprueba también que la tienda está en HTTPS.

El banner de instalación PWA no aparece. Chrome solo emite el evento beforeinstallprompt si el sitio es instalable, lo que exige los iconos 192 px y 512 px definidos en la configuración y un service worker activo. Sin iconos, no hay banner.

El banner de notificaciones no aparece. Comprueba que las claves VAPID estén generadas, que el Web Push esté activado y que el usuario no haya denegado ya las notificaciones. La consola mostrará la razón exacta.

¿Qué ocurre al desinstalar? Con la opción de eliminación de datos, las tablas df_push_subscription y df_push_campaign se eliminan. Sin esa opción, se conservan para preservar tus suscriptores y el historial de campañas.