2023-08 Tiktok API upgrade 1.3
Introduction
This document outlines the process of upgrading to TikTok API version 1.3, which involves making necessary modifications to the existing TikTok Rivers.
What changes were made during the upgrade?
-
In version 1.3, all ID fields that were formerly categorized as INTEGER types in version 1.2 have been converted to STRING types. These alterations in data types might necessitate adjustments in the data types of your Target tables.
-
The boolean type fields now exclusively use "True" and "False" instead of "1" and "0" or "Yes" and "No".
-
All date and Timestamp fields now adhere to a consistent time format: YYYY-MM-DD HH:MM:SS - ISO 8601.
Report changes
** Advertisers :**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | reason | |
| phonenumber | ||
| telephone | rejection_reason | |
| cellphone_number | ||
| telephone_number | ||
| Renamed columns + Datatype changes | id: number | advertiser_id: string |
** Campaigns :**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | budget_optimize_switch | |
| opt_status | ||
| campaign_app_profile_page_type | ||
| industry_types | ||
| status | ||
| optimize_goal | budget_optimize_on | |
| operation_status | ||
| campaign_app_profile_page_state | ||
| special_industries | ||
| secondary_status | ||
| optimization_goal | ||
| Columns datatype changes | advertiser_id: number | |
| campaign_ids: number | ||
| budget_optimize_on: number | advertiser_id: string | |
| campaign_ids: string | ||
| budget_optimize_on: boolean |
** Ad Groups :**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | is_share_disable | |
| placement | ||
| enable_inventory_filter | ||
| external_type | ||
| external_action | ||
| deep_external_action | ||
| age | ||
| operation_system | ||
| connection_type | ||
| device_price | ||
| android_osv | ||
| ios_target_device | ||
| ios_osv | ||
| optimize_goal | ||
| bid | ||
| conversion_bid | ||
| deep_cpabid | ||
| daily_retention_ratio | ||
| status | ||
| opt_status | ||
| action_v2 | ||
| user_actions | ||
| rf_buy_type | ||
| buy_impression | ||
| buy_reach | ||
| rf_predict_cpr | ||
| rf_predict_frequency | ||
| include_custom_actions | ||
| exclude_custom_actions | ||
| dpa_retargeting_type | ||
| brand_safety | ||
| enable_expansion | ||
| ad_app_profile_page_type | ||
| display_mode | share_disabled | |
| placements | ||
| inventory_filter_enabled | ||
| promotion_type | ||
| optimization_event | ||
| secondary_optimization_event | ||
| age_groups | ||
| operating_systems | ||
| network_types | ||
| device_price_ranges | ||
| min_android_version | ||
| ios14_targeting | ||
| min_ios_version | ||
| optimization_goal | ||
| bid_price | ||
| conversion_bid_price | ||
| deep_cpa_bid | ||
| next_day_retention | ||
| secondary_status | ||
| operation_status | ||
| actions | ||
| video_user_actions | ||
| rf_purchased_type | ||
| purchased_impression | ||
| purchased_reach | ||
| rf_estimated_cpr | ||
| rf_estimated_frequency | ||
| included_custom_actions | ||
| excluded_custom_actions | ||
| shopping_ads_retargeting_type | ||
| brand_safety_type | ||
| expansion_enabled | ||
| adgroup_app_profile_page_state | ||
| delivery_mode | ||
| Columns datatype changes | advertiser_id: number | |
| campaign_id: number | ||
| adgroup_id: number | ||
| app_id: number | ||
| store_id: number | ||
| pixel_id: number | ||
| skip_learning_phase: number | ||
| catalog_id: number | ||
| product_set_id: number | ||
| schedule_id: number | advertiser_id: string | |
| campaign_id: string | ||
| adgroup_id: string | ||
| app_id: string | ||
| store_id: string | ||
| pixel_id: string | ||
| skip_learning_phase: boolean | ||
| catalog_id: string | ||
| product_set_id: string | ||
| schedule_id: string | ||
| Renamed columns + Datatype changes | is_comment_disable: number | |
| shop_authorized_bc: number | ||
| audience: number[] | ||
| excluded_audience: number[] | ||
| location: number[] | ||
| interest_category_v2: number[] | ||
| interest_keywords: number[] | ||
| device_models: number[] | ||
| carriers_v2: number[] | ||
| video_download: string | ||
| pangle_block_app_list_id: number[] | ||
| action_categories: number[] | ||
| pangle_audience_package_include: number[] | ||
| pangle_audience_package_exclude: number[] | ||
| catalog_authorized_bc: number | ||
| automated_targeting: string | comment_disabled: boolean | |
| store_authorized_bc_id: string | ||
| audience_ids: string[] | ||
| excluded_audience_ids: string[] | ||
| location_ids: string[] | ||
| interest_category_ids: string[] | ||
| interest_keyword_ids : string[] | ||
| device_model_ids : string[] | ||
| carrier_ids: string[] | ||
| video_download_disabled: boolean | ||
| blocked_pangle_app_ids: string[] | ||
| action_category_ids: string[] | ||
| included_pangle_audience_package_ids: string[] | ||
| excluded_pangle_audience_package_ids: string[] | ||
| catalog_authorized_bc_id: string | ||
| auto_targeting_enabled: boolean | ||
| Deprecated Columns | category : string | |
| interest_category : string | ||
| action_category_ids: string | ||
| action_days: string | ||
| video_actions: string | / |
Ads:
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | status | |
| opt_status | ||
| profile_image | ||
| open_url | ||
| open_url_type | ||
| vast_moat | ||
| is_creative_authorized | ||
| dpa_fallback_type | ||
| dpa_open_url_type | ||
| dpa_video_tpl_id | secondary_status | |
| operation_status | ||
| profile_image_url | ||
| deeplink | ||
| deeplink_type | ||
| vast_moat_enabled | ||
| creative_authorized | ||
| shopping_ads_fallback_type | ||
| shopping_deeplink_type | ||
| shopping_ads_video_package_id | ||
| Columns datatype changes | advertiser_id: number | |
| campaign_id: number | ||
| adgroup_id: number | ||
| ad_id: number | ||
| tiktok_item_id: number | ||
| card_id: number | advertiser_id: string | |
| campaign_id: string | ||
| adgroup_id: string | ||
| ad_id: string | ||
| tiktok_item_id: string | ||
| card_id: string | ||
| Deprecated Columns | / | premium_badge_id |
** _Creative Report _**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | ad_number | num_ads |
| Columns datatype changes | country_code: list[string] | |
| placement: list[string] | country_code: string[] | |
| placement: string[] | ||
| Renamed columns + Datatype changes | related_ads: number[] | |
| related_adgroups: number[] | related_ad_ids: string[] | |
| related_adgroup_ids: string[] | ||
| Deprecated Columns | / | ad_cost_top5 |
| ad_cost_top5_total | ||
| adgroup_cost_top5 | ||
| adgroup_cost_top5_total |
** Pixel Stats**
TikTok endpoint documentation:
| Changes | v1.2 | v1.3 |
|---|---|---|
| Columns datatype changes | pixel_id: number | |
| create_time: number | ||
| event_id: number | pixel_id : string | |
| create_time: string | ||
| event_id: string | ||
| Renamed columns + Datatype changes | owned_by: number | owner_bc_id: string |
** App details**
TikTok endpoint documentation:
[Get info of an app](http://Get info of an app).
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | is_skan_allowed | skan_allowed |
| Columns datatype changes | advertiser_id: number | |
| app_id: number | ||
| tiktok_app_id: number | ||
| partner_id: number | advertiser_id : string | |
| app_id: string | ||
| tiktok_app_id: string | ||
| partner_id: string |
** Video Files**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Renamed columns | poster_url | |
| url | video_cover_url | |
| preview_url | ||
| Deprecated Columns | / | id |
** Image files**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Columns datatype changes | advertiser_id: number | advertiser_id: string |
| Deprecated Columns | / | id: string |
| Renamed columns | ||
| url | image_url |
** _Audience Details _**
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Columns datatype changes | audience_id: number | audience_id: string |
| Deprecated Columns | / | id: string |
Auction Ads Report
TikTok endpoint documentation
| Changes | v1.2 | v1.3 |
|---|---|---|
| Columns datatype changes | dimensions_ad_id: number | |
| metrics_campaign_id: number | ||
| metrics_adgroup_id: number | dimensions_ad_id: string | |
| metrics_campaign_id: string | ||
| metrics_adgroup_id: string |
**Please Note: **
- These modifications, as detailed in the aforementioned reports, have been implemented for the column mapping of all Rivers.**
** - If you are currently using deprecated fields/properties - If no action is taken, these deprecated fields/properties will appear as null in the existing report's data. To eliminate them from the Target table, remove these deprecated elements from the Schema mapping.
Deprecated reports
The following reports were deprecated:
- Advertisers Report
- Campaigns Report
- Adgroups Report
- Ads Report
- Campaign Audience Data
- Ad Group Audience Data
- Ad Audience Data
Please Note:
In order to utilize the upgraded Auction Ads Report, it is essential to update your existing Rivers.
Data Integration makes it possible to select deprecated reports from the API version 1.2 by combining the Report Name, Report Type, and Data Level parameters from API version 1.3.
To obtain metrics for the reports you require from version 1.2, y ou must select the right combination, which is shown in the following table:
| V1.2 | V1.3 |
|---|---|
| Report Name | Report Name |
| Advertisers Report |
Auction Ads Report
| Basic| Advertiser
Campaign Report| Basic| Campaign
Ad Group Report| Basic| Ad Group
Ads Report| Basic| Ad
Campaign Audience Data| Audience| Campaign
Ad Group Audience Data| Audience| Ad Group
Ad Audience Data| Audience| Ad
Here is an illustration of how to get the metrics from the API v1.2 Advertisers Report.
Modifications in Datatypes for BigQuery
When dealing with TikTok reports that are being incorporated into BigQuery, we advise adhering to the outlined procedure below to address inconsistencies in data types during the loading process for pre-existing BigQuery tables:
For TikTok reports that are ingested into BigQuery, we recommend following the steps below to resolve data type mismatches in the loading process for existing BigQuery tables:
-
Rename the Target Tables: Within Data Integration, access the failed Rivers, and for the affected tables, modify the names of the destination tables. Once the renaming is complete for all pertinent cases, initiate the data transfer operation. This action will establish a new table within your database, aligning with the updated data types, and encompassing incremental data from the initial point of failure.
-
Merge the Newly Created Tables: Merge your historical data with the newly formed dataset, carry out the following sequence of steps for each newly generated table.
Within your Target database:
Create a Select statement with a casting function to the data types of the modified columns on the historical table, as detailed per the reports mentioned below.
Review the changes related to “Columns datatype changes” per each table, and not the “Renamed columns” in each table.
- Load this historical data into the new table.
- Rename the historical table (recommended as a backup step that could be dropped after confirming the process succeeded).
- Rename the new table to the historical table name.
Within Data Integration:
For each table, change the name of the Target table to match the name of the original (historical) table.
Cast Commands per Report
Advertisers:
CAST (id AS STRING)
Campaigns
CAST (advertiser_id AS STRING),
CAST (campaign_ids AS STRING)
- The following fields should be cast to BOOL according to your existing columns properties:
budget_optimize_on
Ad Groups:
CAST (shop_authorized_bc AS STRING),
CAST (audience AS STRING),
CAST (excluded_audience AS STRING),
CAST (location AS STRING),
CAST (intrested_catagoryv2 AS STRING),
CAST (device_models AS STRING),
CAST (carriers_v2 AS STRING),
CAST (pangle_block_app_list_id AS STRING),
CAST (action_categories AS STRING),
CAST (pangle_audience_package_include AS STRING),
CAST (pangle_audience_package_exclude AS STRING),
CAST (catalog_authorized_bc AS STRING)
- The following fields should be cast to BOOL according to your existing columns properties:
Is_comment_disable, video_download, automated_targeting
Ads:
CAST (advertiser_id AS STRING),
CAST (campaign_id AS STRING),
CAST (adgroup_id AS STRING),
CAST (ad_id AS STRING),
CAST (tiktok_item_id AS STRING),
CAST (card_id AS STRING)
Creative Report:
CAST (related_ads AS STRING),
CAST (related_adgroups AS STRING)
Pixel Stats:
CAST (owned_by AS STRING)
App details
CAST (advertiser_id AS STRING),
CAST (app_id AS STRING),
CAST (tiktok_app_id AS STRING),
CAST (partner_id AS STRING)
Image files
CAST (advertiser_id AS STRING)
Audience Details
CAST (advertiser_id AS STRING)
Auction Ads Report
CAST (dimensions_ad_id AS STRING),
CAST (metrics_campaign_id AS STRING),
CAST (metrics_adgroup_id AS STRING)
