Skip to main content

TikTok Marketing

This page guides you through the process of setting up the TikTok Marketing source connector.

Prerequisites (Airbyte Cloud)

  • A Tiktok Ads Business account with permission to access data from accounts you want to sync

Prerequisites (Airbyte Open Source)

For the Production environment:

  • Access token
  • Secret
  • App ID

To access the Sandbox environment:

  • Access token
  • Advertiser ID

Step 1: Set up TikTok

  1. Create a TikTok For Business account: Link
  2. (Open source only) Create developer application: Link
  3. (Open source only) For a sandbox environment: create a Sandbox Ad Account Link

Step 2: Set up the source connector in Airbyte

For Airbyte Cloud:

  1. Log into your Airbyte Cloud account.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the source setup page, select Tiktok Marketing from the Source type dropdown and enter a name for this connector.
  4. Select OAuth2.0 Authorization method, then click Authenticate your account.
  5. Log in and Authorize to the Tiktok account
  6. Choose required Start date
  7. click Set up source.

For Airbyte OSS:

  1. Go to local Airbyte page.
  2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
  3. On the Set up the source page, enter the name for the connector and select Tiktok Marketing from the Source type dropdown.
  4. Select Production Access Token or Sandbox Access Token Authorization method, then copy and paste info from step 1.
  5. Choose required Start date
  6. Click Set up source.

Supported streams and sync modes

StreamEnvironmentKeyIncremental
AdvertisersProd,SandboxidNo
AdGroupsProd,Sandboxadgroup_idYes
AdsProd,Sandboxad_idYes
CampaignsProd,Sandboxcampaign_idYes
AdsReportsHourlyProd,SandboxNoneYes
AdsReportsDailyProd,SandboxNoneYes
AdsReportsLifetimeProd,SandboxNoneNo
AdvertisersReportsHourlyProdNoneYes
AdvertisersReportsDailyProdNoneYes
AdvertisersReportsLifetimeProdNoneNo
AdGroupsReportsHourlyProd,SandboxNoneYes
AdGroupsReportsDailyProd,SandboxNoneYes
AdGroupsReportsLifetimeProd,SandboxNoneNo
CampaignsReportsHourlyProd,SandboxNoneYes
CampaignsReportsDailyProd,SandboxNoneYes
CampaignsReportsLifetimeProd,SandboxNoneNo
AdvertisersAudienceReportsHourlyProdNoneYes
AdvertisersAudienceReportsDailyProdNoneYes
AdvertisersAudienceReportsLifetimeProdNoneNo
AdGroupAudienceReportsHourlyProd,SandboxNoneYes
AdGroupAudienceReportsDailyProd,SandboxNoneYes
AdsAudienceReportsHourlyProd,SandboxNoneYes
AdsAudienceReportsDailyProd,SandboxNoneYes
CampaignsAudienceReportsByCountryHourlyProd,SandboxNoneYes
CampaignsAudienceReportsByCountryDailyProd,SandboxNoneYes

Report Aggregation

Reports synced by this connector can use either hourly, daily, or lifetime granularities for aggregating performance data. For example, if you select the daily-aggregation flavor of a report, the report will contain a row for each day for the duration of the report. Each row will indicate the number of impressions recorded on that day.

Output Schemas

Advertisers Stream

{
"contacter": "Ai***te",
"phonenumber": "+13*****5753",
"license_no": "",
"promotion_center_city": null,
"balance": 10,
"license_url": null,
"timezone": "Etc/GMT+8",
"reason": "",
"telephone": "+14*****6785",
"id": 7002238017842757633,
"language": "en",
"country": "US",
"role": "ROLE_ADVERTISER",
"license_province": null,
"display_timezone": "America/Los_Angeles",
"email": "i***************@**********",
"license_city": null,
"industry": "291905",
"create_time": 1630335591,
"promotion_center_province": null,
"address": "350 29th avenue, San Francisco",
"currency": "USD",
"promotion_area": "0",
"status": "STATUS_ENABLE",
"description": "https://",
"brand": null,
"name": "Airbyte0830",
"company": "Airbyte"
}

AdGroups Stream

