TikTok Pixel
The TikTok Pixel
forwards browser conversions to TikTok Ads for optimization, audience
building, and reporting. This destination wraps the standard TikTok Pixel
snippet (loaded from analytics.tiktok.com/i18n/pixel/events.js); there is
no npm SDK for the browser pixel. Events become ttq.track(name, params, { event_id })
calls; identity becomes ttq.identify({ email, phone_number, external_id });
consent toggles ttq.enableCookie / ttq.disableCookie.
TikTok Pixel is a web destination in the walkerOS flow:
Loads the TikTok Pixel SDK, forwards every walkerOS event with a stable
event_id for deduplication, and lets you layer on Advanced Matching and
consent cookie toggling.
Installation
Setup
- Integrated
- Bundled
Configuration reference
| Property | Type | Description | More |
|---|---|---|---|
apiKey | string | Your TikTok Pixel ID. Find it in TikTok Ads Manager under "Assets" → "Events" → "Web Events" → select your pixel → "Setup Web Event" → "Pixel ID". | |
auto_config | boolean | TikTok default: true. Enable automatic form field detection for Advanced Matching. | |
limited_data_use | boolean | TikTok default: false. Restrict data use for compliance with U.S. state privacy laws. | |
identify | any | walkerOS mapping value resolving to an Advanced Matching object with any of: email, phone_number, external_id. All values are auto-hashed (SHA256) by the TikTok SDK before sending. |
Standard events
TikTok recognizes 14 standard events for ad optimization. Use mapping.name
to flip walkerOS event names into the rigid taxonomy. Custom names still
work but receive no optimization signal.
| TikTok name | When to use |
|---|---|
ViewContent | Product / content detail view |
ClickButton | Generic CTA click |
Search | Site search |
AddToWishlist | Item added to a wishlist |
AddToCart | Item added to cart |
InitiateCheckout | User started checkout |
AddPaymentInfo | Payment details entered |
CompletePayment | Order successfully placed (primary conversion) |
PlaceAnOrder | Order placed (alternative) |
Contact | Lead / contact form |
Download | Asset download |
SubmitForm | Generic form submission |
CompleteRegistration | User signup |
Subscribe | Subscription start |
Mapping data.examples
The code data.examples are interactive. You can edit the code to generate your individual event mapping.
ViewContent via mapping.name
The canonical TikTok pattern: walkerOS product view becomes TikTok's
ViewContent standard event with the native parameter shape.
CompleteRegistration with per-event Advanced Matching
User signup is the moment to fire Advanced Matching for the session.
CompletePayment with multi-product contents
The hero example: mapping.data builds the TikTok-native shape; loop
walks event.nested to produce one contents entry per product;
{ key, value: 'EUR' } provides a fallback currency.
Search
Minimal example: a single mapping.data field maps the query string.
Destination-level Advanced Matching
Set identity once on the destination and the runtime state diffing skips
redundant ttq.identify() calls when nothing changed.
Advanced Matching
TikTok matches conversions back to TikTok users via three optional parameters:
email, phone_number, external_id. The SDK hashes them with SHA256 before
sending, so it's safe to pass raw values.
settings.identify (destination-level) fires on first push and re-fires only
when the resolved value changes (runtime state diffing). mapping.settings.identify
(per-event) overrides for one push, which is useful for signup and checkout flows
where the identity becomes available mid-session.
ttq.identify() always fires before ttq.track() so Advanced Matching
is set for the conversion event.
Consent
TikTok is an advertising platform. The typical walkerOS consent key is
marketing (whatever name your CMP reports). The walkerOS config.consent
gate blocks unconsented events from reaching the destination in the first
place; the destination's on('consent') handler then toggles TikTok's own
cookie state for attribution.
The handler iterates every key in config.consent and calls
ttq.enableCookie() only when all required keys are granted. Otherwise
it calls ttq.disableCookie(). This is the conservative semantic that
matches walkerOS's gating model.
TikTok's SDK auto-fires ttq.page() once on load. The destination has no
knob to suppress it. Letting the auto page view fire is the expected
behavior.