Skip to content

Latest commit

 

History

History
557 lines (524 loc) · 21 KB

tiktok-marketing.md

File metadata and controls

557 lines (524 loc) · 21 KB
Raw

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 Open Source:

  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

Stream Environment Key Incremental
Advertisers Prod,Sandbox id No
AdGroups Prod,Sandbox adgroup_id Yes
Ads Prod,Sandbox ad_id Yes
Campaigns Prod,Sandbox campaign_id Yes
AdsReportsHourly Prod,Sandbox None Yes
AdsReportsDaily Prod,Sandbox None Yes
AdsReportsLifetime Prod,Sandbox None No
AdvertisersReportsHourly Prod None Yes
AdvertisersReportsDaily Prod None Yes
AdvertisersReportsLifetime Prod None No
AdGroupsReportsHourly Prod,Sandbox None Yes
AdGroupsReportsDaily Prod,Sandbox None Yes
AdGroupsReportsLifetime Prod,Sandbox None No
CampaignsReportsHourly Prod,Sandbox None Yes
CampaignsReportsDaily Prod,Sandbox None Yes
CampaignsReportsLifetime Prod,Sandbox None No
AdvertisersAudienceReportsHourly Prod None Yes
AdvertisersAudienceReportsDaily Prod None Yes
AdvertisersAudienceReportsLifetime Prod None No
AdGroupAudienceReportsHourly Prod,Sandbox None Yes
AdGroupAudienceReportsDaily Prod,Sandbox None Yes
AdsAudienceReportsHourly Prod,Sandbox None Yes
AdsAudienceReportsDaily Prod,Sandbox None Yes
CampaignsAudienceReportsByCountryHourly Prod,Sandbox None Yes
CampaignsAudienceReportsByCountryDaily Prod,Sandbox None Yes

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

Version Date Pull Request Subject
0.1.17 2022-10-04 17557 Retry error 50002
0.1.16 2022-09-28 17326 Migrate to per-stream state
0.1.15 2022-08-30 16137 Fixed bug with normalization caused by unsupported nested cursor field
0.1.14 2022-06-29 13890 Removed granularity config option
0.1.13 2022-06-28 13650 Added video metrics to report streams
0.1.12 2022-05-24 13127 Fixed integration test
0.1.11 2022-04-27 12838 Added end date configuration for tiktok
0.1.10 2022-05-07 12545 Removed odd production authenication method
0.1.9 2022-04-30 12500 Improve input configuration copy
0.1.8 2022-04-28 12435 updated spec descriptions
0.1.7 2022-04-27 12380 fixed spec descriptions and documentation
0.1.6 2022-04-19 11378 updated logic for stream initializations, fixed errors in schemas, updated SAT and unit tests
0.1.5 2022-02-17 10398 Add Audience reports
0.1.4 2021-12-30 7636 Add OAuth support
0.1.3 2021-12-10 8425 Update title, description fields in spec
0.1.2 2021-12-02 8292 Support reports
0.1.1 2021-11-08 7499 Remove base-python dependencies
0.1.0 2021-09-18 5887 Release TikTok Marketing CDK Connector