Integrating Facebook Ads on Clarisights

Connect your Facebook (Meta) Ads accounts to monitor campaign performance, audience and placement breakdowns, creative-asset reporting (image / video / dynamic-creative), catalog-driven dynamic ads via the product-feed beta, on-Facebook engagement, Pixel and Conversions API events, mobile app installs, video engagement, Meta Lift Studies, and iOS SKAdNetwork-attributed results across every Meta ad surface (Facebook, Instagram, Messenger, Audience Network) alongside the rest of your marketing stack.

At a glance

Prerequisites

• An active Facebook (Meta) Ads account managed through Meta Business Suite / Business Manager or Ads Manager.

• A user role with read access to each ad account: Admin, Advertiser, or Analyst (Analyst is sufficient for reporting). Both personal Facebook accounts and Business Manager System Users are supported.

• Permission on your Facebook profile to authorize third-party apps. Some organisations restrict this at the Business Manager level — check with your Meta admin first.

• If you plan to use Pixel or Conversions API events, those must already be configured and assigned to the relevant ad accounts in Events Manager.

• For the Product feed (beta): the Meta Catalog must be created in Commerce Manager and connected to the ad account, with at least one Advantage+ Catalog / Dynamic Product Ads campaign in flight, and Pixel/CAPI events firing for the catalog’s product IDs.

• For Lift Studies: a brand-lift or conversion-lift study must already be created in Meta Experiments and shared with the connected Business Manager. Lift Study reporting is enabled per company by your CSM — see internal setup docs for the activation flow.

Steps to Connect

Step 1 — Start the connection from Clarisights

In Clarisights, go to Integrations and click + Connect below the Facebook icon.

[TODO: Screenshot needed — Clarisights Integrations page with the Facebook “+ Connect” button highlighted]

Step 2 — Sign in with Facebook

You will be redirected to Facebook. Sign in with the user that has access to the ad accounts you want to connect. If your business uses Single Sign-On to Facebook, sign in with that account.

⚠ Common error: “You don’t have permission to perform this action.” → The Facebook user you signed in as does not have a role on the target ad accounts in Business Manager. Ask a Business Manager admin to assign you (or a dedicated System User) at least Analyst on every ad account you want to connect.

Step 3 — Choose the Pages & Business assets to share

Facebook’s consent screen lists the Pages, Business Manager, and ad accounts the app will be able to read. Keep all of them selected unless your organisation has a specific reason to limit them — deselecting required assets will cause specific reports to fail later.

[TODO: Screenshot needed — Facebook Pages and Business asset selection screen]

Step 4 — Approve the requested permissions

Facebook will display a permission screen listing the access Clarisights requires:

• ads_read — read campaign, insights, and conversion data from your ad accounts

• pages_read_engagement — read engagement metrics on Pages associated with your ads

• pages_show_list — list the Pages you administer (used to associate ads with their Page)

Approve all listed permissions. If any are toggled off, several Clarisights reports will be missing data.

⚠ Common error: “Ad account owner has NOT granted ads_management or ads_read permission.” → The ad account’s owning Business Manager is restricting third-party app access, or you removed ads_read from the consent screen. Re-run the OAuth flow and accept all permissions, and have a Business Manager admin verify that Apps → Clarisights is allowed for the affected ad accounts.

Step 5 — Select the ad accounts to integrate

After authorization, Clarisights automatically discovers every ad account your Facebook user has access to (across all Business Managers) and lists them. Select the accounts you want to connect, optionally rename them, and click Connect Accounts.

[TODO: Screenshot needed — Clarisights ad-account selection screen after the Facebook redirect]

Step 6 — Manage connected accounts

Connected accounts appear on the Integrations page with controls to enable / disable each account and to refresh the user’s access token if it is revoked or rotated.

[TODO: Screenshot needed — Connected Facebook accounts list with the refresh-token control]

Verify the connection

• Go to Integrations → Facebook Ads. Each selected account should show a “Connected” status and the correct currency, timezone, and account-status values.

• First reporting data appears within a few hours of the next scheduled sync; deeper history is filled in by the initial backfill.

