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.
Custom Event Properties	Send custom event properties.
Custom User Properties	Send custom user properties.
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 page_view [3] view_item [3]	ViewContent [3]
complete_tutorial	CompleteTutorial [2]
create_group	CreateGroup [2]
create_role	CreateRole [2]
customize_product	CustomizeProduct [1]
purchase complete_payment	Purchase
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]
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, offline and CRM events only. See Autodiscovery Event Source in Configuration for more details. 2. For app events only. See Autodiscovery Event Source in Configuration for more details. 3. See TikTok "ViewContent" Event Mapping in Configuration for more details.

Field mappings

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 .

Smart Mapping Fields	Commanders Act Default Properties	TikTok Properties
Event Source	partners.tiktok.event_source	event_source [*][1]
-	Pixel Id App Id	event_source_id [*]
-	event_name	data.0.event [*][2]
Event Timestamp	context.event_timestamp	data.0.event_time [*][3]
Event Id	id	data.0.event_id [4]
Click Id	partners.tiktok.ttclid	data.0.user.ttclid [5]
User Id	user.id	data.0.user.external_id [6]
Cookie Id	partners.tiktok.ttp	data.0.user.ttp [7]
Page URL	context.page.url	data.0.page.url
Page Referrer	context.page.referrer	data.0.page.referrer
Device IDFV	context.device.idfv	data.0.user.idfv [8]
Device Attr Status	context.device.att_status	data.0.user.att_status [8][9]
Device IDFA Device GAID	context.device.advertising_id	data.0.user.idfa [8] data.0.user.gaid [10]
App Id	context.app.namespace	data.0.app.app_id [11]
App Name	context.app.name	data.0.app.app_name
App Version	context.app.version	data.0.app.app_version
User Email	user.email	data.0.user.email [6]
User Phone	user.phone	data.0.user.phone [6][12]
Device IP	context.device.ip	data.0.user.ip
Device User Agent	context.device.user_agent	data.0.user.user_agent
Device Language	context.device.language	data.0.user.locale [13]
Limited Data Use	partners.tiktok.ldu	data.0.limited_data_use [14]
Item Content Type	items.X.content_type	data.0.properties.contents.X.content_type [15]
Item Id	items.X.id	data.0.properties.contents.X.content_id data.0.properties.content_ids [16]
Item Price	items.X.product.price	data.0.properties.contents.X.price
Item Quantity	items.X.quantity	data.0.properties.contents.X.quantity
Item Name	items.X.product.name	data.0.properties.contents.X.content_name
Item Category	items.X.product.category_1	data.0.properties.contents.X.content_category
Item Brand	items.X.product.brand	data.0.properties.contents.X.brand
Search Term	search_term	data.0.properties.search_string [17]
Transaction Id	id	data.0.properties.order_id [17]
Shop Identifier	partners.tiktok.shop_id	data.0.properties.shop_id [17]
Transaction Status	status	data.0.properties.status [17]
Content Type	content_type	data.0.properties.content_type [17]
Currency	currency	data.0.properties.currency
Description	event_name	data.0.properties.description
Transaction Value	value	data.0.properties.value
Item list	items.length	data.0.properties.num_items
-	Test Event Code	test_event_code
-	Custom Event Properties	[Any property] [18]
-	Custom User Properties	[Any property] [19]

* 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. 18. Set in the data.0.properties property. See Custom Event Properties in Configuration. 19. Set in the data.0.user property. See Custom User Properties in Configuration.