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 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.
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
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]
Event Mapping
Change the standard mapping between TikTok's events and yours or add new mappings: custom TikTok web events are also supported. More details on how you can set up custom TikTok web events are available following this LINK.
[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.
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.
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 eitherproduct
orproduct_group
depending 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.
Last updated