TikTok for Business offers many tools that let you share the actions people take on your website with TikTok. When you share these events with TikTok, you can better optimize your campaigns and measure ad performance.
TikTok’s Events API is a secure server-to-server integration that allows advertisers to share the actions customers take on their websites directly with TikTok, without needing to install a pixel on your website.
Access Token: When setting up a connection to TikTok, you will need your Access Token. To find your Access Token, go to the Events Manager view on your TikTok dashboard.
Event Source ID: When setting up a connection to TikTok, you will need your Event Source ID, which can be either a Pixel ID, an App ID, or an Offline Event Set ID. To find your Event Source ID, go to the Events Manager view on your TikTok dashboard.
In outgoing TikTok event payloads, 3 primary user identifiers are supported:
For each, a drop-down setting is exposed allowing customers to choose which mParticle identity type should be mapped to that value. All outgoing identity information is SHA-256 hashed as per TikTok’s documentation. See Connection Settings for more information.
Google Advertising ID (GAID) and Apple Advertising ID (IDFA) are supported as device identifiers for connection types other than legacy web. These values will be hashed and sent when available.
NOTE: Anonymous events (with none of the above identifiers) are supported, but it’s highly recommended to send as many identifiers as possible to ensure optimal match rates.
The following event information will be included for all outgoing events, regardless of type.
| mParticle Field | TikTok Event Field | Description |
|---|---|---|
| event.name | event | Conversion event name. Set depending on the incoming event type. |
| event.source_message_id | event_id | The default ID used for the dedupliation of events in TikTok. If unavailable, we fallback on event_id |
| event.timestamp_unixtime_ms | timestamp | The original event timestamp. This must be in millisecond resolution (ex.1455236520490) |
| ip | context.ip | Non-hashed public IP address of the browser. The value from the event batch will be used when present, but when the Enrich with IP Address connection setting is enabled, values from the user’s profile may be used as fallbacks. |
| event.device_info.http_header_user_agent | context.user_agent | Non-hashed user agent from the user’s device. |
Custom Flags must be specified on each valid incoming event to support specific fields within each outgoing TikTok event’s context property.
| mParticle Custom Flag | TikTok Event Field | Is Required | Description | Example |
|---|---|---|---|---|
TikTok.URL |
Context.Page.Url | True | Page url when event happened. Must start with ‘http://’ or ’https://’, otherwise the event will fail TikTok processing | ”http://demo.mywebsite.com/purchase” |
TikTok.Referrer |
Context.Page.Referrer | False | Page referrer. | ”http://demo.mywebsite.com” |
TikTok.Callback |
Context.Ad.Callback | False | TikTok Click ID (ttclid). This represent a tracking parameter appended to a landing page URL whenever a user clicks on an ad on TikTok. Correctly formatted strings should start with “E.C.P”. Don’t send TikTok dummy values. | “E.C.P.v3fQ2RHacdksKfofPmlyuStIIHJ4Af1tKYxF9zz2c2PLx1Oaw15oHpcfl5AH” |
mParticle includes these values in outgoing events to TikTok.
The following additional data will be included for Web connections when the Enable Web Migration setting is enabled, and for Feed connections when the Event Source Type is Web.
| mParticle User Attribute | Data Type | TikTok Event Field | Description |
|---|---|---|---|
$FirstName |
string |
User.FirstName | First name of the user, normalized and hashed |
$LastName |
string |
User.LastName | Last name of the user, normalized and hashed |
$City |
string |
User.City | City of the user, normalized |
$State |
string |
User.State | State of the user, normalized |
$Country |
string |
User.Country | Country of the user, normalized |
$Zip |
string |
User.ZipCode | Zip code of the user, normalized and hashed |
campaignId |
string |
Ad.CampaignId | Campaign ID |
adId |
string |
Ad.AdId | Ad group ID |
creativeId |
string |
Ad.CreativeId | Ad ID |
isRetargeting |
boolean |
Ad.IsRetargeting | Whether the user is a retargeting user |
attributed |
boolean |
Ad.Attributed | Whether the event is attributed |
attributionType |
string |
Ad.AttributionType | Attribution type |
attributionProvider |
string |
Ad.AttributionProvider | Attribution provider |
The following partner identity will be forwarded when available for all events.
| mParticle Partner Identity | TikTok Event Field | Description |
|---|---|---|
tiktok_cookie_id |
user.ttp | Cookie ID of the user |
The following additional data will be included for connection types other than legacy web when available from the mParticle application info
| mParticle Application Info | TikTok Event Field | Description |
|---|---|---|
| package | app.AppId | App ID |
| application_name | app.AppName | App Name |
| application_version | app.Version | App Version |
The only native mParticle event type that’s supported by this integration is CommerceEvent.
mParticle supports the following event mappings:
| mParticle Event | TikTok Event |
|---|---|
Commerce Event with add_to_cart product action. |
AddToCart |
Commerce Event with add_to_wishlist product action. |
AddToWishlist |
Commerce Event with purchase product action. Refunds are not natively supported by TikTok. |
PlaceAnOrder |
Commerce Event with checkout product action. |
InitiateCheckout |
Commerce Event with view_detail product action. |
ViewContent |
Other CommerceEvent types remain unsupported.
mParticle supports the following commerce and product information mappings:
| mParticle Field | TikTok Event Field | Description |
|---|---|---|
| event.product_action.currency | properties.currency | ISO 4217 code. Example: “USD”. |
| event.product_action.total_amount | properties.value | Value of the order or items sold. Example: 100. Note: Price is the price for a single item, and value is the total price of the order. |
| event.product_action.products[x].price | properties.contents[x].price | The price of the item. Example: 25. Note: Price is the price for a single item, and value is the total price of the order. |
| event.product_action.products[x].quantity | properties.contents[x].quantity | Number of item. Example: 4 |
| event.product_action.products[x].id | properties.contents[x].content_id | ID of the product item. Example: “1077218” |
| event.product_action.products[x].category | properties.contents[x].content_category | Category of the page/product. Example: “apparel” |
| event.product_action.products[x].name | properties.contents[x].content_name | Category of the page/product. Example: “apparel” |
In order to support TikTok event types that don’t map one-to-one with mParticle events, we allow customers to manually configure Custom Mappings for a particular connection within our UI. This feature allows incoming mParticle events to be mapped to known TikTok event types, including with specific attributes and outgoing parameters.
All TikTok event mappings support the description property.
In addition, the following additional properties are supported for each respective event:
AddPaymentInfo: price, quantity, currency, value, content_id, content_name, content_categoryAddToCart: price, quantity, currency, value, content_id, content_name, content_categoryAddToWishlist: price, quantity, currency, value, content_id, content_name, content_categoryClickButtonCompletePayment: price, quantity, currency, value, content_id, content_name, content_categoryContactDownloadInitiateCheckout: price, quantity, currency, value, content_id, content_name, content_categoryPlaceAnOrder: price, quantity, currency, value, content_id, content_name, content_categorySearch: querySubscribe: currency, valueViewContent: price, quantity, currency, value, content_id, content_name, content_category| Setting Name | Data Type | Is Required | Is Encrypted | Description |
|---|---|---|---|---|
| Access Token | string | True | True | Provides access to TikTok’s Events API. You can create an access token in the TikTok Events Manger. |
| Setting Name | Platform | Data Type | Default | Is Required | Description |
|---|---|---|---|---|---|
| Event Source Type | Feed | Web, Feed, App, or Legacy Pixel Batch Web | Legacy Pixel Batch Web | True | The Event Source type corresponding with the Event Source ID of your TikTok dataset. Note that some parameters are not available for Legacy Web. Legacy Web connections should migrate to Web before support for Legacy is eventually removed. |
| Event Source ID | All | string |
null | True | The Event Source ID of your dataset, either a Pixel ID or an Offline Event Set ID. |
| Email Identity Type | All | string |
True | The Identity Type to forward as the email to TikTok. | |
| Enable Web Migration | Web | boolean |
False | False | Forward Track Events instead of Legacy Pixel Batch events. Some parameters are not available for Legacy events. |
| External Identity Type | All | string |
Customer ID | True | The Identity Type to forward as the external ID to TikTok. |
| Phone Identity Type | All | string |
Mobile Number | True | The Identity Type to forward as the phone number to TikTok. |
| Content Type | All | string |
product | True | The content_type property can be set to either ‘product’ or ‘product_group’, depending on how your data feed and product catalog are configured on TikTok’s end. |
| Enrich with IP Address | All | boolean |
False | False | If enabled, a batch will be enriched with the most-recently seen IP address value when missing from the batch. |
Was this page helpful?