# 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…

- Page: <https://www.datafirefly.com/en/documentation/datafirefly-server-side-shopware/>
- Language: en
- Last updated: 2026-07-01
- Other languages: [fr](https://www.datafirefly.com/documentation/datafirefly-server-side-shopware/index.md), [es](https://www.datafirefly.com/es/documentation/datafirefly-server-side-shopware/index.md), [de](https://www.datafirefly.com/de/documentation/datafirefly-server-side-shopware/index.md), [it](https://www.datafirefly.com/it/documentation/datafirefly-server-side-shopware/index.md), [pl](https://www.datafirefly.com/pl/documentation/datafirefly-server-side-shopware/index.md), [nl](https://www.datafirefly.com/nl/documentation/datafirefly-server-side-shopware/index.md), [pt](https://www.datafirefly.com/pt/documentation/datafirefly-server-side-shopware/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

DataFirefly Server-Side is the free Shopware connector for the [DataFirefly Server-Side Tracking](https://server-side.datafirefly.com/) 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.

**Business model:** the plugin is free; delivering events requires a subscription to the service (Starter 39 €/month, Growth 119 €/month, Scale 349 €/month). Details and sign-up at [server-side.datafirefly.com](https://server-side.datafirefly.com/).

## 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
```

The plugin adds nothing to the storefront: no `build-storefront` is needed after installation.

## Connecting to the service

### Getting your connection key

1. Log in to your client area at [server-side.datafirefly.com](https://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.

The connection key contains your signing secret: keep it confidential, like a password. If it leaks, regenerate it from your client area and replace it in the plugin configuration.

### 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](https://www.datafirefly.com/en/product/df-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.

When in doubt, the plugin does not send: that is a design choice. No event can leave "by accident" without consent while the gate is on.

## 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=` — reads the configuration of a specific sales channel (default: global configuration).
- `--source-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_`): 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_`) 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.