Set up data connector
Updates [November 2021]:
- Additional metrics from TikTok for Business can be pulled by creating conversion events (see instructions below).
Quick Details
| Data Connector Technology | API (TikTok marketing API v. 1.2) |
| Data Breakdown (segmentation) | Your data is broken down by the following dimensions:
If you don't use the country breakdown, single-targeted campaigns will display country values, but a multi-targeted campaign will be "N/A" unless we can estimate it based on attribution data. Estimated data may not be identical to TikTok. See "How is cost calculated per country?" |
| How far back we pull data | 7 days |
| Time zone | UTC by default |
| Is data available on the creative (ad) level? | Yes |
| Does Singular show your creative assets? | Yes |
Data Mapping
Tip: For more information about any field in Singular reporting, see the Metrics and Dimensions Glossary.
| Field in Singular UI | Field in Singular API | Field in TikTok API |
| Dimensions | ||
| Account ID | adn_account_id | (Taken from [advertiser/info]) |
| Account Name | adn_account_name | advertiser_name |
| App | app | app_name |
| App Site ID | app_site_id | (Taken from the [app_download_url]) |
| Bid Type | bid_type | bid_type |
| Campaign Objective | campaign_objective | objective_type |
| Campaign Status | campaign_status | opt_status |
| Campaign URL | adn_campaign_url | landing_page_url |
| Country | country_field | location |
| Date | date_field | stat_datetime |
| DMA ID | dma_id_field | dma.id |
| DMA Name | dma_name_field | dma.name |
| Network Campaign ID | adn_campaign_id | campaign_id |
| Network Campaign Name | adn_campaign_name | campaign_name |
| Network Creative ID | adn_creative_id | ad_id |
| Network Creative Name | adn_creative_name | ad_name |
| Network Sub Campaign ID | adn_sub_campaign_id | adgroup_id |
| Network Sub Campaign Name | adn_sub_campaign_name | adgroup_name |
| Original Bid Amount | original_bid_amount | bid |
| Original Bid Currency | original_metadata_currency | currency |
| Platform | platform |
|
| Public Id | site_public_id | mobile_app_id |
| Region |
region_field |
region.name |
| Standardized Bid Type | standardized_bid_strategy | optimize_goal |
| Timezone | adn_timezone | timezone |
| Text | creative_text | ad_text |
| Metrics | ||
| Average Frequency | frequency | frequency |
| Comments | comments | comments |
| Likes | likes | likes |
| Network Clicks | adn_clicks | click_cnt |
| Network Impressions | adn_impressions | show_cnt |
| Network Installs | adn_installs | convert_cnt |
| Original Cost | adn_original_cost | stat_cost |
| Original Currency | adn_original_currency | currency |
| Page Follows |
page_follows | follows |
| Reach |
reach | reach |
| Shares |
shares | shares |
| Video Views | video_views | total_play |
| Video Views - 25% | video_views_25pct | play_first_quartile |
| Video Views - 50% | video_views_50pct | play_midpoint |
| Video Views - 75% | video_views_75pct | play_third_quartile |
| Completed Video Views | completed_video_views | play_over |
Setup Instructions
Setup Steps
To set up the TikTok for Business data connector:
-
In your Singular account, go to Settings > Data Connectors.
-
Click Add New Connector and start typing "TikTok". Select "TikTok Ads" from the list that appears.
-
In the configuration window that opens, click Sign In with TikTok and log into your TikTok For Business account.
-
The TikTok platform asks if you want to grant Singular permissions to access TikTok data. Check the Agree to the Platform Service Agreement checkbox and click Confirm.
- After you grant the permissions, the configuration window in Singular indicates that you are connected. You can close the window.
-
TikTok now appears in the list of data connectors. The data connector status is "Pending" while Singular performs the first data pull. Once the first data pull is completed, the status will change to "Active".
-
After the data connector has successfully pulled data into Singular, you can start running reports that include TikTok data. For more information see the Reports FAQ, Singular API Reference, or Singular Data Destinations FAQ.
Sample report:
Additional Metrics (Conversion Events)
Singular pulls metrics from the TikTok for Business metrics list. By default, regular events are pulled from the "in-app events metrics" section and SKAdNetwork events from the "Supported SKAN Metrics" section of the list. In addition to these, you can pull any metric by creating a conversion event in Singular.
To create a conversion event:
- In Singular, go to Settings > Events. If you have both Custom Events and Conversion Events tabs, select Conversion Events.
- Click New Event.
-
In the TikTok Ads dropdown, select the desired metric.
The next day, when Singular pulls daily data for your account, it will pull completions as well.
- After the new event is populated with some data, run a report in the Reports page, and choose the conversion event you created from Events dropdown.
