How to set up a secure data connection with TikTok through Hightouch

TikTok for Business offers many tools that let you share the actions people take on your website with TikTok. When you share these events with TikTok, you can better optimize your campaigns and measure ad performance.

This article describes how to setup a secure data connection through Hightouch. Hightouch supports TikTok Events API, which enables you to send data from your warehouse to events and custom audiences in TikTok.

For more information on these connection tools, please review the following resources:

• About TikTok Events API

Supported syncing

For more information about sync modes, refer to the sync modes docs.

Connect to TikTok

Go to the Destinations overview page and click the Add destination button. Select TikTok and click Continue. You can then authenticate Hightouch to TikTok via OAuth.

Click Log in to TikTok, log in to your TikTok business account, and then click Authorize.

Once you've finished, Hightouch displays an Authorization successful message. To finish connecting, give your TikTok destination a descriptive name.

Sync configuration

Once you've connected your TikTok destination and have a model to pull data from, you can set up your sync configuration to begin syncing data. Go to the Syncs overview page and click the Add sync button to begin. Then, select the relevant model and the TikTok destination you want to sync to.

Syncing web events

Syncing to TikTok's web events lets you report different events from your source model.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Pixel code

You need to provide your TikTok Pixel ID to sync web events. To locate your Pixel ID: Go to TikTok Ads Manager. Hover over the Tools option and click on Events to open Events Manager. On the right side under Datasets overview, click the Pixel you want to use. Copy the Pixel ID value and place it in the respective field within HighTouch.

Check out our blog post to learn how to implement a TikTok Pixel.

Event name

You can specify the event name or type, by a static value or based on a column in your model. The name must be one of these accepted values: AddPaymentInfo, AddToCart, AddToWishlist, ClickButton, CompletePayment, CompleteRegistration, Contact, Download, InitiateCheckout, PlaceAnOrder, Search, SubmitForm, Subscribe, or ViewContent.

Field mapping

You can send additional details on your web events such as the timestamp, event (object) properties, and context (customer) properties. TikTok recommends that you provide as much context information as possible to increase the probability of matching web events with TikTok ads.

Batch size

You can increase the TikTok Events API batch size up to 1,000 per call. This can improve your sync's speed performance. The default is one event per API call. Keep in mind that TikTok fails an entire batch if it detects an erroneous row. If you suspect that you could have erroring rows, don't use a high batch size.

Test event codes

Test event codes are special codes you can include in your event payload to simulate events. This allows you to test your API implementation without recording real event data.

You can optionally enter a test event code as part of your sync configuration. Navigate to Events Manager by clicking the Assets tab, Event and then Manage Web Events. You can find your test event code in the Test Events tab.

Make sure to remove the test event code if you're running a production sync.

PII hashing

TikTok requires customer identity information (email, external_id, and phone_number) to be hashed using a SHA256 hash. By default, Hightouch automatically hashes these properties for you, but you can choose to opt out of this and hash the identity information yourself.

Syncing offline events

Syncing to TikTok's offline events lets you measure and attribute offline activity from people that see or interact with your TikTok ads.

Syncing offline events is an allowlist-only feature in TikTok. If you want access, please contact your TikTok representative. If you initially configured your TikTok destination before 06/06/23, you need to re-authenticate your connection to TikTok.

To ensure syncs send each event, your event model must use a truly unique primary key. See the events syncs documentation for more information.

Event set ID

You need to select an event set ID to sync your offline events. You can create a new event set in your TikTok offline events manager dashboard.

Event name

You can specify the event name or type, by a static value or based on a column in your model. The name must be one of these accepted values: AddPaymentInfo, AddToCart, AddToWishlist, ClickButton, CompletePayment, CompleteRegistration, Contact, Download, InitiateCheckout, PlaceAnOrder, Search, SubmitForm, Subscribe, or ViewContent.

Field mapping

