TikTok Pixel: setup and help

Follow the steps in Quick start.

Open Configure from Module Manager. You need an existing Pixel for your TikTok account. The configuration page shows required setup notices, tracking readiness and Events API diagnostics.

Browser tracking requires both marketing/service permission and permission to send matching data. Storage permission alone is insufficient. The module supports consent decisions from Cookies Revolution, Cookie Banner, Cookiebot, OneTrust and TCF; configure and test the decisions your shop supplies. Unknown permission holds tracking. A detected supported CMP still applies if you turn off the module's consent switch.

The module also checks safe page/referrer context, staff state, ownership and outbound rules. It uses a verified Pixel-specific ttq instance. Remove duplicate or ambiguously initialized TikTok loaders before testing.

Standard event switches

All standard event switches default to Yes. Turn off any events you do not need.

The module loads https://analytics.tiktok.com/i18n/pixel/events.js for your Pixel. Cart events require a confirmed successful quantity increase; an add-button click or updateCart notification alone is insufficient. Events include product IDs and quantity. Current prices and cart value are included only when confirmed.

Purchase data uses Purchase; CompletePayment is an internal alias. It includes the stable order-based event ID, order reference when available, value, currency and purchased contents. The default purchase value policy includes tax and shipping and subtracts discounts. These are provider defaults in this module, not separate settings fields.

Track phone-link clicks, Track actual chat starts, Track successful contact forms and Track product engagement default to No. Phone clicks and supported actual Tawk chat starts map to Contact, with coarse signal metadata. Forms need a server-confirmed success receipt.

Confirmed form event defaults to Lead. Select SubmitForm only if you need that older mapping. Send confirmed forms through the server API defaults to No; turn it on only together with the form signal and API credentials. A form is sent from the server only when its receipt, the visitor's consent and the click attribution were recorded at submission; otherwise it is held. Form values are not copied into the event.

Use Product engagement thresholds for a JSON object. An empty stored field uses package defaults: 3 gallery interactions, 1 variant change, 1 detail interaction or 45 seconds, with a 1500 ms option throttle. Counts accept 1 to 20, dwell 5 to 600 seconds, and throttle 250 to 60000 ms. The default high_intent_product_engagement behavior is once per product/session when storage is allowed.

Track custom events defaults to No. Custom event rules starts empty. Add rules before enabling the switch. Names start with a letter and use letters, digits, underscores or hyphens, with a 50-character limit. Up to 50 rules and 50 distinct names are processed. Standard events, including PageView, Purchase, Contact, SubmitForm, Download and Subscribe, are reserved.

[
  {"event":"GalleryBrowse","trigger":"click","selector":".product-cover img","params":{"content_type":"product"},"once":false},
  {"event":"SizeGuideView","trigger":"url","contains":["/size-guide"],"params":{"content_type":"page"}},
  {"event":"ContactIntent","trigger":"controller","controllers":["contact"],"modules":["contactform"]},
  {"event":"ConfiguratorChanged","trigger":"event","dom_event":"product:configured","params":{"configurator_step":"finish"},"once":false}
]

document.dispatchEvent(new CustomEvent('product:configured'));

Use selector, contains, controllers/modules, or dom_event for the corresponding trigger. once defaults to true for all rule types in this module. The active runtime uses configured parameters and does not merge arbitrary DOM-event detail. Use configured rules instead of the old window.mprtkpxTrack helper.

actionValidateOrder records the consent and identifiers from the buyer's own session and queues an eligible Purchase. A callback, webhook or a request without the buyer's session cannot provide them. The worker checks the original and current consent, matching permission, staff policy, destination and outbound rules again. A purchase without matching identifiers is held. An API token on its own is not enough to send purchases.

Server delivery covers purchases and optional server-confirmed forms. Standard browsing events and custom JSON rules send through the browser. Other frontend calls cannot be sent through the Events API.

Ensure your shared MPR cron runner executes:

task: send_tiktok_events_api_conversions
callable: mprtiktokpixel::cronProcessTikTokConversions
schedule: every:300
context: any
timeout: 30

Purchases use queue provider tiktok_events_api. The same worker processes a separate confirmed-form channel, with a batch of 20 for that channel. Browser and server purchases share the module's order-based event ID; validate provider reporting rather than assuming every queued event is accepted or attributed.

The module sends the purchase when the order is validated, which can be before the payment has settled. There is no setting to wait for a paid status, and no later resend when an order becomes paid.

Check readiness, queue counts and recent HTTP/error rows in the configuration page. Use a customer browser and provider test tools to check page view, product view, successful cart change, checkout, registration and a test order. Test refusal and withdrawal as separate paths.

Send API probe needs a saved Test event code, credentials, tracking ownership and outbound permission. It sends a PageView marked with the test code, with an empty user object and your shop's root URL, not a made-up purchase. A successful probe shows that the connection works; it does not test real purchases or attribution. Clear the code after testing.

Retry failed events returns eligible failed purchase and form rows to pending. Rows without consent or recorded data, rows TikTok rejected permanently and rows whose delivery is uncertain stay as they are. Review the recorded reason before retrying.

If the Pixel does not load, check enabled state, Pixel ID, marketing/service and matching permissions, staff policy, safe URLs, duplicate SDKs and blocked requests. If cart or wishlist events are missing, confirm the expected success signals in your theme.

If purchases are missing from the server queue, check that the buyer's consent and identifiers were recorded when the order was validated; the confirmation page cannot add them later. Check API credentials, worker runs and matching identifiers. If custom JSON fails to save, check names, reserved events, trigger fields and rule limits.

The module does not create a product feed, catalogue or ad campaign. Configure those separately if you use them.

Set Enable TikTok Pixel to No and save to pause this integration. Uninstall through Module Manager to remove its menu, cron registration and module configuration. The shared queue table is kept if another module uses the conversion package; otherwise its uninstall helper drops that table. Shared consent and delivery records are managed separately. Manage the Pixel and historical reports in TikTok.

Use the setting names above when a reference screenshot differs from your installed version.