Integration of TikTok Ads with BigQuery

Connect TikTok Ads to BigQuery with WitCloud and collect daily campaign, ad group and ad performance and cost data for analysis.

Updated

Introduction

This module connects to the TikTok Ads reporting API and stores your advertising data in Google Cloud BigQuery. For every day it collects performance and cost metrics (impressions, clicks, spend, conversions, video views and more) at three levels: campaigns, ad groups and ads. Each level lands in its own table, so you can analyze and compare TikTok results next to your other channels. Every row is one day of one campaign, ad group or ad, with the account currency in the currency column, and each daily run replaces that day's data.

Configuration guide

Follow the steps below to connect TikTok Ads with BigQuery. Once the setup is complete, your ad data is transferred to your BigQuery project automatically.

You need a TikTok for Business login that has access to the advertiser accounts you want to collect. Only advertisers available to that login can be selected.

Module setup

Go to Integrations in the menu and click Add integration.

Integrations list with the Add integration button

Select TikTok from the list of available integrations.

Integration catalog filtered to TikTok Ads

Enter the Collect name, e.g. TikTok Ads PL.

Collect name field filled in with the example name TikTok Ads PL

Authorization

If you have already authorized TikTok in this project, pick the existing authorization from the Select TikTok authorization drop-down and skip the Authorize step.

Click Authorize.

Authorize button next to the Select TikTok authorization field

A TikTok for Business window opens. Log in and grant WitCloud access to your ad accounts (TikTok lists the permissions it asks for, such as reporting). When you confirm, the window closes and the new authorization is selected for you. If something goes wrong, WitCloud shows an error and you can click Authorize again.

Select advertisers

Open Select advertisers and choose the advertiser accounts to collect. The list shows the advertisers that the authorized TikTok login can access.

Select advertisers drop-down open with example TikTok advertisers

You can select several advertisers at once. Each selected advertiser becomes its own data collect, named <Collect name> - <advertiser name> (for example TikTok Ads PL - Demo Store PL).

Select advertisers field with two example advertisers selected

Advanced settings

Click Show advanced settings to open Tables to collect. All three tables (ads, adgroups and campaigns) are selected by default. Remove the ones you do not need; at least one table must stay selected.

Advanced settings open with the Tables to collect field

Click Next.

Historical data and scheduling

In Historical Data, enter the number of days of history to fetch. The maximum is 365 days.

Historical Data field filled in with 365 days

A data synchronization schedule is created automatically. More information on this topic can be found here.

Click Create to complete the configuration.

Data collection settings with the Create button

Done! Your TikTok Ads data will now be synchronized with BigQuery, one collect per selected advertiser.

Data schema

Expand the tables below to view the full data schema collected from TikTok Ads.

