TikTok Ads

TikTok Ads allows marketers to retrieve statistics about their ad account, ads, ad sets, and campaigns running on TikTok. Each ad account can contain one or more campaigns, which are mainly used for setting an objective and configuring a corresponding budget. Within each campaign, you can create multiple ad groups to configure settings like target audience, placements, budget, and schedule, and create ads within each group. The Ad object contains the details needed for displaying an ad, such as the format of the ad, or its creative content.

The following image illustrates the typical campaign structure in TikTok Ads:

Hevo uses the TikTok Marketing API to replicate your TikTok Ads data into the desired Destination database or data warehouses for scalable analysis. For this, you must authorize Hevo to access data from your TikTok Ads account.

Note: TikTok’s authentication system uses pop-ups. Therefore, you must disable ad and pop-up blockers in your internet browser to avoid issues during the Source setup.

If you reside in a country which has blocked TikTok, for example India, you need to use a VPN to connect to your TikTok Ads account and create the Pipeline. Alternatively, set up your Hevo account in any of the following instances: US, EU, or AU. Refer to Selecting your Hevo Region for the instance URLs.

---

Prerequisites

• An active TikTok Ads Manager account with permissions to access data from the ad accounts you want to sync.

• You are connected via a VPN, if the country you are in has blocked TikTok.

---

Configuring TikTok Ads as a Source

Perform the following steps to configure TikTok Ads as the Source in your Pipeline:

1. Click PIPELINES in the Asset Palette.

2. Click + CREATE in the Pipelines List View.

3. In the Select Source Type page, select TikTok Ads.

4. In the Configure your TikTok Ads page, click + ADD TIKTOK ADS ACCOUNT.

   

5. Log in to your TikTok Ads account using your phone number or email ID.

   

6. Click Confirm to authorize Hevo to access your TikTok Ads account and related statistics.
   Note: The permissions that Hevo needs to successfully ingest data are auto-selected.

   

7. In the Configure your TikTok Ads Source page, specify the following:

   

   • Pipeline Name: A unique name for the Pipeline, not exceeding 255 characters.

   • Ad Accounts: The TikTok Ad account(s) from which you want to fetch the data.

   • Historical Sync Duration: The duration for which the existing data in the Source must be ingested. Default duration: 1 Year.

8. Click TEST & CONTINUE.

9. Proceed to configuring the data ingestion and setting up the Destination.

Note: If you own or have access to multiple ad accounts, Hevo can access all those ad accounts and create tables with account IDs appended to the object and report type.

---

Data Replication

Default Pipeline Frequency	Minimum Pipeline Frequency	Maximum Pipeline Frequency	Custom Frequency Range (Hrs)
3 Hrs	1 Hr	24 Hrs	1-48

Note: The custom frequency must be set in hours, as an integer value. For example, 1, 2, 3 but not 1.5 or 1.75.

• Historical Data: In the first run of the Pipeline, Hevo fetches the data of all the objects and reports available in your account up till the current date, and loads it to the Destination.

• Incremental Data: All new and updated records are synchronized with your Destination. For core entities (objects), Hevo performs a full load to capture any data changes. For reports, Hevo incrementally fetches data as per the Pipeline frequency that you select.

• Refresher Data: Hevo performs a full load for the core entities (objects) every time your Pipeline runs, which means that the entire data in the object is refreshed/replicated on each ingestion. In case of reports, Hevo refreshes the data once every 24 hours. Data refresh is required to capture any attribution data and updates made to the data since the last incremental load.

Handling of updates

The status of all fields that are updated in the Destination during replication is changed to STATUS_UPDATE.

Handling of deletes

All fields deleted in the Source are ingested with the status, STATUS_DELETE. When the Events are loaded to the Destination tables, the status of the respective fields is accordingly updated.

Note: For both deletes and updates, the MODIFY_TIME field is updated to the time of the most recent change.

---

Source Considerations

• Country-specific availability: TikTok has been removed by Internet Service Providers (ISPs) in a few countries. If your Hevo account is in any of these countries, you will not be able to create Pipelines. Use a VPN to side-step this issue. Alternatively, set up your Hevo account in any of the following instances: US, EU, or AU. Refer to Selecting your Hevo Region for the instance URLs.

• Maturity of the API : The TikTok Marketing API is still under active development and has not reached a stable state. As a result, attribution functionalities and API rate limits are prohibitive and Hevo adheres to these while running your Pipelines.

• Attributions: For TikTok App Marketers, it is recommended to use a Mobile Measurement Partner (MMP) to track conversions from your TikTok app campaigns till other solutions, such as server-to-server and SDK, mature and can handle different attribution windows. For now, Hevo only supports a click attribution window of 7 days and a view attribution window of 1 day.

---

Schema and Primary Keys

Hevo uses the following schema to upload the records in the Destination database:

---

Data Model

You can replicate object and report data from your TikTok Ads account.

Objects

Objects are the core entities of TikTok Ads. The following is the list of tables (objects) that are created at the Destination when you run the Pipeline:

Object	Description
Advertisers	Contains information about the advertiser account.
Campaign	Contains information about campaigns.
Ad Group	Contains information about ad groups existing in the campaigns.
Ad	Contains information about ads running as part of each ad group.

Reports

Reports are objects that contain data related to the metrics and statistics of the core entities. These can be generated at two levels of time granularity: Daily and Hourly. Reports are generated for the following objects:

• Ads

• Ad Groups

• Campaigns

You can also generate reports based on the parameters, Country, Language, Age Gender, and Platform, as described in the table below.

REPORT NAME	DESCRIPTION
Ad_Age_Gender_Report	The report on the Ad object, grouped by Age Gender.
Ad_Country_Report	The report on the Ad object, grouped by Country.
Ad_Daily_Report	The report on the Ad object, grouped daily.
Ad_Hourly_Report	The report on the Ad object, grouped hourly.
Ad_Language_Report	The report on the Ad object, grouped by Language.
Ad_Platform_Report.	The report on the Ad object, grouped by Platform.
Ad_Reservation_Daily_Report	The report on the Ad object, grouped daily. Captures reserved ads information.
Ad_Reservation_Hourly_Report	The report on the Ad object, grouped hourly. Captures reserved ads information.
AdGroup_Daily_Report	The report on the Ad Group object, grouped daily.
AdGroup_Hourly_Report	The report on the Ad Group object, grouped hourly.
AdGroup_Reservation_Daily_Report	The report on the Ad Group object, grouped daily. Captures reserved ad groups information.
AdGroup_Reservation_Hourly_Report	The report on the Ad Group object, grouped hourly Captures reserved ad groups information.
Campaign_Age_Gender_Report	The report on the Campaign object, grouped by Age Gender.
Campaign_Country_Report	The report on the Campaign object, grouped by Country.
Campaign_Daily_Report	The report on the Campaign object, grouped daily.
Campaign_Hourly_Report	The report on the Campaign object, grouped hourly.
Campaign_Language_Report	The report on the Campaign object, grouped by Language.
Campaign_Platform_Report	The report on the Campaign object, grouped by Platform.
Campaign_Reservation_Daily_Report	The report on the Campaign object, grouped daily.Captures reserved ads information.
Campaign_Reservation_Hourly_Report	The report on the Campaign object, grouped hourly. Captures reserved ads information.

Refer to the Schema and Primary Keys section for more details.

Note: Reservation Ads reporting is currently in Beta. Read Reservation ads reports for more information.

Limitations

None.

---

Revision History