TikTok Basic Report
Note that data generated by third-party data integration counts toward the cluster's data consumption
Summary
Interface overview
| Interface | Type | Granularity | Attribution | Cost | Revenue | Impressions | Clicks | Conversions |
|---|---|---|---|---|---|---|---|---|
| Basic Report | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ |
TikTok Basic Report provides aggregated grouping by ad dimensions. The returned data covers a range of metrics such as impressions, clicks, conversions, and user acquisition cost.
Integration process
- Log in to the TikTok API Business platform, register a developer account, create an app, and get the authorization information
- Log in to the AE backend, go to the Third-party Integration module, add a TikTok Basic Report plan, and complete the related configuration
- Change the authorization URL of the TikTok API app and complete the authorization
- Check whether the AE system receives the data successfully, and build reports
1. Get the authorization information
-
First, visit the TikTok API Business page. You need to log in to or register a TikTok ads account
-
Next, follow the steps to register as a developer
-
After you register as a developer, you need to create an app, as shown in the image below. You can configure the parameters as follows when you create it:
- Application name: the project name. Name it after your project
- App Description: the project description. You can add some notes
- Callback Address: the callback URL. When you create the app, you can enter https://www.thinkingdata.cn/, and change it to the data callback URL of the AE system later
- Scope of Permission: the data permissions that can be accessed. Be sure to select the Reporting permission here, and configure other permissions as needed
- After you click Confirm, your app is initially in a pending state. In about one to two days, the app can pass the review (that is, its status becomes Approved). Get the App ID and Secret of your app
2. Plan configuration
After you complete the preparation on the TikTok platform, log in to the AE system and configure the new plan in the Third-party Integration module. The image below shows the configuration page of TikTok Basic Report. Follow this section to create the plan
2.1 Authorization information configuration
Click the Configure authorization information button under Authorization Information and enter the authorization information you obtained in the previous step in the pop-up:
APP ID and App Secret are obtained in the previous step. For Account ID, enter the ID of the TikTok ads account whose data you want to pull
2.2 Sync Schedule
In the Sync Schedule module, you can set the policy for the AE system to pull TikTok Basic Report data on a schedule. You can choose to pull data for a period of time at a specific time every day. Because pulled data also counts toward the data volume, avoid pulling data for overly long periods on a schedule
2.3 Receive Settings
You can control whether the data is written as events. If you turn this off, the data is not written to the event table, so do not turn off this setting.
2.4 Configuration
Finally, in the Configuration module, you can control the detailed settings of data pulling, including the time aggregation granularity of the data, the metric fields and dimensions to pull, and the event name after ingestion.
The content of the configuration is a JSON, which you can customize as follows:
| Module | Name | Description |
|---|---|---|
| sink_event | event_name | Event name after ingestion; customizable; string type. |
| source | report_types | Aggregation dimension of the data; list type. You can enter only one element, that is, pull only one aggregation dimension at a time. See below for details |
time_granularity | Time aggregation granularity of the data, that is, whether the pulled data is aggregated by day or by hour Valid values: day, hour | |
| metrics | Metrics in the data; list type | |
| group_by | Grouping dimensions in the data; list type |
- Aggregation dimensions
Basic Report provides the following aggregation dimensions. Note that you can select only one dimension for Basic Report. To group by country (region), you can use only the country_code dimension:
| Dimension type | Dimension field | Description | Default |
|---|---|---|---|
Ad dimensions | advertiser_id | Advertiser level | |
| campaign_id | CAMPAIGN level | ||
| adgroup_id | ADGROUP level | ||
| ad_id | AD level | Yes | |
| Country (region) dimension | country_code | Group by country (region) |
Note that the metric fields you can get and the filter conditions supported differ between ad dimensions. Pay close attention to the notes on returned fields and filters to understand the data capabilities of the ad dimension you choose.
Basic Report supports a very rich set of fields. The following shows only the most common grouping dimensions and metric fields. For the complete field list, see TikTok's metrics list.
- Grouping dimensions
The following table shows the grouping dimensions that AE currently pulls by default. To adjust them, enter the field names in source.group_by:
| Field | Display name | Notes |
|---|---|---|
| advertiser_id | Ad account ID | Always ingested |
| campaign_name | Campaign name | Supported only at the CAMPAIGN, ADGROUP, and AD levels |
| campaign_id | Campaign ID | Supported only at the ADGROUP and AD levels |
| adgroup_name | Ad group name | Supported only at the ADGROUP and AD levels |
| adgroup_id | Ad set ID | Ad group ID; supported only at the AD level |
| placement_type | Placement | Supported only at the ADGROUP and AD levels |
aeo_type | AEO ad type | Enum values are Auto Bid, Multi Bid, and IAEO; returns - for non-AEO ad groups. Supported only at the ADGROUP level |
| ad_name | Ad name | Supported only at the AD level |
| ad_text | Ad title | Supported only at the AD level |
| tt_app_id | Promoted app ID | Supported only at the ADGROUP and AD levels; has a value when the promoted object is an App |
| tt_app_name | Promoted app name | Supported only at the ADGROUP and AD levels; has a value when the promoted object is an App |
| mobile_app_id | App ID | ID of the app in Google Play or the Apple App Store. Supported only at the ADGROUP and AD levels; has a value when the promoted object is an App |
| promotion_type | Promotion type | Valid values are app, website, and others. Supported at the ADGROUP and AD levels. Both synchronous and asynchronous reports support this metric. |
| dpa_target_audience_type | Target audience type of DPA ads | Supported at the ADGROUP and AD levels. Both synchronous and asynchronous reports support this metric. |
currency | Currency | Currency code, such as USD. Note that for currency to take effect, the 'dimensions' field in the request must contain adgroup_id/ ad_id/campaign_id/advertiser_id. |
- Metric fields
The following table shows the metric fields that AE currently pulls by default. To adjust them, enter the field names in source.metrics:
| Field | Display name | Notes |
|---|---|---|
| spend | Total spend | Amount spent on ads within the selected time. |
| cash_spend | Cash spend | Cash spent on ads within the selected time range. Supported only at the Advertiser level; lifetime and hourly queries are not supported. Note: Metric updates may be delayed by 24-48 hours |
| voucher_spend | Voucher spend | Voucher amount spent on ads within the selected time range. Supported only at the Advertiser level; lifetime and hourly queries are not supported. Note: Metric updates may be delayed by 24-48 hours |
| cpc | CPC | Average cost per click of the ad spend. |
| cpm | CPM | Average amount you spend per 1,000 impressions. |
| impressions | Number of impressions | Number of ad impressions. |
| clicks | Clicks | Number of ad clicks. |
| ctr | CTR (%) | Percentage of ad impressions that resulted in clicks. |
| reach | Reach | Number of people who saw the ad at least once. This metric is estimated. |
| cost_per_1000_reached | Cost per 1,000 people reached | Average cost to reach 1,000 people. This metric is estimated. |
| conversion | Conversions | Number of times the ad achieved the target conversion. The target conversion varies with the delivery settings at creation (counted based on the impression time). |
| cost_per_conversion | Conversion cost | Average cost per conversion of the ad spend (counted based on the impression time). |
conversion_rate | Conversion rate (%) | Percentage of ad clicks that resulted in conversions (counted based on the impression time). |
| real_time_conversion | Real-time conversions | Number of times the ad achieved the target conversion. The target conversion varies with the delivery settings at creation (counted based on the time the conversion event occurred) |
| real_time_cost_per_conversion | Real-time cost per conversion | Average cost per conversion of the ad spend (counted based on the time the conversion event occurred) |
| real_time_conversion_rate | Real-time conversion rate (%) | Percentage of ad clicks that resulted in conversions (counted based on the time the conversion event occurred) |
| result | Results | Number of results the ad ultimately achieved, corresponding to your optimization goal. (Counted based on the impression time) |
| cost_per_result | Cost per result | Cost of each result. (Counted based on the impression time) |
| result_rate | Result rate (%) | Percentage of ad views or clicks that produced results. (Counted based on the impression time) |
| real_time_result | Real-time results | Number of results the ad ultimately achieved, corresponding to your optimization goal. (Counted based on the time the conversion event occurred) |
| real_time_cost_per_result | Real-time cost per result | Cost of each result. (Counted based on the time the conversion event occurred) |
| real_time_result_rate | Real-time result rate (%) | Percentage of ad views or clicks that produced results. (Counted based on the time the conversion event occurred) |
| secondary_goal_result | Secondary goal result | Number of times the ad achieved the secondary goal, corresponding to your secondary goal. Because the same campaign can correspond to different secondary goals, the total number of results at the campaign dimension cannot be disclosed for now. Go to the ad group dimension to view the corresponding number of secondary goal results. |
| cost_per_secondary_goal_result | Cost per secondary goal result | Cost of each secondary goal result. Because the same campaign can correspond to different secondary goals, the cost per secondary goal result at the campaign dimension cannot be disclosed for now. Go to the ad group dimension to view the corresponding cost per secondary goal result. |
| secondary_goal_result_rate | Secondary goal result rate (%) | Number of secondary goal results as a percentage of ad impressions. |
| frequency | Frequency | Average number of times each reached user viewed the ad. |
| real_time_app_install | Real-time app installs | Number of times users activated the app and were attributed to your ad. (Counted based on the time the conversion event occurred) |
| real_time_app_install_cost | Real-time cost per app install | Cost per app install. (Counted based on the time the conversion event occurred) |
| app_install | App installs | Number of times users activated the app and were attributed to your ad. (Counted based on the impression time.) |
| cost_per_app_install | Cost per app install | Cost per app install. (Counted based on the impression time.) |
| registration | Unique registrations | Number of times deduplicated users registered in the app and were attributed to your ad. (Counted based on the impression time.) |
| cost_per_registration | Cost per unique registration | Cost per deduplicated registration. (Counted based on the impression time.) |
| registration_rate | Registration rate (%) | Ratio of deduplicated user registrations to app activations. (Counted based on the impression time.) |
2.5 Data ingestion rules
By default, we write the pulled data to the AE project as events:
- Because TikTok Marketing API returns aggregated data, we use a fixed value as the user identifier of the data. You can think of all data as attached to a single virtual user
- We use the stat_time_day or stat_time_hour field in the data as the #event_time of the aggregated data
- The default event name is -- tiktok_marketing_api_data
2.6 Standardized fields
If the following event properties exist in the data, we standardize them automatically:
| Original field | Standardized field | Description |
|---|---|---|
| advertiser_id | te_ads_object.ad_account_id | Ad account ID |
| campaign_name | te_ads_object.campaign_name | Campaign name |
| campaign_id | te_ads_object.campaign_id | Campaign ID |
| adgroup_name | te_ads_object.ad_group_name | Ad group name |
| adgroup_id | te_ads_object.ad_group_id | Ad group ID |
| ad_name | te_ads_object.ad_name | Ad name |
| ad_id | te_ads_object.ad_id | Ad ID |
| placement_type | te_ads_object.placement | Ad placement |
| mobile_app_id | te_ads_object.app_id | App ID |
| tt_app_name | te_ads_object.app_name | App name |
| country_code | te_ads_object.country | Country or region code |
| currency | te_ads_object.currency | Currency of the cost or revenue |
| impressions | te_ads_object.impressions | Impressions |
| clicks | te_ads_object.clicks | Clicks |
| app_install | te_ads_object.installs | Conversions (installs) |
| spend | te_ads_object.cost | User acquisition cost |
2.7 Complete authorization
After completing the configuration, click Save and authorize in the upper right corner to save the plan configuration. Next, you need to complete the final authorization:
First, in the Authorization Information page that pops up, copy the URL in the first step
Go back to the TikTok API Business page, edit the app you created earlier, edit Advertiser redirect URLs, and paste in the authorization URL you just copied.
Finally, go back to the AE interface and click Go to authorization. The TikTok authorization page opens. Follow the instructions on the authorization page to complete the authorization
After completing the authorization, in Authorization Information, click I have completed the above two steps in the lower left corner, and then click Complete Authorization in the lower right corner to finish the configuration. You have now completed the TikTok Basic Report data integration.