{
"placement_type": "PLACEMENT_TYPE_AUTOMATIC",
"budget": 20,
"budget_mode": "BUDGET_MODE_DAY",
"display_mode": null,
"schedule_infos": null,
"billing_event": "CPC",
"conversion_window": null,
"adgroup_name": "Ad Group20211020010107",
"interest_keywords": [],
"is_comment_disable": 0,
"rf_buy_type": null,
"frequency": null,
"bid_type": "BID_TYPE_NO_BID",
"placement": null,
"bid": 0,
"include_custom_actions": [],
"operation_system": [],
"pixel_id": null,
"dayparting": "111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111",
"app_type": null,
"conversion_id": 0,
"rf_predict_cpr": null,
"deep_bid_type": null,
"scheduled_budget": 0.0,
"adgroup_id": 1714125049901106,
"frequency_schedule": null,
"exclude_custom_actions": [],
"advertiser_id": 7002238017842757633,
"deep_cpabid": 0,
"is_new_structure": true,
"buy_impression": null,
"external_type": "WEBSITE",
"excluded_audience": [],
"deep_external_action": null,
"interest_category_v2": [],
"rf_predict_frequency": null,
"audience": [],
"pacing": "PACING_MODE_SMOOTH",
"brand_safety_partner": null,
"daily_retention_ratio": null,
"optimize_goal": "CLICK",
"enable_search_result": false,
"conversion_bid": 0,
"schedule_end_time": "2021-10-31 09:01:07",
"opt_status": "ENABLE",
"status": "ADGROUP_STATUS_CAMPAIGN_DISABLE",
"app_id": null,
"external_action": null,
"schedule_type": "SCHEDULE_START_END",
"brand_safety": "NO_BRAND_SAFETY",
"campaign_id": 1714125042508817,
"campaign_name": "Website Traffic20211020010104",
"split_test_adgroup_ids": [],
"action_v2": [],
"is_hfss": false,
"keywords": null,
"create_time": "2021-10-20 08:04:05",
"feed_type": null,
"languages": ["en"],
"enable_inventory_filter": false,
"device_price": [],
"location": [6252001],
"schedule_start_time": "2021-10-20 09:01:07",
"skip_learning_phase": 0,
"gender": "GENDER_UNLIMITED",
"creative_material_mode": "CUSTOM",
"app_download_url": null,
"device_models": [],
"automated_targeting": "OFF",
"connection_type": [],
"ios14_quota_type": "UNOCCUPIED",
"modify_time": "2022-03-24 12:06:54",
"category": 0,
"statistic_type": null,
"video_download": "ALLOW_DOWNLOAD",
"age": ["AGE_25_34", "AGE_35_44", "AGE_45_54"],
"buy_reach": null,
"is_share_disable": false
}

Ads Stream

{
"vast_moat": false,
"is_new_structure": true,
"campaign_name": "CampaignVadimTraffic",
"landing_page_urls": null,
"card_id": null,
"adgroup_id": 1728545385226289,
"campaign_id": 1728545382536225,
"status": "AD_STATUS_CAMPAIGN_DISABLE",
"brand_safety_postbid_partner": "UNSET",
"advertiser_id": 7002238017842757633,
"is_aco": false,
"ad_text": "Open-source\ndata integration for modern data teams",
"identity_id": "7080121820963422209",
"display_name": "airbyte",
"open_url": "",
"external_action": null,
"playable_url": "",
"create_time": "2022-03-28 12:09:09",
"product_ids": [],
"adgroup_name": "AdGroupVadim",
"fallback_type": "UNSET",
"creative_type": null,
"ad_name": "AdVadim-Optimized Version 3_202203281449_2022-03-28 05:03:44",
"video_id": "v10033g50000c90q1d3c77ub6e96fvo0",
"ad_format": "SINGLE_VIDEO",
"profile_image": "https://p21-ad-sg.ibyteimg.com/large/ad-site-i18n-sg/202203285d0de5c114d0690a462bb6a4",
"open_url_type": "NORMAL",
"click_tracking_url": null,
"page_id": null,
"ad_texts": null,
"landing_page_url": "https://airbyte.com",
"identity_type": "CUSTOMIZED_USER",
"avatar_icon_web_uri": "ad-site-i18n-sg/202203285d0de5c114d0690a462bb6a4",
"app_name": "",
"modify_time": "2022-03-28 21:34:26",
"opt_status": "ENABLE",
"call_to_action_id": "7080120957230238722",
"image_ids": ["v0201/7f371ff6f0764f8b8ef4f37d7b980d50"],
"ad_id": 1728545390695442,
"impression_tracking_url": null,
"is_creative_authorized": false
}

Campaigns Stream

