TikTok Pixel
The TikTok Pixel
forwards browser conversions to TikTok Ads for optimization, audience
building, and reporting. This destination loads the TikTok Pixel script from
analytics.tiktok.com/i18n/pixel/events.js unless loadScript is false.
Events become ttq.track(name, params, { event_id })
calls; identity becomes ttq.identify({ email, phone_number, external_id });
with config.consent, consent toggles ttq.enableCookie / ttq.disableCookie.
TikTok Pixel is a web destination in the walkerOS flow:
Installation
npm install @walkeros/collector @walkeros/web-destination-tiktok- Integrated
- Bundled
import { startFlow } from '@walkeros/collector';
import destinationTiktok from '@walkeros/web-destination-tiktok';
await startFlow({
destinations: {
tiktok: {
code: destinationTiktok,
config: {
settings: {
apiKey: 'C4A1B2C3D4E5F6A7B8C9',
},
},
},
},
});
A complete flow.json with this destination:
{
"version": 4,
"flows": {
"default": {
"config": {
"platform": "web"
},
"destinations": {
"tiktok": {
"package": "@walkeros/web-destination-tiktok",
"config": {
"settings": {
"apiKey": "C4A1B2C3D4E5F6A7B8C9"
}
}
}
}
}
}
}The quickstart above sets no consent, so the TikTok Pixel script loads as the
flow starts, every event the destination sends goes out without marketing
consent, and a revocation changes nothing. Add
consent: { marketing: true } to config, next to settings, before you go
live (see Consent).
The destination starts only when window.ttq already provides load. On a
page without that, the quickstart does not start: the console shows one ERROR line
destination init failed with the code vendor-not-ready, every push answers
failed with that code, and each push tries to start it again. Whatever sets
up window.ttq on your page runs outside the walkerOS consent gate, so it has
to wait for consent itself; otherwise the Pixel loads before config.consent
is met.
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 | Enable automatic form field detection for Advanced Matching. Forwarded to ttq.load(); when unset, the TikTok default applies. | |
limited_data_use | boolean | Restrict data use for compliance with U.S. state privacy laws. Forwarded to ttq.load(); when unset, the TikTok default applies. | |
identify | any | walkerOS mapping value resolving to an Advanced Matching object with any of: email, phone_number, external_id. The destination passes the values to ttq.identify() unhashed; TikTok states that its Pixel hashes email and phone number (SHA-256). |
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
With config.consent set to marketing, a walker consent grant for marketing calls ttq.enableCookie so TikTok can set and read its attribution cookie.
{
"marketing": true
}window.ttq.enableCookie()Consent revoked
With config.consent set to marketing, a walker consent revoke for marketing calls ttq.disableCookie so TikTok stops using its first-party cookie.
{
"marketing": false
}window.ttq.disableCookie()Default track
Without a mapping the walker event name is forwarded to ttq.track with an event_id for TikTok dedup.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "0123456789abcdef",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}window.ttq.track("product view", {}, {
"event_id": "0123456789abcdef"
})Advanced matching
With settings.identify mapping email, phone and external id, the first push calls ttq.identify for TikTok advanced matching before the track call.
{
"name": "page view",
"data": {
"email": "user@acme.com",
"phone": "+14135552671"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"pagegroup": "docs"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "44444444dddddddd",
"trigger": "load",
"entity": "page",
"action": "view",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}window.ttq.identify({
"email": "user@acme.com",
"phone_number": "+14135552671",
"external_id": "us3r"
});
window.ttq.track("page view", {}, {
"event_id": "44444444dddddddd"
})Include data
With config.include set to data, the event data section is flattened into prefixed TikTok event parameters.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "22222222bbbbbbbb",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}window.ttq.track("product view", {
"data_id": "ers",
"data_name": "Everyday Ruck Snack",
"data_color": "black",
"data_size": "l",
"data_price": 420,
"data_currency": "EUR"
}, {
"event_id": "22222222bbbbbbbb"
})Purchase
A completed order is mapped to TikTok Purchase with value, currency, and nested product contents.
{
"name": "order complete",
"data": {
"id": "0rd3r1d",
"currency": "EUR",
"value": 462,
"tax": 73.76,
"shipping": 5.22,
"total": 467.22
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "gift",
"data": {
"name": "Surprise"
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "66666666ffffffff",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "Purchase",
"data": {
"map": {
"content_type": {
"value": "product"
},
"value": "data.value",
"currency": {
"key": "data.currency",
"value": "EUR"
},
"order_id": "data.id",
"contents": {
"loop": [
"nested",
{
"map": {
"content_id": "data.id",
"content_name": "data.name",
"quantity": {
"key": "data.quantity",
"value": 1
},
"price": "data.price"
}
}
]
}
}
},
"include": []
}window.ttq.track("Purchase", {
"content_type": "product",
"value": 462,
"currency": "EUR",
"order_id": "0rd3r1d",
"contents": [
{
"content_id": "ers",
"content_name": "Everyday Ruck Snack",
"quantity": 1,
"price": 420
},
{
"content_id": "cc",
"content_name": "Cool Cap",
"quantity": 1,
"price": 42
},
{
"content_name": "Surprise",
"quantity": 1
}
]
}, {
"event_id": "66666666ffffffff"
})View content
A product view is renamed to the TikTok ViewContent standard event with content_type, id, value, and currency.
{
"name": "product view",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420,
"currency": "EUR"
},
"context": {
"shopping": [
"detail",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [],
"consent": {
"functional": true
},
"id": "11111111aaaaaaaa",
"trigger": "load",
"entity": "product",
"action": "view",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "ViewContent",
"data": {
"map": {
"content_type": {
"value": "product"
},
"content_id": "data.id",
"content_name": "data.name",
"content_category": "data.category",
"value": "data.price",
"currency": {
"key": "globals.currency",
"value": "EUR"
}
}
},
"include": []
}window.ttq.track("ViewContent", {
"content_type": "product",
"content_id": "ers",
"content_name": "Everyday Ruck Snack",
"value": 420,
"currency": "EUR"
}, {
"event_id": "11111111aaaaaaaa"
})Rule include overrides
With config.include set to data, a rule include of globals replaces it, so this event forwards only globals.
{
"name": "order complete",
"data": {
"id": "0rd3r1d",
"currency": "EUR",
"value": 462,
"tax": 73.76,
"shipping": 5.22,
"total": 467.22
},
"context": {
"shopping": [
"complete",
0
]
},
"globals": {
"pagegroup": "shop"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "product",
"data": {
"id": "ers",
"name": "Everyday Ruck Snack",
"color": "black",
"size": "l",
"price": 420
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "product",
"data": {
"id": "cc",
"name": "Cool Cap",
"size": "one size",
"price": 42
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
},
{
"entity": "gift",
"data": {
"name": "Surprise"
},
"context": {
"shopping": [
"complete",
0
]
},
"nested": []
}
],
"consent": {
"functional": true
},
"id": "33333333cccccccc",
"trigger": "load",
"entity": "order",
"action": "complete",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"include": [
"globals"
]
}window.ttq.track("order complete", {
"globals_pagegroup": "shop"
}, {
"event_id": "33333333cccccccc"
})Search
A search submit fires TikTok Search with the query field mapped from event data.
{
"name": "search submit",
"data": {
"term": "hiking backpack"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "777777770000aaaa",
"trigger": "test",
"entity": "search",
"action": "submit",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "Search",
"data": {
"map": {
"query": "data.term"
}
},
"include": []
}window.ttq.track("Search", {
"query": "hiking backpack"
}, {
"event_id": "777777770000aaaa"
})Complete registration
A user register fires ttq.identify for advanced matching and then tracks CompleteRegistration.
{
"name": "user register",
"data": {
"email": "new@acme.com",
"phone": "+14135551234",
"user_id": "new-user-123"
},
"context": {
"dev": [
"test",
1
]
},
"globals": {
"lang": "elb"
},
"custom": {
"completely": "random"
},
"user": {
"id": "us3r",
"device": "c00k13",
"session": "s3ss10n"
},
"nested": [
{
"entity": "child",
"data": {
"is": "subordinated"
}
}
],
"consent": {
"functional": true
},
"id": "55555555eeeeeeee",
"trigger": "test",
"entity": "user",
"action": "register",
"timestamp": 1700000000000,
"timing": 3.14,
"source": {
"count": 1,
"trace": "0a1b2c3d4e5f60718293a4b5c6d7e8f9",
"type": "collector",
"schema": "4"
}
}{
"name": "CompleteRegistration",
"include": [],
"data": {
"map": {
"content_type": {
"value": "product"
}
}
},
"settings": {
"identify": {
"map": {
"email": "data.email",
"phone_number": "data.phone",
"external_id": "data.user_id"
}
}
}
}window.ttq.identify({
"email": "new@acme.com",
"phone_number": "+14135551234",
"external_id": "new-user-123"
});
window.ttq.track("CompleteRegistration", {
"content_type": "product"
}, {
"event_id": "55555555eeeeeeee"
})Standard events
TikTok optimizes ads on its
standard events.
Use mapping.name to send a walkerOS event under one of their names, for
example ViewContent, AddToCart or Purchase; an event without a rule goes
out under its walkerOS name. A rule whose data resolves to something other
than an object is sent with empty parameters, and its push answers done.
Advanced matching
TikTok matches conversions back to TikTok users via three optional parameters:
email, phone_number, external_id. The destination passes the resolved
values to ttq.identify() as they are, unhashed. TikTok states that its Pixel
hashes email addresses and phone numbers with SHA-256
(Advanced Matching);
the values still reach TikTok's script in the browser in plain form.
settings.identify (destination-level) fires on first push and re-fires only
when the resolved value changes.
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
For TikTok, an advertising platform, the typical walkerOS consent key is
marketing (whatever name your CMP reports). The walkerOS config.consent
gate holds events until that consent is granted: they wait in the
destination's queue and are sent once it is, and walkerOS injects the Pixel
script only then (see
consent management).
The destination's on('consent') handler then toggles TikTok's own cookie
state for attribution.
config: {
consent: { marketing: true },
settings: { apiKey: 'C4XXXXXXXXXXXXXXXXXXX' },
}The handler acts on a consent command that names at least one key of
config.consent and reads the whole consent state: it calls
ttq.enableCookie() when at least one of those keys is granted, the rule the
gate applies to events, and ttq.disableCookie() when none is.
The destination calls no ttq.page(). A walkerOS page view without a rule
goes out as ttq.track('page view', ...).
Related
- TikTok Events API destination: the server-side counterpart
- Bundled mode