DataFirefly Server-Side para Shopware — Guía completa

Presentación

DataFirefly Server-Side es el conector Shopware gratuito del servicio DataFirefly Server-Side Tracking. Con cada pedido validado, el plugin construye un evento de compra completo y lo envía de servidor a servidor, firmado con HMAC-SHA256, hacia el dispatcher DataFirefly alojado en la UE. El servicio ingiere el evento, lo deduplica y lo difunde hacia tus destinos: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API y Google Ads.

El plugin es deliberadamente minimalista del lado de la tienda: no almacena ninguna credencial de destino, no añade ningún script al storefront, no crea ninguna tabla. Capta, construye, firma, envía — el resto ocurre del lado del servicio.

Requisitos

• Shopware 6.5.x, 6.6.x o 6.7.x (instalación autoalojada — Shopware Cloud no acepta plugins de servidor)
• PHP 8.1 o superior, según tu versión de Shopware, con la extensión curl
• Una suscripción activa al servicio DataFirefly Server-Side Tracking para obtener tu clave de conexión

Instalación

Subiendo el ZIP

1. En la administración de Shopware, abre Extensiones → Mis extensiones → Subir extensión y selecciona el archivo ZIP del plugin.
2. Haz clic en Instalar y luego en Activar.

Por línea de comandos

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

Conexión al servicio

Obtener tu clave de conexión

1. Inicia sesión en tu área de cliente en server-side.datafirefly.com.
2. Abre la sección Conectar tu tienda.
3. Copia la clave de conexión en una línea, con el formato dfss_…. Codifica tu identificador de tenant, tu secreto de firma HMAC y el endpoint de ingesta.

Pegar la clave en Shopware

1. Abre Extensiones → Mis extensiones → DataFirefly Server-Side → Configuración.
2. Pega la clave en el campo Clave de conexión.
3. Activa el interruptor Activar tracking y guarda.

Eso es todo: desde el próximo pedido validado, el evento de compra sale hacia el dispatcher. Una clave ausente o mal formada nunca es un error bloqueante — el plugin simplemente se considera no configurado y no envía nada.

Configuración

• Activar tracking — interruptor principal. Desactivado por defecto.
• Clave de conexión — la clave dfss_… copiada desde tu área de cliente.
• Exigir consentimiento de marketing — activa la puerta de consentimiento (desactivada por defecto, ver más abajo).
• Nombre de la cookie de consentimiento — la cookie depositada por tu herramienta de consentimiento (CMP).
• Valor de la cookie de consentimiento (contiene) — opcional: fragmento de valor esperado dentro de la cookie.

La configuración se gestiona por sales channel: puedes activar el tracking en una tienda y no en otra, o usar claves distintas por canal.

Puerta de consentimiento

El núcleo de Shopware no deposita de forma nativa una cookie única de consentimiento de marketing legible desde el servidor. El plugin ofrece por tanto una puerta genérica, desactivada por defecto: cuando está activa, el evento de compra solo se envía si la cookie configurada está presente en la petición del cliente — y, si se ha definido un valor esperado, solo si el valor de la cookie lo contiene.

Con DataFirefly Cookie Consent

La combinación recomendada en Shopware es nuestro plugin DataFirefly Cookie Consent (banner conforme al RGPD con Google Consent Mode v2 nativo): activa la puerta e indica el nombre de la cookie de consentimiento depositada por el banner (indicado en su documentación). El rechazo o la ausencia de consentimiento de marketing bloquea el envío, en el servidor, antes de cualquier transmisión.

Con otro CMP

Indica el nombre de la cookie que tu CMP deposita cuando el visitante acepta las cookies de marketing (por ejemplo CookieConsent para Cookiebot), y opcionalmente un fragmento de valor (por ejemplo marketing:true). Si tu CMP no deposita una cookie legible desde el servidor, o si gestionas el consentimiento completamente aguas arriba, deja la puerta desactivada.

