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
| Sync Type | Description | Supported Sync Modes |
|---|---|---|
| Web events | Sync data from any source to TikTok's pixel events. | Insert |
| Offline events | Sync data from any source to TikTok's offline events. | Insert |
| Custom audiences | Create audience lists and keep them up-to-date in TikTok. | Add, All (file upload) |
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.
Check out our blog post to learn how to implement a TikTok Pixel to help track conversions.
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.
If mapping the Click Id field, TikTok recommends that you also send the
Page url field for best results.
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.
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.
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)
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
Matched users count
Below only applies to the custom audiences sync type.
Hightouch retrieves the audience metadata from TikTok Ads in real-time. The matched number displayed in Hightouch should reflect what you see in TikTok Ads. Note that the matched numbers are approximated to maintain privacy thresholds. Hightouch takes the matched count to calculate a match rate for your sync, where applicable. The calculation breakdown:
matched_user_count / # of rows queried in the latest sync runThe match rate is
not
calculated when:- syncing to an existing segment because the total number of records to ever be uploaded to the segment is unknown
- removed users from your model is not removed in TikTok Ads because the matched user count would be inflated in the calculation
Common causes for low match rates:
- Your audience model is too small. Most ad platforms do not display the matched number unless there's at least one thousand matched users to maintain privacy thresholds.
- The upload is still processing. We recommend waiting at least
72 hours
from the first sync run for numbers to settle. - Your data isn’t cleaned or hashed properly. Hightouch normalizes and hashes your data according to destination requirements, but it’s still good to make sure that the data is as clean as possible. Note that Hightouch cannot clean your data if you opt to hash it yourself. In that case, ensure you follow the data cleaning requirements forTikTok Ads.
Common errors
If you encounter an error or question not listed below and need assistance, don't hesitate to . We're here to help.
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.
Error 40001: No permission to operate advertiser
This error can happen if the TikTok user credentials used to connect to TikTok don't have the necessary permissions to send data to the advertiser account selected in the sync configuration. When this error happens, you might also see that the advertiser account dropdown menu in the sync configuration is empty.
To solve this, make sure that the credentials used to connect TikTok to Hightouch have the necessary permissions to send data to your advertiser accounts.
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.
Web events
Most errors that occur with web event syncs are validation errors, like an invalid currency code or phone number. TikTok rejects any requests with invalid data, so Hightouch preemptively rejects these rows to make syncs run more efficiently. Please refer to TikTok's documentation to learn more about the expected phone number format and currency codes.
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.