TikTok Ads Cloud Mode Integration

Send events to TikTok Ads using RudderStack cloud mode.

3 minute read

RudderStack lets you send your event data to TikTok Ads via cloud mode.

Note that:
This integration supports both Events 1.0 and Events 2.0 API for sending events to TikTok. RudderStack recommends using the Events 2.0 API to send your events as TikTok will sunset the Events 1.0 API by the second half of 2024.
To send custom events to TikTok Ads using RudderStack Open Source, use rudder-transformer v1.52.0 or later.

Find the open source transformer code for this destination in the GitHub repository.

Track

Use the track call to capture user events along with the associated properties.

A sample track call is shown below:

rudderanalytics.track("Order Completed", {
  checkout_id: "12345",
  order_id: "1234",
  affiliation: "Apple Store",
  total: 20,
  revenue: 15.0,
  shipping: 22,
  tax: 1,
  discount: 1.5,
  coupon: "ImagePro",
  currency: "USD",
  contentType: "product",
  products: [{
      product_id: "123",
      sku: "G-32",
      name: "Monopoly",
      price: 14,
      quantity: 1,
      category: "Games",
      url: "https://www.website.com/product/path",
      image_url: "https://www.website.com/product/path.jpg",
    },
    {
      product_id: "345",
      sku: "F-32",
      name: "UNO",
      price: 3.45,
      quantity: 2,
      category: "Games",
    },
  ],
})

Event mapping

This destination does not strictly adhere to the RudderStack Ecommerce Event Spec.

You can use the Event mapping settings in the dashboard to map your events to the below TikTok standard events:

Add to Cart
Add to Wishlist
Add Payment Info
Click Button
Complete Payment
Complete Registration
Contact
Customize Product
Download
Find Location
Initiate Checkout
Place an Order
Schedule
Search
Submit Form
Subscribe
View Content

Note that RudderStack automatically maps the following standard ecommerce events to the corresponding TikTok standard events:

RudderStack event	TikTok Ads event
`Product Added to Wishlist`	`Add to Wishlist`
`Product Added`	`Add to Cart`
`Checkout Started`	`Initiate Checkout`
`Payment Info Entered`	`Add Payment Info`
`Checkout Step Completed`	`Complete Payment`
`Order Completed`	`Place an Order`

Property mapping

RudderStack maps the following optional event properties to the corresponding TikTok Ads fields:

RudderStack property	TikTok Ads property
`properties.eventId` `properties.event_id` `messageId`	`data.$.event_id`
`timestamp`	`data.$.event_time`
`phone`	`data.$.user.phone`
`properties.contents`	`data.$.properties.contents`
`properties.contentType` `properties.content_type`	`data.$.properties.content_type`
`properties.currency`	`data.$.properties.currency`
`properties.description`	`data.$.properties.description`
`properties.email` `traits.email` `context.traits.email` `context.user.email`	`data.$.user.email`
`properties.limited_data_use`	`data.$.limited_data_use`
`properties.orderId` `properties.order_id`	`data.$.properties.order_id`
`properties.value`	`data.$.properties.value`
`properties.query`	`data.$.properties.query`
`properties.shopId` `properties.shop_id`	`data.$.properties.shop_id`
`properties.ttclid`	`data.$.user.ttclid`
`properties.ttp`	`data.$.user.ttp`
`properties.referrer` `context.page.referrer`	`data.$.page.referrer`
`properties.url` `context.page.url`	`data.$.page.url`
`context.locale`	`data.$.user.locale`
`context.ip` `request_ip`	`data.$.user.ip`
`context.userAgent`	`data.$.user.user_agent`
`properties.testEventCode`	`test_event_code`
From `externalId` `tiktokExternalId`	`data.$.user.external_id`
`firstName` `traits.firstName` `traits.firstname` `traits.first_name` `context.traits.firstName` `context.traits.firstname` `context.traits.first_name`	`data.$.user.first_name`
`lastName` `traits.lastName` `traits.lastname` `traits.last_name` `context.traits.lastName` `context.traits.lastname` `context.traits.last_name`	`data.$.user.last_name`
`context.traits.city` `context.traits.address.city` `properties.city`	`data.$.user.city`
`context.traits.country` `context.traits.address.country` `properties.country`	`data.$.user.country`
`context.traits.address.state` `context.traits.state` `properties.state`	`data.$.user.state`
`zipcode`	Reference

Note that the properties.ttclid to user.ttclid mapping corresponds to the properties.clickId to context.ad.callback mapping in Events 1.0 API.

TikTok will sunset the Events 1.0 API by the second half of 2024. RudderStack recommends using the Events 2.0 API to send your events.

RudderStack property	TikTok Ads property
`properties.eventId`	`event_id`
`timestamp`	`timestamp`
`properties.testEventCode`	`test_event_code`
`properties.contents`	`properties.contents`
`properties.currency`	`properties.currency`
`properties.clickId`	`context.ad.callback`
`properties.value`	`properties.value`
`properties.description`	`properties.description`
`properties.query`	`properties.query`
`properties.context.ad` or `context.ad`	`context.ad`
`properties.context.page` or `context.page`	`context.page`
`properties.context.user`	`context.user`
`context.ip`	`context.ip`
`context.userAgent`	`context.user_agent`
From `externalId` `tiktokExternalId`	`user.external_id`

For custom events, RudderStack maps only the standard fields supported by TikTok Ads and drops all other fields in the event. See TikTok Ads standard fields documentation for more information.

FAQ

I see a 40002 response code with ‘No permission to operate pixel code’ error message, what can I do?

This error code is related to the authentication of your TikTok account. For more information, refer to the TikTok documentation.

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack