Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ocular.dev/llms.txt

Use this file to discover all available pages before exploring further.

Ocular connects to Facebook Ads using OAuth — the easiest option. Token refresh is fully managed by Ocular; you sign in once and pick the ad accounts to sync.

What you need

Admin access to a Meta Business Manager with one or more ad accounts.

What it unlocks

Marketing report, Ad & Campaign Performance, Creative Deep Dive, blended ROAS.
Set up ad tracking first. UTM parameters and fbclid tracking must be configured at the Ad level in Meta Ads Manager before you turn on the connector — retroactive tagging doesn’t work. Walk through the Ad Tracking Setup Guide before continuing here.
Facebook Ads connector placeholder

​
Connect via OAuth

Start the OAuth flow

In Ocular, go to Data Management → Connectors → Add Connector → Facebook Ads, then select Connect with Facebook (OAuth).

Log in and grant permissions

You’ll be redirected to Facebook’s login page. Sign in and select:
  • Your Business Manager
  • The Admin ad account(s) you want to sync
Approve the list of permissions Ocular requests. These are the minimum needed to read spend, impressions, clicks, conversions, and creative-level breakdowns.

Auto-configuration

Ocular automatically fetches every ad account linked to the selected Business Manager.
  • Pick the account(s) you want to sync.
  • Tokens are managed by Ocular — no manual refresh needed.

Save and sync

You’ll be redirected back to the connector page with a YOUR META ACCOUNT IS CONNECTED confirmation.
  • Select the account(s) to sync.
  • Click Create Connector.
Data ingestion begins automatically.
Meta OAuth selection placeholder

​
Breakdowns Ocular ingests

Meta Ads produces 11 breakdown data models, each keyed to date × account × campaign × adset × ad × breakdown_dimension.

Age & Gender

Demographic cohort performance.

Hourly Audience

Dayparting optimisation (audience_hour, day_of_week).

Platform & Device

Cross-platform and device analysis (ad_platform, placement, impression_device).

Region

Geographic performance.

Product

SKU-level catalog optimisation.

Body, Title, Description assets

Ad copy performance by element.

Image asset

Individual image performance by image_hash.

Video asset

Video creative performance.

Creative asset

Combined creative-asset performance.

​
Troubleshooting

Confirm the Facebook account you’re signing in with has Admin access to the Business Manager — view-only or analyst roles can’t authorise the scopes Ocular needs.
The account must be inside the Business Manager you selected. If it’s a personal ad account or owned by a different BM, move or share it into the right BM, then retry the OAuth.
Creative-level breakdowns require that your ads are set up with consistent UTM parameters and the asset IDs are populated. If fbclid and the Ocular custom UTM parameters weren’t configured before the campaign launched, retroactive ingestion won’t fill them — fix the tagging and Ocular will pick up new ads from that point forward.
For ticket-writing format when filing a connector issue, see Working with the Ocular team → Connector-not-working tickets.