TikTok Events Connector Setup Guide

API Information

This connector uses the following vendor API:

API Name: TikTok HTTP API
API Version: v1.3 (Events 2.0)
API Endpoint: https://business-api.tiktok.com/open_api/v1.3/event/track/
Documentation: TikTok Events 2.0

Batch Limits

This connector uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:

Maximum number of requests: 50
Maximum time since oldest request: 5 minutes
Maximum size of requests: 1 MB

Connector actions

Action Name	AudienceStream	EventStream
Send Track Event	✓	✓

Use the Track endpoint to report App, Web, Offline, or CRM events.

Configure settings

Go to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see About Connectors.

After adding the connector, configure the following settings:

Access Token
The Access Token that is configured in TikTok.
Pixel ID
If a TikTok pixel is already integrated for the website, use the existing pixel code. Log in to your TikTok Ads Manager account to find the pixel_code. Create one pixel per website.

Deduplication

To configure this connector to receive event IDs from the TikTok Pixel tag in your Tealium iQ Tag Management account, look for event attributes using the following naming convention:

tiktok_event_id_<TIKTOK_EVENT>_<TAG_UID>

For example, an event from a tag with a UID of 174 sends the following attribute:

tiktok_event_id_Checkout_174

Find your tag’s UID in the Tealium iQ Tags table or the tag details screen:

For each event ID that matches this event ID format, configure a separate action. Map the event-specific event ID attribute to Event ID and map the corresponding event name to Event Name.

For example:

Tealium Attribute/Value	TikTok Parameter
`tiktok_event_id_Checkout_174`	Event ID
`Checkout` (Custom Text)	Event Name

For more information, see TikTok Pixel Tag Setup Guide.

Automatic deduplication

If multiple events with the same event source ID (event_source_id), event type (for example, AddToCart), and event ID (event_id) are received, TikTok uses the first event and discards any later events received within forty-eight hours of the first event.

If a later event is received within five minutes of the first event, TikTok merges its data into the first event. For example, if the first event does not include user email (user.email) but a later duplicate event (received within five minutes) contains this information, TikTok merges the email data into the first event.

Actions

Enter a name for the action and select the action type from the drop-down menu.

The following section describes how to set up parameters and options for each action.

Send Track Event

Parameters

Parameter	Description
Event Source	Select the event source. WEB APP OFFLINE CRM
Event Type	The conversion event name. Achieve a Level Add Payment Information Add to Cart Add to Wishlist Check Out Click Button Complete Payment Complete Registration Complete the Tutorial Contact Create a Group Create a Role Custom Download Generate a Lead Initiate Checkout Install the App In-app AD Click In-app AD Impression Join a Group Launch the App Load an Application Loan is Approved Loan is Disbursed Log in Successfully Place an Order Purchase Rate Search Spend Credits Start the Trial Submit Form Subscribe Unlock an Achievement View Content
Event Source ID	(Required) An ID to track events. If `event_source` is `web`, specify a pixel code in this field. If `event_source` is `offline`, specify an offline event ID in this field. If `event_source` is `app`, specify a TikTok App ID in this field. If `event_source` is `crm`, specify a CRM event ID in this field. To obtain a CRM event ID, use `/crm/list/`.
Event Time	(Required) Timestamp when the event took place with ISO 8601 format `YYYY-MM-DDThh:mm:ssZ`. If you do not provide a timestamp, the connector uses the current timestamp.
Custom Event Name	Required when choosing Custom from the Event Type drop-down.
Pixel ID Override	Pixel ID that can be found in the TikTok Events Manager. This setting overrides Pixel ID used in the Configuration section.
Access Token Override	A custom access token to override the value in the configuration.
Event ID	Any hashed ID that can identify a unique user or session. For example, `SessionID_RandomNumber`. If you set Generate Event ID in the TikTok Pixel tag to `true`, this ID will be automatically generated for every TikTok tracking event.
Limited Data Use	This field is only supported when the Event Source is `WEB` or `APP`. Limited data processing setting. To learn more about the Limited Data Use Feature, see TikTok: Limited Data Use.
Test Event Code	Send test events that will not be included in production data from TikTok Events Manager (`TTEM`). Retrieve the `test_event_code` from the `Test Events` Tab in `TTEM`.

Ad Data

Parameter	Description
Callback	The value of `ttclid` used to match website visitor events with TikTok ads.
Campaign ID	The campaign ID.
Ad ID	The ad group ID.
Creative ID	The Ad ID.
Is Retargeting	Whether the user is retargeting a user.
Attributed	Whether the event is attributed to a provider.
Attribution Type	The type of attribution.
Attribution Provider	The attribution provider name.

Page Data

Parameter	Description
Referrer	Page referrer.
URL	Page URL when the event happened.

User Data

