TikTok is a global social networking service that focuses on short-form videos and reports having 1 Billion active monthly users around the globe. You can use TikTok's Marketing API to target customers by creating custom segments.
Treasure Data's TikTok Integration allows you to send job results from Treasure Data directly to TikTok Marketing using custom audiences.
What can you do with this Integration?
- Send Audience segments to TikTok in order to build the best-fit campaign for retargeting our existing customers, as well as attracting more look-alike audiences.
- Stop targeting when end-users explicitly give the opt-out consent.
Prerequisites
Basic Knowledge of Treasure Data.
Basic knowledge of TikTok Ads Manager and TikTok Marketing API
- A developer account and an approved application in TikTok Marketing API
- Using your preferred tool for making API requests, obtain an access token from TikTok
Requirements and Limitations
- The maximum file size to be uploaded is 50MB per file and 500 files per audience which means we only could support uploading a maximum of 50MB * 500 files = 25000 MB ~ 25GB (the actual size due to restriction in plugin make it around 20GB )
- After the creation of an audience, the audience will be accessible in 1 hour
Maximum 400 custom audiences
Data before hashing needs to be in all uppercase or lowercase
A minimum audience size of 1,000 is required to target Custom Audiences in an ad group
Creating Your Own TikTok Marketing API Developer Account and Application
You'll need to create your own Tiktok Marketing API Developer Account before you can begin creating applications. Learn more about how to Register as a Developer and what you need to do to Create a Developer Application for TikTok.
1. From the TikTok Marketing API homepage, select the Register button on the top right.
2. Type in your login credentials and confirm your password.
3. Select Send Code.
4. Next, you will receive an SMS with a passcode. Type the code into the Verification Code field and select Sign Up.
If you do not receive a passcode select the Send Code button again.
5. After correctly entering the Verification Code, you are redirected to the login screen, where you can use your new credentials.
6. Slide the bar to line up with the displayed image to complete the verification steps.
7. You are now logged into the TikTok Marketing API homepage.
8. Select Become a Developer from the top-right menu.
9. A new screen appears. Type in your login information and choose Direct Advertiser in the field What best describes you or your company. Select Send Code to verify your email and phone.
10. Select Next.
11. Type on your information, including Company Name, Company Website, etc. Then, select Next.
12. Navigate to the Create Application pane. Then, type in your application name and description.
13. Type your local IP address in the Callback Address. You may need to certain permission, such as those in the following example.
14. Select Submit.
15. You are redirected to the My Apps page, where you can view the status of your application. Application approval may take 2 or 3 business days.
Obtain your App ID and Secret and get your Access Token
You must have your App ID and Secret before you can get your TikTok Access Token.
1. From the TikTok Marketing API homepage, select Log In in the top right.
2. Select the My Apps to view your application.
3. Select the app name you want.
4. On the new screen, you can view your basic information, including the App ID and Secret.
5. Note this information for later.
6. Select Copy to retain the Secret on your clipboard.
7. On current application's screen, scroll down to Authorized URL.
8. Copy the Authorized URL, paste it into an open web browser, and press Enter. You will be prompted to log in to your TikTok Ads Account, then a new screen appears and select Confirm.
9. You will be redirected to a non-existent webpage. Copy the URL in the webpage and get the auth_code value.
For example, your URL may look like this:
http://192.168.101.1/callback?auth_code=11111&code=11111&state=your_custom_params
10. Using your preferred API request tool, such as POSTMAN, you can send a request to https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/ with a request body as shown in the following example.
{ "app_id" : "{your_app_id}", "auth_code" : "{auth_code_in_above_step}", "secret" : "{your_app_secret}" }
11. Next, select Send.
12. Alternatively, you may use cURL with the following command
$ curl --location --request POST 'https://business-api.tiktok.com/open_api/v1.2/oauth2/access_token/' \ --header 'Content-Type: application/json' \ --data-raw '{ "app_id" : "{your_app_id}", "auth_code" : "{auth_code_in_above_step}", "secret" : "{your_app_secret}" }'
13. After you receive the response with the access_token and advertiser_ids like in the following example, you are ready to integrate with TikTok.
{ "message": "OK", "code": 0, "data": { "access_token": "********************", "scope": [ 1, 3, 4 ], "advertiser_ids": [ ******************** ] }, "request_id": "11111" }
Use the TD Console to Create Your Connection
Create a New Connection
In Treasure Data, you must create and configure the data connection prior to running your query. As part of the data connection, you provide authentication to access the integration.
1. Open TD Console.
2. Navigate to Integrations Hub > Catalog.
3. Search for and select TikTok.
4. Select Create Authentication.
5. Type the access token to authenticate.
6. Type a name for your connection.
7. Select Continue.
Define your Query
Your query will need to have the id column.
- Complete the instructions in Creating a Destination Integration.
Navigate to Data Workbench > Queries.
Select a query for which you would like to export data.
Run the query to validate the result set.
Select Export Results.
- Select an existing integration authentication.
- Define any additional Export Results details. In your export integration content review the integration parameters.
For example, your Export Results screen might be different, or you might not have additional details to fill out: Select Done.
Run your query.
Validate that your data moved to the destination you specified.
Integration Parameters for TikTok
Parameter | Types | Sample Value | Description |
---|---|---|---|
String | xxxx | Access Token | |
String | v1.2 | API version on TikTok. Do not changes this values unless you're required to change from Treasure Data | |
boolean | false | Flag to indicate that you are trying to push segment to sandbox environment of TikTok | |
String | 12345678901234567890 | Your advertiser's id on TikTok | |
String | Test Audience | Audience’s name | |
Enum (FIRST_NORMAL, FIRST_SHA256, FIRST_MD5, EMAIL_SHA256, PHONE_SHA256, IDFA_SHA256, IDFA_MD5, GAID_SHA256, GAID_MD5) | FIRST_NORMAL | ID Type | |
Enum (APPEND, REMOVE, REPLACE) | Audience's Action (REMOVE, REPLACE, ADD) |
Example Query
SELECT id FROM my_table
Example TD CLI
td query -d my_database -r '{ "accessToken": "__SAVED__", "useSandbox": true, "advertiserId": "12345678901234567890", "apiVersion": "v1.2", "audienceAction": "REPLACE", "audienceName": "test", "encryptionType": "FIRST_NORMAL" }' "select id FROM my_table" -T presto