Freshpaint
HomeLogin
  • Documentation
    • What is Freshpaint?
    • ⚕️HIPAA Mode
    • 🏗️Building Out Your Account
    • 🌐Overview of Features
    • Guides
      • 📡Add Autotrack to your website to collect data from your users
        • Installing the Freshpaint Javascript SDK
        • Installing the Freshpaint SDK with a Content Security Policy (CSP)
        • Installing the Freshpaint Javascript SDK with Server-Side Rendering (SSR) + React
        • Autocapture + React
        • Configuring a Destination
        • Labeling User Actions
        • How do I install Freshpaint with Typescript?
      • 🔁Send historical data to any destination with Time Machine
      • Next.js Quickstart Guide
      • Android Quickstart Guide
        • Installing the Freshpaint Android SDK
        • Configuring a Destination
        • Instrumenting Your App
      • iOS Quickstart Guide
        • Installing the Freshpaint iOS SDK
        • Configuring a Destination
        • Instrumenting Your App
      • React Native Quickstart Guide
        • Installing the Freshpaint React Native SDK
        • Configuring a Destination
        • Labeling User Actions
        • Configuring Property Capture
    • Setting up Properties
    • Setting up Your Destinations
      • Enabling and Disabling a Destination
      • Deleting a Destination
    • Setting up Your Events
    • User Identification
      • Designated Identify Properties
    • Maps
    • Analytics (Beta)
      • Web Analytics Dashboard
      • Campaigns
      • Service Lines
      • Data Glossary
    • Translations
    • Web Tracker Monitoring
      • Tracker Resolution Types
      • Historical Scans
  • Integrations
    • Destinations
      • Demand Side Platforms (DSPs)
        • Basis
          • Basis Quick Start Guide
          • Basis Reference
        • Google Campaign Manager 360
        • StackAdapt
          • StackAdapt Quick Start Guide
          • StackAdapt Reference
        • theTradeDesk
          • theTradeDesk Quick Start Guide
          • theTradeDesk Reference
          • theTradeDesk with CM360 Configuration Guide
        • Viant
          • Viant Quick Start Guide
          • Viant Reference
      • Direct Response Ads
        • Facebook Conversions API
          • Facebook Conversions API Quick Start Guide
          • Facebook Conversions API Reference
        • Google Ads Conversion API
          • Google Ads Conversion API Quick Start Guide
          • Google Ads Conversions API Reference
        • Google Ads
          • Google Ads Quick Start Guide
          • Google Ads Reference
        • LinkedIn Ads
          • LinkedIn Ads Quick Start Guide
          • LinkedIn Ads Reference
        • Microsoft Ads (formerly Bing Ads)
          • Microsoft Ads Quick Start Guide
          • Microsoft Ads Reference
          • Microsoft Ads Multi-Config Reference
        • Pinterest Ads (Beta)
          • Pinterest Ads Quick Start Guide
          • Pinterest Ads Reference
        • Pinterest Tag
        • Reddit Ads
          • Reddit Ads Quick Start Guide
          • Reddit Ads Reference
        • TikTok Ads
        • Twitter Ads
      • Data Activation
        • ActiveCampaign
          • ActiveCampaign Quick Start Guide
          • ActiveCampaign Reference
        • Amplitude
          • Amplitude Quick Start Guide
          • Amplitude Reference
        • Braze (formerly Appboy)
          • Braze Quick Start Guide
          • Braze Reference
        • Customer.io
          • Customer.io Quick Start Guide
          • Customer.io Reference
        • Freshsales
        • Google Analytics 4 Proxy
          • Google Analytics 4 Proxy Quick Start Guide
          • Google Analytics 4 Proxy Reference
          • Google Analytics 4 Proxy Advanced Tracking Configurations
        • Google Analytics 4 Server-Side
          • Google Analytics 4 Server-Side Quick Start Guide
          • Google Analytics 4 Server-Side Reference
        • Heap
        • Hotjar
        • HubSpot Cloud
        • HubSpot Web
        • impact.com
          • Impact.com Quick Start Guide
          • Impact.com Reference
        • Intercom
          • Intercom Quick Start Guide
          • Intercom Reference
        • Iterable
          • Iterable Quick Start Guide
          • Iterable Reference
        • June
        • Klaviyo
        • Mixpanel
          • Mixpanel Quick Start Guide
          • Mixpanel Reference
        • OneSignal
          • OneSignal Quick Start Guide
          • OneSignal Reference
        • Sendinblue
        • Sentry
        • Vero Cloud
        • Webengage
        • Webhooks
        • Woopra
        • Zendesk
      • Data Warehouses
        • Azure Warehouse Setup
        • BigQuery Warehouse Setup
        • Databricks Warehouse Setup
        • Postgres Warehouse Setup
        • Redshift Warehouse Setup
        • S3 Warehouse Setup
        • Snowflake Warehouse Setup
      • Consent Management
        • Osano
        • OneTrust
        • Custom Consent Manager
    • Sources
      • Web
        • Autotrack
        • Precision Tracking
      • CallRail
      • Invoca
      • Customer.io
      • Intercom
      • Mailchimp
      • React Native
      • SendGrid
      • Sendinblue
      • Server-Side
      • iOS
    • 🔷Google Tag Manager integration
      • Google Tag Manager migration
      • Quick Start Guide
    • 📺Freshpaint Video Platform
    • 🖼️Impression Pixel
  • Admin Panel
    • Event Library
      • Event Library Bulk Actions
      • Event Definition Filters
      • Event Tester
      • 🔁Time Machine
      • Visual Tagger
      • Advanced Options
        • Tag Manager
        • Disabling Target Text Capture
        • Cross Domain Tracking
    • Projects & Environments
    • Teams
      • Role-Based Access Control (RBAC)
    • Transformations
      • Standard Events
      • Modify Data
      • Modify User Data
      • SQL Transformations
    • 📈Destination Monitoring
    • 🔎Investigate: Testing and Debugging
      • Live View
      • Event Verification
  • Reference
    • Developer Docs
      • Freshpaint Web SDK Reference
      • Freshpaint Web SDK Options
      • Freshpaint React Native SDK Reference
      • Freshpaint iOS SDK Reference
      • Freshpaint Android SDK Reference
      • HTTP API
    • Frequently Asked Questions
      • How do I circumvent ad blockers?
      • Can Freshpaint track users across domains?
      • Can I install Freshpaint on a Chrome extension?
      • What properties are captured with my events?
      • How Do I Switchover From Segment?
      • How Do I Switch From Native Google Analytics to the Freshpaint Google Analytics Destination?
      • Where do I find my Environment ID?
      • Is Freshpaint GDPR & CCPA Compliant?
      • Can I use transformations to anonymize data for client-side destinations?
      • How do I QA or debug my data?
      • Why Do My Numbers Differ Across Different Tools?
      • Billing: How Does Freshpaint Determine MTUs?
      • Can I Use Freshpaint on Multiple Sites?
      • How Can I Export Data From Freshpaint?
      • How Does Freshpaint Identify Users?
      • How Many Events Should I Create?
      • What Should I Name My Events?
      • How do I track scroll depth?
      • What Data Does Freshpaint Collect?
        • Data Collected on Web
        • Data Collected on React Native
      • Does Freshpaint's Autotrack slow my site down?
      • Running Freshpaint with a Proxy
      • Should my Environment ID be treated as a sensitive key?
      • How Does Freshpaint Determine Session Count?
      • What is the difference between client-side and server-side connection mode?
      • What is a Proxy Integration?
      • Where can I view Freshpaint’s Status?
      • Does Freshpaint provide HIPAA audit logs?
      • Freshpaint Cookie Too Large
      • How does Freshpaint compare to server-side Google Tag Manager?
      • If a user re-installs my app, will Freshpaint generate a new device ID?
      • Why doesn't Freshpaint need a BAA before sending data to Google Ads and Facebook Ads?
      • What Implementation Services Does Freshpaint Offer?
      • Single Sign On (SSO) Setup
