2023-08 Tiktok API Upgrade 1.3
  • 4 Minutes to read
  • Dark
    Light
  • PDF

2023-08 Tiktok API Upgrade 1.3

  • Dark
    Light
  • PDF

Article summary

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?

1. 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.

2. The boolean type fields now exclusively use "True" and "False" instead of "1" and "0" or "Yes" and "No". 

3. 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 Columnscategory: string
interest_category: string
action_category_ids: string
action_days: string
video_actions: string
/


Ads:

TikTok endpoint documentation 

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:

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 documentation:

Get the app list

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
urlimage_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.


Rivery makes it possible to select deprecated reports from the API version 1.2 by combining the Report Name, Report Type, and Data Level parametersfrom API version 1.3.

To obtain metrics for the reports you require from version 1.2, you must select the right combination, which is shown in the following table:

V1.2 V1.3 
Report NameReport NameReport TypeData Level
Advertisers Report 




Auction Ads Report






BasicAdvertiser
CampaignReportBasicCampaign
Ad GroupReportBasicAd Group
Ads ReportBasicAd
Campaign Audience DataAudienceCampaign
Ad Group Audience DataAudienceAd Group
Ad Audience DataAudienceAd

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:

1.  Rename the Target Tables: Within Rivery, 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.

2. 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: Please 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 Rivery: 

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)





Was this article helpful?