TikTok Ads

Send advertising events directly to TikTok Ads

Freshpaint can send Events to your TikTok account for a specified Pixel ID. These server-side Events are sent via the TikTok Events API. The TikTok Events API enables you to measure conversions by sending Freshpaint events directly to TikTok's servers.

Destination Info

• Accepts Track calls

• Supports HIPAA mode

• Supports forwarding from the Google Tag Manager Integration

• Refer to this destination as TikTok Ads in the Integrations object

  • If you've configured multiple Pixel IDs, you can choose a specific one by suffixing the Pixel ID, such as: TikTok Ads::123456789.

  When no suffix is specified, all configured Pixel IDs are selected for inclusion / exclusion.

• Connection Modes:

	Client-side	Server-side
Web
Mobile
Server

Getting Started

To set up the TikTok Ads integration, follow these steps:

• Go to the TikTok Ads configuration page in Freshpaint and click "Configure" for Access Token & Pixel ID.

• In TikTok Ads Manager -> Assets -> Web Events, find your Pixel ID, or create a new Pixel as described at TikTok Events API: Get Started. Copy this value into your TikTok Ads configuration.

img.png

• Click on the Pixel you want to use and generate an Access Token. Copy this value into your TikTok Ads configuration.

img.png

Events

TikTok Event API: Web Event types

Each event sent to the TikTok Event API is categorized as a specific TikTok Event, derived from either the Freshpaint Event Definition name or a Destination Transformation (described further below).

Below are the TikTok Events, as defined in TikTok Events API Reference, with the corresponding Freshpaint Event Definition names which automatically map to them:

TikTok Event	Mapped from Freshpaint Event Definition name	Recommended TikTok properties-object fields
AddToCart	AddToCart product added added product	value, currency, description, quantity, content_type , content_id
AddToWishlist	AddToWishlist
AddPaymentInfo	AddPaymentInfo
ApplicationApproval	ApplicationApproval
CustomizeProduct	CustomizeProduct
Contact	Contact
CompleteRegistration	CompleteRegistration
Download	Download
FindLocation	FindLocation
InitiateCheckout	InitiateCheckout checkout started started checkout
Lead	Lead (formerly SubmitForm) Both event names are mapped to the TikTok Event Lead
Schedule	Schedule
Purchase	Purchase (formerly CompletePayment) Both event names are mapped to The TikTok Event Purchase	value, currency, description, content_id, quantity, content_type
Search	Search products searched searched products
StartTrial	StartTrial	currency, value
SubmitApplication	SubmitApplication
Subscribe	Subscribe
ViewContent	ViewContent product list viewed viewed product list product category viewed viewed product category product viewed viewed product	value, currency, description, content_id, quantity, content_type

Notes:

• TikTok Events are case-sensitive

• Any of the space-delimited names above are case-insensitive and may be alternatively delimited by an underscore or no separation. For example, "product added" can also be expressed as:

  • Product_added

  • productAdded

• These non-TikTok-specific names can be useful when sending to multiple destinations, such as Facebook Conversion API and TikTok Ads, without requiring a Rename Transformation for one or both.

Supported TikTok parameters

Several Freshpaint Built-in Properties are automatically sent to TikTok. To maximize the effectiveness of what is sent, you should define a number of Freshpaint Custom Properties, as described below.

Freshpaint Custom Properties include Dynamic Properties and Data Layer Properties, described at Setting up Properties, and Transformation Constant Properties, described in Transformations.

User Traits

User traits you can define as Custom Properties to improve match rate are:

• email

• phone_number

Other ways you can optimize user match rate:

• Ensure Freshpaint User Identification is being used in your application, so the external_id field gets sent (hashed from Freshpaint Built-in Property distinct_id).

• If you are already using the Pixel SDK with enabled cookie, capture the ttp property as described at TikTok Click ID and Cookies section.

TikTok Field to Freshpaint Property Mapping Reference

Below is the full list of what Freshpaint sends to the TikTok Events API (beyond Pixel ID and Access Token).

In some cases, there are 1 or more alias properties for a field (e.g., for value, aliases are: total, revenue).

Fields mapped to Freshpaint Custom Properties are optional, but some are recommended:

• The User Traits properties described above are always recommended.

• See the Events Section above for recommended TikTok properties-object fields to be sent for specific TikTok Events.

See also the TikTok Events API Reference.

Event Properties

TikTok Events API field	Freshpaint Property	Type	Requirement	Description
event_source		string	Required.	Specifies the type of events sent. Freshpaint currently only supports web events.
event_source_id	pixel_id	string	Required.	Source ID to measure events.
event	< Freshpaint Event Definition name >	string	Required.	May be mapped via a transformation.
event_id	< unique Freshpaint event id >	string	Required.	Unique identifier for the event.
event_time	time	string	Required.	Timestamp that the event took place. Defaults to when Freshpaint processes the event if not provided.

User Properties

