2023-08 Tiktok API upgrade 1.3

Introduction

This topic outlines the process of upgrading to Tiktok API version 1.3, which involves making necessary modifications to the existing Tiktok Data Flows.

Changes made during the upgrade

In version 1.3, the API converts all ID fields that were formerly categorized as INTEGER types in version 1.2 to STRING types. These alterations in data types might require changes to the data types of your Target tables.
The boolean type fields now 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

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

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

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_action`s
`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

TikTok endpoint

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

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:

Get pixels

Get Pixel Event statistics.

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:

Get the app list

[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

Changes	v1.2	v1.3
Renamed columns	`poster_url`
`url`	`video_cover_url`
`preview_url`
Deprecated Columns	/	id

Image files
Tiktok endpoint

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

Changes	v1.2	v1.3
Columns datatype changes	`audience_id:` number	`audience_id`: string
Deprecated Columns	/	id: string

Auction Ads Report

Tiktok endpoint

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

note

Data Integration applies these modifications, as detailed in the mentioned reports, to the column mapping of all Data Flow.
If you are currently using deprecated fields/properties - If you do not take any action, these deprecated fields/properties will appear as null in the existing report's data. To remove them from the Target table, remove these deprecated elements from the Schema mapping.

Deprecated reports

The upgrade deprecated the following reports:

Advertisers Report
Campaigns Report
Ad groups Report
Ads Report
Campaign Audience Data
Ad Group Audience Data
Ad Audience Data

note

To use the upgraded Auction Ads Report, it is essential to update your existing Data Flow.

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 get metrics for the reports you require from version 1.2, select the appropriate combination shown in the table below:

V1.2 Report Name	V1.3 Report Type	Data Level
Advertisers Report	Basic	Advertiser
Auction Ads Report	Basic	Ad
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

Modifications in Datatypes for BigQuery

When you load Tiktok reports into BigQuery, follow the outlined procedure to address inconsistencies in data types during the loading process for pre-existing BigQuery tables:

For Tiktok reports that you ingest into BigQuery, follow 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 Data Flow, and for the affected tables, modify the names of the destination tables. Once the renaming is complete for all pertinent cases, start 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.

note

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 you can drop 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 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 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)