# DataFirefly Push — Guía completa

> Presentación y requisitos DataFirefly Push convierte tu tienda WooCommerce en una plataforma de notificaciones Web Push nativa. Sin SDK, sin tracking de terceros: toda la criptografía (VAPID y cifrado RFC…

- Página: <https://www.datafirefly.com/es/documentation/datafirefly-push/>
- Idioma: es
- Actualizado el: 2026-08-05
- Otros idiomas: [fr](https://www.datafirefly.com/documentation/datafirefly-push/index.md), [en](https://www.datafirefly.com/en/documentation/datafirefly-push/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-push/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-push/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-push/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-push/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-push/index.md)
- Índice: <https://www.datafirefly.com/es/documentation/llms.txt>

## Presentación y requisitos

DataFirefly Push convierte tu tienda WooCommerce en una plataforma de notificaciones Web Push nativa. Sin SDK, sin tracking de terceros: toda la criptografía (VAPID y cifrado RFC 8291) se ejecuta en tu propio servidor en PHP puro mediante OpenSSL. El plugin cubre un opt-in inteligente multi-estilo, diez disparadores automáticos, campañas manuales con constructor visual y segmentación, un panel de analítica completo, una página Mi cuenta dedicada para tus clientes y conformidad RGPD nativa.

- WordPress 6.2 y superior.
- WooCommerce 7.0 y superior, probado hasta 9.6, compatible con HPOS y Cart/Checkout Blocks.
- PHP 8.1 y superior.
- Multilingüe (FR/EN/ES/DE/IT), compatible con Polylang y WPML.
- Compatible con LiteSpeed Cache, WP Rocket y otros plugins de caché: el Service Worker se sirve como PHP standalone.

Ningún servicio externo que conectar, ninguna librería Composer que mantener. Las claves VAPID se generan automáticamente en la activación, las suscripciones y los eventos permanecen en tu propia base de datos.

## Instalación

1. Descarga el archivo `df-push.zip` desde tu cuenta de cliente.
2. En el admin de WordPress, ve a **Plugins > Añadir nuevo > Subir plugin** y suelta el archivo.
3. Haz clic en **Activar**.
4. El menú **DF Push** aparece en la barra lateral de administración con siete submenús: Panel, Campañas, Suscriptores, Disparadores, Opt-in, Ajustes, Webhooks y API.

En la activación, el plugin crea ocho tablas dedicadas con prefijo `dfpush_`, genera tus claves VAPID, programa el cron diario `df_push_daily_lifecycle` y registra el endpoint Mi cuenta. No se requiere ninguna intervención manual.

## Primera configuración: claves VAPID y opt-in

Una vez activado, el plugin es inmediatamente funcional con sus ajustes por defecto: la campana flotante aparece abajo a la derecha tras cinco segundos, el pre-prompt está activado, los disparadores automáticos están listos. Comprueba simplemente dos cosas en **DF Push > Ajustes** antes de comunicar sobre el servicio:

- **Clave pública VAPID**: el bloque muestra tu clave pública generada automáticamente (la application server key que utiliza el navegador). Puedes regenerarla, pero eso invalidará todas las suscripciones existentes.
- **Manifest PWA** y **icono por defecto**: añade tu icono (192×192 mínimo) si `site_icon` no está definido en el sitio.

Ningún servicio externo que registrar, ninguna cuenta de desarrollador Firebase / OneSignal que crear. Las claves VAPID que el plugin genera son suficientes: autentican tu servidor de aplicación ante los servicios push FCM, Mozilla Push y WNS.

## Pestaña Opt-in — prompt, estilos y disparadores

Esta pestaña pilota la solicitud de suscripción. Cinco estilos disponibles, cada uno posicionable y tematizable:

- **Campana flotante** (por defecto): píldora discreta abajo a la derecha o abajo a la izquierda.
- **Banner** en la parte superior o inferior de la página.
- **Modal** centrado con overlay.
- **Slide-in** lateral.
- **Barra fija** anclada arriba.

El **pre-prompt soft-ask** (recomendado) muestra tu mensaje personalizado antes de la solicitud nativa del navegador. Este mecanismo preserva tu cupo de opt-in: en Chrome, rechazar el pre-prompt no agota el presupuesto de solicitudes nativas (×3 frente a 1 sin pre-prompt).

Cinco disparadores configurables y combinables:

- **Retardo** (en segundos) tras la carga de la página.
- **Scroll** en porcentaje de la página (0 = desactivado).
- **Exit-intent** al movimiento de salida del ratón (sólo escritorio).
- **X páginas vistas** en la sesión.
- **Añadir al carrito** (captura el evento WooCommerce `added_to_cart`).

Activa el **test A/B del prompt** con un título y un mensaje variante B, y una división configurable. La asignación se persiste en localStorage para garantizar la coherencia entre sesiones por visitante.

Una vez denegado el permiso del navegador, no puede solicitarse de nuevo por script. Cuida tu pre-prompt y no encadenes una solicitud en el primer scroll: ese patrón muestra un 70 % de rechazo frente al 20-30 % con un pre-prompt activado en el momento correcto.

## Pestaña Disparadores — los automatismos

Diez disparadores automáticos, todos activables individualmente desde la pestaña **Disparadores**. Cada uno se apoya en Action Scheduler para los envíos diferidos, con un fallback síncrono si Action Scheduler no está disponible.

### Carrito abandonado

Tres recordatorios configurables, por defecto a 1 hora, 24 horas y 72 horas tras el abandono. La detección captura el evento `added_to_cart` para los usuarios suscritos a Push y programa tres acciones `df_push_abandoned_cart` a intervalos decrecientes. Los recordatorios se cancelan automáticamente si el pedido se realiza mientras tanto.

### De nuevo en stock (back-in-stock)

En la página de producto, tus visitantes suscritos pueden unirse a una lista de espera por producto. Cuando WooCommerce dispara `woocommerce_product_set_stock_status` con un retorno a _instock_, el plugin envía una notificación a la lista de espera del producto, y luego la vacía.

### Bajada de precio

El plugin mantiene un meta `_df_push_last_price` por producto. En cada actualización de producto, compara el precio anterior y el nuevo. Si la bajada supera el **umbral mínimo en porcentaje** configurado, se envía una notificación al tema _Promociones_.

### Confirmación, envío, reseña

- **Confirmación de pedido**: envío inmediato en `woocommerce_thankyou` al suscriptor si el ID de usuario coincide.
- **Envío**: detecta el número de seguimiento en el pedido leyendo en orden los metas `_tracking_number`, `_wc_shipment_tracking_items` (WooCommerce Shipment Tracking) y `_aftership_tracking_number` (AfterShip). Si se encuentra un número, la notificación lo incluye en su mensaje.
- **Solicitud de reseña**: programada X días después de que el pedido pasa al estado _completed_ (retardo configurable).

### Cumpleaños, reenganche, nuevo producto

- **Cumpleaños**: el cron diario `df_push_daily_lifecycle` lee el campo `billing_birthday` de WooCommerce y envía una notificación a los suscriptores cuyo cumpleaños es ese día.
- **Reenganche**: envío a los suscriptores inactivos desde hace 30, 60 y 90 días (ventanas configurables como CSV: `30,60,90`).
- **Nuevo producto**: al publicar un producto, se envía una notificación al tema _Novedades_.

Cada disparador acepta un payload con plantilla: `{firstname}`, `{product_name}`, `{product_price}`, `{old_price}`, `{order_number}`, `{tracking_number}`, `{category}`, `{discount_code}`. Las variables se resuelven en el momento del envío, no en la programación.

## Pestaña Campañas — constructor visual, segmentación, test A/B

Construye una campaña manual en **DF Push > Campañas > Nueva campaña**. El constructor ofrece una vista previa en tiempo real de la notificación tal como aparecerá en el dispositivo del suscriptor.

- **Contenido**: título, mensaje, URL de destino, imagen hero, hasta dos botones de acción con etiqueta y URL propias.
- **Notificación persistente** (opción _requireInteraction_): la notificación permanece visible hasta la interacción.
- **Segmentación** por idioma, país, dispositivo, tema, y por comportamiento RFM: pedidos mínimos, carrito medio mínimo, días inactivo, categoría comprada. Los segmentos comportamentales se calculan mediante `wc_get_orders` en el lanzamiento.
- **Test A/B**: activa una variante B (título y mensaje), la división es configurable en porcentaje. La asignación es aleatoria por suscriptor, determinista por ID para la coherencia de la analítica.
- **Programación**: elige la fecha y la hora, o envía inmediatamente.
- **Modo de prueba**: envía la campaña sólo a los administradores, desde el constructor, antes del lanzamiento en producción.

El motor de envío fragmenta automáticamente el segmento, respeta las horas de silencio por zona horaria del suscriptor, aplica el límite de frecuencia configurado y purga al vuelo los endpoints que devuelven 404 o 410 (cancelación desde el navegador).

## Panel y analítica

El tablero **DF Push > Panel** agrega tus KPIs de 30 días. Chart.js está empaquetado localmente (sin dependencia de CDN externa).

- **KPIs**: suscriptores activos, tasa de opt-in, envíos, tasa de clics (CTR), conversiones, ingresos atribuidos.
- **Serie temporal 30 días**: envíos frente a clics, una línea por día.
- **Mapa de calor 7 × 24**: mejores franjas de envío en función de los clics, cruzando día de la semana y hora del día.
- **Embudo por campaña**: enviada > entregada > clicada > convertida.
- **Ingresos atribuidos**: una ventana de atribución configurable (72 horas por defecto) vincula cada clic con la primera compra realizada en la ventana por ese suscriptor.
- **Exportación CSV** de todos los eventos para auditoría RGPD o integración BI.

## Página cliente: Mi cuenta → Notificaciones

Una página dedicada **Mi cuenta → Notificaciones** se añade automáticamente al panel de WooCommerce. El cliente dispone de cuatro bloques:

- **Este dispositivo**: estado actual (activado, desactivado, bloqueado por el navegador, no compatible), con botón Activar o Desactivar en este dispositivo.
- **Todos tus dispositivos**: lista de dispositivos suscritos (tipo, navegador, idioma, última actividad), con cancelación individual o cancelación total con un clic.
- **Mis preferencias**: casillas para los temas nativos (Novedades, Promociones, De nuevo en stock). Guardado mediante REST con confirmación.
- **Historial de notificaciones**: las 30 últimas notificaciones recibidas, con título, cuerpo, icono, enlace y fecha.

La URL es `/es/my-account/df-push-notifications/` en español. El rewrite endpoint se registra con el mask `EP_ROOT | EP_PAGES`, con una autoreparación en `init:999` que detecta una regla faltante (caso de flush de permalinks concurrente) y reejecuta el flush automáticamente.

Las acciones del cliente (cancelación, preferencias) pasan por las rutas REST bajo `df-push/v1/account/*`, autenticadas por cookie + nonce `wp_rest`. Ninguna acción puede ejecutarse sobre otra cuenta, incluso si se manipula el identificador del dispositivo en la solicitud.

## RGPD y registro de consentimiento

La conformidad RGPD se trata de forma nativa, no como un añadido cosmético. Cada opt-in y cada cancelación se inscribe en la tabla `dfpush_consent_log` con:

- ID del suscriptor.
- Acción: _subscribe_ o _unsubscribe_.
- IP hasheada en SHA-256 (la IP en claro nunca se persiste).
- User-agent.
- Marca de tiempo UTC.

Los Exportadores y Borradores de privacidad nativos de WordPress están conectados: un cliente puede solicitar la exportación o la eliminación de sus datos personales desde **Herramientas → Exportar datos personales** o **Herramientas → Borrar datos personales**. El plugin incluye entonces sus suscripciones, sus temas, su bandeja y su registro de consentimiento en la respuesta — o los elimina según la solicitud.

## Pestaña Ajustes — anti-spam y atribución

Esta pestaña centraliza los parámetros de respeto al suscriptor y la ventana de atribución:

- **Horas de silencio** (quiet hours): intervalo durante el cual no se envía ninguna notificación. Sensible a la zona horaria del suscriptor (leída en su dispositivo en el momento del opt-in mediante `Intl.DateTimeFormat().resolvedOptions().timeZone`). Por defecto 22h-8h locales.
- **Límite de frecuencia**: número máximo de notificaciones por día por suscriptor. 0 = ilimitado.
- **Hora de envío inteligente**: optimiza la hora de envío por suscriptor basándose en sus franjas de clic históricas.
- **Ventana de atribución**: duración en horas entre un clic y un pedido para que el pedido se atribuya a la notificación. Por defecto 72 horas.
- **Bandeja in-site**: activa o desactiva la campana flotante con el historial de notificaciones del frontend.
- **Manifest PWA**: activa la generación del manifest para hacer el sitio instalable en móvil.

## Pestaña Webhooks y API REST

La pestaña **Webhooks y API** cubre dos mecanismos de integración.

### Webhooks salientes

Configura uno o varios endpoints HTTP por evento. Tres formatos están disponibles:

- **Slack**: payload `{ text }` compatible con los Incoming Webhooks de Slack.
- **Discord**: payload `{ content }` compatible con los Webhooks de Discord.
- **Generic**: payload JSON completo con event, timestamp, data — compatible con Zapier, n8n, Make.

Los eventos disponibles: `subscriber.created`, `campaign.launched`, `notification.clicked`, `order.attributed`. Las solicitudes son no bloqueantes (`wp_remote_post` con `blocking=false`) para no ralentizar nunca el envío principal.

### API REST

Bajo el namespace `df-push/v1`, el plugin expone una ruta pública de envío con token: `POST /wp-json/df-push/v1/send` con la cabecera `X-DF-Push-Token`. El token es regenerable con un clic desde el admin.

```
curl -X POST https://tu-sitio.com/wp-json/df-push/v1/send
  -H "Content-Type: application/json"
  -H "X-DF-Push-Token: TU_TOKEN"
  -d '{
    "title": "Promo flash",
    "body": "20 % en todo el catálogo hasta medianoche",
    "url": "https://tu-sitio.com/promociones",
    "segment": { "lang": "es", "topic": "promos" }
  }'
```

Conserva este token como una contraseña. Quien lo posea puede enviar notificaciones a tus suscriptores. Regenéralo inmediatamente si sospechas de una filtración.

## Bandeja in-site, PWA y multilingüe

Tres funciones complementarias cubren los casos en los que el usuario no ha autorizado el Push.

- **Bandeja in-site**: una campana flotante (configurable en el frontend) abre una lista de las últimas notificaciones recibidas por el usuario, leídas o no, incluso si nunca ha autorizado el Push. Particularmente útil para iOS Safari antes de 16.4 y los usuarios PWA.
- **Manifest PWA**: generado dinámicamente en `/df-push-manifest.json` a partir de `site_icon` o de un icono personalizado. Filtro `df_push_manifest` disponible para ajustar theme color, display, scope, start_url.
- **Multilingüe**: compatible con Polylang y WPML. Las notificaciones se envían en el idioma del suscriptor (detectado en el opt-in), con fallback al idioma por defecto del sitio. Los archivos `.po` y `.mo` en FR, EN, ES, DE, IT están incluidos.

## Service Worker y arquitectura técnica

El Service Worker se sirve mediante un archivo PHP standalone en la URL `/wp-content/plugins/df-push/sw.php`. Este enfoque evita por completo el routing de WordPress: ninguna posibilidad de interferencia con un plugin de caché, una redirección canónica u otro handler `template_redirect`.

La cabecera `Service-Worker-Allowed: /` se envía en respuesta para permitir el registro con scope raíz (`scope: '/'`), aunque el script viva bajo `/wp-content/`.

En el lado de la base de datos, ocho tablas con prefijo `dfpush_`:

- `dfpush_subscribers`: suscriptores y su endpoint Push.
- `dfpush_topic_subs`: asignaciones tema ↔ suscriptor.
- `dfpush_campaigns`: campañas manuales con payload, segmento y programación.
- `dfpush_notifications`: registro de notificaciones individuales enviadas.
- `dfpush_events`: eventos brutos (opt-in, sent, delivered, clicked, converted) para la analítica.
- `dfpush_inbox`: copia persistente de las notificaciones para la bandeja in-site.
- `dfpush_stock_waitlist`: listas de espera de retorno en stock.
- `dfpush_consent_log`: registro RGPD.

La **desinstalación** (eliminación completa desde Plugins) hace drop de estas ocho tablas y purga todas las opciones. La desactivación simple, en cambio, conserva los datos para una reactivación posterior.

## Hooks para desarrolladores

El plugin expone acciones y filtros en los puntos clave para extender su comportamiento sin modificar el núcleo.

- `df_push_booted` (acción): disparada tras el arranque del plugin, útil para registrar extensiones personalizadas.
- `df_push_payload_build` (filtro): modificar el payload JSON enviado al servicio push antes del cifrado.
- `df_push_should_send` (filtro): cortocircuitar el envío según condiciones personalizadas (devuelve _false_ para omitir).
- `df_push_segment_query` (filtro): enriquecer los criterios de segmentación comportamental.
- `df_push_webhook_payload` (filtro): ajustar los payloads de los webhooks salientes.
- `df_push_manifest` (filtro): modificar el manifest PWA generado.
- Acciones Action Scheduler registradas: `df_push_send_one`, `df_push_fan_out`, `df_push_abandoned_cart`, `df_push_review_request`, `df_push_dispatch_campaign`.

## FAQ y resolución de problemas

### El prompt de opt-in no aparece

Tres causas posibles: el permiso del navegador ya está denegado (verifica en los ajustes del navegador), el permiso ya está concedido (el prompt ya no tiene sentido), o un disparador no se ha alcanzado (retardo no transcurrido, scroll insuficiente). En la consola JavaScript, ejecuta `window.DFPush.isSubscribed()` para verificar el estado actual.

### El admin Suscriptores está vacío aunque un opt-in haya tenido éxito

Verifica en la consola de red que la solicitud `POST /wp-json/df-push/v1/subscribe` devuelve un código 200. A partir de la versión 1.0.1, el plugin re-sincroniza automáticamente cualquier `PushSubscription` existente con el servidor en cada carga de página, y registra cualquier error de inserción en BD en `error_log`.

### El Service Worker devuelve un error de registro

Si el error del navegador es "The script resource is behind a redirect" o "Unexpected token '<'", prueba directamente la URL `https://tu-sitio.com/wp-content/plugins/df-push/sw.php`. Debes ver el código JavaScript del Service Worker con un `Content-Type: application/javascript` y la cabecera `Service-Worker-Allowed: /`. Si ves un HTML 403, verifica las reglas htaccess que podrían bloquear la ejecución directa de archivos PHP bajo `wp-content/plugins/`.

### Las notificaciones no se reciben en iOS

Safari en iOS sólo soporta las notificaciones Push desde la versión 16.4 y únicamente para los sitios instalados como PWA mediante el botón **Añadir a la pantalla de inicio**. El manifest PWA generado por el plugin facilita esta instalación. Si no apuntas específicamente a iOS, no es un problema: los demás navegadores reciben las notificaciones normalmente.

### Cómo migrar desde OneSignal o Pusher

Los suscriptores existentes en esos servicios de terceros no son portables: la criptografía Push vincula cada suscripción a un par único (clave VAPID del servidor, endpoint del navegador). Tus visitantes tendrán que volver a suscribirse tras tu paso a DataFirefly Push. Puedes preparar la transición desactivando el SDK anterior unos días antes y comunicando mediante un banner de pre-anuncio sobre la nueva experiencia.

### ¿Qué ocurre en la desinstalación?

La **desactivación** simple conserva todas las tablas y opciones: puedes reactivar el plugin y retomar donde lo dejaste. La **eliminación completa** desde Plugins ejecuta `uninstall.php` que hace drop de las ocho tablas `dfpush_`, purga todas las opciones del plugin (incluyendo las claves VAPID y el token API) y desprograma los crones. Los permalinks se recargan automáticamente en la próxima solicitud.