TikTok Events Connector Setup Guide
This article describes how to set up the TikTok Events connector.
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 thepixel_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.
|
| Event Type | The conversion event name.
|
| Event Source ID | (Required) An ID to track events.
|
| 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
Customfor the Conversion event name. - In the Custom Event Name field, enter the custom event name and click + Add Mapping.
This page was last updated: October 29, 2025