# Tiktok Events Export Integration

This feature is in BETA version. For more information, contact your Customer Success Representative.

## Overview

Many businesses are increasingly adopting TikTok as a key component of their advertising strategy. With over a billion active users, TikTok offers a vast audience and a unique, creative platform for brand promotion. Integrating event data with TikTok’s Events API can significantly enhance a brand’s advertising effectiveness and scale on the platform.

The native Tiktok Events Export connector for exporting event data to the TikTok Events API simplifies syncing event data to the TikTok Events Manager, driving data-driven audience targeting, and real-time insights for optimization.

This connector provides versatile data sync capabilities:

- **Website Event Data**:
  - Enrich your website pixel data with server-side data.
  - Achieve more accurate audience targeting, enhancing your campaign’s effectiveness.
- **App Event Data**:
  - Sync app event data with server-side data.
  - Improve targeting accuracy and optimize your campaign strategies for better results.
- **Offline Conversion Data**:
  - Send offline conversion data, such as physical store visits, to the TikTok Events API.
  - Track and measure the impact of online ads on offline sales, allowing for more informed campaign adjustments.
- **CRM Lead Conversion Data**:
  - Export CRM lead conversion data to TikTok Events API.
  - Enhance B2B lead generation campaigns by targeting users who have shown interest in your products or services, optimizing ad spend for higher quality leads.
- **Data Validation**:
  - Ensure all event data is accurately formatted and validated according to TikTok’s specifications.
  - Streamline the data integration process, reducing the risk of errors and ensuring smooth data sync operations.


## Prerequisites

- Basic knowledge of Treasure Data, including the TD Toolbelt.
- Basic knowledge of TikTok Business.
- TikTok Access Token or TikTok Business account.


## Limitations:

- This connector can support creating new event source for Web Events and Offline Event source type only.
- Experimental Event Source Types: App Event and CRM Event source types are experimental and not fully supported, as TD cannot enable these event sources for our test accounts. Please report any issues encountered with these event source types so that TD can address and fix them.


## Static IP Address of Treasure Data Integration

If your security policy requires IP whitelisting, you must add Treasure Data's IP addresses to your allowlist to ensure a successful connection.

