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?

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 

Campaigns:
TikTok endpoint documentation 

Ad Groups:
TikTok endpoint documentation

Ads:

TikTok endpoint documentation 

Creative Report 
TikTok endpoint documentation 

Pixel Stats
TikTok endpoint documentation:

Get pixels

Get Pixel Event statistics.

App details
TikTok endpoint documentation:

Get the app list

Get info of an app.

Video Files
TikTok endpoint documentation 

Image files
TikTok endpoint documentation 

Audience Details 
TikTok endpoint documentation 

Auction Ads Report

TikTok endpoint documentation

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:

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)