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
• 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 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 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
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 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 no timestamp is provided, the current timestamp will be used.
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 Event Source is WEB or APP. Limited data processing setting. 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 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). Email address, 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 External ID	(Recommended). The external user ID, hashed with SHA256.
Cookie ID	The ID of the cookie.
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.
IDFA	iOS identifier for advertisers.
IDFV	iOS identifier for vendors.
GAID	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	Price of the item. Supports number data type.
Quantity	Number of items. Supports number data type.
Content ID	Product ID in your system.
Content Category	The category of the page or product.
Content Name	The name of the page or product.
Brand	The brand of the product item.

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:

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