TikTok Ads Integration for Nodus
1. Introduction to the TikTok Ads Integration
What Is This Integration?
The TikTok Ads integration connects your TikTok advertising platform data with Nodus, allowing you to extract, analyze, and transform campaign performance metrics, ad creative insights, and audience targeting information. This integration functions as a source connector, bringing your TikTok Ads data into the Nodus ecosystem for advanced analytics and business intelligence.
Prerequisites:
- An active TikTok Ads Business account
- TikTok Advertiser ID for the accounts you want to connect
- Authorization via TikTok Single Sign-On (SSO)
- Appropriate permissions to access advertising data
Connection Overview:
The integration uses TikTok's Marketing API to extract advertising data and performance metrics. Authentication is handled through OAuth 2.0, and the connector extracts data based on predefined templates that specify which datasets to retrieve.
2. Platform Setup Documentation (Setup Form for TikTok Ads)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and TikTok Ads by providing the necessary authentication credentials and account details.
Field-by-Field Breakdown:
Integration Name
- Field Name & Label: Integration Name
- Description & Purpose: A descriptive name to identify this TikTok Ads integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "TikTok Ads - Main Account", "TikTok Marketing - Brand X"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific TikTok Ads account or purpose.
TikTok Advertiser ID
- Field Name & Label: TikTok Advertiser ID
- Description & Purpose: The unique identifier for your TikTok Ads account, used to access campaign data.
- Validation Rules & Format: Numeric string, required field.
- Examples: "7012345678901234567"
- Troubleshooting Tips: You can find your Advertiser ID in the TikTok Ads Manager dashboard. Navigate to the top-right corner of your dashboard and click on your account name to see your Advertiser ID.
External Link
- Link Label: "Locate Your Advertiser ID"
- URL: https://ads.tiktok.com/help/article/account-setup-faq
- Purpose: Helps users locate their TikTok Advertiser ID in the TikTok Ads Manager interface.
Step-by-Step Guide:
- Log in to TikTok Ads Manager
- Navigate to the top-right corner and click on your account name to locate your Advertiser ID
- Enter your Advertiser ID and a meaningful Integration Name in the Nodus setup form
- Click Authorize to launch the TikTok SSO authorization flow
- Grant permissions when prompted by TikTok
- Verify connection and save the configuration
Reference Links:
3. Extraction/Query Configuration (Extraction Form for TikTok Ads)
Purpose & Overview
This section explains how to configure data extraction from TikTok Ads. The platform offers various templates for extracting different types of advertising data and analytics.
Template & Field Documentation:
Template Selection
- Field Name & Label: Select a template
- Description & Purpose: Defines which type of TikTok Ads data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- TikTok Ad Groups - Ad group configuration and targeting information
- TikTok Ads - Individual ad creative and delivery settings
- TikTok Ads Marketing Metadata - Additional metadata about ads including objectives and targeting
- TikTok Audience - Audience targeting and demographic data
- TikTok Basic Report - Core performance metrics for all campaign elements
- TikTok Campaigns - Campaign-level data including budgets, scheduling, and status
- TikTok Source Of Truth Table - Combined dataset with key account metrics and structure
Lookback Range
- Field Name & Label: Lookback Range
- Description & Purpose: Specifies how many days back to extract data
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- 3-day Range
- 7-day Range
- 28-day Range (recommended)
- 90-day Range (Optimal if 90-day DDA is used)
- Troubleshooting Tips: Due to TikTok's data attribution window, we recommend at least a 7-day lookback to ensure all conversion data is captured.
Historic Date Selection
- Field Name & Label: Historic Date
- Description & Purpose: For historical data extraction, specifies a custom date range
- Validation Rules & Format: Date picker, required field
- Troubleshooting Tips: TikTok maintains historical data, but very old data may have limitations.
Workflow & Examples:
- Select the appropriate template (e.g., "TikTok Basic Report" for performance metrics)
- Choose a lookback period or specific historic date range
- Preview the query to confirm configuration
- Execute extraction
Example Use Cases:
Campaign Performance Analysis:
- Template: TikTok Basic Report
- Metrics: Impressions, clicks, spend, conversions
- Lookback: 28-day Range
Creative Performance Analysis:
- Template: TikTok Ads
- Metrics: Creative details with performance metrics
- Lookback: 28-day Range
Audience Analysis:
- Template: TikTok Audience
- Data: Demographic and targeting data
- Historic Date: Custom range for specific campaign periods
Data Mapping & Underlying Models for TikTok Ads
Data Model Overview
The TikTok Ads API returns structured data based on the selected template. Each template corresponds to specific API endpoints and data structures within the TikTok Marketing API.
Schema & Field Mapping
TikTok Ads Schema
| Field | Description |
|---|---|
| advertiser_id | The advertiser account identifier |
| campaign_id | The parent campaign identifier |
| adgroup_id | The parent ad group identifier |
| ad_id | The unique identifier of the ad |
| operation_status | The operational status of the ad |
| dynamic_destination | Destination type for dynamic ads |
| secondary_status | Secondary status information |
| call_to_action | Call-to-action text displayed on the ad |
| call_to_action_id | Identifier for the call-to-action |
| is_aco | Whether this is an Automated Creative Optimization ad |
| ad_format | The format of the ad (image, video, etc.) |
| ad_text | The text content of the ad |
| ad_texts | Multiple text variations for the ad |
| image_ids | JSON list of image identifiers used in the ad |
| video_id | Identifier for the video used in the ad |
| tiktok_item_id | TikTok item identifier |
| music_id | Identifier for music used in the ad |
| creative_type | Type of creative used |
| landing_page_url | URL where users are directed after clicking |
| utm_params | JSON object containing UTM tracking parameters |
| display_name | Display name shown on the ad |
| click_tracking_url | URL used for click tracking |
| deeplink | Deep link URL for mobile apps |
| deeplink_type | Type of deep linking used |
| catalog_id | Product catalog identifier |
| item_group_ids | JSON list of item group identifiers |
| product_set_id | Product set identifier |
| sku_ids | JSON list of SKU identifiers |
| dynamic_format | Format for dynamic ads |
TikTok Ads Metadata Schema
| Field | Description |
|---|---|
| campaign_id | The parent campaign identifier |
| adgroup_id | The parent ad group identifier |
| ad_id | The unique identifier of the ad |
| landing_page_url | URL where users are directed after clicking |
TikTok Ad Groups Schema
| Field | Description |
|---|---|
| adgroup_id | The unique identifier of the ad group |
| placements | JSON list of ad placements |
| promotion_type | Type of promotion |
| promotion_website_type | Website promotion type |
| shopping_ads_type | Type of shopping ads |
| product_source | Source of products for shopping ads |
| shopping_ads_retargeting_type | Retargeting type for shopping ads |
| store_id | Store identifier |
| identity_id | Identity identifier |
| app_download_url | App download URL for app promotion |
| optimization_goal | Primary optimization goal |
| optimization_event | Event optimized for |
| secondary_optimization_event | Secondary event optimized for |
| creative_material_mode | Creative material mode |
| audience_ids | JSON list of audience identifiers |
| excluded_audience_ids | JSON list of excluded audience identifiers |
| audience_type | Type of audience targeting |
| location_ids | JSON list of location identifiers |
| interest_category_ids | JSON list of interest category identifiers |
| interest_keyword_ids | JSON list of interest keyword identifiers |
| age_groups | JSON list of targeted age groups |
| gender | Targeted gender |
| languages | JSON list of targeted languages |
| operating_systems | JSON list of targeted operating systems |
| network_types | JSON list of targeted network types |
| device_price_ranges | JSON list of targeted device price ranges |
| device_model_ids | JSON list of targeted device models |
| household_income | JSON object with household income targeting |
| spending_power | Targeted spending power |
| purchase_intention_keyword_ids | JSON list of purchase intention keywords |
| contextual_tag_ids | JSON list of contextual tag identifiers |
| budget_mode | Budget mode (daily or lifetime) |
| budget | Budget amount |
| schedule_type | Type of ad scheduling |
| pacing | Pacing strategy for budget delivery |
| bid_type | Type of bidding (CPC, CPM, etc.) |
| bid_price | Bid amount |
| roas_bid | Return on ad spend bid |
| conversion_bid_price | Bid price for conversions |
| deep_bid_type | Deep bidding type |
| deep_cpa_bid | Deep cost-per-acquisition bid |
| operation_status | Operational status of the ad group |
| frequency | Frequency cap for ad delivery |
| catalog_id | Product catalog identifier |
| product_set_id | Product set identifier |
| brand_safety_type | Brand safety settings type |
| feed_type | Type of feed |
| is_smart_performance_campaign | Whether this is a smart performance campaign |
TikTok Audience Schema
| Field | Description |
|---|---|
| audience_id | The unique identifier of the audience |
| shared | Whether the audience is shared |
| is_creator | Whether the user is the creator of this audience |
| cover_num | Coverage number |
| create_time | Time when the audience was created |
| is_valid | Whether the audience is valid |
| is_expiring | Whether the audience is expiring |
| expired_time | Time when the audience will expire |
| name | Name of the audience |
| audience_type | Type of audience |
| calculate_type | Calculation type for the audience |
TikTok Basic Report Schema
| Field | Description |
|---|---|
| ad_id | The unique identifier of the ad |
| stat_time_day | Date for the metrics |
| placement_type | Type of ad placement |
| real_time_cost_per_conversion | Real-time cost per conversion |
| adgroup_id | The ad group identifier |
| reach | Number of unique users who saw the ad |
| dpa_target_audience_type | Dynamic product ads target audience type |
| tt_app_id | TikTok app identifier |
| secondary_goal_result | Results for secondary goal |
| frequency | Average number of times users saw the ad |
| result | Primary campaign result metric |
| campaign_name | Name of the campaign |
| cost_per_result | Cost per result |
| real_time_result | Real-time results |
| cpc | Cost per click |
| spend | Amount spent on the ad |
| ad_text | Text content of the ad |
| conversion_rate | Conversion rate percentage |
| campaign_id | The campaign identifier |
| conversion | Number of conversions |
| cost_per_conversion | Cost per conversion |
| ctr | Click-through rate |
| real_time_conversion | Real-time conversions |
| cpm | Cost per 1,000 impressions |
| promotion_type | Type of promotion |
| ad_name | Name of the ad |
| impressions | Number of times the ad was shown |
| real_time_result_rate | Real-time result rate |
| tt_app_name | Name of TikTok app |
| mobile_app_id | Mobile app identifier |
| cost_per_1000_reached | Cost per 1,000 users reached |
| real_time_cost_per_result | Real-time cost per result |
| cost_per_secondary_goal_result | Cost per secondary goal result |
| clicks | Number of clicks received |
| result_rate | Result rate |
| secondary_goal_result_rate | Secondary goal result rate |
| adgroup_name | Name of the ad group |
| real_time_conversion_rate | Real-time conversion rate |
TikTok Campaigns Schema
| Field | Description |
|---|---|
| advertiser_id | The advertiser account identifier |
| campaign_id | The unique identifier of the campaign |
| campaign_name | Name of the campaign |
| campaign_type | Type of campaign |
| is_smart_performance_campaign | Whether this is a smart performance campaign |
| budget_mode | Budget mode (daily or lifetime) |
| budget | Budget amount |
| operation_status | Operational status of the campaign |
| objective | Campaign objective |
| objective_type | Type of campaign objective |
| app_promotion_type | Type of app promotion |
| campaign_product_source | Product source for the campaign |
| budget_optimize_on | Budget optimization settings |
| bid_type | Type of bidding at campaign level |
| roas_bid | Return on ad spend bid at campaign level |
| deep_bid_type | Deep bidding type at campaign level |
| special_industries | JSON list of special industry categories |
TikTok Source of Truth Schema
| Field | Description |
|---|---|
| stat_time_day | Date for the metrics |
| advertiser_id | The advertiser account identifier |
| spend | Total amount spent |
| impressions | Total number of impressions |
| reach | Total number of unique users reached |
5. Troubleshooting & FAQs for TikTok Ads
Common Issues & Error Messages
Authentication Failures
- Error: "Invalid access token" or "Token expired"
- Solution: Re-authorize the integration through TikTok SSO. TikTok access tokens have limited lifetimes and may need to be refreshed.
Permission Issues
- Error: "Permission denied" or "Insufficient permissions"
- Solution: Ensure your TikTok Ads account has the appropriate permissions. You need to have at least "Advertiser" level permissions to access the data.
Missing Data
- Common Causes:
- Date range outside of campaign activity period
- Data processing delays on TikTok's side
- Solution: Adjust template filters, check campaign dates, and allow 24-48 hours for complete data processing
Data Latency
- Issue: Recent performance data appears incomplete
- Solution: TikTok has a reporting data latency of approximately 11 hours. For more complete data, we recommend using a lookback window of at least 3 days.
Contact & Support Information
- Nodus Support: support@nodus.com
Data Retention & Limitations
- TikTok typically retains detailed ad performance data, but historical data limits may vary
- The API has a request limitation that the connector respects with automatic retries
- TikTok offers both auction and reservation ad types - ensure you select the correct report type
- Attribution window considerations: TikTok's reporting uses attribution windows to report conversions, which may lead to metric updates over time