TikTok Ads Destination Config Reference Beta

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.

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:

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:

• 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