TikTok

Empower your marketing team by utilizing web events in TikTok

Overview

With Hightouch and the TikTok marketing API, you can send data from your warehouse to events and custom audiences in TikTok. Deliver relevant ads by utilizing data from various sources within your data warehouse.

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.

Pixel code

You need to provide your TikTok pixel code to sync web events. To find the pixel code, navigate to your TikTok Marketing Dashboard and go to Assets menu > Manage Web Events. Select the pixel you want to sync to and copy the ID.

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 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 actually 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 track and measure offline activity from people that see or interact with your ads.

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, emails or phones. The emails and phones array values must include at least one value, but you can include multiple elements. If you have 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.

File upload API mode (Deprecated)

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.

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

Common errors

If you encounter an error or question not listed below and need assistance, don't hesitate to reach out. We're here to help.

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.

Sync alerts

Hightouch can alert you of sync issues via Slack, PagerDuty, SMS, or email. For details, please visit our article on alerting.