Parameter	Description
User Email	Recommended. The user’s email address, hashed with SHA256.
User Phone Number	Recommended. The user’s phone number, hashed with SHA256. Include country code with `+` and remove any other characters (spaces, `-`) between numbers (for example, for the USA: `+12125551212`). If the country code is `86`, do not include country code (for example: `13800000000`).
User External ID	Recommended. The external user ID, hashed with SHA256.
Cookie ID	The ID of the cookie.
IP	The non-hashed public IP address of the browser. To increase the probability of matching website visitor events with TikTok ads, we recommend sending both IP and User Agent.
User Agent	The non-hashed user agent from the user’s device. To increase the probability of matching website visitor events with TikTok ads, we recommend sending both IP and User Agent. Unless you disable automapping, this parameter will be automapped to the User Agent of the visitor.
IDFA	The iOS identifier for advertisers.
IDFV	The iOS identifier for vendors.
GAID	The Google Advertising ID.
Locale	The locale language and locale in `la-CO` format where `la` is a two-letter code representing the language and `CO` is a two-letter uppercase code representing the country.
Att Status	Whether the user has authorized your mobile app to access app-related data for tracking the user or the device. This is an iOS-only field. Supported values are `AUTHORIZED`, `DENIED`, `NOT_DETERMINED`, `NOT_APPLICABLE`.
Vertical Choice	Select the vertical to display vertical-specific parameters under Property Data. Available options are `Hotel`, `Flight`, `Destination`, and `No Vertical Selected`.

Property Data

Parameter	Description
Content Type	The type of the product. This value must be `product` or `product_group`, depending on how your data feed is configured for your product catalog.
Currency	3 character ISO 4217 code. For example, `EUR`, `USD`, `JPY`.
Value	Total value of the order or items sold.
Query	The text used in a search query.
Description	A description of the app event.
Order ID	The order ID.
Shop ID	The shop ID.

Hotel vertical specific parameters

Parameter	Description
Content IDs	Product IDs associated with the event, such as SKUs.
City	Hotel city location.
Region	Hotel region.
Country	Hotel country.
Check-in Date	Hotel check-in date.
Check-out Date	Hotel check-out date.
Number of Adults	Number of adults in the booking.
Number of Children	Number of children in the booking.
Suggested Hotels	Suggested hotels for this user. Can be a string or an array of strings.

Flight vertical specific parameters

Parameter	Description
Destination City	Destination city name.
Departing Departure Date	Date of flight departure. Accepted formats are `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mmTZD`, `YYYY-MM-DDThh:mm:ssTZD`. For example, `20180623`, `2018-06-23`, `2017-06-23T15:30GMT`, `2017-06-23T15:30:00GMT`.
Returning Departure Date	Date of return flight. Accepted formats are `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mmTZD`, `YYYY-MM-DDThh:mm:ssTZD`. For example, `20180623`, `2018-06-23`, `2017-06-23T15:30GMT`, `2017-06-23T15:30:00GMT`.
Origin Airport	Origin airport code. For example, `JFK`.
Destination Airport	Destination airport code. For example, `CDG`.
Number of Adults	Number of adults.
Number of Children	Number of children.
Number of Infants	Number of infants.
Travel Class	Class of the flight ticket. This value must be `economy`, `premium`, `business`, or `first`.
User Score	Represents the relative value of this potential customer to advertiser. For example, `50`.
Preferred Number of Stops	Number of preferred stops.

Destination vertical specific parameters

Parameter	Description
Content IDs	Product IDs associated with the event, such as SKUs.
City	Destination city location.
Region	Destination region.
Country	Destination country.
Travel Start	The start date of the user’s trip. Accepted formats are `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mmTZD`, `YYYY-MM-DDThh:mm:ssTZD`. For example, `20180623`, `2018-06-23`, `2017-06-23T15:30GMT`, `2017-06-23T15:30:00GMT`.
Travel End	The end date of the user’s trip. Accepted formats are `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mmTZD`, `YYYY-MM-DDThh:mm:ssTZD`. For example, `20180623`, `2018-06-23`, `2017-06-23T15:30GMT`, `2017-06-23T15:30:00GMT`.
Number of Adults	Number of adults.
Number of Children	Number of children.
Number of Infants	Number of infants.
Suggested Destinations	A list of IDs representing destination suggestions for this user.

Content Data

Parameter	Description
Price	The price of the item. Supports number and array of numbers data types.
Quantity	The number of items. Supports integer and array of number data types.
Content ID	The product ID or IDs in your system. Supports string and array of strings data types.
Content Category	The category or categories of the page or product. Supports string and array of strings data types.
Content Name	The name of the page or product. Supports string and array of strings data types.
Brand	The brand of the product item. Supports string and array of strings data types.

App Data

Parameter	Description
App ID	The mobile app ID.
App Version	The app version number.
Application Name	The application name.

Lead Data

Parameter	Description
Lead ID	ID of TikTok leads.
Lead Event Source	The lead event source.

Automatic Deduplication

Parameter	Description
Disable Automapping	If automapping is disabled, any automatically mapped parameters will not be sent to the vendor by default.

The connector automatically maps the following parameters by default:

TikTok Click ID (ttclid)
User Agent

To disable automapping, set Disable Automapping to true. Any automatically mapped parameters will not be sent to the vendor.

Custom events

To select a custom event for this connector:

Under the Event Type category, select Custom for the Conversion event name.
In the Custom Event Name field, enter the custom event name and click + Add Mapping.