TikTok Events API

TikTok for Business is a global platform designed to give brands and marketers the solutions to be creative storytellers and meaningfully engage with the TikTok community. 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 2.0.

The Events API for APP support is currently under beta testing.

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.

• Automatic hashing: information is automatically hashed matching partner specifications.

• 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 custom events are available for reporting and audience creation purposes. Optimization is currently NOT supported.

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.
Pixel Id	Required for Web events. Your pixel identifier as provided by TikTok. More details are available by following this LINK.
App Id	Required for App events. Your app identifier as provided by TikTok. 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]
Event Mapping	Change the standard mapping between TikTok's events and yours or add new mappings: custom events are also supported. More details on how you can set up custom TikTok web events are available following this LINK.
TikTok "ViewContent" Event Mapping	Select page_view, view_item or both to send TikTok ViewContent event. See Quick reference for more details on event mapping.
Autodiscovery Event Source	Flag this option to set TikTok event_source based on the value provided in the "Smart Mapping" field Experience Type or in the standard property context.app . The "Smart Mapping" field Event Source has priority over this option.
Do Not Lower Case User Id	When flagged and the User Id (See Smart Mapping section) is provided in clear test, the user identifier is not forced to lower case before applying SHA256 hash algorithm.

[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

TikTok standard events are detailed in this LINK.

Commanders Act Events	TikTok Events
achieve_level	AchieveLevel [2]
add_payment_info	AddPaymentInfo
add_to_cart	AddToCart
add_to_wishlist	AddToWishlist
application_approval	ApplicationApproval [1]
begin_checkout	InitiateCheckout [1]
click_button view_content	ViewContent
complete_tutorial	CompleteTutorial [2]
create_group	CreateGroup [2]
create_role	CreateRole [2]
customize_product	CustomizeProduct [1]
purchase	CompletePayment [1][4] Checkout [2]
complete_payment	CompletePayment [1][4] Purchase [2]
contact	Contact [1]
download	Download [1]
find_location	FindLocation [1]
submit_form generate_lead	Lead [1]
generate_lead	GenerateLead [2]
in_app_ad_click	InAppADClick [2]
in_app_ad_impr	InAppAdImpr [2]
install_app	InstallApp [2]
join_group	JoinGroup [2]
launch_app	LaunchAPP [2]
loan_application	LoanApplication [2]
loan_approval	LoanApproval [2]
loan_disbursal	LoanDisbursal [2]
login	Login [2]
view_content page_view[3] view_item[3]	ViewContent
rate	Rate [2]
schedule	Schedule [1]
search	Search
sign_up	CompleteRegistration [1] Registration [2]
spend_credits	SpendCredits [2]
start_trial	StartTrial
submit_application	SubmitApplication [1]
subscribe	Subscribe
unlock_achievement	UnlockAchievement [2]

[1] For web events only. See event_source in Configuration for more details. [2] For app events only. See event_source in Configuration for more details. [3] Depending on your selection for TikTok "ViewContent" Event Mapping . See Configuration for more details. [4] 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 data.0.user.ttp with the resulting value. The Tiktok Click ID 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 context.page.url .

Commanders Act Properties	TikTok Properties
partners.tiktok.event_source	event_source [*][1]
Pixel Id App Id	event_source_id [*]
event_name	data.0.event [*][2]
context.event_timestamp	data.0.event_time [*][3]
id	data.0.event_id [4]
partners.tiktok.ttclid	data.0.user.ttclid [5]
user.id	data.0.user.external_id [6]
partners.tiktok.ttp	data.0.user.ttp [7]
context.page.url	data.0.page.url
context.page.referrer	data.0.page.referrer
context.device.advertising_id	data.0.user.idfa [8]
context.device.idfv	data.0.user.idfv [8]
context.device.att_status	data.0.user.att_status [8][9]
context.device.advertising_id	data.0.user.gaid [10]
context.app.namespace	data.0.app.app_id [11]
context.app.name	data.0.app.app_name
context.app.version	data.0.app.app_version
user.email	data.0.user.email [6]
user.phone	data.0.user.phone [6][12]
context.device.ip	data.0.user.ip
context.device.user_agent	data.0.user.user_agent
context.device.language	data.0.user.locale [13]
partners.tiktok.ldu	data.0.limited_data_use [14]
items.X.content_type	data.0.properties.contents.X.content_type [15]
items.X.id	data.0.properties.contents.X.content_id data.0.properties.content_ids [16]
items.X.product.price	data.0.properties.contents.X.price
items.X.quantity	data.0.properties.contents.X.quantity
items.X.product.name	data.0.properties.contents.X.content_name
items.X.product.category_1	data.0.properties.contents.X.content_category
items.X.product.brand	data.0.properties.contents.X.brand
search_term	data.0.properties.search_string [17]
id	data.0.properties.order_id [17]
partners.tiktok.shop_id	data.0.properties.shop_id [17]
status	data.0.properties.status [17]
content_type	data.0.properties.content_type [17]
currency	data.0.properties.currency
event_name	data.0.properties.description
value	data.0.properties.value
items.length	data.0.properties.num_items
Test Event Code	test_event_code

[*] Mandatory property. [1] Supported values: web , app , offline , and crm . When Autodiscovery Event Source is flagged, if the "Smart Mapping" field Experience Type is set with a property holding the value native app or the object context.app has at least a property then this is set with app . The "Smart Mapping" Event Source has priority over the autodiscovery feature. Default value: web . [2] See Quick reference for more details on event mapping. [3] If not provided, the current timestamp is used. [4] Required if you are sending web events from both TikTok browser pixel and this destination. Used in deduplication together with event_source_id and data[0].event . More details are available following this LINK. [5] If not provided, the cookie ttclid or context.page.url is used. [6] If provided in clear text, it's automatically hashed with SHA-256. [7] If not provided, the cookie _ttp is used. [8] Set when the "Smart Mapping" property Device Platform or context.device.type is set with iOS (case insensitive). [9] Supported values: AUTHORIZED , DENIED , NOT_DETERMINED , RESTRICTED and NOT_APPLICABLE. More details are available following this LINK. [10] Set when the "Smart Mapping" property Device Platform or context.device.type is set with Android (case insensitive). [11] Required for app events. [12] Phone number in the E.164 format. [13] See BCP 47 language identifier. [14] See Events API 2.0 - Limited Data Use for more details. [15] Supported values: product and product_group . Default: product . [16] Required for Video Shopping Ads (VSA). [17] Set for web events.