• Quick start: create a new report, add Facebook as the data source, and add Account · Campaign · Impressions · Link Clicks · Spend. Then add the Publisher Platform (Breakdown) dimension to verify breakdown data has arrived.

Data available

Hierarchy

How Facebook’s native levels map to the standard Clarisights levels:

Dimensions

Account-level

Campaign-level

Ad Set-level (incl. targeting)

Ad-level

Creative assets

For ads using Meta’s Dynamic Creative feature (and for ad formats that surface individual creative components), Clarisights ingests asset-level reporting so you can see which creative variants are driving performance. Asset rows live below the Ad level: a single ad can produce many asset rows, one per asset variant per asset type.

The following asset types are supported:

Asset-level dimensions exposed on each row:

Asset rows support the same Performance, Engagement, Video, Pixel-attributed and App-event metrics that Ad rows support, with the same attribution-window selectors. Per-asset numbers may not sum to the parent ad if Meta withholds rows below its minimum-impression threshold.

Which asset types are pulled per company is configurable via the Facebook channel preference (disabled_asset_types) — by default all non-product asset types are enabled. Product asset reporting is treated as a separate beta integration; see the next section.

[TODO: Screenshot needed — Asset-level table showing Image and Video assets under a Dynamic Creative ad]

Product feed & dynamic ads (beta)

Beta: Product feed reporting runs through a separate Clarisights pipeline and is enabled per company. Contact your CSM or support to opt in. Prerequisites listed above (Meta Catalog connected, Pixel/CAPI events firing for catalog products, Advantage+ Catalog / DPA campaigns running) must be met for any data to land.

For Advantage+ Catalog (formerly Dynamic Product Ads / DPA / DABA) campaigns, Clarisights ingests catalog-level reporting that links each performance row to the specific product that was served. Product rows are surfaced as a dedicated product asset type underneath the Ad level, and a daily backfill spans the most recent days at this granularity.

Dimensions available on product rows:

Product rows expose the same Spend, Impressions, Click, and Pixel/CAPI conversion metrics as the parent Ad row, restated per product. The product pipeline runs only at this granularity for ads in catalog-enabled campaigns; non-catalog ads will not produce product rows.

Note: To keep storage reasonable, the product-feed pipeline filters out very low-impression product rows (typically below the bottom impression bucket Meta returns). Product totals will not always reconcile 1:1 with parent-ad totals because of this filtering and Meta’s privacy minimums.

[TODO: Screenshot needed — Product asset table showing Product ID / Product Name with Spend and Pixel: Purchase Conversion Value]

Breakdown dimensions

Facebook breakdowns split a metric across an additional dimension (e.g., Spend by Country). They are exposed in Clarisights with a (Breakdown) suffix in the dimension picker. To avoid data explosion they are stored at the Account and Campaign levels only and cannot be combined with Ad Set or Ad attributes.

Breakdowns are not enabled by default for new tenants. Contact support to enable any of the above.

Metrics

Performance & cost

Engagement & on-Facebook actions

Video

Mobile app & in-app ad metrics

Conversions API & Pixel

Web conversions land via the Meta Pixel (browser-side beacon) and / or the Conversions API (CAPI) (server-side events) and are exposed under the FB Pixel: prefix in Clarisights. Both event sources are merged transparently — Clarisights does not separate them in the dimension picker. Where Meta deduplicates an event between Pixel and CAPI (using event_id), the de-duplicated count is what arrives.

• Standard events: Purchase, Add to Cart, Add Payment Info, Add to Wishlist, Initiate Checkout, Lead, Registration, View Content, Search, Contact, Customize Product, Donations, Find Location, Schedule, Start Trial, Submit Application, Subscribe, Recurring Subscription Payment, Cancel Subscription. Each event has both a count metric and a Conversion Value metric where applicable.

• Per-window variants: every Pixel/CAPI event is also exposed at the supported click and view attribution windows (see Attribution windows below).

• Custom conversions: standard-event subscriptions cover the events listed above. Custom conversions configured in Events Manager that are built on top of standard events flow in as the underlying standard event; bespoke custom conversions outside the standard catalogue are not surfaced as separate metrics.

• iOS / ITP coverage: full-funnel coverage on iOS Safari and other ITP browsers requires Conversions API to be configured alongside the Pixel — Pixel-only setups will under-report on those surfaces.

Conversions — Pixel / CAPI (web)

Conversions — App events (App / SDK / MMP)

Conversions — Offline

On-Facebook conversions

Events that complete on Meta surfaces (e.g., Lead Ads, Click-to-Messenger flows, On-Facebook destinations) are exposed under the On Facebook: prefix.

SKAdNetwork (iOS attribution)

For iOS app campaigns affected by ATT (App Tracking Transparency), Meta returns aggregated SKAdNetwork data that Clarisights surfaces as a parallel set of (SKAN) metrics. Each SKAN metric typically has three variants: total, click-attributed, and view-attributed.

For background on how Clarisights reports SKAN events, see Intro to SKAdNetwork (SKAN) reporting on Clarisights and SKAdNetwork: Changes to Facebook Data on Clarisights.

Attribution windows

Conversion metrics in Clarisights respect Meta’s action attribution windows. Meta’s 2021 ATT-driven changes deprecated the legacy 28-day-click and 7-day-view defaults; Clarisights honours the post-2021 window model and stores historical data with whichever windows applied at the time of the impression / click.

Standard windows exposed in Clarisights:

• 1d_view, 7d_view, 28d_view — view-through conversions at 1 day / 7 days / 28 days

• 1d_click, 7d_click, 28d_click — click-through conversions at 1 day / 7 days / 28 days

The default attribution window can be set per company; individual widgets can override it via the attribution-window selector. The set of windows available per company is configurable through the Facebook channel preference (attribution_windows).

Dynamic / first-conversion windows (where enabled by Meta for a given account):

• incrementality_first_conversion — Meta’s incrementality-modelled first-conversion window

• 1d_ev_first_conversion, 1d_click_first_conversion, 7d_click_first_conversion, 28d_click_first_conversion, 1d_view_first_conversion — first-conversion (engaged-view / click / view) variants

Dynamic windows are pulled per supported event when Meta exposes them on the ad account. Where Meta has not opted the account into a window, the metric remains empty rather than throwing an error.

Lift Studies

Special integration: Lift Study reporting is a separate Clarisights pipeline (Performance Integration channel fb_lift_study) that runs alongside the core Facebook Ads OAuth connection. Enabling it requires CSM-led setup at the company level. Refer to the internal Setup Lift Studies for a Company playbook in Internal Docs for the activation steps.

Once enabled, Clarisights ingests Brand Lift Studies (BLS) and Conversion Lift Studies (CLS) created in Meta Experiments and exposes them as a dedicated dataset. Up to 720 days of lift study history is fetched on enable.

Per-cell metrics fall into three groups depending on whether the study is Brand Lift, Conversion Lift, or shared:

Limitations & known constraints

• Attribution-window changes (2021): Meta deprecated the legacy 28-day click and 7-day view defaults in early 2021 in response to ATT. Conversion totals reported today reflect the post-2021 window model. Historical data created before that change will continue to use the windows that applied at the time of the impression / click.

• SKAdNetwork constraints: SKAN data is aggregated, delayed (Apple postback windows of up to ~3 days), and may be subject to privacy thresholds where Meta returns null counts for low-volume cohorts. SKAN totals do not reconcile 1:1 with on-Pixel / MMP-attributed totals.

• Breakdowns are limited to Account & Campaign: to keep storage and query performance reasonable, breakdown data is stored at the account and campaign levels only. Breakdowns cannot be combined with Ad Set or Ad attributes in the same widget.

• Breakdown-incompatible metrics: certain Meta fields (e.g., app_store_clicks, newsfeed_avg_position, newsfeed_clicks, newsfeed_impressions, relevance_score) cannot be requested when a breakdown is applied and will not appear in breakdown widgets.

• Demographic minimums: Meta enforces minimum-impression / engagement thresholds before demographic and geo breakdowns are returned for a given cohort — rows below the threshold are simply absent from the report.

