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

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

Event mapping

events_to_standard:
  - from: Order Completed
    to: CompletePayment

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:
  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:
  web: device
  cloud: cloud

Source types

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

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

warehouse is the token a Reverse ETL source resolves to. Rudder CLI manages the destination’s warehouse entry — if the destination is connected to a Reverse ETL source, set connection_mode.warehouse: cloud in its spec, or apply removes it.

Rudder CLI can also declare the Reverse ETL connection itself, for the types listed under Supported destinations — see Manage Reverse ETL Connections using Rudder CLI.

The dashboard additionally offers TikTok Ads to AMP and Shopify sources. Rudder CLI doesn’t manage those connections, so amp and shopify 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. Every type an event stream source can resolve to is supported here, so this check always passes.

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:

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

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

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

Note that:

• rudder-cli import writes only the secrets the API returns, as {{ .VAR }} references, and leaves the others out. Add any secret key it leaves out, then supply the variables before you apply — see Secrets.
• 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.

Changes by release

For changes across every destination type, see Destination Type Changes by Release.

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