You need, at minimum, the event name and at least one user property (such as emails or phones. The emails and phones array values must include at least one value, but you can include multiple elements. If you have a single email or phone number as strings in a model column, Hightouch converts them into arrays with one element.

Batch size

You can increase the TikTok Events API batch size up to 100 per call. This can improve your sync's speed performance. The default is 100 events per API call. Keep in mind that TikTok fails an entire batch if it detects an erroneous row. If you suspect that you could have erroring rows, don't use a high batch size.

PII hashing

TikTok requires user identity information (emails and phone_numbers) to be hashed using a SHA256 hash. By default, Hightouch automatically hashes these properties for you but you can choose to opt out of this and hash the identity information yourself.

Syncing custom audiences

Hightouch lets you create and maintain custom audiences via the File upload API or Segment API. You can read more on the different APIs and decide which is best for your use case in TikTok's docs.

Segment API mode (Recommended)

TikTok lets you make real-time batch updates through their Segment API. Hightouch sends data to the selected audience list as data gets added in your source model. We recommend this integration type because the API is newer and the integration is maintained by our team.

User identifiers

To identify which users to add or update in an audience, select model columns and the corresponding Tiktok fields. You can match on any of the following hashed user fields:

• IDFA_SHA256

• IDFA_MD5

• GAID_SHA256

• GAID_MD5

• EMAIL_SHA256

• PHONE_SHA256

Hightouch automatically hashes the selected properties for you unless you specify otherwise.

Increase match rates in TikTok by enabling Match Booster.

File upload API mode (Deprecated)

While TikTok still supports this API, Hightouch has deprecated the integration. We no longer add enhancements to the File upload API, and by end of 2023, we will programmatically migrate existing syncs to the Segment API mode and fully sunset this functionality.

TikTok lets you upload an entire audience through their file upload API. Hightouch uploads the entire model query results for each sync run. These results effectively replaces the previous file upload.

Record matching

The File upload mode lets you match on any one of these hashed user properties:

• IDFA_SHA256

• IDFA_MD5

• GAID_SHA256

• GAID_MD5

• EMAIL_SHA256

• or PHONE_SHA256

The property contains the name of what type of hash TikTok expects. Hightouch automatically hashes the selected property for you unless you specify otherwise. Hightouch also creates the audience list, if it doesn't exist yet, with the selected property's hash type.

Advertiser account

For both modes, you need to select the advertiser account you want to sync to.

Editing the advertiser account in the sync configuration is only possible before triggering the first sync run. Otherwise, making this change results in an error. If you want to use a different advertiser account once the sync has already run, you need to create a new sync.

Custom audience list

Hightouch lets you use an existing audience in TikTok or create a new one for both modes. Note that if you're using Segment mode, you can't change your audience list name once your sync has run, instead, you will have to create a new sync.

Tips and troubleshooting

Web events

Most errors customers encounters are validation errors, like an invalid currency code or phone number. TikTok rejects any request with invalid currency codes or phone number so Hightouch preemptively reject these rows before making the request to make the sync run more efficiently. Please refer to TikTok's documentation on what the expected currency codes are and what format the phone number should be in. Note: the currency code list may get updated from time to time.

Custom audiences

If you want to switch your custom audience sync mode from File upload API to Segment API, you need to run a full resync after saving the new configuration.

File upload API mode

Audiences with fewer than 1000 users are invalid and won't be available in TikTok. For more information, please refer to TikTok's documentation.

TikTok allows one file-based audience upload per day per audience. See TikTok's docs for more information on their limits.

Live debugger

Hightouch provides complete visibility into the API calls made during each of your TikTok sync runs, except for syncs in custom audience file upload mode. In this mode, Hightouch syncs the full query results set, and therefore doesn't make a change data capture computation. As a result, you won't see any payload details in the Live debugger.

For the web event and custom audience segment mode syncs, we recommend reading our article on debugging tips and tricks to learn more.