Meta Ads

When you finish, one Datalyr event reaches the Meta Conversions API and appears in Events Manager.

Before you start

Requirement	Detail
Meta login	Has access to the ad account in Meta Business settings
Meta Pixel ID	Events Manager → Data sources, the 15-16 digit ID under the dataset name
Test Events code	Events Manager → Test events, the `TEST…` string
A live event	The trigger event exists in Events

Connect Meta

Open Sources

Open Sources. Find the Meta Ads card.

Authorize

Select connect. Complete Facebook Login for Business. Approve every requested permission.

Pick the ad account

Choose the ad account that runs the campaigns. Select set as primary.

The card reads needs primary account until you finish step 3, and we pull campaign spend only after that. To change the primary account, select disconnect, then reconnect. Disconnecting clears the synced Meta campaign data.

Create the rule

Open the editor

Open Conversions. Select manage rules. Select new rule.

Set the trigger

Fill rule name. Pick the trigger event. Pick Meta as target platform.

Pick the pixel

Pick the pixel under Meta Pixel / App. Select next.

Map the event

Pick the platform standard event. Set value to dynamic for revenue events. Set currency.

Save

Select save. Enable the rule.

Reference

We post to POST /v25.0/{pixel_id}/events on the Meta Graph API.

Standard events

Asset type	Event names we send
Pixel (web, server)	`AddPaymentInfo`, `AddToCart`, `AddToWishlist`, `CompleteRegistration`, `Contact`, `InitiateCheckout`, `Lead`, `Purchase`, `Schedule`, `Search`, `StartTrial`, `SubmitApplication`, `Subscribe`, `ViewContent`
App	`fb_mobile_activate_app`, `fb_mobile_add_to_cart`, `fb_mobile_complete_registration`, `fb_mobile_content_view`, `fb_mobile_initiated_checkout`, `fb_mobile_purchase`, `fb_mobile_search`

Matching fields in `user_data`

Field	Source	Normalization before SHA-256
`em`	email in the event, the user profile, or an email-shaped `user_id`	lowercase, trim; rejected unless it matches `[email protected]`
`ph`	phone in the event or the user profile	digits only, country code kept, leading `+` removed
`fn`, `ln`	first and last name, or the first and last word of a full name	lowercase, trim
`ct`	city, or `geo_city` from the event	lowercase, every character outside `a-z` removed
`st`	state, or `geo_region`	mapped to a 2-letter lowercase code
`zp`	postal code	lowercase, spaces and dashes removed, first 5 characters for `us`
`country`	country, or `geo_country_code`	mapped to a lowercase ISO alpha-2 code; omitted when unmappable
`db`	date of birth	`YYYYMMDD`
`ge`	gender	`m` or `f`; anything else is omitted
`external_id`	array of `user_id`, `visitor_id`, and mapped IDs	hashed verbatim, with no lowercase and no trim
`fbc`	`_fbc` cookie, or built from `fbclid`	not hashed
`fbp`	`_fbp` cookie	not hashed
`client_ip_address`	event IP, or the linked visitor record	not hashed
`client_user_agent`	browser user agent	not hashed; dropped when it starts with `node`, `undici`, `axios`, `got`, `curl`, `python`, `java`, `go-http-client`, or `wget`
`madid`, `anon_id`	advertising ID and install ID, `action_source: app` only	not hashed

We build fbc as fb.1.{creation_time_ms}.{fbclid}. The creation time is the moment the fbclid first arrived, not the conversion time.

Value, currency, and `custom_data`

Field	Rule
`value`	The rule’s `value_path`, else `value_static`, else `value` / `revenue` / `total` / `amount` in the event
`currency`	The rule’s currency. Datalyr writes `USD` if the rule sets none
Other fields	`order_id`, `predicted_ltv`, `content_ids`, `content_type`, `content_name`, `content_category`, `num_items`, `search_string`, `customer_type`, `num_previous_purchases`

`action_source`

Event source	`action_source`	Effect
Web SDK	`website`	Datalyr sends `event_source_url` and `referrer_url`
iOS, Android, React Native SDK	`app`	Datalyr sends `app_data` with `extinfo` and `madid`
Stripe, Shopify, RevenueCat, Superwall, Whop, ClickFunnels, Checkout Champ, server API	`system_generated`	Datalyr sends no URL

Deduplication

We send event_id, the same UUID the browser Meta Pixel fires with, and Meta collapses the pair into one conversion. This works only when the Pixel and Datalyr fire on the same page load.

Verify

Set a Test Events code before you select send test event. Meta has no validate-only mode, so a test without a code creates a real billable conversion.

Open Conversions. Select manage rules. Open your rule.
Select send test event.
Open Events Manager → Test events in Meta.
Confirm the event name, value, and currency match the rule.
Return to Datalyr. Confirm the rule’s sent count went up by 1.

When it does not work

Symptom	Cause	Check	Fix
Rule detail shows `skipped`, reason `test_event_code_required`	The rule has no Test Events code	The rule’s `config.test_event_code`	Contact support to set the Test Events code
Delivery status `skipped`, reason `zero_value_purchase`	A `Purchase` resolved to a value of 0	The `value_path` against a real event payload	Point `value_path` at the amount field, or pick a different platform event
Delivery status `skipped`, reason `event_too_old`	`event_time` is over 7 days old	The event’s timestamp in Events	Meta rejects these. Fix the source’s delivery lag
HTTP 400, error `code: 100`	`Purchase` carries a value but no currency	The rule’s currency field	Set a currency on the rule
HTTP 400	Bad pixel ID, or a field Meta rejects	The pixel ID against Events Manager	Repick the asset in the rule
Error `code: 190`	The Meta token expired or was revoked	The card state in Sources	Select disconnect, then reconnect
`events_received: 0` with no error	Meta accepted the request but ingested nothing	The delivery response body	Nothing. We retry once through the dead-letter queue
Card reads `needs primary account`	Authorization finished, no ad account chosen	The Meta Ads card	Select select account
Match quality is low	Only `fbp` reached Meta, with no email or phone	`user_identifiers_count` on the delivery row	Collect email at checkout, or map `em` in the rule

Conversion delivery: retry, dedup, and status rules for every platform.
Conversions: read one delivery row and its response body.
Attribution: how fbclid reaches a server-side purchase.

Get started

Installation

Revenue

Using Datalyr

Advanced

Integrations

Account & billing

Troubleshooting

Before you start

Connect Meta

Create the rule

Reference

Standard events

Matching fields in `user_data`

Value, currency, and `custom_data`

`action_source`

Deduplication

Verify

When it does not work

Next

​Before you start

​Connect Meta

​Create the rule

​Reference

​Standard events

​Matching fields in user_data

​Value, currency, and custom_data

​action_source

​Deduplication

​Verify

​When it does not work

​Next

Before you start

Connect Meta

Create the rule

Reference

Standard events

Matching fields in `user_data`

Value, currency, and `custom_data`

`action_source`

Deduplication

Verify

When it does not work

Next