Facebook Ads Settings

Connect your Facebook Ads account to Alpha Insights for automatic ad spend tracking, campaign performance insights, and profit-based ROAS calculations. This powerful integration eliminates manual data entry and provides campaign-level profitability analysis.

Accessing Facebook Ads Settings

  1. Go to Alpha Insights → Settings
  2. Navigate to the Facebook settings page
  3. You'll see the Facebook API configuration interface

Integration Status: Beta

The Facebook Ads integration is currently in beta. It's fully functional and production-ready, with ongoing improvements and feature additions.

What This Integration Does

API Connection

Connect Alpha Insights to your Facebook Ad Account using secure OAuth authentication.

Connect To Facebook

Connection Status Display

Shows your current connection status:

Initial Connection Setup

  1. Click Connect to Facebook button
  2. Facebook popup window opens
  3. Log in with Facebook account that has admin access to your ad account
  4. Facebook asks for permissions - click "Continue" to grant ads_read permission
  5. Select your Ad Account from the list provided
  6. Click Connect Account button
  7. A success screen appears with your connected account name
  8. Click Fetch All Data to immediately import your historical ad data
  9. Or click outside the modal to configure settings first, then fetch data later using "Refresh All Campaign Data" button
  10. If data fetch is successful, you'll see a completion message
  11. If data fetch fails (e.g., large account, API issues), you'll see a helpful message explaining your account IS connected and you can fetch data later
  12. Page reloads to show your active connection status

Important requirements:

Reconnecting

Facebook access tokens expire after maximum 60 days. When expiry approaches or token expires:

  1. You'll see "Token Invalid" or "Connection Expired" status
  2. Click Reconnect Facebook button
  3. Log in to Facebook again
  4. Grant permissions
  5. Connection restored with new 60-day token

Tip: Set a calendar reminder to reconnect every 55 days to avoid interruption

Disconnecting

To remove the Facebook connection:

  1. Click Remove Connection button
  2. Confirm disconnection
  3. Access token is cleared from database
  4. Scheduled syncs stop immediately
  5. Historical data remains in database (unless you delete it)

API Status

View detailed connection health information:

API Status:

Connection Expiry Date: When your access token expires (60 days max from connection)

API Status Message: Detailed error or success message from last API check

Last API Check: Timestamp of most recent connection verification

Alpha Campaign Profit Tracking

The most powerful feature - track which Facebook campaigns actually drive profit, not just revenue.

How It Works

  1. You add a special tracking parameter to your Facebook ad URLs
  2. When someone clicks your ad, this parameter is captured in their session
  3. When they make a purchase, the order is linked to the specific Facebook campaign
  4. Alpha Insights calculates the profit for that order
  5. You can see true profit-based ROAS, not just revenue-based

UTM Tracking Key / Values

The magic parameter: meta_cid={{campaign.id}}

What it does:

Setting Up UTM Tracking

Method 1: In Facebook Ads Manager (Recommended)

  1. Go to Facebook Ads Manager
  2. For each ad campaign, edit the ad
  3. Find the "Website URL" or landing page URL field
  4. Add the tracking parameter to your URL

Examples:

Original URL:
https://yourstore.com/products

Add parameter:
https://yourstore.com/products?meta_cid={{campaign.id}}

If URL already has parameters (contains ?):
https://yourstore.com/products?color=blue&meta_cid={{campaign.id}}
(Use & instead of ?)

Facebook automatically replaces {{campaign.id}} with the actual campaign ID when someone clicks

Method 2: URL Parameters at Campaign Level

  1. In Facebook Ads Manager, go to campaign settings
  2. Find "URL Parameters" section (under "Tracking")
  3. Enter: meta_cid={{campaign.id}}
  4. This applies to all ads in the campaign automatically

Recommendation: Use Method 2 for new campaigns - it's easier and applies to all ads

Testing Your Tracking

  1. Click your Facebook ad (or use Preview URL from Facebook)
  2. Look at the URL in your browser
  3. You should see: meta_cid=123456789 (with an actual number)
  4. This confirms tracking is working

