Facebook Ads Integration for Nodus
1. Introduction to the Facebook Ads Integration
What Is This Integration?
The Facebook Ads integration connects your Facebook 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 Facebook Ads data into the Nodus ecosystem for advanced analytics and business intelligence.
Prerequisites:
- An active Facebook Ads Manager account with appropriate access permissions
- Facebook Ad Account ID for the accounts you want to connect
- Authorization via Facebook Single Sign-On (SSO)
- Read permissions for the Facebook Marketing API
Connection Overview:
The integration uses Facebook'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 Facebook Ads)
Purpose & Scope
This section covers how to set up the initial connection between Nodus and Facebook 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 Facebook Ads integration within your Nodus account.
- Validation Rules & Format: Text string, required field.
- Examples: "Facebook Ads - Main Account", "FB Marketing - Client X"
- Troubleshooting Tips: Use a descriptive name that clearly identifies the specific Facebook Ads account or purpose.
Facebook Ad Account ID
- Field Name & Label: Facebook Ad Account ID
- Description & Purpose: The unique identifier for your Facebook Ad Account, used to access campaign data.
- Validation Rules & Format: Numeric string with "act_" prefix, required field.
- Examples: "act_123456789"
- Troubleshooting Tips: You can find your Ad Account ID in the Facebook Ads Manager under Account Settings or in the URL when viewing your account (it will appear as "actXXXXXXXXX"). Make sure to include the "act" prefix.
External Link
- Link Label: "Locate Your Account ID"
- URL: https://developers.facebook.com/docs/facebook-login
- Purpose: Helps users locate their Facebook Ad Account ID in the Facebook Ads Manager interface.
Step-by-Step Guide:
- Log in to Facebook Ads Manager
- Navigate to Account Settings to locate your Ad Account ID
- Note the Ad Account ID (including the "act_" prefix)
- Enter your Ad Account ID and a meaningful Integration Name in the Nodus setup form
- Click Authorize to launch the Facebook SSO authorization flow
- Grant permissions when prompted by Facebook
- Verify connection and save the configuration
Reference Links:
3. Extraction/Query Configuration (Extraction Form for Facebook Ads)
Purpose & Overview
This section explains how to configure data extraction from Facebook 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 Facebook Ads data to extract
- Validation Rules & Format: Dropdown selection, required field
- Available Options:
- Marketing Ads - Basic ad configuration and status information
- Marketing Ads Metadata - Additional metadata about ads including objectives and targeting
- Marketing Ads Insights - Performance metrics including impressions, clicks, and conversions
- Marketing Ads Creatives - Creative content and settings for all ad formats
- Marketing Ads Creatives Metadata - Additional metadata about ad creatives
- Marketing Source of Truth - Combined dataset with key account metrics
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
- Troubleshooting Tips: Select a longer range for historical analysis or a shorter range for recent performance data. The recommended 28-day range aligns with Facebook's attribution window.
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: Facebook maintains historical data, but some metrics may only be available for limited time periods.
Workflow & Examples:
- Select the appropriate template (e.g., "Marketing Ads Insights" 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: Marketing Ads Insights
- Metrics: Impressions, clicks, spend, conversions
- Lookback: 28-day Range
Creative Performance Analysis:
- Template: Marketing Ads Creatives + Marketing Ads Insights
- Metrics: Creative details with performance metrics
- Lookback: 28-day Range
Account Structure Audit:
- Template: Marketing Source of Truth
- Data: Account structure, campaign settings, targeting criteria
- Historic Date: Custom range for specific campaign periods
4. Data Mapping & Underlying Models for Facebook Ads
Data Model Overview
The Facebook Ads API returns structured data based on the selected template. Each template corresponds to specific API endpoints and data structures within the Facebook Marketing API.
Schema & Field Mapping
Marketing Ads Schema
| Field | Description |
|---|---|
| id | The unique identifier of the ad |
| name | The name of the ad |
| campaign_id | The campaign identifier |
| adset_id | The ad set identifier |
| creative | JSON object containing creative details |
| configured_status | The status set by the advertiser |
| effective_status | The effective status considering campaign and ad set status |
| bid_amount | The bid amount for the ad |
| bid_type | The type of bidding used |
| created_time | The ad creation timestamp |
| updated_time | The last update timestamp |
| targeting | JSON object containing targeting details |
| source_ad_id | ID of the source ad if this is a copy |
| conversion_specs | List of conversion specifications |
| account_id | The associated account identifier |
Marketing Ads Metadata Schema
| Field | Description |
|---|---|
| id | The unique identifier of the ad |
| creative | JSON object containing detailed creative configuration |
| created_time | The ad creation timestamp |
| updated_time | The last update timestamp |
Marketing Ads Insights Schema
| Field | Description |
|---|---|
| ad_id | The unique identifier of the ad |
| ad_name | The name of the ad |
| adset_id | The ad set identifier |
| adset_name | The name of the ad set |
| campaign_id | The campaign identifier |
| campaign_name | The name of the campaign |
| account_id | The account identifier |
| account_name | The name of the account |
| date_start | Start date for the metrics |
| date_stop | End date for the metrics |
| impressions | Number of times the ad was shown |
| clicks | Number of clicks received |
| spend | Amount spent on the ad |
| reach | Number of unique people who saw the ad |
| buying_type | The buying type (AUCTION, RESERVED) |
| unique_clicks | Number of unique clicks |
| inline_link_clicks | Number of clicks on links within the ad |
| inline_post_engagement | Number of post engagements |
| actions | List of actions taken (conversions by type) |
| action_values | List of action values (conversion values) |
| unique_actions | List of unique actions |
| video_p25_watched_actions | List of 25% video completion actions |
| video_p50_watched_actions | List of 50% video completion actions |
| video_p75_watched_actions | List of 75% video completion actions |
| video_p95_watched_actions | List of 95% video completion actions |
| video_p100_watched_actions | List of 100% video completion actions |
| video_play_curve_actions | List of video play curve data |
| outbound_clicks | List of outbound clicks |
| unique_outbound_clicks | List of unique outbound clicks |
| created_time | The timestamp when the data was created |
| updated_time | The timestamp when the data was last updated |
| account_currency | The currency of the account |
Marketing Ads Creatives Schema
| Field | Description |
|---|---|
| id | The unique identifier of the creative |
| name | The name of the creative |
| account_id | The account identifier |
| actor_id | The actor (page) identifier |
| object_type | The type of creative (LINK, VIDEO, etc.) |
| status | The status of the creative |
| title | The headline of the ad |
| body | The primary text of the ad |
| thumbnail_url | URL of the creative thumbnail |
| video_id | ID of the creative video (if applicable) |
| effective_object_story_id | The effective story ID |
| call_to_action_type | The call-to-action button type |
| url_tags | URL parameters for tracking |
| object_story_spec | JSON object with story specifications |
| asset_feed_spec | JSON object with asset feed specifications |
| instagram_actor_id | Instagram actor ID |
| instagram_user_id | Instagram user ID |
| effective_instagram_media_id | Effective Instagram media ID |
| effective_instagram_story_id | Effective Instagram story ID |
| instagram_permalink_url | Instagram permalink URL |
| effective_authorization_category | Effective authorization category |
Marketing Ads Creatives Metadata Schema
| Field | Description |
|---|---|
| id | The unique identifier of the creative |
| asset_feed_spec | Detailed JSON configuration for dynamic creative assets |
| url_tags | URL parameters used for tracking |
Marketing Account Insights Schema
| Field | Description |
|---|---|
| account_id | The unique identifier of the account |
| account_name | The name of the account |
| date_start | Start date for the metrics |
| date_stop | End date for the metrics |
| impressions | Number of times ads were shown |
| clicks | Number of clicks received |
| spend | Amount spent on advertising |
| reach | Number of unique people who saw ads |
| unique_clicks | Number of unique clicks |
| inline_link_clicks | Number of clicks on links within ads |
| inline_post_engagement | Number of post engagements |
| actions | List of actions taken (conversions by type) |
| action_values | List of action values (conversion values) |
| unique_actions | List of unique actions |
| outbound_clicks | List of outbound clicks |
| unique_outbound_clicks | List of unique outbound clicks |
| video_p25_watched_actions | List of 25% video completion actions |
| video_p50_watched_actions | List of 50% video completion actions |
| video_p75_watched_actions | List of 75% video completion actions |
| video_p95_watched_actions | List of 95% video completion actions |
| video_p100_watched_actions | List of 100% video completion actions |
| created_time | The timestamp when the data was created |
| updated_time | The timestamp when the data was last updated |
| account_currency | The currency of the account |
5. Troubleshooting & FAQs for Facebook Ads
Common Issues & Error Messages
Authentication Failures
- Error: "Invalid access token" or "Token expired"
- Solution: Re-authorize the integration through Facebook SSO. Facebook access tokens have limited lifetimes and may need to be refreshed.
Missing Data
- Common Causes:
- Date range outside of campaign activity period
- Insufficient permissions for the account
- Solution: Adjust template filters, check campaign dates, verify account permissions
Insights Data Delay
- Issue: Recent performance data appears incomplete
- Solution: Facebook Insights data can have up to 24-hour delay. For the most recent data, set appropriate expectations or schedule extractions to run after the data is fully processed.
Contact & Support Information
- Nodus Support: support@nodus.com
Data Retention & Limitations
- Facebook typically retains detailed ad performance data for up to 37 months
- Some metrics (like demographic breakdowns) may only be available for more recent periods
- Facebook has strict rate limits that can impact extraction frequency and volume
- Attribution data can change over time as conversions are reported (up to 28 days after ad interaction)