DataFirefly Server-Side for Shopware — Complete guide

Overview

DataFirefly Server-Side is the free Shopware connector for the DataFirefly Server-Side Tracking service. Every time an order is placed, the plugin builds a complete purchase event and sends it server-to-server, signed with HMAC-SHA256, to the EU-hosted DataFirefly dispatcher. The service ingests the event, deduplicates it and delivers it to your destinations: Meta CAPI, GA4, TikTok Events API, Pinterest Conversions API and Google Ads.

The plugin is deliberately minimal on the shop side: no destination credentials are stored, no script is added to the storefront, no database table is created. It captures, builds, signs, sends — everything else happens on the service side.

Requirements

• Shopware 6.5.x, 6.6.x or 6.7.x (self-hosted installation — Shopware Cloud does not accept server plugins)
• PHP 8.1 or above, per your Shopware version, with the curl extension
• An active DataFirefly Server-Side Tracking subscription to obtain your connection key

Installation

Via ZIP upload

1. In the Shopware administration, open Extensions → My extensions → Upload extension and select the plugin ZIP file.
2. Click Install, then Activate.

Via the command line

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

Connecting to the service

Getting your connection key

1. Log in to your client area at server-side.datafirefly.com.
2. Open the Connect your shop section.
3. Copy the one-line connection key, in the dfss_… format. It encodes your tenant ID, your HMAC signing secret and the ingestion endpoint.

Pasting the key into Shopware

1. Open Extensions → My extensions → DataFirefly Server-Side → Configuration.
2. Paste the key into the Connection key field.
3. Enable the Enable tracking toggle and save.

That’s it: from the next placed order, the purchase event goes out to the dispatcher. A missing or malformed key is never a blocking error — the plugin simply considers itself unconfigured and sends nothing.

Configuration

• Enable tracking — master switch. Off by default.
• Connection key — the dfss_… key copied from your client area.
• Require marketing consent — enables the consent gate (off by default, see below).
• Consent cookie name — the cookie set by your consent tool (CMP).
• Consent cookie value (contains) — optional: expected value fragment inside the cookie.

Configuration is per sales channel: you can enable tracking on one shop and not another, or use different keys per channel.

Consent gate

Shopware core does not set a single server-readable marketing-consent cookie. The plugin therefore provides a generic gate, disabled by default: when it is on, the purchase event is only sent if the configured cookie is present in the shopper’s request — and, if an expected value is set, only if the cookie value contains it.

With DataFirefly Cookie Consent

The recommended combination on Shopware is our DataFirefly Cookie Consent plugin (GDPR-compliant banner with native Google Consent Mode v2): enable the gate and enter the name of the consent cookie set by the banner (listed in its documentation). Refused or missing marketing consent blocks the send, server-side, before any transmission.

With another CMP

Enter the name of the cookie your CMP sets when the visitor accepts marketing cookies (for example CookieConsent for Cookiebot), and optionally a value fragment (for example marketing:true). If your CMP does not set a server-readable cookie, or if you handle consent entirely upstream, leave the gate disabled.

Privacy-first behaviour

• Gate on + no cookie name configured → nothing is sent.
• Gate on + cookie missing or empty → nothing is sent.
• Gate on + expected value configured but absent from the cookie value → nothing is sent.
• No request available (CLI or headless flows without an HTTP request) → nothing is sent.

Testing the connection

The plugin ships a console command that sends a synthetic page_view to the dispatcher, without touching real orders:

bin/console datafirefly:serverside:test

Available options:

• --sales-channel-id=<id> — reads the configuration of a specific sales channel (default: global configuration).
• --source-url=<url> — includes a sourceUrl in the test event.

A 2xx HTTP code confirms the connection key, signature and endpoint are correct — even if no destination is configured on the service side yet.

How it works

The purchase event

The plugin subscribes to Shopware’s order placed event. On each trigger, it builds a purchase event with an idempotent order-based ID (order_<id>): if you also run browser tags, the service applies client + server deduplication and each conversion is counted only once.

Data sent

• Transaction: paid value, currency, order number, products, quantities, item count.
• Matching: email, customer ID, phone, first name, last name, city, postcode and country from the billing address.
• Browser identifiers captured at order time: _fbp, _fbc, _ttp and the GA4 client id (_ga cookie).

Building is defensive: every optional field is only added when present and valid (the dispatcher validates strictly — 2-character country, 3-character currency, etc.). In headless flows where some order associations may be missing, the corresponding fields are simply omitted, never fabricated.

HMAC signing

Every event is signed with HMAC-SHA256 using your tenant secret: the signed bytes are exactly the posted bytes, with a timestamp checked within a 300-second anti-replay window. The transmitted headers are the tenant ID, the timestamp and the signature. Your Meta, GA4, TikTok, Pinterest and Google Ads credentials stay on the service side — never in the shop, never in the browser.

Fail-safe

The whole subsystem is designed to never impact the checkout: 2-second (connection) and 4-second (total) timeouts, every error caught and logged as a warning to the Shopware logs with the HTTP code and order number — no exception ever reaches the checkout flow.

Troubleshooting

• No event goes out — check the toggle is enabled for the right sales channel, that the key starts with dfss_ with no spaces or line breaks, and that the consent gate is not on without a configured cookie.
• The test command fails — a code 0 with a curl message indicates an outbound network issue (firewall); a 401/403 indicates an invalid or regenerated key: copy it again from your client area.
• Events marked undelivered in the logs — the HTTP code and order number are logged to the Shopware logs (warning channel). A 4xx code means the payload was rejected by the dispatcher’s strict validation; check the Event Inspector in your client area for details.
• Duplicate conversions on Meta or GA4 — make sure your browser tags send the same event ID (order_<id>) to benefit from deduplication.

Changelog

• 1.0.0 (2026-07-01) — initial release: idempotent server-side purchase event, HMAC-SHA256 signing with anti-replay window, one-line connection key, opt-in CMP cookie consent gate, per-sales-channel configuration, test console command, fail-safe design.