TikTok Events Connector Setup Guide | Server-Side Connectors

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. 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 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 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 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.
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	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	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.
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, hashed with SHA256.
User Phone Number	(Recommended). 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 Email	(Recommended). Email address, 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. When you provide the Tealium iQ Tag ID, we will automatically look for the Event ID value that Tealium iQ sends.
Access Token Override	A custom Access Token to override the value in the Configuration.

Disable Automapping

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.