Data schema for tiktok_ads
Field NameModeType
ad_idNULLABLESTRING
ad_nameNULLABLESTRING
add_billingNULLABLEINTEGER
add_payment_infoNULLABLEINTEGER
add_to_wishlistNULLABLEINTEGER
adgroup_idNULLABLESTRING
adgroup_nameNULLABLESTRING
app_event_add_to_cartNULLABLEINTEGER
app_installNULLABLEINTEGER
button_clickNULLABLEINTEGER
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
checkoutNULLABLEINTEGER
clicksNULLABLEINTEGER
complete_paymentNULLABLEINTEGER
conversion_rateNULLABLEFLOAT
conversionNULLABLEINTEGER
cost_per_1000_reachedNULLABLEFLOAT
cost_per_conversionNULLABLEFLOAT
cost_per_resultNULLABLEFLOAT
cost_per_secondary_goal_resultNULLABLESTRING
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
cta_app_installNULLABLEINTEGER
cta_conversionNULLABLEINTEGER
cta_purchaseNULLABLEINTEGER
cta_registrationNULLABLEINTEGER
ctrNULLABLEFLOAT
currencyNULLABLESTRING
custom_page_events_valueNULLABLEFLOAT
custom_page_eventsNULLABLEINTEGER
dateNULLABLESTRING
download_startNULLABLEINTEGER
engaged_view_15sNULLABLEINTEGER
engaged_view_through_conversionsNULLABLEINTEGER
engaged_viewNULLABLEINTEGER
evta_app_installNULLABLEINTEGER
evta_payments_completedNULLABLEINTEGER
evta_purchaseNULLABLEINTEGER
evta_registrationNULLABLEINTEGER
formNULLABLEINTEGER
frequencyNULLABLEFLOAT
impressionsNULLABLEINTEGER
initiate_checkoutNULLABLEINTEGER
launch_appNULLABLEINTEGER
next_day_openNULLABLEINTEGER
on_web_add_to_wishlistNULLABLEINTEGER
on_web_orderNULLABLEINTEGER
on_web_subscribeNULLABLEINTEGER
online_consultNULLABLEINTEGER
page_content_view_eventsNULLABLEINTEGER
page_event_searchNULLABLEINTEGER
product_details_page_browseNULLABLEINTEGER
purchaseNULLABLEINTEGER
reachNULLABLEINTEGER
real_time_conversion_rateNULLABLEFLOAT
real_time_conversionNULLABLEINTEGER
real_time_cost_per_conversionNULLABLEFLOAT
real_time_cost_per_resultNULLABLEFLOAT
real_time_result_rateNULLABLEFLOAT
real_time_resultNULLABLEINTEGER
registrationNULLABLEINTEGER
result_rateNULLABLEFLOAT
resultNULLABLEINTEGER
sales_leadNULLABLEINTEGER
secondary_goal_result_rateNULLABLESTRING
secondary_goal_resultNULLABLESTRING
skan_add_payment_infoNULLABLEINTEGER
skan_add_to_wishlistNULLABLEINTEGER
skan_app_installNULLABLEINTEGER
skan_checkoutNULLABLEINTEGER
skan_click_time_conversionNULLABLEINTEGER
skan_conversionNULLABLEINTEGER
skan_launch_appNULLABLEINTEGER
skan_purchaseNULLABLEINTEGER
skan_registrationNULLABLEINTEGER
skan_resultNULLABLEINTEGER
skan_sales_leadNULLABLEINTEGER
skan_subscribeNULLABLEINTEGER
skan_total_add_payment_infoNULLABLEINTEGER
skan_total_add_to_wishlist_valueNULLABLEFLOAT
skan_total_add_to_wishlistNULLABLEINTEGER
skan_total_checkout_valueNULLABLEFLOAT
skan_total_checkoutNULLABLEINTEGER
skan_total_launch_appNULLABLEINTEGER
skan_total_purchase_valueNULLABLEFLOAT
skan_total_purchaseNULLABLEINTEGER
skan_total_registrationNULLABLEINTEGER
skan_total_sales_lead_valueNULLABLEFLOAT
skan_total_sales_leadNULLABLEINTEGER
skan_total_subscribe_valueNULLABLEFLOAT
skan_total_subscribeNULLABLEINTEGER
skan_total_view_content_valueNULLABLEFLOAT
skan_total_view_contentNULLABLEINTEGER
skan_view_contentNULLABLEINTEGER
spendNULLABLEFLOAT
subscribeNULLABLEINTEGER
total_add_billing_valueNULLABLEFLOAT
total_add_payment_infoNULLABLEINTEGER
total_add_to_wishlist_valueNULLABLEFLOAT
total_add_to_wishlistNULLABLEINTEGER
total_app_event_add_to_cart_valueNULLABLEFLOAT
total_app_event_add_to_cartNULLABLEINTEGER
total_button_click_valueNULLABLEFLOAT
total_checkout_valueNULLABLEFLOAT
total_checkoutNULLABLEINTEGER
total_complete_payment_rateNULLABLEFLOAT
total_download_start_valueNULLABLEFLOAT
total_form_valueNULLABLEFLOAT
total_initiate_checkout_valueNULLABLEFLOAT
total_landing_page_viewNULLABLEINTEGER
total_launch_appNULLABLEINTEGER
total_next_day_openNULLABLEINTEGER
total_on_web_add_to_wishlist_valueNULLABLEFLOAT
total_on_web_order_valueNULLABLEFLOAT
total_on_web_subscribe_valueNULLABLEFLOAT
total_online_consult_valueNULLABLEFLOAT
total_page_event_search_valueNULLABLEFLOAT
total_page_view_content_events_valueNULLABLEFLOAT
total_pageviewNULLABLEINTEGER
total_product_details_page_browse_valueNULLABLEFLOAT
total_purchase_valueNULLABLEFLOAT
total_purchaseNULLABLEINTEGER
total_registrationNULLABLEINTEGER
total_sales_lead_valueNULLABLEFLOAT
total_sales_leadNULLABLEINTEGER
total_subscribe_valueNULLABLEFLOAT
total_subscribeNULLABLEINTEGER
total_user_registration_valueNULLABLEFLOAT
total_value_per_pageviewNULLABLEFLOAT
total_view_content_valueNULLABLEFLOAT
total_view_contentNULLABLEINTEGER
total_web_event_add_to_cart_valueNULLABLEFLOAT
user_registrationNULLABLEINTEGER
value_per_complete_paymentNULLABLEFLOAT
video_play_actionsNULLABLEINTEGER
video_views_p100NULLABLEINTEGER
video_views_p25NULLABLEINTEGER
video_views_p50NULLABLEINTEGER
video_views_p75NULLABLEINTEGER
video_watched_2sNULLABLEINTEGER
video_watched_6sNULLABLEINTEGER
view_contentNULLABLEINTEGER
vta_app_installNULLABLEINTEGER
vta_complete_payment_roasNULLABLEFLOAT
vta_complete_payment_valueNULLABLEFLOAT
vta_complete_paymentNULLABLEINTEGER
vta_conversionNULLABLEINTEGER
vta_purchaseNULLABLEINTEGER
vta_registrationNULLABLEINTEGER
web_event_add_to_cartNULLABLEINTEGER
Data schema for tiktok_adgroups
Field NameModeType
add_billingNULLABLEINTEGER
add_payment_infoNULLABLEINTEGER
add_to_wishlistNULLABLEINTEGER
adgroup_idNULLABLESTRING
adgroup_nameNULLABLESTRING
app_event_add_to_cartNULLABLEINTEGER
app_installNULLABLEINTEGER
button_clickNULLABLEINTEGER
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
checkoutNULLABLEINTEGER
clicksNULLABLEINTEGER
complete_paymentNULLABLEINTEGER
conversion_rateNULLABLEFLOAT
conversionNULLABLEINTEGER
cost_per_1000_reachedNULLABLEFLOAT
cost_per_conversionNULLABLEFLOAT
cost_per_resultNULLABLEFLOAT
cost_per_secondary_goal_resultNULLABLESTRING
cpcNULLABLEFLOAT
cpmNULLABLEFLOAT
cta_app_installNULLABLEINTEGER
cta_conversionNULLABLEINTEGER
cta_purchaseNULLABLEINTEGER
cta_registrationNULLABLEINTEGER
ctrNULLABLEFLOAT
currencyNULLABLESTRING
custom_page_events_valueNULLABLEFLOAT
custom_page_eventsNULLABLEINTEGER
dateNULLABLESTRING
download_startNULLABLEINTEGER
engaged_view_15sNULLABLEINTEGER
engaged_view_through_conversionsNULLABLEINTEGER
engaged_viewNULLABLEINTEGER
evta_app_installNULLABLEINTEGER
evta_payments_completedNULLABLEINTEGER
evta_purchaseNULLABLEINTEGER
evta_registrationNULLABLEINTEGER
formNULLABLEINTEGER
frequencyNULLABLEFLOAT
impressionsNULLABLEINTEGER
initiate_checkoutNULLABLEINTEGER
launch_appNULLABLEINTEGER
next_day_openNULLABLEINTEGER
on_web_add_to_wishlistNULLABLEINTEGER
on_web_orderNULLABLEINTEGER
on_web_subscribeNULLABLEINTEGER
online_consultNULLABLEINTEGER
page_content_view_eventsNULLABLEINTEGER
page_event_searchNULLABLEINTEGER
product_details_page_browseNULLABLEINTEGER
purchaseNULLABLEINTEGER
reachNULLABLEINTEGER
real_time_conversion_rateNULLABLEFLOAT
real_time_conversionNULLABLEINTEGER
real_time_cost_per_conversionNULLABLEFLOAT
real_time_cost_per_resultNULLABLEFLOAT
real_time_result_rateNULLABLEFLOAT
real_time_resultNULLABLEINTEGER
registrationNULLABLEINTEGER
result_rateNULLABLEFLOAT
resultNULLABLEINTEGER
sales_leadNULLABLEINTEGER
secondary_goal_result_rateNULLABLESTRING
secondary_goal_resultNULLABLESTRING
skan_add_payment_infoNULLABLEINTEGER
skan_add_to_wishlistNULLABLEINTEGER
skan_app_installNULLABLEINTEGER
skan_checkoutNULLABLEINTEGER
skan_click_time_conversionNULLABLEINTEGER
skan_conversionNULLABLEINTEGER
skan_launch_appNULLABLEINTEGER
skan_purchaseNULLABLEINTEGER
skan_registrationNULLABLEINTEGER
skan_resultNULLABLEINTEGER
skan_sales_leadNULLABLEINTEGER
skan_subscribeNULLABLEINTEGER
skan_total_add_payment_infoNULLABLEINTEGER
skan_total_add_to_wishlist_valueNULLABLEFLOAT
skan_total_add_to_wishlistNULLABLEINTEGER
skan_total_checkout_valueNULLABLEFLOAT
skan_total_checkoutNULLABLEINTEGER
skan_total_launch_appNULLABLEINTEGER
skan_total_purchase_valueNULLABLEFLOAT
skan_total_purchaseNULLABLEINTEGER
skan_total_registrationNULLABLEINTEGER
skan_total_sales_lead_valueNULLABLEFLOAT
skan_total_sales_leadNULLABLEINTEGER
skan_total_subscribe_valueNULLABLEFLOAT
skan_total_subscribeNULLABLEINTEGER
skan_total_view_content_valueNULLABLEFLOAT
skan_total_view_contentNULLABLEINTEGER
skan_view_contentNULLABLEINTEGER
spendNULLABLEFLOAT
subscribeNULLABLEINTEGER
total_add_billing_valueNULLABLEFLOAT
total_add_payment_infoNULLABLEINTEGER
total_add_to_wishlist_valueNULLABLEFLOAT
total_add_to_wishlistNULLABLEINTEGER
total_app_event_add_to_cart_valueNULLABLEFLOAT
total_app_event_add_to_cartNULLABLEINTEGER
total_button_click_valueNULLABLEFLOAT
total_checkout_valueNULLABLEFLOAT
total_checkoutNULLABLEINTEGER
total_complete_payment_rateNULLABLEFLOAT
total_download_start_valueNULLABLEFLOAT
total_form_valueNULLABLEFLOAT
total_initiate_checkout_valueNULLABLEFLOAT
total_landing_page_viewNULLABLEINTEGER
total_launch_appNULLABLEINTEGER
total_next_day_openNULLABLEINTEGER
total_on_web_add_to_wishlist_valueNULLABLEFLOAT
total_on_web_order_valueNULLABLEFLOAT
total_on_web_subscribe_valueNULLABLEFLOAT
total_online_consult_valueNULLABLEFLOAT
total_page_event_search_valueNULLABLEFLOAT
total_page_view_content_events_valueNULLABLEFLOAT
total_pageviewNULLABLEINTEGER
total_product_details_page_browse_valueNULLABLEFLOAT
total_purchase_valueNULLABLEFLOAT
total_purchaseNULLABLEINTEGER
total_registrationNULLABLEINTEGER
total_sales_lead_valueNULLABLEFLOAT
total_sales_leadNULLABLEINTEGER
total_subscribe_valueNULLABLEFLOAT
total_subscribeNULLABLEINTEGER
total_user_registration_valueNULLABLEFLOAT
total_value_per_pageviewNULLABLEFLOAT
total_view_content_valueNULLABLEFLOAT
total_view_contentNULLABLEINTEGER
total_web_event_add_to_cart_valueNULLABLEFLOAT
user_registrationNULLABLEINTEGER
value_per_complete_paymentNULLABLEFLOAT
video_play_actionsNULLABLEINTEGER
video_views_p100NULLABLEINTEGER
video_views_p25NULLABLEINTEGER
video_views_p50NULLABLEINTEGER
video_views_p75NULLABLEINTEGER
video_watched_2sNULLABLEINTEGER
video_watched_6sNULLABLEINTEGER
view_contentNULLABLEINTEGER
vta_app_installNULLABLEINTEGER
vta_complete_payment_roasNULLABLEFLOAT
vta_complete_payment_valueNULLABLEFLOAT
vta_complete_paymentNULLABLEINTEGER
vta_conversionNULLABLEINTEGER
vta_purchaseNULLABLEINTEGER
vta_registrationNULLABLEINTEGER
web_event_add_to_cartNULLABLEINTEGER
Data schema for tiktok_campaigns
Field NameModeType
dateNULLABLESTRING
campaign_idNULLABLESTRING
campaign_nameNULLABLESTRING
cost_per_conversionNULLABLEFLOAT
real_time_conversionNULLABLEINTEGER
cpcNULLABLEFLOAT
conversion_rateNULLABLEFLOAT
frequencyNULLABLEFLOAT
real_time_conversion_rateNULLABLEFLOAT
impressionsNULLABLEINTEGER
real_time_cost_per_resultNULLABLEFLOAT
conversionNULLABLEINTEGER
real_time_resultNULLABLEINTEGER
cost_per_secondary_goal_resultNULLABLESTRING
secondary_goal_result_rateNULLABLESTRING
clicksNULLABLEINTEGER
cost_per_1000_reachedNULLABLEFLOAT
reachNULLABLEINTEGER
real_time_cost_per_conversionNULLABLEFLOAT
cpmNULLABLEFLOAT
ctrNULLABLEFLOAT
result_rateNULLABLEFLOAT
secondary_goal_resultNULLABLESTRING
cost_per_resultNULLABLEFLOAT
real_time_result_rateNULLABLEFLOAT
spendNULLABLEFLOAT
resultNULLABLEINTEGER
currencyNULLABLESTRING
add_billingNULLABLEINTEGER
add_payment_infoNULLABLEINTEGER
add_to_wishlistNULLABLEINTEGER
app_event_add_to_cartNULLABLEINTEGER
app_installNULLABLEINTEGER
button_clickNULLABLEINTEGER
checkoutNULLABLEINTEGER
complete_paymentNULLABLEINTEGER
cta_app_installNULLABLEINTEGER
cta_conversionNULLABLEINTEGER
cta_purchaseNULLABLEINTEGER
cta_registrationNULLABLEINTEGER
custom_page_events_valueNULLABLEFLOAT
custom_page_eventsNULLABLEINTEGER
download_startNULLABLEINTEGER
engaged_view_15sNULLABLEINTEGER
engaged_view_through_conversionsNULLABLEINTEGER
engaged_viewNULLABLEINTEGER
evta_app_installNULLABLEINTEGER
evta_payments_completedNULLABLEINTEGER
evta_purchaseNULLABLEINTEGER
evta_registrationNULLABLEINTEGER
formNULLABLEINTEGER
initiate_checkoutNULLABLEINTEGER
launch_appNULLABLEINTEGER
next_day_openNULLABLEINTEGER
on_web_add_to_wishlistNULLABLEINTEGER
on_web_orderNULLABLEINTEGER
on_web_subscribeNULLABLEINTEGER
online_consultNULLABLEINTEGER
page_content_view_eventsNULLABLEINTEGER
page_event_searchNULLABLEINTEGER
product_details_page_browseNULLABLEINTEGER
purchaseNULLABLEINTEGER
registrationNULLABLEINTEGER
sales_leadNULLABLEINTEGER
skan_add_payment_infoNULLABLEINTEGER
skan_add_to_wishlistNULLABLEINTEGER
skan_app_installNULLABLEINTEGER
skan_checkoutNULLABLEINTEGER
skan_click_time_conversionNULLABLEINTEGER
skan_conversionNULLABLEINTEGER
skan_launch_appNULLABLEINTEGER
skan_purchaseNULLABLEINTEGER
skan_registrationNULLABLEINTEGER
skan_resultNULLABLEINTEGER
skan_sales_leadNULLABLEINTEGER
skan_subscribeNULLABLEINTEGER
skan_total_add_payment_infoNULLABLEINTEGER
skan_total_add_to_wishlist_valueNULLABLEFLOAT
skan_total_add_to_wishlistNULLABLEINTEGER
skan_total_checkout_valueNULLABLEFLOAT
skan_total_checkoutNULLABLEINTEGER
skan_total_launch_appNULLABLEINTEGER
skan_total_purchase_valueNULLABLEFLOAT
skan_total_purchaseNULLABLEINTEGER
skan_total_registrationNULLABLEINTEGER
skan_total_sales_lead_valueNULLABLEFLOAT
skan_total_sales_leadNULLABLEINTEGER
skan_total_subscribe_valueNULLABLEFLOAT
skan_total_subscribeNULLABLEINTEGER
skan_total_view_content_valueNULLABLEFLOAT
skan_total_view_contentNULLABLEINTEGER
skan_view_contentNULLABLEINTEGER
subscribeNULLABLEINTEGER
total_add_billing_valueNULLABLEFLOAT
total_add_payment_infoNULLABLEINTEGER
total_add_to_wishlist_valueNULLABLEFLOAT
total_add_to_wishlistNULLABLEINTEGER
total_app_event_add_to_cart_valueNULLABLEFLOAT
total_app_event_add_to_cartNULLABLEINTEGER
total_button_click_valueNULLABLEFLOAT
total_checkout_valueNULLABLEFLOAT
total_checkoutNULLABLEINTEGER
total_complete_payment_rateNULLABLEFLOAT
total_download_start_valueNULLABLEFLOAT
total_form_valueNULLABLEFLOAT
total_initiate_checkout_valueNULLABLEFLOAT
total_landing_page_viewNULLABLEINTEGER
total_launch_appNULLABLEINTEGER
total_next_day_openNULLABLEINTEGER
total_on_web_add_to_wishlist_valueNULLABLEFLOAT
total_on_web_order_valueNULLABLEFLOAT
total_on_web_subscribe_valueNULLABLEFLOAT
total_online_consult_valueNULLABLEFLOAT
total_page_event_search_valueNULLABLEFLOAT
total_page_view_content_events_valueNULLABLEFLOAT
total_pageviewNULLABLEINTEGER
total_product_details_page_browse_valueNULLABLEFLOAT
total_purchase_valueNULLABLEFLOAT
total_purchaseNULLABLEINTEGER
total_registrationNULLABLEINTEGER
total_sales_lead_valueNULLABLEFLOAT
total_sales_leadNULLABLEINTEGER
total_subscribe_valueNULLABLEFLOAT
total_subscribeNULLABLEINTEGER
total_user_registration_valueNULLABLEFLOAT
total_value_per_pageviewNULLABLEFLOAT
total_view_content_valueNULLABLEFLOAT
total_view_contentNULLABLEINTEGER
total_web_event_add_to_cart_valueNULLABLEFLOAT
user_registrationNULLABLEINTEGER
value_per_complete_paymentNULLABLEFLOAT
video_play_actionsNULLABLEINTEGER
video_views_p100NULLABLEINTEGER
video_views_p25NULLABLEINTEGER
video_views_p50NULLABLEINTEGER
video_views_p75NULLABLEINTEGER
video_watched_2sNULLABLEINTEGER
video_watched_6sNULLABLEINTEGER
view_contentNULLABLEINTEGER
vta_app_installNULLABLEINTEGER
vta_complete_payment_roasNULLABLEFLOAT
vta_complete_payment_valueNULLABLEFLOAT
vta_complete_paymentNULLABLEINTEGER
vta_conversionNULLABLEINTEGER
vta_purchaseNULLABLEINTEGER
vta_registrationNULLABLEINTEGER
web_event_add_to_cartNULLABLEINTEGER