> For the complete documentation index, see [llms.txt](https://docs.chord.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chord.co/activate/event-streaming/destinations/advertising/tiktok/tiktok-pixel.md). # TikTok Pixel The **TikTok Pixel** destination loads the TikTok Pixel JavaScript SDK in the browser and forwards ecommerce and engagement events to TikTok Ads. Unlike the [TikTok Conversions API](/activate/event-streaming/destinations/advertising/tiktok/tiktok-conversions-api.md), its events start in the browser and can use the full TikTok Pixel feature set. Use this destination alongside the [TikTok Conversions API](/activate/event-streaming/destinations/advertising/tiktok/tiktok-conversions-api.md) for maximum signal coverage. See [TikTok](/activate/event-streaming/destinations/advertising/tiktok.md) for how the two fit together. ## Getting started Chord loads the TikTok Pixel for you, so you don't install any script. You need your TikTok Pixel ID, found in TikTok Ads Manager under **Assets > Events > Web Events**. ## Settings * **Destination Name** (required): a name to tell this destination apart. * **Pixel Code** (required): your TikTok Pixel ID. * **Limited Data Use (LDU)** (optional): turns on TikTok's Limited Data Use feature, which helps you meet opt-out rules under some US state privacy laws. Off by default. * **Auto Page View** (optional): sends a page view when the pixel loads on the page. On by default. * **Product Content ID Field** (required): which product field to send as the content ID: `sku`, `variant_id`, `product_id` or `id`. Defaults to `sku`. The value must match your product catalog. * **Dedup Source Property** (optional): a property path, for example `properties.order_id`, that Chord uses as the event ID for deduplication with the TikTok Conversions API. If it is empty, or the event has no value there, Chord uses the message ID. Set the same value on the TikTok Conversions API destination. See [TikTok](/activate/event-streaming/destinations/advertising/tiktok.md). * **Consent Requirements** (optional): the consent categories a visitor must accept before Chord sends data to this destination. See [Consent](/activate/event-streaming/consent.md). ## Connect Add **TikTok Pixel** from the destination catalog, using the settings above. See [Connect a destination](/activate/event-streaming/connect-a-destination.md) for the full steps. ## Event mapping Every event with user data first calls `ttq.identify()` with that data, then sends the conversion event. | Chord event | TikTok event | Notes | | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----- | | `page` | *(page view on load)*. Fires when the pixel loads if **Auto Page View** is on. Later page events send user identification only | | | `identify` | `ttq.identify()` only. No conversion event is sent | | | [`Order Completed`](/collect-data/tracking-plan/order-completed.md) | `CompletePayment` | | | [`Checkout Started`](/collect-data/tracking-plan/checkout-started.md) | `InitiateCheckout` | | | [`Payment Info Entered`](/collect-data/tracking-plan/payment-info-entered.md) | `AddPaymentInfo` | | | [`Product Added`](/collect-data/tracking-plan/product-added.md) | `AddToCart` | | | [`Product Viewed`](/collect-data/tracking-plan/product-viewed.md) | `ViewContent` | | | [`Product Clicked`](/collect-data/tracking-plan/product-clicked.md) | `ClickButton` | | | [`Product Added to Wishlist`](/collect-data/tracking-plan/product-added-to-wishlist.md) | `AddToWishlist` | | | [`Products Searched`](/collect-data/tracking-plan/products-searched.md) | `Search` | | | [`Signed Up`](/collect-data/tracking-plan/signed-up.md) | `CompleteRegistration` | | | [`Subscription Created`](/collect-data/tracking-plan/subscription-created.md) | `Subscribe` | | | [`Email Captured`](/collect-data/tracking-plan/email-captured.md) | `Lead` | | | `Form Submitted` | `SubmitForm` | | | `Callback Started` | `Contact` | | | `Download Link Clicked` | `Download` | | | *(any other track event)* | The Chord event name, as is. See [Custom events](#custom-events) | | ## Identify Sets user identity on the TikTok pixel for enhanced matching. Chord calls `ttq.identify()` before every event that has a user ID, an anonymous ID, an email or a phone number. **TikTok SDK call:** `ttq.identify(userData)` | Chord source (priority order) | TikTok field | Notes | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `properties.email` > `context.traits.email` > `traits.email` | `email` or `sha256_email` | Sent as `sha256_email` if the value is already a SHA-256 digest. Otherwise sent as `email`, and TikTok hashes it | | `properties.phone` > `context.traits.phone` > `traits.phone` | `phone_number` or `sha256_phone_number` | Sent as `sha256_phone_number` if the value is already a SHA-256 digest. Otherwise sent as `phone_number` in E.164 format. A value with fewer than 7 digits, one repeated digit, or a placeholder such as `n/a` is not sent | | `userId` > `anonymousId` | `external_id` | | | `properties.first_name` > `context.traits.first_name` > `traits.first_name` > first word of the address name | `first_name` | Lowercased, whitespace removed | | `properties.last_name` > `context.traits.last_name` > `traits.last_name` > second word of the address name | `last_name` | Lowercased, whitespace removed | | `properties.address.city` > `context.traits.address.city` > `traits.address.city` | `city` | Lowercased, non-alphanumeric characters removed | | `properties.address.state` > `context.traits.address.state` > `traits.address.state` | `state` | Lowercased, non-alphanumeric characters removed | | `properties.address.country` > `context.traits.address.country` > `traits.address.country` | `country` | Lowercased, non-alphanumeric characters removed | | `properties.address.zipcode` > `properties.address.postalCode` > `properties.address.zip`, then the same fields on `context.traits.address` and `traits.address` | `zip_code` | Lowercased, whitespace removed | ## PII handling TikTok's `track()` event schema does not include PII fields. Email, phone and name belong only in `ttq.identify()`, where TikTok hashes them in the browser with SHA-256 before sending. To prevent accidental PII exposure, these fields are always left out of track event payloads, even if a property mapping writes to them: `email`, `phone`, `phone_number`, `first_name`, `last_name` and `address`. If a mapping writes to one of these fields (for example `properties.email → properties.email`), the value still reaches `ttq.identify()` through the normal user data lookup. It does not appear in the `track()` payload. ## Event properties Every track event is sent with the same set of properties. Product data depends on the event: * **Order Completed, Checkout Started and Payment Info Entered** read every item in `properties.products[]`. * **All other events** read the product from the top-level `properties` (for example `properties.sku` and `properties.price`), and use the first item of `properties.products[]` for any field the top level lacks. An event with no product data sends an empty `contents` array. **TikTok SDK call:** `ttq.instance(pixelCode).track(eventName, eventProperties, { event_id })` | Chord source (priority order) | TikTok field | Notes | | ----------------------------------------------------------------------------------------------------------- | -------------- | ----------------------------------------------------------- | | The property named in **Dedup Source Property** | `event_id` | Falls back to `messageId` | | *(hardcoded)* `"product"` | `content_type` | | | `properties.currency` > `properties.meta.i18n.currency` | `currency` | Defaults to `"USD"` | | `properties.value` > `properties.total` > `properties.price` | `value` | Falls back to the sum of `price × quantity` across products | | `properties.cart_id` > `properties.cartId` > `properties.order_id` > `properties.orderId` > `properties.id` | `order_id` | Omitted if none is present | | `properties.shop_id` | `shop_id` | Omitted if not present | | First product's `description` | `description` | Omitted if not present | | `properties.query` | `query` | Omitted if not present | | Each product, as in the next table | `contents` | | **Each item in `contents`** | Chord source (priority order) | TikTok field | Notes | | -------------------------------------------------------------------------- | ------------------ | ----- | | The field you chose in **Product Content ID Field**, read from the product | `content_id` | | | Product `name` | `content_name` | | | Product `category` | `content_category` | | | Product `price` | `price` | | | Product `quantity`, which defaults to `1` | `quantity` | | | Product `brand` | `brand` | | If **Product Content ID Field** is not set, which only happens on destinations created before the field existed, `content_id` is the product's `sku` > `product_id` > `id`. ## Custom events Any track event that is not in the table above is sent to TikTok under its Chord event name, as is. The payload has the same properties as every other event. If the event carries `products`, `currency`, `value` or order data, Chord sends them. Custom properties from property mappings are also included. If the TikTok event name you want does not match your Chord event name, use a property mapping in Chord to rename the event before it reaches this destination. ## Custom property forwarding Configure destination mappings in Chord with `properties.*` destination paths to forward additional event properties alongside the computed schema fields in the `ttq.instance(...).track(...)` payload. Only explicitly-configured non-schema fields are forwarded — nothing flows through automatically. **How to configure:** 1. In Chord, open the destination's connection and find **Property Mappings**. See [Property mappings](/activate/event-streaming/property-mappings.md#add-a-mapping) for the steps. 2. Add a mapping with source path `properties.loyalty_tier` and destination path `properties.loyalty_tier`. 3. On the next event, `loyalty_tier` will appear in the event properties payload sent to TikTok. **What is excluded:** * Fields Chord already computes: `currency`, `value`, `revenue`, `order_id`, `products`, `shop_id`, `description` and `query`. * PII fields (`email`, `phone`, `phone_number`, `first_name`, `last_name` and `address`). See [PII handling](#pii-handling). These are left out of track event payloads and handled by `ttq.identify()` instead. A mapping to a field that Chord computes is ignored. The computed value is always the one sent. ## Initialization Chord sets up the `ttq` function queue, then loads `https://analytics.tiktok.com/i18n/pixel/events.js`. The partner name is set to `"Chord"`. If **Auto Page View** is `true` (default), an initial page view is fired immediately after initialization. Chord tracks SDK loading state (`fresh` → `loading` → `loaded`/`failed`) to prevent duplicate script loads. If the script fails to load, subsequent events are silently dropped. ## CSP requirements If your site uses a Content Security Policy, allow the following domains: | Directive | Domain | | ------------- | ------------------------------ | | `script-src` | `https://analytics.tiktok.com` | | `connect-src` | `https://analytics.tiktok.com` | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.chord.co/activate/event-streaming/destinations/advertising/tiktok/tiktok-pixel.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.