Integrating Facebook Ads on Clarisights

Connect your Facebook (Meta) Ads accounts to report on campaign performance, audience and placement breakdowns, creative-asset reporting (image, video and text variants), catalog product reporting (beta), on-Facebook actions, Pixel and Conversions API events, custom conversions, mobile app events, video engagement, Meta Lift Studies and SKAdNetwork-attributed iOS results across every Meta 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).

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

• If you plan to report on Pixel or Conversions API events, they must already be set up and assigned to the relevant ad accounts in Events Manager.

• For product reporting (beta): Advantage+ catalog ads (formerly Dynamic Product Ads) running on a Meta catalog, and a product feed file (CSV at a URL) that your Clarisights account team can register for you.

• For Lift Studies: a brand lift or conversion lift study created in Meta Experiments in a Business Manager the connecting Facebook user belongs to. Lift Study reporting is enabled per company by your Clarisights account team.

Steps to Connect

Step 1: Start the connection from Clarisights

In Clarisights, open Integrations (the database-stack icon in the left sidebar). Under Set up new connection, find the Facebook card (use the search box or See All) and click + Connect.

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.

⚠ 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 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 businesses, Pages 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: ad accounts you deselect here will not be available in Clarisights.

To learn how Meta lets you grant an app access to your business assets, see Meta's documentation: Facebook Login for Business.

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 manage (used to associate ads with their Page)

• business_management: only requested when Lift Study reporting is enabled for your company; used to read the lift studies owned by your businesses

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 ads_read was declined on the consent screen. Connect again and accept all permissions, and have a Business Manager admin check that Clarisights is allowed to access the affected ad accounts.

Step 5: Select the ad accounts to integrate

After you authorize, Clarisights lists every ad account your Facebook user can access (across all of its Business Managers) under New Accounts, with each account’s ID, timezone and currency. Select the accounts you want to connect and click Connect Accounts.

Step 6: Manage connected accounts

Connected accounts are listed on the Facebook Accounts page under the Facebook user that connected them. Use the Status toggle to pause or resume an account, and Refresh Token to sign in to Facebook again if access was revoked or expired. To connect another Facebook user, click + Account.

Verify the connection

• Open Integrations and select Facebook under Manage connected channels. Each account you selected should be listed with its Status toggle on and the expected Timezone | Currency.

• Last refreshed fills in once the first sync completes, usually within a few hours; deeper history is then filled in by the initial backfill.

• Quick check: in a report, click Create Widget and build a table with Account and Campaign as dimensions and FB: Impressions, FB: Link Clicks and FB: Spend as metrics.

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 that use multiple creative assets (Dynamic Creative, flexible format and similar Advantage+ creative options), Meta reports performance for each individual asset. Clarisights stores these as Asset rows below the Ad level, so a single ad produces one row per asset variant, per asset type.

The following asset types are supported:

Dimensions on each asset row:

Asset rows carry delivery metrics (spend, impressions, clicks, link clicks, engagement) and conversion metrics. Totals across assets do not add up to the ad total, because the same impression is reported once for each asset type it included, and Meta may withhold low-volume rows.

All asset types except Product are pulled by default; individual asset types can be switched off for your company on request.

Product reporting (beta)

Beta: Product reporting is enabled per company. Contact your Clarisights account team or support to opt in.

For Advantage+ catalog ads (formerly Dynamic Product Ads), Clarisights reports performance for each catalog product that was shown. Product rows appear as the Product asset type below the Ad level, for ads that use a catalog. Product data covers the last three days on every refresh.

Dimensions available on product rows:

Product rows carry spend, impressions, clicks, link clicks, outbound clicks, Instant Experience clicks and engagement metrics (reactions, comments, shares, saves). Conversion metrics are not reported per product.

Note: Rows for products with no impressions are not stored. Product totals do not always match the parent ad totals because of Meta’s privacy thresholds.

Breakdown dimensions

Facebook breakdowns split a metric across an additional dimension (e.g., Spend by Country). They appear in the dimension picker with a (Breakdown) suffix, for example Country (Breakdown). Breakdowns are stored per campaign, so they can be combined with Account and Campaign dimensions but not with Ad Set or Ad dimensions.

Ad set breakdown: value rule sets

For ad sets that use Meta value rules (bid adjustments for specific audiences), Clarisights can break ad set performance down by rule set, including conversions. This breakdown is stored per ad set, so it can be combined with Ad Set dimensions.

Breakdowns are not enabled by default. Contact support to enable the ones you need.

Metrics

Facebook metrics are grouped by prefix: FB: (delivery, engagement, video and app), FB Pixel: (website events), FB App: (app events), FB Offline: (offline events), On Facebook: (actions completed on Meta surfaces) and FB OCC - AGG: (your custom conversions). Money metrics come in two versions: the plain metric is converted to your reporting currency, and the (Local currency) version keeps the ad account’s currency.

Performance & cost

Engagement & on-Facebook actions

Video

Mobile app & in-app ad metrics

Conversions API & Pixel

Website conversions recorded by the Meta Pixel (browser) and the Conversions API (server) appear under the FB Pixel: prefix. Meta combines both sources and removes duplicates (events sent by both with the same event ID) before reporting, so Clarisights shows one deduplicated count per event.

• Standard events: View Content, Search, Add to Cart, Add to Wishlist, Initiate Checkout, Add Payment Info, Purchase, Lead, Registration, Contact, Customize Product, Donate, Find Location, Schedule, Start Trial, Submit Application, Subscribe, Recurring Subscription Payment and Cancel Subscription. Each has a count, a Unique count, and a Conversion Value (plus Conversion Value (Local currency)) metric.

• Attribution window variants: each event is also available for individual windows, for example FB Pixel: Purchase - 7 days (click) or FB Pixel: Purchase - 1 day (view) (see Attribution windows below).

