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 events that may not happen in the browser, and improve accuracy by tracking events both in the browser (if you're already using TikTok Pixel) and on the server.

Destination Info

• Accepts Track calls

• Supports HIPAA mode

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

• 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 contents, quantity, content_type (alternatively in contents array)c
AddToWishlist	AddToWishlist
AddPaymentInfo	AddPaymentInfo
ClickButton	ClickButton
CompletePayment	CompletePayment	value, currency, description content_id, quantity, content_type (alternatively in contents array)
Contact	Contact
CompleteRegistration	CompleteRegistration
Download	Download
InitiateCheckout	InitiateCheckout checkout started started checkout
PlaceAnOrder	PlaceAnOrder order completed completed order	value, currency, description content_id, quantity, content_type (alternatively in contents array)
Search	Search products searched searched products
SubmitForm	SubmitForm
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 (alternatively in contents array)

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.

TikTok Events API field	Freshpaint Property	Type	Requirement	Description
event	< freshpaint Event Definition name >	string	Required Built-in	May be mapped via a transformation.
event_id	< unique freshpaint event id >	string	Required Built-in	Unique identifier for the event.
timestamp	Time	string	Required Built-in	Timestamp that the event took place.
test_event_code	test_event_code	string		Used only for adhoc real-time testing
context. ip	$ip	string	Built-in	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.
context. user_agent	$user_agent user_agent	string	Built-in	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. The built-in $user_agent is recommended, but if user_agent is specified, it will always be used.
context. ad. callback	$ttclid	string	Built-in	TikTok Click ID. TikTok Click ID ($ttclid) is a tracking parameter appended to a landing page URL whenever a user clicks on an ad on TikTok. This is automatically captured by Freshpaint, if available.
context. page. referrer	$referrer	string	Built-in	Page referrer.
context. page. url	$current_url	string	Built-in	Page url when event happened.
context. user. email	email (hashed)	string		The email of the user if available.
context. user. external_id	distinct_id (hashed)	string	Built-in	User unique identifier.
context. user. phone_number	phone_number (hashed) / phone (hashed)	string		The phone number of the user.
context. user. ttp	ttp	string		Cookie ID. If you also use Pixel SDK and enabled cookie, Pixel SDK automatically saves a unique identifier in the _ttp cookie. The value of _ttp is used to match website visitor events with TikTok ads. For details, see Set up TikTok Click ID and Cookies section.
properties. currency	currency	string		ISO 4217 code. Example: "USD". Is set to "USD" by default if value present.
properties. query	query	string		The text string that was searched for.
properties. description	description / name	string		Description of the item or page. Example: "Lightweight cotton".
properties. value	value / revenue / total	number		Value of the order or items sold. Example: 100. Note: Price is the price for a single item, and value is the total price of the order. For example, if you have two items each sold for $10, the price parameter would pass 10 and the value parameter would pass 20.
properties. content_type	content_type	string		Must be either 'product' or 'product_group'
properties. contents	array form: contents / products non-array form: content_id / id / product_id / productId / sku quantity (number) price (number) content_name content_category	object array		Use contents when you have 1 or more content IDs. Alternatively , you can specify top-level properties content_id, quantity, price, content_name, content_category If you use contents as a parameter, you must also include the following in a sub-object: product_id or ids, and the quantity (number of items added to cart or purchased). quantity defaults to 1 when there is at least one content_id specified.

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.

Check whether it's working

You can use the Freshpaint Event Tester to quickly verify events from Freshpaint are received properly by TikTok. To do so, follow these steps:

• In TikTok Ads Manager, navigate to TikTok Ads Manager -> Assets -> Web Events, then select your Pixel ID

• Copy the test_event_code

• Go to the TikTok Ads configuration page in Freshpaint and click "Test Event"

• Choose a TikTok-enabled event

• Paste the test_event_code from above

• Optionally, enter test values for $current_url, $ip, $user_agent, value, currency, contents, etc., preserving the distinct_id, token, time values. Here are some test values to use:

  "test_event_code": "YOURTESTCODE",
  
  "$current_url": "https://mysite.com",
  "$ip": "1.2.3.4",
  "$user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_5) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
  
  "value": 22,
  "currency": "USD",
  "description": "necessities",
  
  "content_type": "product",
    
  "contents": [
    {
      "content_id": "a1",
      "quantity": 2
    }
  ]

• Click "Test Event"

• In TikTok Ads Manager, look for the event under "Event Activity"

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

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