Comportamiento privacy-first

• Puerta activa + nombre de cookie no configurado → no sale nada.
• Puerta activa + cookie ausente o vacía → no sale nada.
• Puerta activa + valor esperado configurado pero ausente del valor de la cookie → no sale nada.
• Sin petición disponible (flujos CLI o headless sin petición HTTP) → no sale nada.

Probar la conexión

El plugin incluye un comando de consola que envía un page_view sintético hacia el dispatcher, sin tocar pedidos reales:

bin/console datafirefly:serverside:test

Opciones disponibles:

• --sales-channel-id=<id> — lee la configuración de un sales channel específico (por defecto: configuración global).
• --source-url=<url> — incluye una sourceUrl en el evento de prueba.

Un código HTTP 2xx confirma que la clave de conexión, la firma y el endpoint son correctos — incluso si aún no hay ningún destino configurado del lado del servicio.

Funcionamiento técnico

El evento purchase

El plugin se suscribe al evento de pedido validado de Shopware. En cada disparo, construye un evento purchase con un identificador idempotente basado en el pedido (order_<id>): si también usas tags de navegador, el servicio aplica la deduplicación cliente + servidor y cada conversión se cuenta una sola vez.

Datos enviados

• Transacción: valor pagado, divisa, número de pedido, productos, cantidades, número de artículos.
• Coincidencia: e-mail, identificador de cliente, teléfono, nombre, apellidos, ciudad, código postal y país de la dirección de facturación.
• Identificadores de navegador capturados en el momento del pedido: _fbp, _fbc, _ttp y el client id de GA4 (cookie _ga).

La construcción es defensiva: cada campo opcional solo se añade si está presente y es válido (el dispatcher valida estrictamente — país de 2 caracteres, divisa de 3, etc.). En los flujos headless donde pueden faltar algunas asociaciones del pedido, los campos correspondientes simplemente se omiten, nunca se fabrican.

Firma HMAC

Cada evento se firma con HMAC-SHA256 usando el secreto de tu tenant: los bytes firmados son exactamente los bytes enviados, con una marca de tiempo verificada en una ventana anti-replay de 300 segundos. Las cabeceras transmitidas son el identificador de tenant, el timestamp y la firma. Tus credenciales de Meta, GA4, TikTok, Pinterest y Google Ads permanecen del lado del servicio — nunca en la tienda, nunca en el navegador.

Fail-safe

Todo el subsistema está diseñado para no impactar nunca el checkout: timeouts de 2 segundos (conexión) y 4 segundos (total), todos los errores capturados y registrados como warning en los logs de Shopware con el código HTTP y el número de pedido — ninguna excepción llega al túnel de compra.

Solución de problemas

• No sale ningún evento — comprueba que el interruptor está activado para el sales channel correcto, que la clave empieza por dfss_ sin espacios ni saltos de línea, y que la puerta de consentimiento no está activa sin cookie configurada.
• El comando de prueba falla — un código 0 con un mensaje curl indica un problema de red saliente (firewall); un 401/403 indica una clave inválida o regenerada: cópiala de nuevo desde tu área de cliente.
• Eventos marcados como no entregados en los logs — el código HTTP y el número de pedido quedan registrados en los logs de Shopware (canal warning). Un código 4xx significa que el payload fue rechazado por la validación estricta del dispatcher; consulta el Event Inspector de tu área de cliente para el detalle.
• Conversiones duplicadas en Meta o GA4 — asegúrate de que tus tags de navegador envían el mismo identificador de evento (order_<id>) para beneficiarte de la deduplicación.

Changelog

• 1.0.0 (01/07/2026) — versión inicial: evento purchase server-side idempotente, firma HMAC-SHA256 con ventana anti-replay, clave de conexión en una línea, puerta de consentimiento opt-in por cookie de CMP, configuración por sales channel, comando de consola de prueba, diseño fail-safe.