• Custom conversions: custom conversions created in Events Manager are imported from each ad account automatically. They appear as FB OCC - AGG: <conversion name> and FB OCC - AGG: <conversion name> Revenue, combined across ad accounts that use the same name, with the same per-window variants.

Conversions: Pixel / Conversions API (web)

Conversions: App events

Conversions: Offline

On-Facebook conversions

Actions completed on Meta surfaces (Lead Ads forms, messaging ads, Shops and other on-Facebook destinations) appear under the On Facebook: prefix.

SKAdNetwork (iOS attribution)

For iOS app campaigns, Meta returns aggregated SKAdNetwork (SKAN) results, which Clarisights shows as a parallel set of (SKAN) metrics. Most have click-attributed and view-attributed variants too.

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 follow Meta’s attribution windows: a click-through window (1, 7 or 28 days) and a view-through window (1, 7 or 28 days), each of which can also be set to None. Unless your company has changed it, Facebook conversions use Meta’s default of 7-day click and 1-day view.

• The company default is set by your admin. A report can use a different window: open the report’s menu and choose Attribution Window.

• To compare windows side by side, add the per-window metric variants instead, for example FB Pixel: Purchase - 1 day (click) next to FB Pixel: Purchase - 7 days (click).

Additional attribution models can be enabled for your company on request. They appear as extra metric variants with a suffix such as:

• (Incremental All Conversion) and (Incremental First Conversion)

• 1 day (engaged view), 1 day (engaged view all conversions) and 1 day (engaged view first conversion)

• 1 / 7 / 28 day (click first conversion) and 1 / 7 / 28 day (view first conversion)

• (SKAN click 2nd postback) / (SKAN view 3rd postback)

• (Inline) and (DDA)

Values are only filled in where Meta returns them for your ad account; otherwise they stay empty.

Lift Studies

Special integration: Lift Study reporting runs alongside the core Facebook Ads connection and is enabled per company by your Clarisights account team. Once it is enabled, the Facebook connection asks for the extra business_management permission.

Once enabled, Clarisights imports the Brand Lift and Conversion Lift studies from the businesses the connected Facebook user belongs to and exposes them as a separate data source. Up to 720 days of study history is loaded when it is first enabled.

Per-cell metrics fall into three groups:

Limitations & known constraints

• Attribution model changes (2021): after Apple’s App Tracking Transparency changes, Meta moved to a 7-day click / 1-day view default and limited longer view windows. Historical data keeps the windows that applied when it was reported.

• SKAdNetwork constraints: SKAN data is aggregated, delayed by Apple’s postback timers, and subject to privacy thresholds, so low-volume rows may be empty. SKAN totals do not match Pixel or MMP-attributed totals.

• Breakdowns are stored per campaign: campaign breakdowns cannot be combined with Ad Set or Ad dimensions in the same widget; value rule set breakdowns are stored per ad set.

• Breakdown thresholds: Meta withholds demographic and location rows below its minimum thresholds, so breakdown totals can be lower than the unbroken total.

• Reporting delay and restatement: most metrics arrive within a few hours, but conversion and SKAN metrics can take up to about 72 hours to settle, and Meta restates recent days as late conversions arrive. Clarisights re-pulls recent days on every refresh to pick these up.

• Conversions API coverage: on iOS Safari and other browsers that limit cookies, Pixel-only setups under-report; Meta recommends sending events through the Conversions API as well.

• Asset rows need multi-asset ads: Meta only reports per-asset results for ads that use multiple creative assets (Dynamic Creative, flexible format and similar). Single-creative ads appear at the Ad level only.

• Product reporting (beta): product rows exist only for Advantage+ catalog ads, carry no conversion metrics, and cover a rolling three-day window on each refresh.

• Lift Studies need setup: lift study data does not appear until Lift Study reporting is enabled for your company, and results follow Meta’s publication timing for each study.

• Additional attribution models: incremental, engaged-view, first-conversion and similar windows are only filled in where Meta returns them for your ad account.

• Large accounts: Meta limits how much data an app can request per ad account. When an account is throttled, Clarisights pauses requests for it until the limit resets and retries automatically, so very large accounts can take longer to refresh.

• Access revoked: if access is removed in Meta Business Manager, or the connecting user loses access to an ad account, that account stops syncing until someone with access reconnects with Refresh Token.

Operating notes

• API version: Meta Marketing API v26.0 (Graph API). Clarisights follows Meta’s version schedule and moves to new versions as older ones are retired.

• Refresh schedule: reporting data is refreshed several times a day for all levels, and the current day is refreshed through the day. Account status and creative details are refreshed daily. Product reporting (beta) re-pulls the last three days on each run.

• Lookback / backfill: routine refreshes cover recent days; longer historical ranges can be backfilled on request through support. Lift Studies load up to 720 days when first enabled.

• Adding new ad accounts: ad accounts created or shared with the Facebook user after the first connection are not added automatically. Click Refresh Token (or + Account for a different Facebook user), sign in, and select the new accounts.

• Multiple Business Managers: one Facebook user can connect ad accounts from several Business Managers in a single sign-in.

• Currency conversion: spend and conversion values are pulled in the ad account’s currency and converted to your reporting currency; the (Local currency) metrics keep the original amounts. See Currency Conversion.

• Access tokens: when you connect, Clarisights exchanges Facebook’s short-lived token for a long-lived one. Reconnect with Refresh Token if the token expires or is revoked, for example after a password change or a change to your Business Manager permissions.

Need help?

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

• The integration name and ad account ID (from the Facebook Accounts page in Integrations)

• 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 used in the widget you are comparing

• For asset, product or Lift Study questions: the ad ID and the asset, product or study ID involved