{
"create_time": "2021-10-19 18:18:08",
"campaign_id": 1714073078669329,
"roas_bid": 0.0,
"advertiser_id": 7002238017842757633,
"modify_time": "2022-03-28 12:01:56",
"campaign_type": "REGULAR_CAMPAIGN",
"status": "CAMPAIGN_STATUS_DISABLE",
"objective_type": "TRAFFIC",
"split_test_variable": null,
"opt_status": "DISABLE",
"budget": 50,
"is_new_structure": true,
"deep_bid_type": null,
"campaign_name": "Website Traffic20211019110444",
"budget_mode": "BUDGET_MODE_DAY",
"objective": "LANDING_PAGE"
}

AdsReportsDaily Stream - BasicReports

{
"dimensions": {
"ad_id": 1728545390695442,
"stat_time_day": "2022-03-29 00:00:00"
},
"metrics": {
"real_time_result_rate": 0.93,
"campaign_id": 1728545382536225,
"placement": "Automatic Placement",
"frequency": 1.17,
"cpc": 0.35,
"ctr": 0.93,
"cost_per_result": 0.3509,
"impressions": 6137,
"cost_per_conversion": 0,
"real_time_result": 57,
"adgroup_id": 1728545385226289,
"result_rate": 0.93,
"cost_per_1000_reached": 3.801,
"ad_text": "Open-source\ndata integration for modern data teams",
"spend": 20,
"conversion_rate": 0,
"real_time_cost_per_conversion": 0,
"promotion_type": "Website",
"tt_app_id": 0,
"real_time_cost_per_result": 0.3509,
"conversion": 0,
"secondary_goal_result": null,
"campaign_name": "CampaignVadimTraffic",
"cpm": 3.26,
"result": 57,
"ad_name": "AdVadim-Optimized Version 3_202203281449_2022-03-28 05:03:44",
"secondary_goal_result_rate": null,
"clicks": 57,
"reach": 5262,
"cost_per_secondary_goal_result": null,
"real_time_conversion": 0,
"real_time_conversion_rate": 0,
"mobile_app_id": "0",
"tt_app_name": "0",
"adgroup_name": "AdGroupVadim",
"dpa_target_audience_type": null
}
}

AdvertisersReportsDaily Stream - BasicReports

{
"metrics": {
"cpm": 5.43,
"impressions": 3682,
"frequency": 1.17,
"reach": 3156,
"cash_spend": 20,
"ctr": 1.14,
"spend": 20,
"cpc": 0.48,
"cost_per_1000_reached": 6.337,
"clicks": 42,
"voucher_spend": 0
},
"dimensions": {
"stat_time_day": "2022-03-30 00:00:00",
"advertiser_id": 7002238017842757633
}
}

AdGroupsReportsDaily Stream - BasicReports

{
"metrics": {
"real_time_conversion": 0,
"real_time_cost_per_conversion": 0,
"cost_per_1000_reached": 3.801,
"mobile_app_id": "0",
"reach": 5262,
"cpm": 3.26,
"conversion": 0,
"promotion_type": "Website",
"clicks": 57,
"real_time_result_rate": 0.93,
"real_time_conversion_rate": 0,
"cost_per_conversion": 0,
"dpa_target_audience_type": null,
"result": 57,
"cpc": 0.35,
"impressions": 6137,
"cost_per_result": 0.3509,
"tt_app_id": 0,
"cost_per_secondary_goal_result": null,
"frequency": 1.17,
"spend": 20,
"secondary_goal_result_rate": null,
"real_time_cost_per_result": 0.3509,
"real_time_result": 57,
"placement": "Automatic Placement",
"result_rate": 0.93,
"tt_app_name": "0",
"campaign_name": "CampaignVadimTraffic",
"secondary_goal_result": null,
"campaign_id": 1728545382536225,
"conversion_rate": 0,
"ctr": 0.93,
"adgroup_name": "AdGroupVadim"
},
"dimensions": {
"adgroup_id": 1728545385226289,
"stat_time_day": "2022-03-29 00:00:00"
}
}

CampaignsReportsDaily Stream - BasicReports

{
"metrics": {
"cpc": 0.43,
"spend": 20,
"clicks": 46,
"cost_per_1000_reached": 4.002,
"impressions": 5870,
"ctr": 0.78,
"frequency": 1.17,
"cpm": 3.41,
"campaign_name": "CampaignVadimTraffic",
"reach": 4997
},
"dimensions": {
"campaign_id": 1728545382536225,
"stat_time_day": "2022-03-28 00:00:00"
}
}

AdsAudienceReportsDaily Stream - AudienceReports

