# Facebook Dynamic Ads + Pixel PRO — Complete Guide

> Overview Facebook Dynamic Ads + Pixel PRO connects your PrestaShop catalog to Facebook and Instagram. The module exports a high-quality product feed (XML in the Facebook RSS format or CSV),…

- Page: <https://www.datafirefly.com/en/documentation/dffbadspixel-2/>
- Language: en
- Last updated: 2026-09-14
- Other languages: [fr](https://www.datafirefly.com/documentation/dffbadspixel/index.md), [es](https://www.datafirefly.com/es/documentation/dffbadspixel-3/index.md), [de](https://www.datafirefly.com/de/documentation/dffbadspixel-4/index.md), [it](https://www.datafirefly.com/it/documentation/dffbadspixel-5/index.md), [pl](https://www.datafirefly.com/pl/documentation/dffbadspixel/index.md), [pt](https://www.datafirefly.com/pt/documentation/dffbadspixel/index.md), [nl](https://www.datafirefly.com/nl/documentation/dffbadspixel/index.md)
- Index: <https://www.datafirefly.com/en/documentation/llms.txt>

## Overview

Facebook Dynamic Ads + Pixel PRO connects your PrestaShop catalog to Facebook and Instagram. The module exports a high-quality product feed (XML in the Facebook RSS format or CSV), installs the Facebook pixel on your store and enables the Conversions API for reliable server-side tracking. It generates a separate feed for each Country / Language / Currency combination, gives you fine-grained control over exported data (exclusions, custom labels, Google category mapping) and is built for large catalogs of up to 200,000 products.

Compatible with PrestaShop 8.0 to 9.x, PHP 7.4 to 8.3, multistore and multilingual. `cURL` is required for the Conversions API. No Composer dependency in production.

## Installation

1. In your back office, open **Modules → Module Manager → Upload a module**.
2. Upload the `dffbadspixel.zip` file.
3. The module installs and automatically creates its tables (`dffbadspixel_exclusion`, `dffbadspixel_label`, `dffbadspixel_capi_queue`) as well as the **Facebook Dynamic Ads + Pixel** admin tab.

A unique security token is generated on installation. It secures the feed and CRON URLs, and is shown in the module's **URLs & CRON** tab.

## Product feed tab

This is the heart of the module. Here you choose the format and generation mode, the product selection and the detail of the exported data.

### Format and generation

- **Format** — XML (Facebook RSS + Google namespace), CSV, or both.
- **Generation mode** — _On the fly_ (streamed on each URL call) or _CRON_ (cached files, recommended for large catalogs).
- **gzip compression**, **batch size** (chunking) and **active countries only** to optimize performance.

### Selection and granularity

- **Export by** category or by brand, with fine selection (a filter field makes it easy to search the list).
- **Granularity** by product or by variant.
- **Feed ID mode**: back-office ID (with language and/or variant option), reference or EAN.
- **Description type** (short/long), **availability** (based on stock or always in stock), **colors**, **sizes**, additional images or **cover image only**.

### Shipping, tracking and quality

- **Real shipping costs** computed via your PrestaShop carriers (zone, weight/price ranges), reference carrier or cheapest one, with configurable free shipping.
- **UTM parameters** and **GA4** integration.
- **Quality limits**: maximum title and description lengths used by the validator (Diagnostics tab).

### General exclusions

Right under the Feed tab: exclude out-of-stock products, products without EAN/MPN, or below a minimum price.

## Advanced exclusions

In the **Exclusions** tab, add targeted rules to remove certain products from the feed. Each rule is based on a type and a value:

- **Word / phrase** — excludes if the name or description contains the term.
- **Product**, **Variant**, **Supplier** — by ID.
- **Feature value** or **Attribute** — by ID.

## Custom labels and apparel tags

**Custom labels** (`custom_label_0` to `custom_label_4`) enrich the segmentation of your campaigns: category name, a feature value, a price range, or the "new" / "best-seller" labels.

The **Apparel tags** tab adds the Meta fields dedicated to clothing: `age_group`, `gender`, plus `pattern` and `material` mapped to product features.

## Category mapping & currencies

In the **Mapping & currencies** tab, map your PrestaShop categories to Google/Facebook categories:

- **CSV import** in the `id_category;google_category` format (separator `;` or `,`, optional header).
- **Import from another module** DataFirefly installed (standard version, Google Merchant Center, GMC Pro or TikTok Ads).
- **Automatic keyword suggestion** — fills empty mappings from the category name.
- Manual row-by-row editing, with a search filter.

The **Currency / Country table** defines the currency used for each country when generating multi-country feeds. Without a mapping, the store's default currency is used.

Start without category mapping: Meta accepts the feed without `google_product_category`. Add it gradually to your main categories to improve delivery.

## Facebook pixel

In the **Pixel** tab, enable the pixel and enter your **pixel ID**. The module injects the base code (PageView) and contextual events: ViewContent, ViewCategory, Search, InitiateCheckout, AddToCart and AddToWishlist.

- **Advanced matching** — sends additional customer information, SHA-256 hashed, to improve your audiences.
- **Customizable HTML selectors** for the "wishlist" and "checkout" buttons, useful if your theme changed the default markup.
- **Configurable Purchase value**: with or without tax, with or without shipping and/or wrapping.

## Conversions API (asynchronous)

The Conversions API sends events directly from your server and recovers conversions the pixel alone cannot detect (blockers, cookies). In the **Conversions API** tab:

1. Enable the Conversions API and paste the **access token** generated in your Meta Business Manager.
2. Keep **asynchronous mode** enabled (recommended): events are queued and then sent in batches via CRON, without slowing down the store.
3. Adjust the **batch size** and the number of **max retries** if needed. A **test event code** lets you validate the integration in the Business Manager.

Events are deduplicated with the browser pixel through a shared `event_id` (for example `order-1234` for a purchase). User data is SHA-256 hashed before sending.

### Purchase trigger statuses

Since version 2.1.0, the Purchase event is fired when the order **moves into a trigger status**, not when it is created. Tick the relevant statuses in the Conversions API tab: on installation, the statuses PrestaShop flags as paid are pre-selected. If no status is ticked, the module falls back to those same paid statuses.

This behaviour is essential with asynchronous payments (bank transfer, Bizum, SEPA, Klarna): the order is created awaiting payment and Purchase is only sent once payment is confirmed. Because sending is fully server-side, it does not depend on the confirmation page, even if the customer never returns to the store. An `event_id` guard prevents duplicates if the order changes status several times.

### User data sent

When available, the module sends: `em` (email), `ph` (phone), `fn`, `ln`, `ct`, `zp`, `external_id`, `fbp`, `fbc`, `client_ip_address` and `client_user_agent`. All personal data is SHA-256 hashed before sending. The `external_id` uses the customer ID (or the guest identifier for visitors). The `fbc` is read from the `_fbc` cookie and, if it does not exist yet, rebuilt from the `fbclid` URL parameter.

## GDPR consent and CMP

The **Consent** tab enforces marketing consent on the pixel _and_ on server-side sending. Until consent is granted, the pixel stays in `revoke` mode (Meta Consent Mode) and no event is queued or sent through the Conversions API.

Detection is cascading:

1. **IAB TCF v2.2** — reads `__tcfapi` (purpose 1 and Meta vendor 89).
2. **Your CMP cookie** — configurable name and expected value (Axeptio, Cookiebot, Didomi, PrestaShop GDPR modules…).
3. **JavaScript API** — call `window.dffbConsentGrant()` on acceptance and `window.dffbConsentRevoke()` on refusal from a custom banner.

The decision read in the browser is mirrored into a `dffb_consent` cookie, so the Conversions API applies exactly the same choice server-side. A `dffb:consent` event is also dispatched on `document`.

## Feed URLs and CRON task

The **URLs & CRON** tab shows the base feed URL, the CRON URL and the list of URLs per Country / Language / Currency combination.

### Feed URL

```
https://your-store.com/index.php?fc=module&module=dffbadspixel&controller=feed&token=YOUR_TOKEN&id_lang=1&id_currency=1&id_country=8&format=xml
```

The `id_lang`, `id_currency`, `id_country` and `format` (`xml` or `csv`) parameters select the feed to serve. This is the URL you declare as a feed source in the Meta catalog.

### CRON task

In CRON mode, schedule the endpoint call to (re)generate the cached files and flush the Conversions API queue:

```
*/30 * * * * curl -s "https://your-store.com/index.php?fc=module&module=dffbadspixel&controller=cron&token=YOUR_TOKEN" > /dev/null
```

The optional `job` parameter targets a specific task: `feeds` (feed generation), `capi` (Conversions API queue sending) or `all` (default). The response is a text summary.

## Diagnostics: preview and validation

The **Diagnostics** tab brings together two tools:

- **Conversions API queue** — number of pending, failed and sent events.
- **Feed preview & validation** — generates an XML sample and a quality report flagging problematic lines: missing image, invalid GTIN (checked via checksum), title or description too long, insufficient product identifier.

## Security

In the **Security** tab:

- **IP allowlist** — restricts access to the feed and CRON to certain addresses or CIDR ranges (for example Meta servers). Empty = no restriction.
- **Token rotation** — regenerates the URL token. The old one remains tolerated until invalidation, giving you time to update your feeds in Meta.

After a token rotation, remember to update your feed sources in the Business Manager, then invalidate the old token from the Security tab to close the transition window.

## Troubleshooting

### The feed returns "Forbidden"

The token is missing, incorrect, or the calling IP is not in the allowlist. Check the token in the URLs & CRON tab and empty the IP allowlist while testing.

### The feed is empty or incomplete

Check the category/brand selection (empty = whole catalog), the exclusion rules, and stock if the "out of stock" exclusion is active. In CRON mode, first run the `job=feeds` task to generate the cache.

### Conversions API events do not reach Meta

Make sure `cURL` is available, that the access token is valid, and run the `job=capi` task. Track the queue in the Diagnostics tab; errors are logged in **Advanced parameters → Logs** with the `[dffbadspixel]` prefix.

### The pixel does not fire on a button

If your theme changed the markup, adjust the "wishlist" and "checkout" HTML selectors in the Pixel tab.

## Best practices

- Use **CRON mode + gzip** for large catalogs: on-the-fly generation is still possible but more costly on each call.
- Enable **pixel and Conversions API together**: `event_id` deduplication avoids double counting while improving coverage.
- Fill in the **Google category mapping** and **GTINs** to maximize your products' eligibility for Advantage+ and Shopping placements.