• Reporting delay & restatement: most metrics arrive within a few hours, but conversion and SKAN metrics can take up to ~72 hours to fully reconcile. Meta also restates older days when late conversions land — this is normal and is reflected in scheduled refresh runs.

• Conversions API requirement for some metrics: full-funnel coverage of web events on iOS Safari and other ITP browsers requires Conversions API to be configured alongside the Meta Pixel. Pixel-only setups will under-report on those surfaces.

• Asset-level reporting requires Dynamic Creative: image / video / title / body / description / link URL / CTA asset rows are only generated by Meta for ads that opt into Dynamic Creative (or for ad formats that surface individual creative components). Static, single-creative ads will only appear at the Ad level.

• Product-feed (beta) constraints: product rows are only produced for Advantage+ Catalog / Dynamic Product Ad campaigns with a Meta Catalog connected and Pixel/CAPI events firing for the catalog’s product IDs. Product-level totals will not reconcile 1:1 with parent-ad totals because of Meta privacy minimums and a low-impression filter applied to keep storage manageable. The pipeline currently runs on a 3-day rolling window.

• Lift Studies are CSM-enabled: brand-lift / conversion-lift data does not flow until your CSM enables the fb_lift_study PI channel for the company; results are also subject to Meta’s study-publication timing.

• Dynamic / first-conversion windows are account-scoped: first-conversion windows (incrementality_first_conversion, 1d_ev_first_conversion, etc.) are only returned for accounts Meta has opted into them. Other accounts will see empty values for those windows.

• Rate limits & large queries: the Marketing API enforces per-app, per-account, and Business-Use-Case (BUC) rate limits, and rejects queries that scan too much data with a LargeDataScopeError. Clarisights automatically retries with smaller page sizes and async report jobs, but exceptionally large breakdown queries may take additional time to materialise.

• Token revocation: if Clarisights’ access is revoked in Meta Business Manager (or the authorising user loses ad-account access), the integration stops syncing for the affected accounts until a user with access re-authenticates from the Integrations page.

Operating notes

• API version: Meta Marketing API v23.0 (Graph API). Clarisights tracks Meta’s deprecation schedule and migrates to newer versions as they are released.

• Refresh schedule: full reporting pulls run multiple times per day across the four core levels (account, campaign, ad set, ad). A current-day incremental job runs through the day so today’s data stays fresh between full pulls. Account-status, video-asset, and account-discovery jobs run daily. Asset-level reports run on the same cadence as ad-level reports for enabled asset types. Product-feed (beta) runs on a separate 3-day rolling pipeline triggered from the parent product_feed_bq_update DAG.

• Lookback / backfill: routine refreshes cover recent days; longer historical windows are filled in by dedicated backfill jobs that you can request from support. Lift Studies backfill up to 720 days on enable.

• Auto account sync: a daily job picks up newly created / newly granted ad accounts so they appear in Clarisights without re-authenticating.

• Multi-account & multi-Business Manager: a single Facebook user can connect ad accounts across multiple Business Managers in one OAuth flow. Re-running the OAuth flow is the supported way to add accounts that were granted to the user after the original connection.

• Currency conversion: spend and conversion value are pulled in the ad account’s native currency and converted to your reporting currency. Native amounts remain available via the “Local currency” metric variants.

• Credential rotation: Meta short-lived tokens are exchanged for long-lived tokens at connect time and refreshed transparently. Re-authenticate from the Integrations page only if the token is revoked, the password changes, or the user loses ad-account access.

• Rate-limit handling: when Meta returns BUC throttle headers, Clarisights blocks affected accounts for the regain time the API specifies and retries automatically — no action is required.

Need help?

When contacting support from the in-app messenger, please include:

• The integration name and ad account ID (Integrations → Facebook Ads)

• The exact error message or screenshot

• The step where the issue occurred

• When the issue started

• For data discrepancies: the date range, attribution window, and any breakdowns applied in the comparing widget

• For asset / product-feed / Lift Study questions: the ad ID and asset / product / study ID involved