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, 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. WEB APP OFFLINE CRM
Event Type	The conversion event name. Achieve a Level Add Payment Information Add to Cart Add to Wishlist Check Out Click Button Complete Payment Complete Registration Complete the Tutorial Contact Create a Group Create a Role Custom Download Generate a Lead Initiate Checkout Install the App In-app AD Click In-app AD Impression Join a Group Launch the App Load an Application Loan is Approved Loan is Disbursed Log in Successfully Place an Order Purchase Rate Search Spend Credits Start the Trial Submit Form Subscribe Unlock an Achievement View Content
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.
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:

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.