Powered by GitBook
On this page
  • Destination Info
  • Getting Started
  • Events
  • TikTok Event API: Web Event types
  • Supported TikTok parameters
  • Sending the same events from TikTok Pixel and TikTok Events API
  • Check whether it's working
  • Transformations
  • 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

Was this helpful?

  1. Integrations
  2. Destinations
  3. Direct Response Ads

TikTok Ads

Send advertising events directly to TikTok Ads

PreviousReddit Ads ReferenceNextTwitter Ads

Last updated 1 month ago

Was this helpful?

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

Destination Info

  • Accepts calls

  • Supports

  • Supports forwarding from the

  • Refer to this destination as TikTok Ads in the

  • Connection Modes:

Client-side
Server-side

Web

Mobile

Server

Getting Started

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

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

  • In , find your Pixel ID, or create a new Pixel as described at . Copy this value into your TikTok Ads configuration.

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

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).

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.

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:

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.

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

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.

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:

  • Copy the test_event_code

  • 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

  • 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

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:

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.

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.

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:

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:

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

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

Ensure Freshpaint 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 .

See also the .

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 .

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 .

In TikTok Ads Manager, navigate to , then select your Pixel ID

Go to the in Freshpaint and click "Test Event"

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

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

To optimize for conversions, use Transformations to match Freshpaint events to

TikTok Events API
Track
HIPAA mode
Google Tag Manager Integration
Integrations object
TikTok Ads configuration page
TikTok Ads Manager -> Assets -> Web Events
TikTok Events API: Get Started
TikTok Events API Reference
Setting up Properties
Transformations
User Identification
TikTok Click ID and Cookies section
TikTok Events API Reference
TikTok Event Deduplication
TikTok Ads Manager -> Assets -> Web Events
TikTok Ads configuration page
Transformations
Transformations
TikTok Ads configuration page
TikTok Standard Events
TikTok Click ID and Cookies section
img.png
img.png
img.png
img.png
img.png
img.png
img.png
img.png
img.png
img.png
img.png
img.png