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
- Documentation: TikTok Events API
Batch Limits
This connector uses batched requests to support high-volume data transfers to the vendor. Requests are queued until one of the following thresholds is met:
- 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 App Event | ✓ | ✓ |
Send Web Event | ✓ | ✓ |
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 find the pixel_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: tiktok_event_id_Checkout_32
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 the Automatic Deduplication value is populated, the connector will look for the corresponding variable within the UDO object. You are no longer required to add an Event ID if this section is populated with a mapping to Tealium iQ Tag ID and you are using Tealium iQ. However, the following approach may still be needed when using EventStream without Tealium iQ.
The connector uses the following order of operations:
- If the Automatic Deduplication contains a mapping and the value is found in the data layer (for example,
tiktok_event_id_ViewContent_30
), the data layer value supersedes anything mapped in Event ID. - If Automatic Deduplication contains a mapping and the connector can’t find the tag ID version, but the connector can find the legacy version (with no ID attached), the value of the legacy version is used (for example,
tiktok_event_id_ViewContent
). - If Automatic Deduplication contains a mapping, but the value isn’t found, the mapped Event ID is used, if it is populated.
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 Web Event
Parameters
Parameter | Description |
---|---|
Event Type | Required. Conversion event name. |
Custom Event Name | (Required). App event name. |
Pixel ID Override | (Required). Pixel ID that can be found in the TikTok Events Manager. This setting overrides Pixel ID used in the Configuration section. |
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. |
IP | Public IP address of the browser. It must not be hashed. To increase the probability of matching website visitor events with TikTok ads, we recommend sending both IP and User Agent. |
User Agent | 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. |
Test Event Code | To test event tracking, use this field to specify a test code. If the event is received in TikTok, this test code will display in the Test Events tab of the TikTok Pixel in TikTok Ads Manager. |
Timestamp | 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. |
Callback | The value of ttclid used to match website visitor events with TikTok ads. |
Referrer | Page referrer. |
URL | Page URL when event happened. |
User External ID | (Recommended). The external user ID. It must be hashed with SHA256. |
User Phone Number | (Recommended). User’s phone number. It must be hashed with SHA256. Include country code with + and remove any other characters (spaces, - ) between numbers (For instance, an example from the USA: +12125551212 ). If the country code is 86 , do not include country code (Example: 13800000000 ). |
User Email | (Recommended). Email address. It must be hashed with SHA256. |
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. |
Content Price | Price of the item. Supports number data type. |
Content Quantity | Number of items. Supports number data type. |
Content ID | Product ID in your system. |
Content Brand | The brand of the product item. |
Content Description | A description of the product item. |
Description | A description of the app event. |
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. |
Tealium iQ Tag ID | The ID of a Tealium TikTok Pixel tag to use for Automatic Deduplication of events. If provided, Tealium automatically looks for your Event ID value that is sent from Tealium iQ. |
This page was last updated: May 8, 2023