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:
Installation
- Integrated
- Bundled
Configuration
This destination uses the standard destination config wrapper (consent, data, env, id, ...). For the shared fields see destination configuration. Package-specific fields live under config.settings and are listed below.
Settings
| 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. |
Mapping
Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.
| Property | Type | Description | More |
|---|---|---|---|
identify | any | Per-event Advanced Matching mapping. Resolves to an object with any of: email, phone_number, external_id. Overrides destination-level settings.identify for this rule. |
Examples
Consent granted
A walker consent grant for marketing calls ttq.enableCookie so TikTok can set and read its attribution cookie.
Consent revoked
A walker consent revoke for marketing calls ttq.disableCookie so TikTok stops using its first-party cookie.
Default track
Without a mapping the walker event name is forwarded to ttq.track with an event_id for TikTok dedup.
Advanced matching
Destination-level identify calls ttq.identify with email, phone, and external id for TikTok advanced matching.
Include data
Destination-level include flattens the event data section into prefixed TikTok event parameters.
Complete payment
A completed order is mapped to TikTok CompletePayment with value, currency, and nested product contents.
View content
A product view is renamed to the TikTok ViewContent standard event with content_type, id, value, and currency.
Rule include overrides
A per-rule include replaces the destination-level include so this event forwards only globals.
Search
A search submit fires TikTok Search with the query field mapped from event data.
Complete registration
A user register fires ttq.identify for advanced matching and then tracks CompleteRegistration.
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 |
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.