DataFirefly Server-Side — Complete guide

DataFirefly Server-Side is the free WooCommerce connector for the DataFirefly Server-Side Tracking service. The plugin captures your shop’s events and signs them; the service delivers them server-side to your advertising and analytics platforms. This guide covers installation, connection, how the client + server funnel works, deduplication, the server-side purchase, choosing client destinations, consent management, reliability and the subscription.

Requirements

• WordPress 5.8 or above
• WooCommerce 5.0 or above (HPOS — High-Performance Order Storage — compatible)
• PHP 7.4 or above
• A working WordPress cron (or a real system cron) for the retry queue and deferred delivery
• A DataFirefly Server-Side subscription to get your connection key

Installation

1. Get the datafirefly-serverside-2_2_0.zip file from your DataFirefly client space.
2. In the WordPress back office, go to Plugins → Add New → Upload Plugin, select the ZIP and click Install Now.
3. Activate the plugin. A new DataFirefly Server-Side menu appears in the administration.

One-key connection

The plugin is configured with a single connection key, which activates client and server tracking at the same time.

1. From your DataFirefly client space, copy the connection key (it starts with dfss_).
2. Paste it into the field on the plugin’s Connection screen.
3. Click Connect. The plugin activates client and server tracking, sends a test event to the dispatcher and puts the client tags in place for the configured destinations.
4. Check that the status switches to Connected ✓ and use the Send test event button to confirm delivery.

Advanced mode (manual entry)

If you prefer not to use the single key, the advanced mode lets you enter the tenant, secret and endpoint manually. Reserve it for specific setups: the one-key mode covers almost every case.

Full client + server funnel

The plugin tracks the whole funnel in the browser, while the purchase conversion fires on the server.

• Browser side: page_view, view_content (product view), add_to_cart, initiate_checkout and add_payment_info.
• Server side: purchase, triggered from the WooCommerce order hooks.

Both layers share the same event identifier to enable deduplication.

Merchandising events (since v2.1.1)

The tracker also covers your catalog merchandising: view_item_list (view of a product list — category, search results), select_item (click on a product in a list), view_promotion and select_promotion (promotion view and click). The associated context — list id and name, promotion id and name, creative and slot — is forwarded server-side to enrich your journey analytics.

Deduplication by event_id

For each order, the client event and the server event carry the same event_id, built on the order id (for example order_1042). Meta, GA4 and the other platforms rely on it to count each conversion only once. You recover the conversions the browser lets slip, without double counting.

Choosing client destinations (Meta, GA4, TikTok)

Since version 2.2.0, each client tag can be enabled or disabled individually in the plugin settings, under the Client destinations row:

• Meta (Facebook pixel, fbevents.js)
• Google Analytics 4 (gtag.js)
• TikTok (TikTok pixel)

An unticked destination never loads its third-party script in your visitors’ browsers and never sets its cookies. Not using Meta? Untick it: less JavaScript, fewer requests, a faster and leaner page. Destinations not configured on your DataFirefly account are flagged in the settings screen.

Server-side purchase: reliable and unspoofable

The purchase conversion is triggered by the WooCommerce order hooks (payment complete, processing, completed), idempotently: a lock (_dfss_sent) guarantees the same purchase is never sent twice, even if several hooks fire.

• Because the event comes from the server, no ad blocker or ITP can prevent it.
• Conversely, the public collection endpoint (beacon) deliberately excludes the purchase event: it is impossible to inject a fake purchase from the browser to inflate your Meta or GA4 revenue.
• The event context (value, currency, products) is authoritative on the server: the browser “guesses” nothing.

Consent management

The consent gate is on by default: nothing is sent until marketing consent is granted.

Native compatibility with Cookie Consent v2

The plugin natively detects the DataFirefly Cookie Consent — GDPR & Google Consent Mode v2 module and reads its consent cookie (dfcc_consent) directly on the server. If the marketing category is refused, the event is discarded, whatever the browser claims. That is the recommended combination: banner, Consent Mode v2 and server-side tracking speak the same language.

Other consent solutions

Without Cookie Consent v2, the plugin also supports WP Consent API, Complianz, Cookiebot and IAB TCF v2. You can keep your current banner and hook the tracking onto it.

Reliability: retry queue and activity log

An event that could not be delivered is not lost: it is queued and resent automatically by a cron every 5 minutes.

The activity log shows, in real time and without jargon, what has been delivered, what is queued and what has been rejected, with the HTTP code and the number of attempts. It is your first diagnostic reflex.

Security

• No secret in the browser: only public identifiers (pixel, measurement id) are exposed on the client.
• The signing secret and your destination credentials stay on the server.
• Every event is HMAC-signed before reaching the dispatcher, hosted in the EU (Germany).
• The plugin is distributed under the GPLv2 or later license and follows the WordPress coding standards.

DataFirefly Server-Side service subscription

The plugin captures and signs; the DataFirefly Server-Side Tracking service ingests and delivers server-side to five destinations: Meta CAPI, GA4 (Measurement Protocol), TikTok Events API, Pinterest Conversions API and Google Ads. The dispatcher is hosted in Germany, ingestion is HMAC-signed, personal data is masked and firing respects consent. One integration, one consolidated invoice, several sites possible.

Discover the plans and subscribe at server-side.datafirefly.com:

• Starter — 39 €/month: 1 site, up to 500K events
• Growth — 119 €/month: 5 sites, up to 2M events
• Scale — 349 €/month: 20 sites, up to 10M events

Troubleshooting

The status stays “Not connected”

Check that the key starts with dfss_ and was copied in full. A key pointing to a domain other than datafirefly.com (HTTPS) is refused. Retry the Send test event button.

The purchase doesn’t come through

The purchase fires from the order hooks: make sure the order reaches a payment status (complete / processing / completed). Check the activity log to see whether the event is queued or rejected, and check the cron if events are stuck.

The Meta (or GA4, TikTok) script doesn’t load

Two possible causes: the destination is unticked in Client destinations (intended behavior since v2.2.0), or it is not configured on your DataFirefly account — the settings screen then flags it. After a change on the account side, use the Refresh destination ids button.

Conversions counted twice

Check that no other tracking plugin is already sending a competing purchase without a shared event_id. With DataFirefly Server-Side alone, the order-based event_id guarantees deduplication.

Nothing is sent although consent seems granted

The gate is on by default. Check that the marketing category is actually accepted in your consent solution, and that it is detected (Cookie Consent v2, WP Consent API, Complianz, Cookiebot or IAB TCF v2).