X Pixel + Web Conversions API: setup and help

1. Upload and install the ZIP in Modules > Module Manager, then open X Pixel + Web Conversions API > Configure.
2. Enter X Pixel ID in X Pixel Settings.
3. Enter the real ViewContent Event ID, Purchase Event ID, and IDs for the other conversions you intend to enable.
4. Review the Track event switches, enable Enable X Pixel, and click Save.
5. Grant marketing consent in a normal visitor browser and open a product page.
6. Confirm uwt.js loads and the configured ViewContent event is emitted.
7. If using Web Conversions API, configure all four OAuth credentials and verify an eligible event through the queue and send_x_conversions task.

• 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: empty. 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 confirmed successful cart additions; 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 acknowledged successful wishlist signals; 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: empty.

• AddToCart Event ID. X Event ID for cart addition conversions; default: empty.

• StartCheckout Event ID. X Event ID for checkout start conversions; default: empty.

• Purchase Event ID. X Event ID for purchase conversions; default: empty. Required when purchase tracking is enabled.

• Search Event ID. X Event ID for search conversions; default: empty.

• AddToWishlist Event ID. X Event ID for wishlist conversions; default: empty.

• SignUp Event ID. X Event ID for account creation conversions; default: empty.

• 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: empty.

• 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: empty.

• X API secret. OAuth 1.0a consumer secret for X Ads API; default: empty.

• X access token. OAuth 1.0a access token for X Ads API; default: empty.

• X access token secret. OAuth 1.0a access token secret for X Ads API; default: empty.

• Test twclid. Retained optional test click ID; the current probe refuses to send; default: empty.

• X Ads API version. Numeric API version used in the X Ads API endpoint; default: 12.

• Send IP and user agent match keys. Allows IP address and user agent together as matching identifiers when authorization permits; default: 1.

• Queue batch limit. Maximum queued conversion events processed per run, from 1 to 100; default: 20.

• Persist consent withdrawals. Default: 0. Enable the durable marketing-withdrawal veto for queued conversions.

Click Save after changes. X Pixel ID requires 3 to 128 letters, numbers, underscores, or hyphens. Enter the account-configured Event ID for every conversion you enable. Event ID fields default to empty. They identify the conversion definition; they are separate from each occurrence's conversion_id used for deduplication.

The current form also exposes these settings. All signal switches default to No. Enable only the actions you intend to observe.

Shared thresholds are three gallery views, one variant change, one detail click, a 45-second dwell, and a 1500 ms option throttle. Gallery, variant, and detail counts are bounded to 1 through 20. Dwell is bounded to 5 through 600 seconds. Throttle is bounded to 250 through 60000 ms. For example:

{"min_gallery_views":3,"min_variant_changes":1,"min_detail_clicks":1,"dwell_seconds":45,"option_throttle_ms":1500}

You can also provide gallery_selectors, variant_selectors, and detail_selectors. Keep defaults unless your theme needs different selectors. These optional signals require consent, employee-policy, and tracking-ownership checks just like commerce events.

Keep the consent and employee-exclusion settings enabled during initial setup. Test from a normal visitor browser that is not marked as an employee. A logged-in Back Office session, an internal-traffic rule, or a visitor opt-out can suppress tracking.

The shared consent layer supports MPR consent integrations and additional CMP adapters. It must obtain a usable marketing decision for the destination. An unknown, stale, or refused decision can hold events. The module does not supply a cookie banner. A legacy consent preference does not override a live refusal from a detected CMP.

The module must own the configured destination in the shared tracking coordinator. Missing, ambiguous, or conflicting ownership can hold browser and server delivery. Remove duplicate theme tags or resolve the owner when another MPR module manages the same account.

Production sending also follows the outbound policy. An event shown in demo or preview mode is not necessarily delivered to your advertising account. Purchases and server form events are sent only with the consent the buyer gave at the time; a later cron run cannot supply that consent.

The runtime loads https://static.ads-twitter.com/uwt.js and uses twq. Base PageView uses the Pixel configuration call. Other enabled events require their mapped X Event IDs. A valid Pixel ID alone does not configure product, cart, checkout, purchase, search, wishlist, or registration conversions.

The module uses header and media hooks for configuration, order confirmation for the browser purchase, order validation to record the buyer's consent and queue eligible server delivery, and account creation for the next eligible registration event. Private requests bind checkout and sign-up data to the native visitor session. Footer hooks handle successful contact forms. Staff markers are refreshed through Back Office and dispatcher hooks.

StartCheckout requires a detected checkout-start page and usable cart context. Searches need an available query. Automatic cart events require a successful positive quantity change. Wishlist events need acknowledged successful additions.