Please find the complete list of static IP addresses, organized by region, at the following link:
[https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/](https://api-docs.treasuredata.com/en/overview/ip-addresses-integrations-result-workers/)

## Use the TD Console

Before running your query, you must create and configure the data connection in Treasure Data. As part of the data connection, you provide authentication to access the integration.

### Create Authentication

Your first step is to create a new authentication with a set of credentials.

1. Select **Integrations Hub**.
2. Select **Catalog**.


![](/assets/26617500.ca92fa4ab9277dca95973c6bd413fc662a3f0d04b57d58f7a8c952a29f28bbec.6bd3f7a7.png)

1. Search for your Integration in the Catalog; hover over the icon and select **Create Authentication**.


![](/assets/26617501.d6a5ad453f9fa98b4336af9506dadbd04ea44299e2f9af7fd760f75ac68e3f88.25ec5a77.png)

1. Ensure that the **Credentials** tab is selected, and then enter credential information for the integration. Choose one of the following:


- **OAuth Authentication Workflow**


Select the link "Click here" to start the OAuth authentication flow. After completing the authentication, a new OAuth connection will be created and available in the dropdown box

![](/assets/screenshot-2024-07-17-at-10.08.02.ba4580bf39d487924a012186dd0d09d31611535a8cd4080ba6a076c89488cc9e.0efdb04c.png)

Select **Continue** to create a new connection.

- **Access Token Workflow**


Obtain the access token from the TikTok Events Manager and input it in the **TikTok Access Token** field.

![](/assets/screenshot-2024-07-17-at-10.14.16.bd102375ccefd6e5a0e3d491c5006d3aec776093dfeb9eb865659bd0f6580b33.0efdb04c.png)

**New Authentication Fields**

| Parameter | Description |
|  --- | --- |
| auth_method | Authentication method. Supported values:   - oauth: OAuth authentication - access_token: Long live access token generated in the TikTok Event Manager. |
| access_token | You can obtain the TikTok Access Token from the TikTok Event Manager. This parameter is only available for access token authentication methods. |


1. Select **Continue**.
2. Enter a name for your authentication, and select Done.


### Define your Query

1. Navigate to **Data Workbench > Queries**.
2. Select **New Query**.
3. Run the query to validate the result set.


![](/assets/export-integration-template_26617476-2024-02-05.7a13029cf9bb61c96f1ef577583007e067c336b7d0cabc7a9222402f86046b29.9f8ceb9f.png)

### Specify the Result Export Target

1. Select **Export Results**.


![](/assets/export-integration-template_26617476-2024-02-05-1.5b83da44688e6582943f259dce9d18f20176855b764e46205a8d99cc64749f96.9f8ceb9f.png)

You can select an existing authentication or create a new authentication for the external service to be used for output. Choose one of the following:

- **Use Existing Integration**


![](/assets/export-integration-template_26617476-2024-02-05-2.654362d5d36805519ec64f0c0dcb467e4921dcd3e2760a0f6f6d4b2ddb672a3a.9f8ceb9f.png)

- **Create a New Integration**


The connection does not support creating a new connection in the result export. So, you need to have already created the connection.

### Configuration guide

1. Specifying the target event source in the Tiktok Event Managers for upload event data.


![](/assets/screenshot-at-aug-07-15-50-27.741c0c8bc2df295a12c45e99f0256b506ff5a1c24c07a1460776206736e6a9ef.0efdb04c.png)

| Field | Description |
|  --- | --- |
| Specify Event Data Source Type | Select the type of TikTok event data source you are using. Supported event source types include:- Web Events
- Mobile App Events
- Offline Events
- CRM Events

 |
| Specify The Target Event Source, Event Source ID, Event Source Name, Advertiser ID | Select the specific event source to upload event data to. The method you choose depends on the authentication method you use. Supported methods include:1. Use Event Source ID:
  - Authentication: Access token or OAuth authentication.
  - Instructions: Obtain the event source ID from the TikTok Events Manager:
    - Web Events: Pixel ID
    - Mobile App Events: TikTok App ID
    - Offline Events: Offline Event Set ID
    - CRM Events: CRM Event Set ID
    - Input: Fill in the "Event Source ID" input box.
*Leave the "Event Source Name" and "Advertiser ID" input boxes blank.*
2. Use Existing Event Source Name:
  - Authentication: OAuth authentication.
  - Supported for: Web Events and Offline Events.
  - Instructions: Query the existing event source name by filling in the "Event Source Name" and "Advertiser ID" input boxes.
*Ensure the "Event Source Name" is correct* to query the right event source ID. Leave the "Event Source ID" blank.
3. Create New Event Source Name:
  - Authentication: OAuth authentication.
  - Supported for: Web Events and Offline Events.
  - Instructions: Create a new event source name by filling in the "Event Source Name" and "Advertiser ID" input boxes. Note that only up to 10 event sources can be created for the Offline Event type.

 |


1. Other configuration options for data sync operations:
![](/assets/screenshot-at-aug-07-16-18-32.39ffa0710eb1cf054125637e7b67205e776f7d3a39ad9bd2baedceb9f0c51322.0efdb04c.png)
| Field | Description |
|  --- | --- |
| Test Event Code | The TikTok Test Event Code for debug purposes. |
| Thread Count Number | Number of parallel requests to TikTok Events. Min: 1, Max: 10, Default: 5. |
| Enabled Limited Data Processing | The boolean value to enable/disable a limited data processing option. *See* [*Events API 2.0 - Limited Data Use*](https://business-api.tiktok.com/portal/docs?id=1771101204435970) *for more details* |
| Skip on invalid record? | The flag to continue or stop the job when the job handles an invalid record. |


### (Optional) Other configurations

- You can [create an activation](/products/customer-data-platform/audience-studio/activation/create-an-activation) in the **Audience Studio** to export segment data to this integration.
- You can use [Scheduled Job](/products/customer-data-platform/data-workbench/queries/scheduling-a-query) with Result Export to periodically upload data to a target destination.


## (Optional) Export Integration Using the CLI

You can also use CLI(Toolbelt) to export results to TikTok Events.

You need to specify the information for export to your SFTP server as `*--result` option of `td query`* command. About *`td query`* command, you can refer to [this article](https://docs.treasuredata.com/display/PD/TD+Toolbelt+Job+and+Query+Command+Reference).

The format of the option is JSON and the general structure is as follows.


```json
{
  "type": "tiktok_events",
  "auth_method": "oauth",
  "access_token": "78cdexxxen",
  "event_data_source": "WEB",
  "target_event_source_method": "NAME",
  "event_source_name": "Test",
  "advertiser_id": "7373xxx",
  "event_source_id": "CPUI2xxx",
  "test_event_code": "TESTXXX",
  "thread_count": 5,
  "limited_data_use": true,
  "skip_invalid_record": true
}
```

### Parameters

| Name | Description | Value | Default Value | Required |
|  --- | --- | --- | --- | --- |
| type | Describe the name of the service as the destination of export. | tiktok_events | N/A | Yes |
| auth_method | Authentication method | Supported values:- oauth - access_token

 | oauth | Yes |
| access_token | TikTok access token generated from oauth flow or obtained from Events Manager. | N/A | N/A | Yes |
| event_data_source | TikTok event data sources. | Supported event sources:- WEB
- APP
- OFFLINE
- CRM

 | WEB | Yes |
| target_event_source | The target event source method. | Supported values: - ID - NAME - NEW | ID | Yes |
| event_source_name | The name of the event source. Input this field when the value of target_event_source is NAME or NEW | N/A | N/A | Yes, if the value of target_event_source is NAME or NEW |
| advertiser_id | The advertiser ID value. Input this field when the value of target_event_source is NAME or NEW | N/A | N/A | Yes, if the value of target_event_source is NAME or NEW |
| event_source_id | The event source id. Input this field when the value of target_event_source is ID | - WEB: Using the Pixel ID
- APP: Using TikTok App ID
- OFFLINE: Using Offline Event Source ID
- CRM: Using CRM Event Source ID

 | N/A | Yes, if the value of target_event_source is ID |
| test_event_code | The TikTok test event code. | N/A | N/A | No |
| thread_count | The number of parallel requests to TikTok Events API. | N/A | 5 | Yes |
| limited_data_use | The limited data use flag. | true/false | false | No |
| skip_invalid_record | The flag to continue or stop the job when handling the invalid record. | true/false | false | No |


### Example for Usage

OAuth authentication


```bash
td query \
  --result '{
    "type": "tiktok_events",
    "auth_method": "oauth",
    "access_token": "373xxx",
    "event_data_source": "WEB",
    "target_event_source_method": "NAME",
    "event_source_name": "Test",
    "advertiser_id": "737xxx",
    "event_source_id": "738xxx",
    "thread_count": 5,
    "limited_data_use": false,
    "skip_invalid_record": false
  }' \
  -d sample_datasets \
  "SELECT * FROM www_access" \
  -T presto
```

Access token authentication


```bash
td query \
  --result '{
    "type": "tiktok_events",
    "auth_method": "access_token",
    "access_token": "373xxx",
    "event_data_source": "WEB",
    "target_event_source_method": "ID",
    "event_source_name": "Test",
    "advertiser_id": "737xxx",
    "event_source_id": "738xxx",
    "thread_count": 5,
    "limited_data_use": false,
    "skip_invalid_record": false
  }' \
  -d sample_datasets \
  "SELECT * FROM www_access" \
  -T presto
```

## External references

- [Tiktok Events List of Standard Paramaters](https://business-api.tiktok.com/portal/docs?id=1771101151059969)