X Pixel + Web Conversions API — Documentation

X Pixel + Web Conversions API adds X Ads tracking to your PrestaShop store, including browser Pixel events and optional server-side conversion delivery. It helps you measure product views, carts, checkout starts, purchases, sign-ups, searches, wishlist activity, and custom actions from one back-office module.

Features

• Browser X Pixel. The module injects the X Pixel from displayHeader and can send the base PageView configuration event.
• Product and search events. Product pages can send ViewContent, and the PrestaShop search controller can send Search with the visitor's query.
• Cart and wishlist tracking. AddToCart uses the PrestaShop updateCart event bus with a fallback click detector, and AddToWishlist listens to common wishlist event buses and buttons.
• Checkout and purchase tracking. Checkout start pages can send StartCheckout, while displayOrderConfirmation and actionValidateOrder cover purchase browser and API events.
• Sign-up tracking. actionCustomerAccountAdd marks new account creation and sends SignUp after the customer reaches the account page.
• X Event ID mapping. Each conversion event has its own X Event ID field, used for browser sends and Web Conversions API deduplication.
• Web Conversions API queue. Eligible events can be queued server-side and sent to https://ads-api.x.com/{version}/measurement/conversions/{pixel_id}.
• Custom event rules. Merchants can define click, URL, controller, and DOM-event rules in JSON for store-specific conversion actions.
• Consent-aware loading. When enabled, tracking waits for marketing consent from mprcookiesrevolution or mprcookiebanner.
• Diagnostics panel. The back office shows queue counts, readiness checks, recent API events, an API probe button, and a retry button for failed events.

Configuration options

• Enable X Pixel. Master switch for browser X tracking; default: 0. Set it in the module configuration page after entering a valid Pixel ID.
• X Pixel ID. Event Source ID from X Events Manager; default: ``. It accepts letters, numbers, underscores, and dashes.
• Exclude employees. Stops tracking injection while a logged-in back-office employee is browsing the front office; default: 1.
• Respect cookie consent. Waits for marketing consent when mprcookiesrevolution or mprcookiebanner is active; default: 1.
• Track PageView. Allows the base X Pixel configuration call to record page visits; default: 1.
• Track ViewContent. Sends product view events on product pages when a ViewContent Event ID is configured; default: 1.
• Track AddToCart. Sends cart addition events from the cart event bus or fallback add-to-cart buttons; default: 1.
• Track StartCheckout. Sends checkout start events when PrestaShop detects the checkout start page and the cart contains products; default: 1.
• Track Purchase. Sends purchase events on order confirmation and order validation; default: 1.
• Track Search. Sends search events on the PrestaShop search controller when a query is present; default: 1.
• Track AddToWishlist. Sends wishlist events from supported wishlist buttons and event buses; default: 1.
• Track SignUp. Sends sign-up events after a customer account is created; default: 1.
• ViewContent Event ID. X Event ID for product view conversions; default: ``.
• AddToCart Event ID. X Event ID for cart addition conversions; default: ``.
• StartCheckout Event ID. X Event ID for checkout start conversions; default: ``.
• Purchase Event ID. X Event ID for purchase conversions; default: ``. Required when purchase tracking is enabled.
• Search Event ID. X Event ID for search conversions; default: ``.
• AddToWishlist Event ID. X Event ID for wishlist conversions; default: ``.
• SignUp Event ID. X Event ID for account creation conversions; default: ``.
• Track custom events. Enables the custom event JSON rules field; default: 0.
• Custom event rules. JSON array defining click, URL, controller, or DOM-event conversion rules; default: ``.
• Enable Web Conversions API events. Queues eligible server-side events and sends them to X Ads API when credentials are complete; default: 0.
• X API key. OAuth 1.0a consumer key for X Ads API; default: ``.
• X API secret. OAuth 1.0a consumer secret for X Ads API; default: ``.
• X access token. OAuth 1.0a access token for X Ads API; default: ``.
• X access token secret. OAuth 1.0a access token secret for X Ads API; default: ``.
• Test twclid. Optional real twclid used only by the back-office API probe; default: ``.
• X Ads API version. Numeric API version used in the X Ads API endpoint; default: 12.
• Send IP and user agent match keys. Adds IP address and user agent to API identifiers when other user identifiers exist; default: 1.
• Queue batch limit. Maximum queued conversion events processed per run, from 1 to 100; default: 20.

