Meta Ads Integration

Server-side Conversions API (CAPI) forwarding for Meta (Facebook) ads.

Prerequisites#

Meta Business Manager account
Facebook Dataset (Pixel) created in Events Manager

Setup#

In Meta Events Manager → Data Sources → select your pixel → Settings → copy the Dataset ID.
In Meta Business Settings → System Users → create a system user → generate an access token with the ads_management permission.
In the AppRefer dashboard → Settings → Integrations → Meta: paste the Dataset ID and Access Token → Save.
Click "Test Connection" to verify your credentials are valid.

How It Works#

When a user attributed to Meta (has an fbclid) triggers an event, AppRefer sends it to the Conversions API:

Meta CAPI Endpoint

POST graph.facebook.com/v24.0/{datasetId}/events

The fbclid is formatted as fb.1.{timestamp}.{fbclid} in the fbc parameter of the request payload.

Event Mapping#

AppRefer Event	Meta CAPI Event
install	Lead
purchase / INITIAL_PURCHASE / RENEWAL	Purchase
sign_up	CompleteRegistration
start_trial / qualified_trial	StartTrial
subscribe	Subscribe
add_to_cart	AddToCart
initiate_checkout	InitiateCheckout
search	Search
view_content	ViewContent

Advanced Matching#

When available, hashed PII is included in the user_data object sent to Meta. Supported fields:

Field	Key	Format
Email	em	SHA256(lowercase(trim(email)))
Phone	ph	SHA256(E.164 format)
First Name	fn	SHA256(lowercase(trim(name)))
Last Name	ln	SHA256(lowercase(trim(name)))
Date of Birth	db	SHA256(YYYYMMDD)

Improve Match Rates

Advanced Matching improves match rates by 20-30%. Call setAdvancedMatching() in the SDK after user login to provide hashed PII for better conversion attribution.

Ad Spend Sync and Shared Accounts#

Add each Meta ad account to adAccountIds. AppRefer reads the account's ISO currency directly from Meta and stores and displays campaign spend in that currency. Campaign and app totals are only calculated when their spend rows use one currency; mixed-currency totals are labelled instead of adding unlike units.

An account used by more than one app must also have an app-specific adAccountOwnership rule with mode shared and either exact campaign IDs or explicit campaign-name prefixes owned by that app:

Meta cost-sync integration config

{
  "adAccountIds": ["act_123456789"],
  "adAccountOwnership": {
    "act_123456789": {
      "mode": "shared",
      "campaignNamePrefixes": ["BR |"]
    }
  }
}

Shared accounts fail closed

A shared account without a non-empty campaign ID or name-prefix allowlist contributes no spend and records a sync error. If any ownership map is present, every configured account must have a matching rule. This prevents a sibling app's campaigns from being assigned to the current app. Existing ad-account-only configurations keep their historical dedicated-account behavior; add an explicit shared rule before reusing an account across apps.

Deduplication#

Each event is sent with a unique event_id. Meta automatically deduplicates events with the same event_id within a 48-hour window.