# TikTok Ads Destination Config Reference

TikTok Ads is an advertising destination. RudderStack sends conversion events to TikTok’s Events API from its servers, or loads the TikTok pixel in the browser in device mode.

In a TikTok Ads destination spec:

type: tiktok_ads
definition_version: 1

Sample configuration

yaml

version: rudder/v1
kind: destination
metadata:
  name: tiktok-ads-prod
spec:
  id: tiktok-ads-prod
  display_name: TikTok Ads Production
  type: tiktok_ads
  definition_version: 1
  enabled: true
  config:
    pixel_code: "{{ .TIKTOK_PIXEL_CODE }}"
    access_token: "{{ .TIKTOK_ACCESS_TOKEN }}"
    version: v2
    hash_user_properties: true

    events_to_standard:
      - from: Order Completed
        to: CompletePayment
      - from: Product Added
        to: AddToCart
    send_custom_events: false

    event_filtering:
      whitelist:
        - Order Completed
        - Product Added

    connection_mode:
      web: device
      cloud: cloud
    consent_management:
      web:
        - provider: oneTrust
          consents:
            - marketing

The above example loads the TikTok pixel on web sources in device mode and sends server-side events in cloud mode. event_filtering affects only the device-mode web traffic — see Event filtering.

Config keys

config accepts only the keys listed below. The shared config key rules cover unknown keys, defaults, and immutability.

In cloud mode TikTok Ads accepts only track events. In device mode, web sources also send identify and page.

Connection

pixel_code

RequiredSecret

Type: string

Description: Code of the TikTok pixel that receives the events. Used in both modes.

Notes:

At most 100 characters, and must not contain line breaks.
A {{ path || fallback }} template is accepted in place of a literal.

See How do I create a pixel in TikTok Ads?.

access_token

Secret

Type: string

Description: TikTok long-term access token for the Events API. Cloud mode needs it; device mode doesn’t.

Notes:

Rudder CLI doesn’t require this key, even when a source connects in cloud mode. Without it, cloud-mode delivery fails at TikTok.

Supply it as a {{ .VAR }} reference rather than a literal — see Secrets.

version

Type: string

Default value: v2

Description: TikTok Events API version for cloud mode.

Notes:

v2 or v1. Use v2 — TikTok announced the sunset of Events API 1.0.
A {{ path || fallback }} template is accepted in place of a literal.

hash_user_properties

Type: boolean

Default value: true

Description: SHA-256 hash contextual user properties such as external_id, email, and phone_number before sending them.

Notes:

Applies to cloud mode only.

Event mapping

events_to_standard

Type: array of objects

Description: Maps RudderStack event names to TikTok standard events. Events without a mapping follow the default mapping in Event mapping.

Notes:

from — RudderStack event name. At most 100 characters, and must not contain line breaks.
to — one of AddPaymentInfo, AddToCart, AddToWishlist, ClickButton, CompletePayment, CompleteRegistration, Contact, Download, InitiateCheckout, PlaceAnOrder, Search, SubmitForm, Subscribe, ViewContent, CustomizeProduct, FindLocation, Schedule, Purchase, Lead, ApplicationApproval, SubmitApplication, or StartTrial.
Both fields accept a {{ path || fallback }} template in place of a literal.

yaml

events_to_standard:
  - from: Order Completed
    to: CompletePayment

send_custom_events

Type: boolean

Default value: false

Description: Send events that don’t map to a standard event as TikTok custom events. For custom events, only TikTok’s standard fields are sent; other fields are dropped.

Event filtering

Client-side event filtering is applied by the RudderStack SDK, so it affects only web sources connected in device mode. Events sent in cloud mode reach TikTok unfiltered, whatever this block says.

event_filtering

Type: object

Description: Restricts which track events the SDK passes to the TikTok pixel, by event name.

Notes:

whitelist — array of event names to allow; every other track event is dropped.
blacklist — array of event names to drop; every other track event is allowed.
The two are mutually exclusive, and Rudder CLI enforces it — setting both fails validation.
Each name is at most 100 characters, or a {{ path || fallback }} template.
Omit the block entirely to filter nothing.

yaml

event_filtering:
  blacklist:
    - Product Viewed

Per-source keys

Both keys are objects keyed by the local source type — the tokens listed under Source types. A key naming a source type this destination doesn’t support fails validation.

connection_mode

Type: object

Description: Maps each source type you connect to the mode its events reach TikTok in, using the modes in Source types.

Notes:

An entry is required for each source type you connect — see Connect a source.
A mode the source type doesn’t support on this destination fails validation — for example device for android.

yaml

connection_mode:
  web: device
  cloud: cloud

consent_management

Type: object

Description: Consent provider configuration per source type. The entry shape, accepted providers, and the rules on resolution_strategy and consents are shared across all destination types — see Consent management.

Source types

TikTok Ads accepts events from these source types in the mentioned connection modes:

Source type	Connection mode
`android`	`cloud`
`android_kotlin`	`cloud`
`ios`	`cloud`
`ios_swift`	`cloud`
`web`	`cloud`, `device`
`unity`	`cloud`
`react_native`	`cloud`
`flutter`	`cloud`
`cordova`	`cloud`
`cloud`	`cloud`

Only web offers device mode, which loads the TikTok pixel in the browser. See TikTok Ads device mode and RudderStack Connection Modes.

The dashboard additionally offers TikTok Ads to AMP, Shopify, and Reverse ETL sources. Rudder CLI doesn’t manage those connections, so amp, shopify, and warehouse are invalid here.

Connect a source

An event stream connection to this destination is checked against two rules at validate time.

The source’s type must be supported. A source’s type resolves to one of the tokens above before the check — a JavaScript source resolves to web, and webhook and server-side SDK sources resolve to cloud. An unsupported type reports:

destination 'tiktok-ads-prod' (type 'tiktok_ads') does not support source 'my-source':
source type 'amp' is not among supported source types: android, android_kotlin, ...

The destination config must carry a connection_mode entry for that source type. This lives on the destination spec, not on the connection spec. Without it:

destination 'tiktok-ads-prod' config has no 'connection_mode' entry for source type 'web'

TikTok Ads needs no additional config keys to connect a source of any type, in any mode.

Secrets

pixel_code and access_token are the secret keys. Write each as a {{ .VAR }} reference and supply the value at apply time:

yaml

config:
  pixel_code: "{{ .TIKTOK_PIXEL_CODE }}"
  access_token: "{{ .TIKTOK_ACCESS_TOKEN }}"

bash

export RUDDER_TIKTOK_PIXEL_CODE="..."
export RUDDER_TIKTOK_ACCESS_TOKEN="..."
rudder-cli apply

# or
rudder-cli apply --var-file secrets.vars.yaml

Note that:

The YAML that rudder-cli import writes may or may not include secret keys. Before you apply, make sure every secret key your configuration needs is present and populated through variable substitution.
In device mode the pixel code is embedded in the page’s JavaScript, so treating it as a secret protects your YAML, not the value itself.

See How to Use Variable Substitution in Rudder CLI.

See more

TikTok Ads Destination for pixel setup and verifying delivery
Destination Type Reference for Rudder CLI for the rules shared across destination types
Destination YAML Reference for the spec envelope