Customization examples

Custom click event rule for product gallery interactions:

[
  {
    "event": "GalleryBrowse",
    "x_event_id": "tw-gallery-123",
    "trigger": "click",
    "selector": ".product-images img,.images-container img",
    "params": {
      "property": "product_gallery"
    },
    "capi": true
  }
]

URL and controller rules for campaign or checkout pages:

[
  {
    "event": "LandingPageVisit",
    "x_event_id": "tw-landing-123",
    "trigger": "url",
    "contains": ["/promo", "utm_campaign=x"],
    "params": {
      "property": "campaign_landing"
    },
    "once": true,
    "capi": true
  },
  {
    "event": "CheckoutPageView",
    "x_event_id": "tw-checkout-123",
    "trigger": "controller",
    "controllers": ["order"],
    "params": {
      "property": "checkout"
    },
    "capi": true
  }
]

DOM-event rule using the module's default custom event name:

[
  {
    "event": "ConfiguratorComplete",
    "x_event_id": "tw-configurator-123",
    "trigger": "event",
    "dom_event": "mprxpix:custom",
    "params": {
      "property": "configurator"
    },
    "capi": true
  }
]

Trigger that DOM event from your theme or configurator script:

<script>
document.dispatchEvent(new CustomEvent('mprxpix:custom', {
  detail: {
    params: {
      product_id: '123',
      product_name: 'Custom shower tray',
      value: 249.90,
      currency: 'EUR'
    }
  }
}));
</script>

Add extra parameters to a tracked click target with data attributes:

<button
  class="track-x-demo"
  data-x-param-product_id="123"
  data-x-param-product_name="Demo product"
  data-mprxpix-param-property="custom_button">
  Track event
</button>

Call the browser tracker directly after the module has booted:

<script>
if (typeof window.mprxpixTrack === 'function') {
  window.mprxpixTrack('GalleryBrowse', 'tw-gallery-123', {
    product_id: '123',
    product_name: 'Demo product',
    currency: 'EUR',
    conversion_id: 'gallery_123_001'
  }, true);
}
</script>

The module also normalizes common browser event names before sending:

ViewContent -> viewcontent
AddToCart -> addtocart
StartCheckout -> startcheckout
InitiateCheckout -> startcheckout
Purchase -> purchase
CompletePayment -> purchase
Search -> search
AddToWishlist -> addtowishlist
SignUp -> signup
CompleteRegistration -> signup

Installation

1. Download the module ZIP from your mypresta.rocks account.
2. In PrestaShop Back Office, go to Modules > Module Manager.
3. Click Upload a module and upload the ZIP file.
4. Open the module configuration page.
5. Enter your X Pixel ID from X Events Manager.
6. Enable X Pixel tracking and save.
7. Add the X Event IDs for the conversions you want to optimize in X Ads.
8. If you use Web Conversions API, enter all four OAuth 1.0a credentials and save.
9. Check the diagnostics panel for Pixel ID, browser tracking, Purchase Event ID, API credentials, custom rules, twclid status, and queue table status.

How it works

After configuration, the module loads the X Pixel on the front office when tracking is active and consent rules allow it. Visitors do not see a new storefront block; the module works in the page header, order confirmation hook, account creation hook, and conversion API queue.

In the back office, merchants see the settings form plus Web Conversions API diagnostics. The diagnostics panel shows pending, sending, sent, and failed queue counts, recent event rows, a Send API probe action for testing credentials with a real twclid, and Retry failed events to return failed events to the pending queue.

Honest limits

• X Event IDs are required for conversion events; purchase tracking needs a Purchase Event ID when enabled.
• Web Conversions API requires a valid X Ads API app with OAuth 1.0a API key, API secret, access token, and access token secret.
• API matching is strongest when X provides a real twclid in the ad click URL; the module stores it in the mprxpix_twclid cookie.
• When consent respect is enabled, tracking waits for marketing consent if mprcookiesrevolution or mprcookiebanner is active.
• The API queue cron task is registered as send_x_conversions with schedule every:300; server-side delivery depends on that task being processed.
• Custom event rules must be valid JSON and each enabled rule needs an event name and x_event_id.

Compatibility: PrestaShop 1.6 to 9.0 (latest), PHP 7.1+. We continue to support upcoming PrestaShop versions.