To increase the accuracy of targeting and optimization models, it is highly recommended to include multiple types of matching data. You can use Advanced Matching, TikTok Click IDs (ttclid), and Cookies to attribute conversions.

Tiktok Events API Field	Freshpaint Property	Type	Requirement	Description
ttclid	$ttclid	string		TikTok Click ID, a data connection parameter appended to a landing page URL whenever a user clicks on an ad on TikTok.
email	email	string		The email address of the customer. Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.
phone	phone_number or phone	string		The phone number of the customer. Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.
external_id	distinct_id	string		External ID, a unique identifier on the advertiser's side, such as loyalty membership IDs, user IDs, and external cookie IDs. Note: Freshpaint will hash this value, do not send Freshpaint pre-hashed email values.
ttp	ttp	string		Cookie ID.
ip	$ip or ip_address	string		Non-hashed public IP address of the user's device.
user_agent	$user_agent or user_agent	string		Non-hashed user agent from the user’s device.
locale	locale	string		The BCP 47 language identifier. For reference, refer to the IETF BCP 47 standardized code.

Properties Parameters

Tiktok Events API Field	Freshpaint Parameter	Type	Required	Description
content_ids	products or contents	string[]	Required for Video Shopping Ads	Unique ID or array of multiple IDs of the products or content.
content_type	content_type	string	Required for Video Shopping Ads	The type of content in the event. Enum values: product, product_group.
currency	currency	string	Recommended for revenue related events	The ISO 4217 currency code. Examples: EUR, USD, JPY.
value		float	Recommended for revenue related events	Value of the order or items sold.
num_items	quantity	integer		The quantity of items.
search_string		string		The user-entered string for search.
description	description or name	string		Description of the item or page.
order_id		string		Order ID.
shop_id		string		Shop ID.

Ad Contents Properties

Tiktok Events API Field	Freshpaint Parameter	Type	Required	Description
price	price	float		The price of the item.
content_id	content_id, product_id, productID, id, or sku	string	Required for Video Shopping Ads	Unique ID of the product or content.
content_category	content_category	string		Category of the page or product.
content_name	content_name	string		Name of the page or product.
brand	brand	string		Brand name of the product item.

Page Properties

Tiktok Events API Field	Freshpaint Parameter	Type	Required	Description
url	$current_urlor url	string	Required	The browser URL where the event happened.
referrer	$referrer	string		The referrer URL.

Sending the same events from TikTok Pixel and TikTok Events API

If you are already using TikTok Pixel, sending the same events from both the browser and the server can improve the accuracy of browser events by providing redundancy. Events that previously would have been lost (e.g. due to the TikTok Pixel being blocked or network errors) can still be captured using the TikTok Events API via the Freshpaint TikTok Ads integration.

However, the event_id used by TikTok Pixel to deduplicate events is generated differently than that used by the Freshpaint TikTok Ads destination, so if you gather the same events with both TikTok Pixel and Freshpaint, they are likely to not be deduplicated by TikTok, and you may get diagnostic warning messages related to this. To minimize the chance of duplication, ensure the TikTok Event is set properly and the recommended match fields described above are included. For further details see TikTok Event Deduplication.

Transformations

Freshpaint Transformations allow you to customize how Freshpaint Events map to TikTok Events:

• Map any Freshpaint Event Definition name to a TikTok Event

• Rename Freshpaint Custom Properties mapped to supported TikTok property-object fields

• Rename any Freshpaint Property mapped to a supported TikTok Field

• Define a Constant Property when a Custom Property is not available

• Suppress a Freshpaint Property from being sent to TikTok

To create a TikTok Ads Transformation, go to Transformations or the TikTok Ads configuration page in Freshpaint and click "Event Transformations".

Map any Freshpaint Event Definition name to a TikTok Event

To optimize for conversions, use Transformations to match Freshpaint events to TikTok Standard Events.

Select Standard Event

In the example below, the Event Definition named "TikTok event" is mapped to a TikTok Search Event:

img.png

img.png

Rename Freshpaint Custom properties mapped to supported TikTok Property Object fields

Select Standard Event

In this example, the "order_total" Freshpaint Custom Property is renamed to the mapped value name.

img.png

img.png

Rename any Freshpaint Property mapped to a supported TikTok Field

Select Modify Data

Here, the "phone_nbr" Freshpaint Custom Property is renamed to the mapped phone_number name.

img.png

img.png

Define a Constant Property when a Custom Property is not available

Select Modify Data

In this case, there is no Freshpaint Custom Property currency defined, so we set a Transformation Constant Property:

img.png

img.png

Suppress a Freshpaint Property from being sent to TikTok

Select Modify Data

Finally, we might want to ensure that no search information is sent, so we suppress the Freshpaint Custom Property query if it's present:

img.png

img.png

Using the GTM Integration

If using the Google Tag Manager (GTM) Integration, you should define the event name and any other properties on the tag.

If you're using multiple TikTok instances, you can specify the Instance Pixel ID as well, as shown below: