TikTok Events Connector Setup Guide
This article describes how to set up the TikTok Events connector.
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
- API Endpoint:
https://business-api.tiktok.com/open_api/v1.3/event/track/
- Documentation: TikTok Events API
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:
- Max number of requests: 50
- Max time since oldest request: 5 minutes
- Max 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
Navigate 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 you already have a TikTok pixel integrated for the website, you can use the existing pixel code. You can findpixel_code
by logging in your TikTok ads manager account. We recommend that you create one Pixel per website.
Deduplication for TikTok Pixel and TikTok Conversions for Web Events
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:
Format: tiktok_event_id_<TIKTOK_EVENT>_<TAG_UID>
For example, an event from a tag with a UID of 174
would send the following attribute value:
tiktok_event_id_Checkout_174`
You can find your tag’s UID in the Tealium iQ Tags table or the tag details screen:

For each event ID that matches the above 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_Purchase |
Event ID |
“Purchase” (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 will use the first one and discard any later events received within 48 hours of the first event. If a later event is received within 5 minutes of the first event, TikTok attempts to merge 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 5 minutes) contains this information, TikTok merges the email data into the first event.
Action Settings — Parameters and Options
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.
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 no timestamp is provided, the current timestamp will be used. |
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 | Limited data processing setting. This field is only supported when Event Source is WEB or APP . To learn more about the Limited Data Use Feature, see TikTok: Limited Data Use. |
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 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 . |
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. |
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 automapped parameters will not be sent to the vendor by default. |
The connector automaps the following parameters by default:
- TikTok Click ID (
ttclid
) - User Agent
To disable automapping, set Disable Automapping to true
. Any automapped 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.
This page was last updated: February 7, 2025