A valid ad click twclid is stored as mprxpix_twclid with a 90-day cookie lifetime. The X API can also use other authorized match identifiers, including IP plus user agent when enabled. A click ID is not the only possible server match key.

Enable Track custom events, paste a JSON array into Custom event rules, and save. Adapt selectors and paths to your shop. Use click, url, controller, or event triggers. A controller rule can also include a modules list. Event names allow letters, numbers, underscores, and hyphens, up to 64 characters. The limit is 15 distinct names. once limits a rule within its current page runtime.

[
  {
    "event": "GalleryBrowse",
    "trigger": "click",
    "selector": ".product-images img,.images-container img",
    "params": {
      "property": "product_gallery"
    },
    "once": false,
    "x_event_id": "tw-replace-with-real-event-1",
    "capi": true
  },
  {
    "event": "LandingView",
    "trigger": "url",
    "contains": [
      "/special-offer"
    ],
    "params": {
      "property": "special_offer"
    },
    "once": true,
    "x_event_id": "tw-replace-with-real-event-2",
    "capi": true
  },
  {
    "event": "ContactView",
    "trigger": "controller",
    "controllers": [
      "contact"
    ],
    "params": {
      "property": "contact_page"
    },
    "once": true,
    "x_event_id": "tw-replace-with-real-event-3",
    "capi": true
  },
  {
    "event": "SizeGuideOpen",
    "trigger": "event",
    "dom_event": "mprxpix:custom",
    "params": {
      "property": "size_guide"
    },
    "once": false,
    "x_event_id": "tw-replace-with-real-event-4",
    "capi": true
  }
]

Trigger the DOM rule from your theme after tracking has initialized:

document.dispatchEvent(new CustomEvent('mprxpix:custom'));

Replace every example x_event_id with your actual X Event ID. The runtime sends the configured custom name and target. URL rules match the page path, rather than query strings such as utm_campaign=x. Use the configured rule parameters for supported static event data. Arbitrary DOM detail.params and data-x-param-* values are not merged by the current trigger handler.

Common incoming event names normalize to internal kinds. ViewContent maps to view_item; AddToCart to add_to_cart; StartCheckout and InitiateCheckout to begin_checkout; Purchase and CompletePayment to purchase; Search to search; AddToWishlist to add_to_wishlist; SignUp and CompleteRegistration to sign_up.

The task send_x_conversions is registered with schedule every:300. It becomes due every five minutes. Your shared MPR cron runner must execute due tasks; the schedule declaration alone does not run a worker. The batch-limit setting caps queue rows per processing run, from 1 through 100, with a default of 20.

The module does not include a standalone cron.php entry point. Use the shared scheduler already configured for your shop. Confirm task execution in that scheduler and check queue timestamps and status on this module's configuration page.

The diagnostics include readiness checks, queue counters, recent rows, Send API probe, and Retry failed events. Resolve the reason for failure before retrying. Returning failed rows to pending does not bypass current consent, employee policy, account ownership, or destination checks.

Configure all four OAuth 1.0a credentials for Web Conversions API. The client uses https://ads-api.x.com/{version}/measurement/conversions/{pixel_id} with the numeric X Ads API version. The installed value is 12; change it only to the version required for your account and deployed API integration.

The visible Send API probe button refuses transmission because a verified test mode or test-event code is unavailable. Filling Test twclid does not enable a test send. Use an authorized real event and inspect its delivery result instead.

1. Check Pixel ID, each enabled Event ID, required-configuration notices, readiness, integrity, and ownership.
2. Grant marketing consent from a normal visitor browser.
3. Open a product and confirm uwt.js and the event for your ViewContent Event ID.
4. Perform a successful cart addition and confirm the mapped cart event.
5. For a test order, inspect the occurrence conversion_id and queue result where server delivery is enabled.
6. Confirm the shared cron task runs and check the platform's own event records.

If base tracking works but conversions do not, check the Event IDs. If nothing loads, check employee and consent state, ownership, outbound policy, duplicate twq or SDK snippets, and browser blocking. If the server queue fails, check all four credentials, API version, matching data, and scheduler runs. A blank or invalid engagement JSON configuration can hold the runtime until corrected.

The current runtime does not expose window.mprxpixTrack. Use configured rules and supported DOM triggers for your integrations.

Turn off the browser and server switches and save if you want to stop tracking while retaining configuration. Uninstall from Module Manager to remove module settings, menu entries, and registered tasks.

Uninstall invokes the shared conversion-queue cleanup. The shared queue table is retained while another conversion module uses it and can be dropped when the last user is removed. Export diagnostics you need before uninstalling. Do not assume uninstall removes events already sent to the advertising platform or clears all browser attribution storage.

Requires PrestaShop 1.6 or later and PHP 7.1 or later.