TikTok Audience 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 |
|---|---|---|---|---|---|---|---|---|
| Audience Report | API | Aggregated metrics | ✅ | ✅ | ✅ | ✅ |
Compared with Basic Report, TikTok Audience Report provides more aggregated grouping dimensions for users (called audience dimensions), but returns relatively fewer types of metrics and has a processing delay of 6-12 hours.
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 Audience 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 Audience 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 Audience 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
Audience Report provides the following aggregation dimensions. Note that you can select only one audience dimension and one ad dimension for Audience Report. The audience dimension is required, and the ad dimension is optional. There are also some exceptions; see the Notes column of the table below for more information.
In addition, to group by country (region), you can use only the country_code dimension:
| Dimension type | Dimension field | Description | Remarks | Default |
|---|---|---|---|---|
Ad dimensions | advertiser_id | Group by advertiser ID | ||
| campaign_id | Group by campaign ID | |||
| adgroup_id | Group by ad group ID | |||
| ad_id | Group by ad ID | Yes | ||
Audience dimensions | country_code | Group by targeted country | If you group by country, you can use only the country_code dimension | |
| gender | Group by gender | age and gender can be used together | ||
| age | Group by age | age and gender can be used together | ||
province_id | Group by province-level region. For valid region values, see Location targeting. | Cannot be used together with time dimensions | ||
| dma_id | Group by designated market area (DMA). This regional division exists only in the United States. For valid values, see Location targeting. | Cannot be used together with time dimensions | ||
| ac | Group by network | |||
| language | Group by audience language | |||
| platform | Group by operating system | Yes | ||
| interest_category | Group by tier-1 interest category | Cannot be used together with time dimensions | ||
| interest_category_tier2 | Group by tier-2 interest category | Cannot be used together with time dimensions | ||
| interest_category_tier3 | Group by tier-3 interest category | Cannot be used together with time dimensions | ||
| interest_category_tier4 | Group by tier-4 interest category | Cannot be used together with time dimensions | ||
| behavior_id | Group by behavior | Cannot be used together with time dimensions | ||
| placement | Group by placement | Cannot be used together with time dimensions | ||
| device_brand_id | Group by device brand | Cannot be used together with time dimensions. When you use this dimension, lifetime cannot be set to true |
Audience 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 (except device_brand_name, behavior_name, action_category, action_scene, user_action, and action_period: these 6 fields are not pulled by default, and their usage conditions are described in the table). To adjust them, enter the field names in source.group_by:
| Metric | Brief description | Detailed description |
|---|---|---|
| advertiser_id | Ad account ID | Always ingested |
| campaign_name | Campaign name | Campaign name; supported only at the CAMPAIGN, ADGROUP, and AD levels |
| campaign_id | Campaign ID | Campaign ID; supported only at the ADGROUP and AD levels |
| adgroup_name | Ad group name | Ad group name; supported only at the ADGROUP and AD levels |
| placement_type | Placement | Placement; supported only at the ADGROUP and AD levels |
| adgroup_id | Ad set ID | Ad group ID; supported only at the AD level |
| aeo_type | AEO ad type | AEO (App Event Optimization) 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 | Ad name; supported only at the AD level |
| ad_text | Ad title | Ad title; supported only at the AD level |
| tt_app_id | Promoted 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 | Promoted app name; supported only at the ADGROUP and AD levels; has a value when the promoted object is an App |
| mobile_app_id | ID of the promoted app in Google Play or the Apple App Store | ID of the promoted 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 |
| device_brand_name | Device brand name | Supported when the dimensions include device_brand_id. |
| behavior_name | Behavior name | Supported when the dimensions include behavior_id. |
| action_category | Action category | Supported when the dimensions include behavior_id. Supported only by real-time reports, not by asynchronous reports. |
| action_scene | Action scene. Enum values: VIDEO_RELATED (video actions), CREATOR_RELATED (creator actions). | Supported when the dimensions include behavior_id. Supported only by real-time reports, not by asynchronous reports. |
| user_action | User action | For the video action scene, valid values include WATCHED_TO_END (watched to the end), LIKED (liked), COMMENTED (commented), and SHARED (shared). For the creator action scene, valid values include FOLLOWING (followed) and VIEW_HOMEPAGE (viewed the profile page). |
| action_period | Action period in days. Valid values: 7, 15. | Supported only by real-time reports, not by asynchronous reports. |
| promotion_type | 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 for DPA | 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:
| Metric | Brief description | Detailed description |
|---|---|---|
| spend | Total spend | Amount spent on ads within the selected time. |
| 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. |
| 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) |
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_audience_report
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 |
| conversion | te_ads_object.installs | Conversions |
| 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 Audience Report data integration.