The TikTok Events API
As an advertiser running ads on TikToK, you can pass Identity Envelope data with online conversion events to TikTok Events API with the TikTok Conversions API program. The CAPI program ensures more conversions are reported, which allows better measurement, optimization, and ad targeting.
This article illustrates how to integrate your ATS API implementation with TikTok Conversions API and create the call to send the events. This implementation method also allows you to send mobile app events to the TikTok Events API.
Requirements
To get started, you must have the following prepared:
- TikTok ad account ID: If you’ve already set up a TikTok Ads Manager account for your website, we recommend that you use the same Ad Account ID for your browser and server events. See TikTok's article “Ad Account Information FAQs”.
- TikTok Authentication Token: To give ATS access and authenticate requests to TikTok, you need an access token from TikTok. To learn how to do this, see TikTok's article "Setup guide for Web".
- ATS Configuration ID: Creating a call to the TikTok Conversion API endpoint requires an ATS configuration ID. To retrieve this ID, log in to Console and select ATS > Web. Select a configuration, and select the Admin tab. You can find the Configuration ID in the "Placement Details" area.
- App ID (mobile events only): Your App ID will be in either reverse DNS format (Android), or short numerical string (iOS) typically present in App Store or Playstore URLs.
- For iOS Apps, use the app ID found in the App Store URL
1a) Example: Apple Store URL: https://apps.apple.com/us/app/angry-birds/id343200656
1b) id = "343200656" - For Android Apps in the Google Play store, use the app ID found in the Google Play store URL.
2a) Example: Google Play store URL: https://play.google.com/store/apps/details?id=com.rovio.angrybird
2b) id = "com.rovio.angrybirds"
- For iOS Apps, use the app ID found in the App Store URL
- TikTok App ID (mobile events only): You must create an app and generate a TikTok App ID in your TikTok Ads Manager account. To learn more, see TikTok's article "Setup Guide for App".
Set Up TikTok CAPI in Console
Before sending events to our conversions API adapter, you must first integrate an ATS configuration with TikTok CAPI program in Console. During this process, you will have to provide the ad account ID with an authentication token from TikTok.
To set up the integration, log in to Console and follow the steps in “Set Up TikTok Conversions API Integrations in Console”.
Store the Identity Envelope With a Timestamp
Once you start calling the ATS envelope API as you normally would with conversions API enabled, you must store the identity envelope in a first-party cookie or local storage. See Store the Envelope With a Timestamp to learn how to do this.
Create the Request
POST: https://capi.analytics.rlcdn.com/send-events/atsconfigid
While the CAPI endpoint supports collecting and sending batch events, all events must belong to the same user session. Sending large batches (e.g., 1000 events) or combining events across multiple user sessions may result in unexpected behavior.
Web Event Examples
{
"events": [
{
"event_manager": [
"tiktok"
],
"event_id": "1234",
"event_type": "AddToCart",
"event_time": 1714692283,
"event_source_url": "https://yourwebshop.com/pageId",
"user_data": {
"partner_id": "AgNTagi_Y2T6eSlK9l3X7uJ11ib8QP2RXvpd2id5wnpjZBOvMGlVDhKsr2MrYrG6iDQHE7Gzlfx-O1fMCbKqchgakzLDkH66ETOgpeBdEx0GKzpPGRVaP22fwCLFZN1sjjnl"
},
"custom_data": [
{
"key": "currency",
"value": "USD"
},
{
"key": "value",
"value": "1337.99"
},
{
"key": "contents",
"value": [
{
"content_id": "15353004",
"price": "11.99"
},
{
"content_id": "15353005",
"price": "12.99"
}
]
}
]
}
]
}
{
"events": [
{
"event_manager": [
"tiktok"
],
"event_id": "6543",
"event_type": "CompletePayment",
"event_time": 1714692420,
"event_source_url": "https://yourwebshop.com/checkout",
"user_data": {
"partner_id": "AgNTagi_Y2T6eSlK9l3X7uJ11ib8QP2RXvpd2id5wnpjZBOvMGlVDhKsr2MrYrG6iDQHE7Gzlfx-O1fMCbKqchgakzLDkH66ETOgpeBdEx0GKzpPGRVaP22fwCLFZN1sjjnl"
},
"custom_data": [
{
"key": "currency",
"value": "USD"
},
{
"key": "value",
"value": "24.98"
},
{
"key": "content_type",
"value": "product"
},
{
"key": "contents",
"value": [
{
"content_id": "SKU123",
"price": "12.49"
},
{
"content_id": "SKU456",
"price": "12.49"
}
]
}
]
}
]
}
{
"events": [
{
"event_manager": [
"tiktok"
],
"event_id": "9876",
"event_type": "ViewContent",
"event_time": 1714692350,
"event_source_url": "https://yourwebshop.com/product/XYZ456",
"user_data": {
"partner_id": "AgNTagi_Y2T6eSlK9l3X7uJ11ib8QP2RXvpd2id5wnpjZBOvMGlVDhKsr2MrYrG6iDQHE7Gzlfx-O1fMCbKqchgakzLDkH66ETOgpeBdEx0GKzpPGRVaP22fwCLFZN1sjjnl"
},
"custom_data": [
{
"key": "currency",
"value": "EUR"
},
{
"key": "value",
"value": "49.99"
},
{
"key": "quantity",
"value": "1"
},
{
"key": "contents",
"value": [
{
"content_id": "XYZ456",
"price": "49.99"
}
]
}
]
}
]
}
{
"events": [
{
"event_manager": [
"tiktok"
],
"event_id": "12345",
"event_type": "InitiateCheckout",
"event_time": 1744699800,
"event_source_url": "https://yourwebshop.com/checkout",
"user_data": {
"partner_id": "AgNTagi_Y2T6eSlK9l3X7uJ11ib8QP2RXvpd2id5wnpjZBOvMGlVDhKsr2MrYrG6iDQHE7Gzlfx-O1fMCbKqchgakzLDkH66ETOgpeBdEx0GKzpPGRVaP22fwCLFZN1sjjnl"
}
}
]
}
Mobile Event Examples
You must pass your App ID under the app_data section when sending mobile events.
{
"events": [
{
"event_type": "CheckOut",
"event_id": "1",
"event_time": 1726475954,
"event_source_url": "https://www.jasna.sim.com",
"event_manager": [
"tiktok"
],
"user_data": {
"partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast",
"idfa": "{{IDFA}}",
"idfv": "{{IDFV}}",
"gaid": "{{GAID}}",
"att_status": "AUTHORIZED"
},
"app_data": {
"app_id": "com.ecommerce.mobileapp",
"app_name": "ECommerceApp",
"app_version": "2.1.0"
},
"custom_data": [
{
"key": "currency",
"value": "EUR"
},
{
"key": "value",
"value": "49.99"
},
{
"key": "content_type",
"value": "product"
},
{
"key": "contents",
"value": [
{
"content_id": "XYZ456",
"price": "49.99"
}
]
}
]
}
]
}
{
"events": [
{
"event_type": "InstallApp",
"event_id": "1",
"event_time": 1726475954,
"event_source_url": "https://play.google.com/store/apps/details?id=com.example.myapp",
"event_manager": [
"tiktok"
],
"user_data": {
"partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast",
"idfa": "{{IDFA}}",
"idfv": "{{IDFV}}",
"gaid": "{{GAID}}",
"att_status": "AUTHORIZED"
},
"app_data": {
"app_id": "com.test.flyingsneakers",
"app_name": "Flying Sneakers",
"app_version": "3.0.2"
}
}
]
}
{
"events": [
{
"event_type": "LaunchAPP",
"event_id": "1",
"event_time": 1726476500,
"event_source_url": "https://play.google.com/store/apps/details?id=com.fitness.workouttracker",
"event_manager": [
"tiktok"
],
"user_data": {
"partner_id": "Adsogthdhfqzjjfgttojrgkuqignabexgeorndpcgxcxwuehgvtccffzoecbcxwdtfpldast",
"idfa": "{{IDFA}}",
"idfv": "{{IDFV}}",
"gaid": "{{GAID}}",
"att_status": "AUTHORIZED"
},
"app_data": {
"app_id": "com.fitness.workouttracker",
"app_name": "Workout Tracker",
"app_version": "13.0.1"
}
}
]
}
Refresh the ATS Envelopes
You can refresh existing CAPI-scoped envelopes by calling:
https://api.rlcdn.com/api/identity/v2/envelope/refresh?pid=[placement id]&it=[envelope type]&iv=[envelope value]&ct=[consent type]&cv=[consent string]
You must populate the it parameter with 19 to correspond to the CAPI-scoped envelope type. This will reset the envelope expiration to the maximum allowed value.
To learn more about refreshing envelopes, see Implement the ATS Envelope Refresh API.
Updated 8 months ago