{ 
{
"result": 17,
"clicks": 17,
"real_time_conversion_rate": 0,
"adgroup_id": 1728545385226289,
"cpm": 3.01,
"cost_per_result": 0.4165,
"real_time_cost_per_result": 0.4165,
"mobile_app_id": 0,
"spend": 7.08,
"cpc": 0.42,
"placement": "Automatic Placement",
"real_time_conversion": 0,
"dpa_target_audience_type": null,
"real_time_result_rate": 0.72,
"adgroup_name": "AdGroupVadim",
"tt_app_id": 0,
"ctr": 0.72,
"ad_text": "Open-source\ndata integration for modern data teams",
"result_rate": 0.72,
"ad_name": "AdVadim-Optimized Version 3_202203281449_2022-03-28 05:03:44",
"conversion_rate": 0,
"real_time_result": 17,
"tt_app_name": "0",
"cost_per_conversion": 0,
"real_time_cost_per_conversion": 0,
"conversion": 0,
"impressions": 2350,
"promotion_type": "Website",
"campaign_id": 1728545382536225,
"campaign_name": "CampaignVadimTraffic"
},
"dimensions": {
"gender": "MALE",
"age": "AGE_25_34",
"ad_id": 1728545390695442,
"stat_time_day": "2022-03-28 00:00:00"
}
}

AdvertisersAudienceReportsDaily Stream - AudienceReports

{
"dimensions": {
"stat_time_day": "2022-03-28 00:00:00",
"gender": "FEMALE",
"advertiser_id": 7002238017842757633,
"age": "AGE_35_44"
},
"metrics": {
"spend": 3.09,
"ctr": 0.93,
"cpc": 0.44,
"clicks": 7,
"cpm": 4.11,
"impressions": 752
}
}

AdGroupAudienceReportsDaily Stream - AudienceReports

{
"dimensions": {
"gender": "MALE",
"age": "AGE_25_34",
"stat_time_day": "2022-03-29 00:00:00",
"adgroup_id": 1728545385226289
},
"metrics": {
"cost_per_conversion": 0,
"campaign_id": 1728545382536225,
"campaign_name": "CampaignVadimTraffic",
"clicks": 20,
"dpa_target_audience_type": null,
"mobile_app_id": 0,
"promotion_type": "Website",
"conversion_rate": 0,
"cpm": 3.9,
"cost_per_result": 0.3525,
"cpc": 0.35,
"real_time_cost_per_conversion": 0,
"ctr": 1.11,
"spend": 7.05,
"result": 20,
"real_time_result": 20,
"impressions": 1806,
"conversion": 0,
"real_time_result_rate": 1.11,
"real_time_conversion_rate": 0,
"real_time_conversion": 0,
"adgroup_name": "AdGroupVadim",
"tt_app_name": "0",
"placement": "Automatic Placement",
"real_time_cost_per_result": 0.3525,
"result_rate": 1.11,
"tt_app_id": 0
}
}

CampaignsAudienceReportsByCountryDaily Stream - AudienceReports

{
"metrics": {
"impressions": 5870,
"campaign_name": "CampaignVadimTraffic",
"cpm": 3.41,
"clicks": 46,
"spend": 20,
"ctr": 0.78,
"cpc": 0.43
},
"dimensions": {
"stat_time_day": "2022-03-28 00:00:00",
"campaign_id": 1728545382536225,
"country_code": "US"
}
}

Performance considerations

The connector is restricted by requests limitation. This connector should not run into TikTok Marketing API limitations under normal usage. Please create an issue if you see any rate limit issues that are not automatically retried successfully.

Changelog

VersionDatePull RequestSubject
0.1.142022-06-2913890Removed granularity config option
0.1.132022-06-2813650Added video metrics to report streams
0.1.122022-05-2413127Fixed integration test
0.1.112022-04-2712838Added end date configuration for tiktok
0.1.102022-05-0712545Removed odd production authenication method
0.1.92022-04-3012500Improve input configuration copy
0.1.82022-04-2812435updated spec descriptions
0.1.72022-04-2712380fixed spec descriptions and documentation
0.1.62022-04-1911378updated logic for stream initializations, fixed errors in schemas, updated SAT and unit tests
0.1.52022-02-1710398Add Audience reports
0.1.42021-12-307636Add OAuth support
0.1.32021-12-108425Update title, description fields in spec
0.1.22021-12-028292Support reports
0.1.12021-11-087499Remove base-python dependencies
0.1.02021-09-185887Release TikTok Marketing CDK Connector