TikTok Events API

TikTok is a social platform short-form video hosting service. The TikTok Events API is a server-side integration that allows you to share website and app visitor events directly with TikTok using their Events API for Web and Events API for App version 1.3.

The Events API for App support is currently under beta testing and coming soon.

Key features

The TikTok Events API destination provides the following key features:

• Events structure: our Events reference matches TikTok's one, meaning that your data is properly bridged to the expected fields in an optimized way.

• Prebuilt mappings: data mapping for event-based destinations happens automatically, which simplifies user inputs.

• Smart mapping: data mapping can be readjusted using your datalayer defined fields.

• Support for multi-item data: information included in the item array is dispatched to TikTok.

• Support for test event code: real-time validation in your test environments with field test_event_code.

Destination setup

Before you get started with this destination, make sure you can access TikTok Ads Manager.

TikTok doesn't support custom event and/or additional property in the payload. In case these are still sent, TikTok will fully discard the associated event and its data.

Configuration

Settings	Description
Access Token	Required for WEB events. Your API Access Token as provided by TikTok. More details are available by following this LINK.
TikTok Pixel ID	Required for WEB events. Your Pixel ID as provided by TikTok. You can only add a single pixel id per destination. More details are available by following this LINK.
Test Event Code	For Web events only. This is used to test event tracking before deploying in production. This code can be found in the TikTok Ads Manager following Assets ➜ Events ➜ Manage (Web Events) ➜ Select your pixel ➜ Test Events (Tab) [1]

[1] The Test Event Code can only be set in test environments as TikTok won't save data coming from live events where this code is included. More details are available following this LINK.

Quick reference

Web events

TikTok supported web events are detailed in this LINK.

Commanders Act Events	TikTok Events
add_payment_info	AddPaymentInfo
add_to_cart	AddToCart
add_to_wishlist	AddToWishlist
begin_checkout	InitiateCheckout
click_button	ClickButton
complete_payment purchase	CompletePayment [1]
contact	Contact
download	Download
page_view	ViewContent
search	Search
sign_up	CompleteRegistration
submit_form	SubmitForm
subscribe	Subscribe

[1] With CompletePayment events you can take advantage of TikTok Value-Based Optimization for Web (VBO Web).

Field Mappings

Most properties can be remapped using our "Smart Mapping" feature. TikTok client-side pixel saves a unique identifier in cookie _ttp, which is used to match website visitor events with TikTok ads. This destination starts by getting this identifier from partners.tiktok.ttp . If it's not present, it looks for the previously mentioned cookie _ttp and sets TikTok context.user.ttp with the resulting value. The Tiktok Click ID, also known as ttclid, is a tracking parameter that is attached to your ad's landing page URLs. This destination checks if partners.tiktok.ttclid is set with the ttclid value. If it's not present, it looks for cookie ttclid. If none is found it tries by parsing the value from page.location.href . Advanced matching parameters are highly recommended to improve attribution rates: ensure properties.user.email and/or properties.user.phone is set. More details on the phone number format rules are available following this LINK.

Commanders Act Properties	TikTok Properties
context.event_timestamp	timestamp [1]
id	event_id [2]
TikTok Pixel ID	pixel_code
Test Event Code	test_event_code
context.page.url	context.page.url
context.page.referrer	context.page.referrer
context.device.ip	context.ip
context.device.user_agent	context.user_agent
user.id	context.user.external_id [3]
user.email	context.user.email [3]
user.phone	context.user.phone_number [3]
items.X.content_type	properties.contents.X.content_type [4]
items.X.id	properties.contents.X.content_id
items.X.product.price	properties.contents.X.price
items.X.quantity	properties.contents.X.quantity
items.X.product.category_1	properties.contents.X.content_category
items.X.product.name	properties.contents.X.content_name
content_type	properties.content_type [4]
currency	properties.currency
event_name	properties.description
search_term	properties.query
value	properties.value
status	properties.status
partners.tiktok.ttp	context.user.ttp [5]
partners.tiktok.ttclid	context.ad.callback [6]

[1] Automatically converted in the ISO 8601 format. [2] This is required if you are sending overlapping events from both TikTok client-side pixel and this destination. More details on the deduplication are available following this LINK. [3] Field automatically hashed with SHA256 if passed in clear. [4] This is eitherproductorproduct_groupdepending on how you have configured your data feed when you set up your product catalog. Default value:product. [5] partners.tiktok.ttp has priority over cookie _ttp. [6] partners.tiktok.ttclid has priority over cookie ttclid. and page.location.href parsing.