Skip to main content
Ask your AI

TikTok Pixel

Web Source code Package

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.

Where this fits

TikTok Pixel is a web destination in the walkerOS flow:

Installation​

npm install @walkeros/collector @walkeros/web-destination-tiktok
import { startFlow } from '@walkeros/collector';
import destinationTiktok from '@walkeros/web-destination-tiktok';

await startFlow({
  destinations: {
    tiktok: {
      code: destinationTiktok,
      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​

PropertyTypeDescriptionMore
apiKey*stringYour TikTok Pixel ID. Find it in TikTok Ads Manager under "Assets" → "Events" → "Web Events" → select your pixel → "Setup Web Event" → "Pixel ID".
auto_configbooleanEnable automatic form field detection for Advanced Matching. Forwarded to ttq.load(); when unset, the TikTok default applies.
limited_data_usebooleanRestrict data use for compliance with U.S. state privacy laws. Forwarded to ttq.load(); when unset, the TikTok default applies.
identifyanywalkerOS 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).
* Required fields

Mapping​

Per-event rules under config.mapping. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

PropertyTypeDescriptionMore
identifyanyPer-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.

Event
{
  "marketing": true
}
Out
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.

Event
{
  "marketing": false
}
Out
window.ttq.disableCookie()

Default track

Without a mapping the walker event name is forwarded to ttq.track with an event_id for TikTok dedup.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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": []
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "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": []
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "include": [
    "globals"
  ]
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "name": "Search",
  "data": {
    "map": {
      "query": "data.term"
    }
  },
  "include": []
}
Out
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.

Event
{
  "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"
  }
}
Mapping
{
  "name": "CompleteRegistration",
  "include": [],
  "data": {
    "map": {
      "content_type": {
        "value": "product"
      }
    }
  },
  "settings": {
    "identify": {
      "map": {
        "email": "data.email",
        "phone_number": "data.phone",
        "external_id": "data.user_id"
      }
    }
  }
}
Out
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.

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.

Page views

The destination calls no ttq.page(). A walkerOS page view without a rule goes out as ttq.track('page view', ...).

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)