Viewing Campaign Profit

After setting up tracking:

  1. Wait for orders to come in from your Facebook ads
  2. Go to Alpha Insights campaign reports
  3. You'll see profit attributed to each Facebook campaign
  4. Calculate true ROAS: (Profit ÷ Ad Spend) × 100

Example:

Why profit ROAS matters: A campaign with high revenue might have low profit if products have low margins

API Settings

Configure how Alpha Insights syncs with Facebook.

API Call Schedule

What it does: Controls how often Alpha Insights checks Facebook for new data

Options:

What gets synced on schedule:

Recommendation:

Collect Campaign Insights

Options: True or False

What it does: When enabled, fetches detailed metrics for each campaign:

Recommendation: Keep enabled (True) for full campaign reporting and analysis

Collect Daily Ad Spend

Options: True or False

What it does: Automatically creates expense records for your daily Facebook ad spend

How it works:

  1. Every day (per schedule), Alpha Insights checks your Facebook ad spend
  2. Creates an expense entry for that day's total spend
  3. Expense is categorized in your selected expense category
  4. This expense is included in net profit calculations
  5. Shows up in expense reports and net profit calculations

Recommendation: Keep enabled (True) for automatic expense tracking - no manual data entry needed

Ad Spend Expense Category

What it is: The expense category where Facebook ad spend is stored

How to configure:

  1. Select category from dropdown (shows all your expense categories)
  2. Or click Add New Category to create one
  3. Common names: "Facebook Advertising", "Digital Marketing", "Paid Ads"

Why it matters: Allows you to separate Facebook ad costs from other expenses in reports

Recommendation: Create a dedicated "Facebook Ads" category for clean reporting

Request Timeout

Default: 5 seconds

Range: 5-60 seconds

What it does: How long to wait for Facebook API responses before timing out

When to change:

Recommendation: Keep at 5 seconds unless experiencing timeout issues

Number Of Results To Collect Per Call

Default: 50

Range: 1-500

What it does: How many records Facebook returns per API request

Technical details:

When to change: Only reduce if experiencing timeout errors

API Data

View information about synced Facebook data in your database.

Daily Expenses Stored: Number of daily ad spend expense records created

Campaigns Stored: Number of Facebook campaigns being tracked

Last Successful Data Fetch: When the last sync completed successfully

Next Scheduled Data Fetch: When the next automatic sync will run

Use this to verify:

API Tools

Maintenance and data management tools for your Facebook integration.

Refresh All API Data

What it does: Immediately fetches all Facebook data for all time (up to 36 month limit)

When to use:

How it works:

  1. Click Refresh All Campaign Data button
  2. Process runs in background (takes 1-3 minutes depending on account size)
  3. Creates new records or updates existing ones
  4. Does NOT delete any data
  5. Facebook API limit: 36 months maximum history

Note: This is a large API request - use sparingly. Regular scheduled syncs only check past 30 days.

Check API Status

What it does: Immediately tests your Facebook API connection and displays status

When to use:

Results shown:

Delete All Expense Data

What it does: Removes all Facebook ad spend expense records from your database

Important notes:

When to use:

Delete All Campaign Data

What it does: Removes all Facebook campaign insights from your database

Important notes:

When to use: Same scenarios as deleting expense data

Important Information

Facebook API Limitations

Data Syncing Details

Privacy and Security

Facebook API Log

At the bottom of the settings page, you'll see the Facebook API Log.

What it shows:

Use for troubleshooting:

Troubleshooting

Connection Failed / Token Invalid

Solution: Click "Reconnect Facebook" and log in again

Permission Denied Error

Cause: Logged in Facebook account doesn't have admin access to ad account

Solution: Log in with an account that has admin permissions, or request admin access

No Campaigns Showing

Check:

Ad Spend Not Matching Facebook

Common reasons:

Syncs Not Running

Check:

Best Practices

Setup

Ongoing Use

Campaign Tracking

Summary

The Facebook Ads integration provides:

Once configured, the Facebook integration runs automatically, providing you with accurate campaign profitability analysis and eliminating manual ad spend tracking!