From 830791edf3cc8c9aced11502d36de951339ac450 Mon Sep 17 00:00:00 2001 From: Bilal Mansouri <124762008+bighadj22@users.noreply.github.com> Date: Tue, 8 Sep 2026 13:35:49 +0100 Subject: [PATCH] docs(skills): vendor official Meta Pixel & Conversions API references MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the meta-ads skill: 23 unaltered official documentation pages from developers.facebook.com (fetched with Firecrawl, source URL + date prefixed on each file), organized as: - references/pixel/ — 9 docs: overview, get-started, standard-events reference, conversion tracking, advanced matching, SPA, custom audiences, GDPR, data processing options - references/conversions-api/ — 14 docs: overview, get-started, using-the-api, full parameters set (server-event, customer-information, custom-data, original-event, main-body), deduplication, best practices, verifying setup, offline events, payload helper SKILL.md indexes the docs, maps them onto CodFlow's tracking stack (theme01 pixel scripts, the CAPI workflow, capi_event_log, the browser-eventID === server-event_id dedup contract), and sets working rules for tracking changes: ground every change against these docs, never break the dedup equality, a conversion mode must fire from both sides deliberately, and the reference files themselves are read-only. --- .agents/skills/meta-ads/SKILL.md | 106 ++++ .../conversions-api/capi-best-practices.md | 164 ++++++ .../capi-custom-data-parameters.md | 106 ++++ .../capi-customer-information-parameters.md | 84 +++ .../conversions-api/capi-deduplication.md | 123 +++++ .../conversions-api/capi-get-started.md | 105 ++++ .../capi-main-body-parameters.md | 18 + .../conversions-api/capi-offline-events.md | 180 ++++++ .../capi-original-event-parameters.md | 30 + .../conversions-api/capi-overview.md | 67 +++ .../conversions-api/capi-parameters.md | 119 ++++ .../conversions-api/capi-payload-helper.md | 202 +++++++ .../capi-server-event-parameters.md | 56 ++ .../conversions-api/capi-using-the-api.md | 511 ++++++++++++++++++ .../conversions-api/capi-verifying-setup.md | 65 +++ .../pixel/pixel-advanced-matching.md | 82 +++ .../pixel/pixel-conversion-tracking.md | 322 +++++++++++ .../pixel/pixel-custom-audiences.md | 40 ++ .../pixel/pixel-data-processing-options.md | 37 ++ .../meta-ads/references/pixel/pixel-gdpr.md | 65 +++ .../references/pixel/pixel-get-started.md | 112 ++++ .../references/pixel/pixel-overview.md | 54 ++ .../pixel/pixel-reference-standard-events.md | 65 +++ .../pixel/pixel-single-page-apps.md | 88 +++ 24 files changed, 2801 insertions(+) create mode 100644 .agents/skills/meta-ads/SKILL.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-best-practices.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-custom-data-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-customer-information-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-deduplication.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-get-started.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-main-body-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-offline-events.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-original-event-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-overview.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-payload-helper.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-server-event-parameters.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-using-the-api.md create mode 100644 .agents/skills/meta-ads/references/conversions-api/capi-verifying-setup.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-advanced-matching.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-conversion-tracking.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-custom-audiences.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-data-processing-options.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-gdpr.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-get-started.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-overview.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-reference-standard-events.md create mode 100644 .agents/skills/meta-ads/references/pixel/pixel-single-page-apps.md diff --git a/.agents/skills/meta-ads/SKILL.md b/.agents/skills/meta-ads/SKILL.md new file mode 100644 index 0000000..70d5ae1 --- /dev/null +++ b/.agents/skills/meta-ads/SKILL.md @@ -0,0 +1,106 @@ +--- +name: meta-ads +description: Official Meta (Facebook) Pixel and Conversions API reference docs for CodFlow's tracking stack — standard events, event parameters, deduplication, advanced matching, test events, and best practices. Use whenever working on Meta Pixel integration, CAPI server events, conversion tracking, event deduplication, attribution, or reviewing PRs that touch tracking (cod-server/src/workflows/capi.ts, capi-helpers.ts, capi_event_log, theme01 pixel scripts, store_pixel_config). +--- + +# Meta Ads — Pixel & Conversions API Official Documentation + +CodFlow's tracking stack (Meta Pixel in theme01 + Conversions API in +cod-server) must always match **Meta's official behavior**. This skill +vendors the official documentation so every change — ours or a +contributor's — can be grounded against the real spec instead of guesses, +blog posts, or AI memory. + +**Rule for agents and contributors: any tracking change must be verified +against these docs before review.** When replying to a tracking PR, read +the relevant reference here first and cite it. + +## The docs (all unaltered official content, fetched from developers.facebook.com) + +### Pixel — browser side (`fbq()`) + +| File | What it covers | +|---|---| +| `references/pixel/pixel-overview.md` | What the Pixel is, redundant setup with CAPI | +| `references/pixel/pixel-get-started.md` | Installing the base code, the `fbq` queue | +| `references/pixel/pixel-reference-standard-events.md` | **The standard-event table** — exact definitions of `Purchase`, `Lead`, `InitiateCheckout`, etc. + object properties. The source of truth for "which event is this action?" | +| `references/pixel/pixel-conversion-tracking.md` | Firing events on actions vs page load, purchase-confirmation-page pattern | +| `references/pixel/pixel-advanced-matching.md` | `em`, `ph` etc. customer params on `fbq('init')` | +| `references/pixel/pixel-single-page-apps.md` | SPA pitfalls (irrelevant to our full-page loads — know why) | +| `references/pixel/pixel-custom-audiences.md` | Audience creation from Pixel data | +| `references/pixel/pixel-gdpr.md` | GDPR/Limited Data Use reasoning | +| `references/pixel/pixel-data-processing-options.md` | `_fbp` cookie + data processing options | + +### Conversions API — server side (`/events` endpoint) + +| File | What it covers | +|---|---| +| `references/conversions-api/capi-overview.md` | What CAPI is, redundant setup recommendation | +| `references/conversions-api/capi-get-started.md` | System user tokens, access, first request | +| `references/conversions-api/capi-using-the-api.md` | Endpoint mechanics, payloads, batching, error handling | +| `references/conversions-api/capi-parameters.md` | Parameters index | +| `references/conversions-api/capi-server-event-parameters.md` | **`event_name`, `event_time`, `event_id`, `event_source_url`, `action_source`** — the per-event field contract | +| `references/conversions-api/capi-customer-information-parameters.md` | Hashed `ph`, `em`, `client_ip_address`, `client_user_agent`, `fbp`, `fbc` — what we send and how it's normalized | +| `references/conversions-api/capi-custom-data-parameters.md` | `value`, `currency`, `contents`, `content_ids`, `order_id`, `num_items` | +| `references/conversions-api/capi-original-event-parameters.md` | Original-event dedup fields (aggregated/merged events) | +| `references/conversions-api/capi-main-body-parameters.md` | `data[]`, `test_event_code` wrapper | +| `references/conversions-api/capi-deduplication.md` | **Pixel ↔ CAPI dedup: browser `eventID` must equal CAPI `event_id` AND names must match.** The rule behind CodFlow's eventID = orderId pattern | +| `references/conversions-api/capi-best-practices.md` | Meta's recommended architecture, timing, and matching quality guidance | +| `references/conversions-api/capi-verifying-setup.md` | Events Manager validation, Test Events | +| `references/conversions-api/capi-offline-events.md` | Offline conversion semantics (delayed events — the category our purchase-on-delivery model lives in) | +| `references/conversions-api/capi-payload-helper.md` | Meta's interactive payload builder (for debugging shapes) | + +## How CodFlow maps onto these docs (quick orientation) + +- **Browser:** theme01's `BaseHead.astro` loads the canonical `fbevents.js` + snippet (PageView on load); `thank-you.astro` fires the conversion event + with `{ eventID: orderId }` — the fourth `fbq` argument, per the dedup doc. +- **Server:** `cod-server/src/workflows/capi.ts` (Cloudflare Workflow) + sends the mirrored event via `/events` with `event_id: orderId`; + `capi-helpers.ts` gates which status transitions trigger it; + `capi_event_log` records what was sent (and powers idempotency). +- **Config:** `store_pixel_config` (pixel id, access token, test event + code, conversion event choice, test mode) — Settings → Tracking. +- **Dedup contract:** browser `eventID` === CAPI `event_id` === orderId, + same `event_name` on both sides. Any tracking change that breaks this + equality double-counts conversions (see capi-deduplication.md). +- **Standard-event semantics:** which CodFlow moment maps to which Meta + event is governed by pixel-reference-standard-events.md — notably + `Purchase` is defined as at-checkout ("lands on thank you or + confirmation page") and `Lead` as a completed sign-up. COD + purchase-on-delivery is an offline-style delayed Purchase (see + capi-offline-events.md) — legitimate, but it must be a deliberate + merchant choice, not a silent default. + +## Working rules for tracking changes + +1. **Ground first.** Read the relevant reference file(s) above before + writing or reviewing a single line of tracking code. Cite the doc in + the PR/review when a decision hinges on Meta behavior. +2. **Never break the dedup equality** (browser eventID === server + event_id, matching names) — silent double-counting or + double-sending is the #1 tracking bug class. +3. **A new conversion-event mode must fire from BOTH sides** (browser + + CAPI mirror) or from exactly ONE side deliberately, never accidentally. + PR #103's lesson: a mode that exists only in the settings enum is not a + feature. +4. **`capi_event_log` is the idempotency ledger** — anything that can fire + twice (webhook retries, status toggles) must be guarded through it. +5. **Test Mode** (`test_event_code`) exists for verification — use + capi-verifying-setup.md's flow before claiming an event works. +6. **Docs are read-only reference.** These files are unaltered Meta + content (only a source header is prepended). Never edit them to match + code — if code and docs disagree, the CODE changes (or Meta did, and + we re-fetch). + +## Refreshing the docs + +Meta updates its docs; when a tracking question can't be answered from +these files (or the content looks outdated), re-fetch with Firecrawl: + +```sh +firecrawl scrape "https://developers.facebook.com/documentation/" --only-main-content +``` + +Keep the source header (URL + fetch date) on every file so staleness is +auditable. Content below the header stays unaltered. diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-best-practices.md b/.agents/skills/meta-ads/references/conversions-api/capi-best-practices.md new file mode 100644 index 0000000..37b8cb9 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-best-practices.md @@ -0,0 +1,164 @@ + + +Ads and Commerce + +Was this helpful? + +# Best Practices - Conversions API + +Updated: Jun 28, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices.md) + +Use these best practices as general recommendations to make the most effective use of the Conversions API. Follow the [implementation](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices#capi-implement) and [post-implementation](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices#post-implementation) recommendations to ensure a smooth integration and optimal results when sharing data with Meta. + +In addition to the following best practices, [watch this video](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#video) for a more hands-on tutorial on using the Conversions API. The video guides you through how to: + +[Send Requests](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#send) +Handle [Dropped Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#dropped-events), [Event Transaction Time](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#event-transaction-time), and [Batch Requests](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#batch-requests) +[Verify Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#verify) +Use the [Test Events Tool](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#testEvents) + +Web, app, and physical store events shared using the Conversions API require specific parameters. The list of [required parameters is available here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters). + +## Implementation + +When setting up your campaign, simplify the account structure and use the following established campaign best practices: + +Implement [Learning Phase best practices⁠](https://www.facebook.com/business/help/112167992830700?id=561906377587030) +Refrain from making [significant campaign edits⁠](https://www.facebook.com/business/help/316478108955072?id=561906377587030) +[Minimize Auction Overlap⁠](https://www.facebook.com/business/help/537699989762051?id=561906377587030) +Select [Automatic Placements⁠](https://www.facebook.com/business/help/965529646866485?id=802745156580214) and [Campaign Budget Optimization⁠](https://www.facebook.com/business/help/153514848493595?id=629338044106215) +[Choose the right bid strategy⁠](https://www.facebook.com/business/help/1619591734742116?id=2196356200683573) based on your business goals + +### Set up redundant events + +Use the Conversions API in addition to the Meta Pixel, and share the same events using both tools. This is a _redundant event setup_. For example, if you share `Purchase`, `Initiate Checkout`, and `Contact` events using the Meta Pixel, you should also share those same events from your server using the Conversions API. + +The Conversions API allows you to share website events that the Pixel may lose due to network connectivity issues or page loading errors. The Conversions API can also be used to share other types of important events and data that occur offline or at a later time that the Pixel cannot capture. + +### Ensure redundant events can be deduplicated + +When sending redundant events using the Meta Pixel and Conversions API, ensure that both events use the identical `event_name` and that either `event_id` or a combination of `external_id` and `fbp` are included. Include all of these parameters to help Meta properly deduplicate events and reduce double reporting of identical events. [Learn more about deduplication, when it’s necessary and how to set it up.⁠](https://www.facebook.com/business/help/823677331451951) + +### Send required and recommended parameters + +The following [server event](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event) and [customer information](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) parameters are required: + +| Parameter | Type | When Required | +| --- | --- | --- | +| [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) | Server event | All events | +| [`event_source_url`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-source-url) | Server event | All website events | +| [`client_user_agent`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#client-user-agent) | Customer information | All website events | + +By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. Also include the `external_id` and `event_id` event parameters for all events. + +Sending additional [customer information parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) may help increase Event Match Quality. You can use only matched events for ads attribution and ad delivery optimization. Higher matching quality produces better results. You cannot use unmatched events for attribution or ad delivery optimization, but you can still use them for basic measurement. Examples of high-quality customer information parameters include: + +email address (`em`) +IP address (`client_ip_address`) +name (`fn` and `ln`) +phone number (`ph`) + +### Baseline requirements for matching + +Following the release of Graph API version 13.0, Meta will be updating the baseline requirements for which combinations of customer information parameters are considered valid with a Conversions API event. These changes will help Meta provide better feedback for when an event has a combination of customer information parameters that is so broad that it is unlikely to be effective for matching. + +An event is considered invalid if it only includes customer information parameters that consist of one of the following combinations, (or a subset thereof). + +`ct` \+ `country` \+ `st` \+ `zp` \+ `ge` \+ `client_user_agent` +`db` \+ `client_user_agent` +`fn` \+ `ge` +`ln` \+ `ge` + +For example, if an event had only the customer information parameters `ge`, `ct`, `st`, and `country` (this could correspond to a man in Menlo Park, California, USA), it would be rejected because those customer information parameters are a subset of one of the above combinations. + +### Ensure `fbp` and `fbc` parameters are refreshed + +The [`fbp`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) and [`fbc`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) parameters are cookie values typically set on your site visitors’ browsers in connection with Meta’s first-party cookie solution, and are subject to change. If you send them as [user parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters), you should regularly refresh their values. + +These values will be set as first-party cookies when the Meta Pixel is implemented on your website and can be retrieved for use in Conversions API requests. + +### Share events closer to real time + +Sharing events when they happen can help your campaigns achieve the best results. You can share server events using the Conversions API in real time or in [batches](https://developers.facebook.com/docs/graph-api/making-multiple-requests) close to real time. + +### Use test events + +Use the [Test Events tool⁠](https://www.facebook.com/business/help/1624255387706033) to validate your Conversions API connection. Typically, developers should use their own customer information parameters (for example, name, email address, phone number) for test events, because these events may get discarded if they don’t match a Facebook or Meta account. + +You can use the Test Events tool to: + +Verify that you’ve set up your server events correctly and Meta has received them. +Verify that you’ve deduplicated events correctly by seeing which events were processed and deduplicated. +Debug any unusual activity. + +[Learn how to test your server events using the Test Events tool.⁠](https://www.facebook.com/business/help/1624255387706033) + +### Use Payload Helper + +Fill out the required and recommended data parameter fields in the [Payload Helper](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper) tool to see how your payload should be structured and to get recommendations for which parameters to include. + +### Use our Business SDK + +The [code samples](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api) in our documentation include Business SDK examples in Python, Java, Ruby, PHP, and Node. They can save some development effort, such as hashing user parameters, which is done automatically in the Business SDK. + +If you are not planning to use the Business SDK, implement [hashing](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#normalize-and-hash). + +### Use the Conversions API for offline events + +The Conversions API [supports all offline events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events) and should be used as the comprehensive container for these types of events. Examples include physical store sales, phone calls, actions taken on devices (such as smart TVs or game consoles), and offline subscriptions. + +When sending offline events, be sure to include the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) event parameter, and choose the appropriate value (should not be `website`). The action source is required to determine the campaign objectives for which the event is intended. + +By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. + +## Additional best practices for partners + +### Agencies: send `partner_agent` string + +Partners or agencies that share events on behalf of their advertisers should send a unique [`partner_agent`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/set-up-conversions-api-as-a-platform#attribute-events-to-your-platform-using-the-partner_agent-field) string, including platform name as documented. If applicable, work with your dedicated Meta representative to decide on a suitable agent string. + +### Website platforms: onboarding advertisers + +By default, website platform partners may consider whether to offer Conversions API selectively or to opt-in advertisers. The Meta Pixel and Conversions API share the same business terms. Opt-in your customers to also share their data using the Conversions API when they set up the Meta Pixel. Using both tools provides more complete and reliable data sharing. Provide your customers with information about both the Conversions API and Meta Pixel to help inform their choice. + +## Post-implementation + +### Check Event Match Quality + +If you share server events using the Conversions API, you can see the Event Match Quality (EMQ) for each event in Events Manager. An event’s EMQ score (out of 10) indicates how effective your server event’s customer information may be at matching it to a Facebook or Meta account. Learn more about EMQ best practices [here⁠](https://www.facebook.com/business/help/765081237991954?id=818859032317965). + +Event Match Quality is currently available only for web events. For other event types such as offline and physical store events, app events, conversion leads or any integration under alpha or beta stages, contact your Meta representative for guidance on improving event match quality. + +### Run a test + +When using the Conversions API, test and optimize your Meta advertising strategy. Some testing options include: + +**[Conversion Lift Study](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lift-studies)**: Understand the incremental performance impact of using server events. + +**[Split Testing](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/split-testing)**: Understand which campaign strategy achieves the best and most efficient outcomes to optimize performance. + +## Learn more + +[Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api) +[Conversions API End-to-End Implementation](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/end-to-end-implementation) +[`fbp` and `fbc` parameters, Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) +[Payload Helper, Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper) +[Parameters, Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) +[Offline Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events) +[Conversions API `partner_agent` string](https://developers.facebook.com/documentation/ads-commerce/conversions-api/set-up-conversions-api-as-a-platform#attribute-events-to-your-platform-using-the-partner_agent-field) +[Deduplication for Meta Pixel and Conversions API Events, Help Center⁠](https://www.facebook.com/business/help/823677331451951) +[Batch Requests](https://developers.facebook.com/docs/graph-api/making-multiple-requests) +[Test Your Server Events Using the Test Events Tool, Help Center⁠](https://www.facebook.com/business/help/1624255387706033) +[Meta Business SDK](https://developers.facebook.com/docs/business-sdk) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-custom-data-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-custom-data-parameters.md new file mode 100644 index 0000000..ef0447b --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-custom-data-parameters.md @@ -0,0 +1,106 @@ + + +Ads and Commerce + +Was this helpful? + +# Standard Parameters + +Updated: Nov 17, 2025 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data.md) + +This table lists all standard parameters users can send to Meta. + +| Website Standard Parameters | App Standard Parameters | Offline Standard Parameters | Description | +| --- | --- | --- | --- | +| `availability` | `fb_availability` | `availability` | Value must be `available_soon`, `for_rent`, `for_sale`, `off_market`, `recently_sold` or `sale_pending`. | +| `body_style` | `fb_body_style` | `body_style` | Body style of the vehicle: `CONVERTIBLE`, `COUPE`, `HATCHBACK`, `MINIVAN`, `TRUCK`, `SUV`, `SEDAN`, `VAN`, `WAGON`, `CROSSOVER`, `OTHER`. | +| `checkin_date` | `fb_checkin_date` | `checkin_date` | The date the user is wanting to check-in to the hotel in the hotel’s time-zone. We accept dates in `YYYYMMDD`, `YYYY-MM-DD`, `YYYY-MM-DDThh:mmTZD` and `YYYY-MM-DDThh:mm:ssTZD`. | +| `city` | `fb_city` | `city` | Provide the city of the location from user intent. | +| `condition_of_vehicle` | `fb_condition_of_vehicle` | `condition_of_vehicle` | Condition of vehicle. | +| `content_ids` | `fb_content_ids` | `content_ids` | The content IDs associated with the event, such as product SKUs for items in an `AddToCart` event. | +| `content_type` | `fb_content_type` | `content_type` | Should be set to `product` or `product_group`:
Use `product` if the keys you send represent products. Sent keys could be `content_ids` or `contents`.
Use `product_group` if the keys you send in `content_ids` represent product groups. Product groups are used to distinguish products that are identical but have variations such as color, material, size or pattern. | +| `contents` | `fb_contents` | `contents` | A list of JSON objects that contain the product IDs associated with the event plus information about the products.
Available fields: `id`, `quantity`, `item_price`, `delivery_category`. | +| `country` | `fb_country` | `country` | Provide the country of the location from user intent. | +| `currency` | `fb_currency` | `currency` | Required for purchase events.
The currency for the `value` specified, if applicable. Currency must be a valid [ISO 4217⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FISO_4217%3Ffbclid%3DIwAR2qARpy3ufnmcEY-sVHvTzUA1AsFOsLYdNsrZP6UYAMRt6NVM5SAhfzfJg&h=AUBYDlnZW9N6Dv7h1E_SI--rWxc2CUQSj3OmfukSS4GYEWVqnI13x7H-rJCMbNuQeepc2Ct4OAtZt7BxeEbNFaSbzF0rj7w_jyju5kx3SNdUbueKbHkdlG0_e_1uAlgo3TUg31BVqCfLQg) three-digit currency code. | +| `delivery_category` | `fb_delivery_category` | `delivery_category` | Optional for purchase events.
Type of delivery for a purchase event. Supported values are:
`in_store` — Customer needs to enter the store to get the purchased product.
`curbside` — Customer picks up their order by driving to a store and waiting inside their vehicle.
`home_delivery` — Purchase is delivered to the customer’s home. | +| `departing_arrival_date` | `fb_departing_arrival_date` | `departing_arrival_date` | The date and time for arrival at the destination of the outbound journey. | +| `departing_departure_date` | `fb_departing_departure_date` | `departing_departure_date` | The date and time for start of the outbound journey. | +| `destination_airport` | `fb_destination_airport` | `destination_airport` | Use official IATA code of destination airport. | +| `destination_ids` | `fb_destination_ids` | `destination_ids` | If you have a destination catalog, you can associate one or more destinations in your destination catalog with a specific hotel event. | +| `dma_code` | `fb_dma_code` | `dma_code` | The Designated Market Area (DMA) code, which the user looks at for offers. | +| `drivetrain` | `fb_drivetrain` | `drivetrain` | Drivetrain of the vehicle: `4X2`, `4X4`, `AWD`, `FWD`, `RWD`, `OTHER`, `NONE`. | +| `exterior_color` | `fb_exterior_color` | `exterior_color` | Exterior color. | +| `fuel_type` | `fb_fuel_type` | `fuel_type` | Fuel type of the vehicle: `DIESEL`, `ELECTRIC`, `FLEX`, `GASOLINE`, `HYBRID`, `PETROL`, `PLUGIN_HYBRID`, `OTHER`, `NONE`. | +| `hotel_score` | `fb_hotel_score` | `hotel_score` | An indicator representing the relative value of this hotel to the advertiser compared to its other hotels. | +| `interior_color` | `fb_interior_color` | `interior_color` | Interior color. | +| `lead_event_source` | `lead_event_source` | `lead_event_source` | Lead event source. | +| `lease_end_date` | `fb_lease_end_date` | `lease_end_date` | Specified using ISO 8601 date format: `YYYY-MM-DD`. | +| `lease_start_date` | `fb_lease_start_date` | `lease_start_date` | Allows us to recommend properties based off their date availability (using `available_dates_price_config` in the catalog), and improve the user landing experience (using template tags). | +| `listing_type` | `fb_listing_type` | `listing_type` | Value must be `for_rent_by_agent`, `for_rent_by_owner`, `for_sale_by_agent`, `for_sale_by_owner`, `foreclosed`, `new_construction` or `new_listing`. | +| `make` | `fb_make` | `make` | Make or brand of the vehicle. | +| `mileage.unit` | `fb_mileage.unit` | `mileage.unit` | Mileage unit. | +| `mileage.value` | `fb_mileage.value` | `mileage.value` | Mileage value. | +| `model` | `fb_model` | `model` | Model of the vehicle. | +| `neighborhood` | `fb_neighborhood` | `neighborhood` | Neighborhood of interest. | +| `net_revenue` | `net_revenue` | `net_revenue` | The margin value of a conversion event. | +| `num_adults` | `fb_num_adults` | `num_adults` | Number of adults that will be staying. | +| `num_children` | `fb_num_children` | `num_children` | Number of children that will be staying. | +| `num_infants` | `fb_num_infants` | `num_infants` | Number of infants that will be staying. | +| `num_items` | `fb_num_items` | `num_items` | Use only with `InitiateCheckout` events.
The number of items that a user tries to buy during checkout. | +| `order_id` | `fb_order_id` | `order_id` | The order ID for this transaction as a string. | +| `origin_airport` | `fb_origin_airport` | `origin_airport` | Use official IATA code of departure airport. | +| `postal_code` | `fb_postal_code` | `postal_code` | Postal code. | +| `predicted_ltv` | `predicted_ltv` | `predicted_ltv` | The predicted lifetime value of a conversion event. | +| `preferred_baths_range` | `fb_preferred_baths_range` | `preferred_baths_range` | Number of bathrooms chosen as range. | +| `preferred_beds_range` | `fb_preferred_beds_range` | `preferred_beds_range` | Number of bedrooms chosen as range. | +| `preferred_neighborhoods` | `fb_preferred_neighborhoods` | `preferred_neighborhoods` | Preferred neighborhoods. | +| `preferred_num_stops` | `fb_preferred_num_stops` | `preferred_num_stops` | Indicate the preferred number of stops the user is looking for. | +| `preferred_price_range` | `fb_preferred_price_range` | `preferred_price_range` | Preferred price range for vehicle. Min/max, up to 2 decimals. | +| `preferred_star_ratings` | `fb_preferred_star_ratings` | `preferred_star_ratings` | A tuple of minimum and maximum hotel star rating that a user is filtering for. | +| `price` | `fb_price` | `price` | Cost and currency of the vehicle. Format the price as the cost, followed by the [ISO currency code⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FISO_4217%3Ffbclid%3DIwAR2ULtemU7YsoTB8AJImQX-3SI6WZpHxKb3WXANzqKV00yn6PBbYGdGQmWs&h=AUBYDlnZW9N6Dv7h1E_SI--rWxc2CUQSj3OmfukSS4GYEWVqnI13x7H-rJCMbNuQeepc2Ct4OAtZt7BxeEbNFaSbzF0rj7w_jyju5kx3SNdUbueKbHkdlG0_e_1uAlgo3TUg31BVqCfLQg), with a space between cost and currency. | +| `product_catalog_id` | `product_catalog_id` | `product_catalog_id` | Product catalog id. | +| `property_type` | `fb_property_type` | `property_type` | Must be `apartment`, `condo`, `house`, `land`, `manufactured`, `other` or `townhouse`. | +| `region` | `fb_region` | `region` | State, district, or region of interest. | +| `returning_arrival_date` | `fb_returning_arrival_date` | `returning_arrival_date` | The date and time when the return journey is done. | +| `returning_departure_date` | `fb_returning_departure_date` | `returning_departure_date` | The date and time for start of the return journey. | +| `search_string` | `fb_search_string` | `search_string` | Use only with `Search` events.
A search query made by a user. | +| `state_of_vehicle` | `fb_state_of_vehicle` | `state_of_vehicle` | State of vehicle. | +| `suggested_destinations` | `fb_suggested_destinations` | `suggested_destinations` | Suggested destinations. | +| `suggested_home_listings` | `fb_suggested_home_listings` | `suggested_home_listings` | Suggested home listings. | +| `suggested_hotels` | `fb_suggested_hotels` | `suggested_hotels` | Suggested hotels. | +| `suggested_jobs` | `fb_suggested_jobs` | `suggested_jobs` | Suggested jobs. | +| `suggested_local_service_businesses` | `fb_suggested_local_service_businesses` | `suggested_local_service_businesses` | Suggested local service businesses. | +| `suggested_location_based_items` | `fb_suggested_location_based_items` | `suggested_location_based_items` | Suggested location based items. | +| `suggested_vehicles` | `fb_suggested_vehicles` | `suggested_vehicles` | Suggested vehicles. | +| `transmission` | `fb_transmission` | `transmission` | Transmission of the vehicle:: `AUTOMATIC`, `MANUAL`, `OTHER`, `NONE`. | +| `travel_class` | `fb_travel_class` | `travel_class` | Must be `economy`, `premium`, `business` or `first`. | +| `travel_end` | `fb_travel_end` | `travel_end` | Travel end date. | +| `travel_start` | `fb_travel_start` | `travel_start` | Travel start date. | +| `trim` | `fb_trim` | `trim` | Max characters: 50. | +| `user_bucket` | `fb_user_bucket` | `user_bucket` | User bucket. | +| `value` | `_valueToSum` | `value` | Required for purchase events or any events that utilize value optimization.
A numeric value associated with the event. This must represent a monetary amount. | +| `vin` | `fb_vin` | `vin` | VIN. | +| `year` | `fb_year` | `year` | Year the vehicle was launched in `yyyy` format. | +| | | `item_number` | Unique identifier to distinguish events within the same order or transaction. | +| | `ad_type` | | Ad type. | +| | `fb_content` | | A list of JSON object that contains the International Article Number (EAN) when applicable, or other product or content identifier(s) as well as quantities and prices of the products. Required: `id`, `quantity`.
Example: “\[{"id": "1234", "quantity": 2,}, {"id": "5678", "quantity": 1,}\]”. | +| | `fb_content_id` | | International Article Number (EAN) when applicable, or other product or content identifier(s). For multiple product ids: e.g. “\["1234","5678"\]”. | +| | `fb_description` | | A string description. | +| | `fb_level` | | Level of a game. | +| | `fb_max_rating_value` | | Upper bounds of a rating scale, for example 5 on a 5 star scale. | +| | `fb_payment_info_available` | | `1` for yes, `0` for no. | +| | `fb_registration_method` | | Facebook, Email, Twitter, etc. | +| | `fb_success` | | `1` for yes, `0` for no.. | +| | `_valueToSum` | | Numeric value of individual event to be summed in reporting. | + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-customer-information-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-customer-information-parameters.md new file mode 100644 index 0000000..719fb83 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-customer-information-parameters.md @@ -0,0 +1,84 @@ + + +Ads and Commerce + +Was this helpful? + +# Customer Information Parameters + +Updated: Jan 9, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters.md) + +The customer information parameters are a set of user identifiers you share alongside your event information. For more information about required and recommended parameters, see [Best Practices - Conversions API: Send Required and Recommended Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices#req-rec-params). + +In the Graph API v13.0 release there were new requirements around the combinations of customer information parameters that are considered valid. Please review the [best practices](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices#baseline-requirements-for-matching) to ensure your Conversions API integrations are not interrupted. + +Please visit the [Meta Privacy and Data Use Guide⁠](https://www.facebook.com/business/m/privacy-and-data?Data-Use-&-Ads) to learn what data is sent when using the Conversions API. + +Our systems are designed to not accept customer information that is unhashed Contact Information, unless noted below. Contact Information is information that personally identifies individuals, such as names, email addresses, and phone numbers, that we use for matching purposes only. If you are using the [Meta Business SDK](https://developers.facebook.com/docs/business-sdk), the hashing is done automatically. + +## Pixel Comparison + +You can send many of the customer information parameters through the Meta Pixel, though some (for example, `client_user_agent`) are sent automatically as part of how the internet works. For example, to send `external_id` through the Pixel, use the following code: + +``` +fbq('init', 'PIXEL_ID', {'external_id': 12345}); +``` + +Read about the other parameters you can pass with Pixel in the [Advanced Matching documentation](https://developers.facebook.com/docs/facebook-pixel/advanced/advanced-matching). + +Vice versa, make sure to apply the same set of customer information parameters your system is currently sharing to the browser side to the server side. + +## Formatting the `user_data` Parameters + +You must provide at least one of the following `user_data` parameters with the correct formatting in your request. + +_**Note**: If you are using the [parameter builder library](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameter-builder-library), the format will contain an additional appendix at the end of each param. Check the parameter builder library page for more details._ + +[Please download this CSV file](https://l.facebook.com/l.php?u=https%3A%2F%2Fscontent-lax7-1.xx.fbcdn.net%2Fv%2Ft39.8562-6%2F314008612_2367937923355843_814664035015443172_n.csv%3F_nc_cat%3D101%26ccb%3D1-7%26_nc_sid%3Db8d81d%26_nc_ohc%3DK2Qnp1FovtAQ7kNvwEtbhFd%26_nc_oc%3DAdq2tz5FfwHhGVahgLJZgm6M2EGLmqc62anJHy3h0XRTFshp7Jayaz_9qRMBNJIW3FE%26_nc_zt%3D14%26_nc_ht%3Dscontent-lax7-1.xx%26_nc_gid%3D3BAUPgLzsh_SSSD0QJMcKw%26_nc_ss%3D7b289%26oh%3D00_AQJFHv0bNHF4QOGW1q29OMgpK2OxvY09nqkKaoZqchq-Hw%26oe%3D6AA532A4&h=AUA_5w61yNHePD60Ol70WT0kj2wYt3TN1h9HsCpWUyYxS6GsTP3Q-q0V1tu1NXv5faLrZmeqezLVBWqRzjIKb88E_BN6ULnef6z5Qck7Y_P2FCWEHR4mgvP2FvWwynt1ty136MYf7YuRSw) for examples of properly normalized and hashed data for the parameters below. + +[Download (Right-click > Save Link As)](https://l.facebook.com/l.php?u=https%3A%2F%2Fscontent-lax7-1.xx.fbcdn.net%2Fv%2Ft39.8562-6%2F314008612_2367937923355843_814664035015443172_n.csv%3F_nc_cat%3D101%26ccb%3D1-7%26_nc_sid%3Db8d81d%26_nc_ohc%3DK2Qnp1FovtAQ7kNvwEtbhFd%26_nc_oc%3DAdq2tz5FfwHhGVahgLJZgm6M2EGLmqc62anJHy3h0XRTFshp7Jayaz_9qRMBNJIW3FE%26_nc_zt%3D14%26_nc_ht%3Dscontent-lax7-1.xx%26_nc_gid%3D3BAUPgLzsh_SSSD0QJMcKw%26_nc_ss%3D7b289%26oh%3D00_AQJFHv0bNHF4QOGW1q29OMgpK2OxvY09nqkKaoZqchq-Hw%26oe%3D6AA532A4&h=AUA_5w61yNHePD60Ol70WT0kj2wYt3TN1h9HsCpWUyYxS6GsTP3Q-q0V1tu1NXv5faLrZmeqezLVBWqRzjIKb88E_BN6ULnef6z5Qck7Y_P2FCWEHR4mgvP2FvWwynt1ty136MYf7YuRSw) + +| Parameter | Description | +| --- | --- | +| `em`
Email
string or list | **Hashing required.**
Trim any leading and trailing spaces. Convert all characters to lowercase.
**Example:**
_Input:_ John\_Smith@gmail.com
_Normalized format:_ john\_smith@gmail.com
_Expected SHA256 output:_ 62a14e44f765419d10fea99367361a727c12365e2520f32218d505ed9aa0f62f | +| `ph`
Phone Number
string or list | **Hashing required.**
Remove symbols, letters, and any leading zeros. Phone numbers must include a country code to be used for matching (e.g., the number 1 must precede a phone number in the United States). Always include the country code as part of your customers’ phone numbers, even if all of your data is from the same country.
**Example:**
_Input:_ US phone number (650)555-1212
_Normalized format:_ 16505551212
_Expected SHA256 output:_
e323ec626319ca94ee8bff2e4c87cf613be6ea19919ed1364124e16807ab3176 | +| `fn`
First Name
string or list | **Hashing required.**
Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.
**Example:**
_Input:_ Mary
_Normalizaed format:_ mary
_Expected SHA256 output:_ 6915771be1c5aa0c886870b6951b03d7eafc121fea0e80a5ea83beb7c449f4ec
_Input:_ 정
_Normalized format:_ UTF-8 character “정”
_Expected SHA256 output:_ 8fa8cd9c440be61d0151429310034083132b35975c4bea67fdd74158eb51db14
_Input:_ Valéry
_Normalized format:_ valéry
_Expected SHA256 output:_ 08e1996b5dd49e62a4b4c010d44e4345592a863bb9f8e3976219bac29417149c | +| `ln`
Last Name
string or list | **Hashing required.**
Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation. If using special characters, the text must be encoded in UTF-8 format.
See First Name (`fn`) for examples. | +| `db`
Date of Birth
string or list | **Hashing required.**
We accept the YYYYMMDD format accommodating a range of month, day and year combinations, with or without punctuation.
**Year:** Use the YYYY format from 1900 to current year.
**Month:** Use the MM format: 01 to 12.
**Date:** Use the DD format: 01 to 31.
**Example:**
_Input:_ 2/16/1997
_Normalized format:_ 19970216
_Expected SHA256 output:_ 01acdbf6ec7b4f478a225f1a246e5d6767eeab1a7ffa17f025265b5b94f40f0c | +| `ge`
Gender
string or list | **Hashing required.**
We accept gender in the form of an initial in lowercase.
**Example:**
f for female
m for male | +| `ct`
City
string or list | **Hashing required.**
Using Roman alphabet a-z characters is recommended. Lowercase only with no punctuation, no special characters, and no spaces. If using special characters, the text must be encoded in UTF-8 format.
**Example:**
paris
london
newyork | +| `st`
State
string or list | **Hashing required.**
Use the [2-character ANSI abbreviation code⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FFederal_Information_Processing_Standard_state_code&h=AUA_5w61yNHePD60Ol70WT0kj2wYt3TN1h9HsCpWUyYxS6GsTP3Q-q0V1tu1NXv5faLrZmeqezLVBWqRzjIKb88E_BN6ULnef6z5Qck7Y_P2FCWEHR4mgvP2FvWwynt1ty136MYf7YuRSw) in lowercase. Normalize states outside the U.S. in lowercase with no punctuation, no special characters, and no spaces.
**Example:**
az
ca | +| `zp`
Zip Code
string or list | **Hashing required.**
Use lowercase with no spaces and no dash. Use only the first 5 digits for U.S. zip codes. Use the area, district, and sector format for the UK.
**Example:**
U.S zip code: 94035
Australia zip code: 1987
France zip code: 75018
UK zip code: m11ae | +| `country`
Country
string or list | **Hashing required.**
Use the lowercase, 2-letter country codes in [ISO 3166-1 alpha-2⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fen.wikipedia.org%2Fwiki%2FISO_3166-1_alpha-2&h=AUA_5w61yNHePD60Ol70WT0kj2wYt3TN1h9HsCpWUyYxS6GsTP3Q-q0V1tu1NXv5faLrZmeqezLVBWqRzjIKb88E_BN6ULnef6z5Qck7Y_P2FCWEHR4mgvP2FvWwynt1ty136MYf7YuRSw).
**Important Note:** Always include your customers’ countries’ even if all of your country codes are from the same country. We match on a global scale, and this simple step helps us match as many Accounts Center accounts as possible from your list.
**Example:**
_Input:_ United States
_Normalized format:_ us
_Expected SHA256 output:_ 79adb2a2fce5c6ba215fe5f27f532d4e7edbac4b6a5e09e1ef3a08084a904621 | +| `external_id`
External ID
string or list | **Hashing recommended.**
Any unique ID from the advertiser, such as loyalty membership IDs, user IDs, and external cookie IDs. You can send one or more external IDs for a given event.
If an External ID is being sent via other channels, it should be in the same format as when sent via the [Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/external-id). | +| `client_ip_address`
Client IP Address
string | **Do not hash.**
The IP address of the browser corresponding to the event must be a valid IPV4 or IPV6 address. IPV6 is preferable over IPV4 for IPV6-enabled users. The `client_ip_address` user data parameter must never be hashed.
No spaces should be included. Always provide the real IP address to ensure accurate event reporting.
**Note:** This information is automatically added to events sent through the browser, but it must be manually configured for events sent through the server.
**Example:**
_IPV4:_ 168.212.226.204
_IPV6:_ 2001:0db8:85a3:0000:0000:8a2e:0370:7334 | +| `client_user_agent`
Client User Agent
string | **Do not hash.**
The user agent for the browser corresponding to the event. The `client_user_agent` is required for website events shared using the [Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api).
Sending both the `client_ip_address` and `client_user_agent` parameters for all of the events you’re sending through the Conversions API may help improve event matching and could also help improve ad delivery for any ad campaigns optimizing on the events you send through the Conversions API.
**Note:** This information is automatically added to events sent through the browser, but must be manually configured for events sent through the server.
**Example:**
Mozilla/5.0 (Windows NT 10.0; Win64; x64)
AppleWebKit/537.36 (KHTML, like Gecko)
Chrome/87.0.4280.141
Safari/537.36 | +| `fbc`
Click ID
string | **Do not hash.**
The Meta click ID value is stored in the `_fbc` browser cookie under your domain. See [Managing `fbc` and `fbp` Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) for how to get this value or generate this value from a `fbclid` query parameter.
The format is: fb.${subdomain\_index}.${creation\_time}.${fbclid}.
_**Note**: If you are using the [parameter builder library](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameter-builder-library), the format will contain an additional appendix at the end of each param. Check the parameter builder library page for more details._
**Example:**
`fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890` | +| `fbp`
Browser ID
string | **Do not hash.**
The Meta browser ID value is stored in the `_fbp` browser cookie under your domain. See [Managing `fbc` and `fbp` Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) for how to get this value.
The format is `fb.${subdomain_index}.${creation_time}.${random_number}`.
_**Note**: If you are using the [parameter builder library](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameter-builder-library), the format will contain an additional appendix at the end of each param. Check the parameter builder library page for more details._
**Example:**
fb.1.1596403881668.1116446470 | +| `subscription_id`
Subscription ID
string | **Do not hash.**
The subscription ID for the user in this transaction; it is similar to the order ID for an individual product. | +| `fb_login_id`
Facebook Login ID
integer | **Do not hash.**
The ID issued by Meta when a person first logs into an instance of an app. This is also known as App-Scoped ID. | +| `lead_id`
Lead ID
integer | **Do not hash.**
The ID associated with a lead generated by [Meta’s Lead Ads](https://developers.facebook.com/documentation/ads-commerce/marketing-api/guides/lead-ads). | +| `anon_id`
string | **Do not hash.**
Your install ID. This field represents unique application installation instances.
_**Note:** This parameter is for app events only_ | +| `madid`
string | Your mobile advertiser ID, the advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device. | +| `page_id`
string | **Do not hash.**
Your Page ID. Specifies the page ID associated with the event. Use the Facebook page ID of the page associated with the bot. | +| `page_scoped_user_id`
string | **Do not hash.**
Specifies the page-scoped user ID associated with the messenger bot that logs the event. Use the page-scoped user ID provided to your webhook. | +| `ctwa_clid`
string | **Do not hash.**
Click ID generated by Meta for ads that click to WhatsApp. | +| `ig_account_id`
string | **Do not hash.**
[Instagram Account ID](https://developers.facebook.com/docs/instagram-api/reference/ig-user) that is associated with the business. | +| `ig_sid`
string | **Do not hash.**
Users who interact with Instagram are identified by Instagram-Scoped User IDs (IGSID). IGSID can be obtained from this [webhook](https://developers.facebook.com/documentation/business-messaging/instagram-messaging/webhooks). | + +## See Also + +[Custom Data Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data) +[Meta Privacy and Data Use Guide⁠](https://www.facebook.com/business/m/privacy-and-data#Data-Use-&-Ads) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-deduplication.md b/.agents/skills/meta-ads/references/conversions-api/capi-deduplication.md new file mode 100644 index 0000000..2d83e62 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-deduplication.md @@ -0,0 +1,123 @@ + + +Ads and Commerce + +Was this helpful? + +# Handling Duplicate Pixel and Conversions API Events + +Updated: Jun 28, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events.md) + +For optimal ad performance, we recommend that advertisers implement the Conversions API alongside their Meta Pixel. We call this a “redundant setup” and detail more about this recommended approach [here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/end-to-end-implementation#pick-your-integration-type). + +When advertisers use a redundant setup, they must set up a deduplication method to ensure that the ad delivery system is able to differentiate between distinct and overlapping events. This document describes multiple deduplication method options to help Facebook deduplicate your events. + +Advertisers who do not send the same event twice via both the Conversions API and Meta Pixel do not need to set up deduplication for those events. + +The Conversions API now enables advertisers to send web, app, and physical store events to Meta through a single endpoint rather than across multiple. Learn more about [the Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api). + +## Event deduplication options + +Facebook tries to deduplicate identical events sent through Meta Pixel and the Conversions API. We have two ways of deduplicating your events: + +### Event ID and event name (recommended) + +#### Required parameters + +For this approach, the `event_id` parameter is added to your events from both the Conversions API and the browser Pixel. The `event_id` parameter is an identifier that can uniquely distinguish between similar events. Read more about [the `event_id` parameter](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-id). + +#### Approach description + +We determine if events are identical based on their **ID** and **name**. So, for an event to be deduplicated: + +In corresponding events, a Meta Pixel’s `eventID` must match the Conversion API’s `event_id`. +In corresponding events, a Meta Pixel’s `event` must match the Conversion API’s `event_name`. + +Once the events are received, we employ a number of strategies to deduplicate between the events which may help improve optimization and measurement. If server and browser events do not differ meaningfully in their content, we generally prefer the event that is received first. + +Note that the `eventID` parameter for the Pixel is the fourth argument in the `fbq` track call. + +**Example** + +``` +fbq('track', 'Purchase', {value: 12, currency: 'USD'}, {eventID: 'EVENT_ID'}); +``` + +### FBP or external ID + +#### Required parameters + +For this approach, you must use `event_name`, `fbp` and/or `external_id` consistently across browser and server events. See [Customer Information Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) for more information about the `external_id` and `fbp` parameters. + +#### Approach description + +If you have configured the `external_id` and/or `fbp` parameters to be passed via both browser and server, we take care to remove duplicate events automatically. This is how the process works: + +You send us a browser event with `event_name` and `fbp` and/or `external_id`. +Then, you send us a server event with `event_name` and `fbp` and/or `external_id`. +We compare the server event with the previously sent browser event. Specifically, we compare the `event_name` and `fbp` and/or `external_id` combinations. +We employ a number of strategies to deduplicate between the events which may help improve optimization and measurement. If server and browser events do not differ meaningfully in their content, we generally prefer the event that is received first. + +#### Approach limitations + +This deduplication method: + +Generally, it only works for deduplicating events sent first from the browser and then through the server. Server events will not be discarded if a browser event has not been received in the past 48 hours, even if an identical browser event arrives after the server event +Does not deduplicate events when only using one event source, that is browser-only or server-only. If you send us two consecutive browser events with the same information, we do not discard either. If you send us two consecutive server events with the same information, we do not discard either. + +## Setting up deduplication on the browser Pixel + +For better matching, we need accurate information from your events coming through both Meta Pixel and the Conversions API: + +The `eventID` inside the optional `eventData` parameter should be a unique value. Depending on your Meta Pixel implementation, you can use: + +`track` to send the event for all Pixels on the page + +``` +fbq('track', 'Purchase', {value: 12, currency: 'USD'}, {eventID: 'EVENT_ID'}); +``` + +`trackSingle` to send the event for one Pixel + +``` +fbq('trackSingle', 'SPECIFIC_PIXEL_ID', 'Purchase', {value: 12, currency: 'USD'}, {eventID: 'EVENT_ID'}); +``` + +An image Pixel tag with the `eid` parameter + +``` + +``` + +If the event you are sharing does not contain parameters such as value and currency, you can set it up as follows: + +``` +fbq('track', 'Lead', {}, {eventID: 'EVENT_ID'}); +``` + +The `eventID` from the Meta Pixel must match the `event_id` in the corresponding event coming from the Conversions API. + +If we find the same server key combination (`event_id` and `event_name`) **and** browser key combination (`eventID` and `event`) sent to the same Pixel ID within 48 hours, we discard the subsequent events. + +If you are sending us your events via both browser and the Conversions API along with matching `event_ids`, keep in mind that events are only deduplicated if they are received within 48 hours of when we receive the first event with a given `event_id`. + +## Verifying your deduplication setup + +Learn how to verify your deduplication and event merging setup in the [Verifying Your Setup](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup) documentation. + +## Learn more + +[Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) +[Payload Helper](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-get-started.md b/.agents/skills/meta-ads/references/conversions-api/capi-get-started.md new file mode 100644 index 0000000..1be9750 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-get-started.md @@ -0,0 +1,105 @@ + + +Ads and Commerce + +Was this helpful? + +# Get started with the Conversions API + +Updated: Jun 28, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/get-started.md) + +**Ads Management Standard Access is now Marketing API Access Tier** + +**No code changes are needed.** + +Tier labels have been updated: “Standard Access” is now **Limited Access**, and “Advanced Access” is now **Full Access**. The revised qualification threshold for Full Access has been reduced from 1,500 to **500 Marketing API calls** in the past 15 days. The underlying permission identifier remains the same, and existing access levels are preserved automatically. Learn more in the [Marketing API Access Tier documentation](https://developers.facebook.com/docs/features-reference#marketing-api-access-tier). + +This page describes the process of implementing the Conversions API and details implementation prerequisites. If you are a third-party partner offering Conversions API functionalities for advertisers, there are [different requirements](https://developers.facebook.com/documentation/ads-commerce/conversions-api/set-up-conversions-api-as-a-platform) to get started. + +If your business has a firewall for outbound requests, see [Crawler IPs and User Agents](https://developers.facebook.com/docs/sharing/webmasters/crawler#identify) to get Facebook’s IP addresses. Be aware that the list of addresses changes often. + +Web, app, and physical store events shared using the Conversions API require specific parameters. The list of [required parameters is available here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters). + +## Process overview + +The process of setting up a Conversions API integration consists of the following high-level steps: + +Choosing the integration method that is right for you. +Completing the necessary prerequisites for that implementation method. +Implementing using that integration method. +Verifying your setup and adhering to best practices that help improve ad performance. + +## Integration methods + +There are several methods for integrating with the Conversions API, and they vary by level of effort, cost, and the features they enable. See [this article⁠](https://www.facebook.com/business/help/433493041367251?id=818859032317965) for an overview of Conversions API setup options. + +The primary focus of this developer documentation is building direct integrations. + +## Requirements + +### Pixel ID + +You must obtain a [Pixel ID⁠](https://www.facebook.com/business/help/952192354843755?id=1205376682832142) to use the Conversions API. If you’ve already set up a Pixel for your website, use the same Pixel ID for your browser and server events. + +### Meta Business Suite + +You also need a [Meta Business Suite⁠](https://business.facebook.com/) to use the API. Meta Business Suite helps advertisers integrate Facebook marketing efforts across their business and with external partners. If you don’t have a Meta Business Suite yet, see the Help Center article on [how to Create a Meta Business Suite⁠](https://www.facebook.com/business/help/1710077379203657). + +### Access token + +To use the Conversions API, you need an access token. There are two ways of getting your access token: + +Using Events Manager (Recommended) +Using your own app + +#### Using Events Manager (recommended) + +To use the Conversions API, you need to generate an access token. Pass the access token as a parameter in each API call. Inside Events Manager, follow these steps: + +**Step 1** \- Choose the Pixel you want to implement. + +**Step 2** \- Select the Settings tab. + +![Events Manager Pixel header tab bar with the Settings tab selected, next to Overview, Test Events, Diagnostics, History, and Implementations.](https://scontent-lax7-1.xx.fbcdn.net/v/t39.2365-6/256580685_927677734830755_2094553860769734043_n.png?_nc_cat=105&ccb=1-7&_nc_sid=e280be&_nc_ohc=zO6uu29Z0b8Q7kNvwHQW9GS&_nc_oc=AdpjApoE3f08mK6CjTnBfzVthghU2Hk7jHfuC2zZtP6lI8xK5blv2jJvm831pMrXO4g&_nc_zt=14&_nc_ht=scontent-lax7-1.xx&_nc_gid=omkISsDjSHCExSYcWdQHQA&_nc_ss=7b289&oh=00_AQKuv_TzZywvYYP6eTN-sKegXknIjTyUlsI-79rcfNUY5Q&oe=6AB8A03F) + +**Step 3** \- Find the Conversions API section and click on the **Generate access token** link under Set up manually, and follow the instructions pop-up: + +**Note**: The Generate access token link is only visible to users with developer privileges for the business. The link is hidden from other users. + +![Events Manager Settings page Conversions API section with the Generate access token link highlighted under Set up direct integration.](https://scontent-lax3-2.xx.fbcdn.net/v/t39.2365-6/590086877_1236076635017652_6418235756617021850_n.png?_nc_cat=111&ccb=1-7&_nc_sid=e280be&_nc_ohc=KiSmmE-zyqoQ7kNvwHcbuyi&_nc_oc=AdqjJ4gircWvD3BsM6hb1QpSsSTpOIDn1DFUdosbafkvuds0JhyABnh_6MjiqOnIRxo&_nc_zt=14&_nc_ht=scontent-lax3-2.xx&_nc_gid=omkISsDjSHCExSYcWdQHQA&_nc_ss=7b289&oh=00_AQJD_wCr3rubz8jB8fMbl47nthoPQvZBhWxdNGCMiH5rmg&oe=6AB8AA1F) + +Once you have your token, click on the **Manage Integrations** button in the Overview tab in Events Manager. In the pop-up screen, click the **Manage** button next to Conversions API. Clicking Manage automatically creates a Conversions API app and Conversions API system user for you. _There is no need to go through App Review or request any permissions_. + +![Events Manager Integrations pop-up showing Conversions API In Progress with its Manage button and the Manage Integrations button highlighted.](https://scontent-lax3-2.xx.fbcdn.net/v/t39.2365-6/256525579_1605874206422638_8242489354165474255_n.png?_nc_cat=107&ccb=1-7&_nc_sid=e280be&_nc_ohc=u6srGIPi--wQ7kNvwETPMUf&_nc_oc=Ado2yrLoDXfrNdAvIfw9zBBc6ocyu79HX1WKKN7QiHYRjoeO4zX7FstvDGj1j9iBc8Y&_nc_zt=14&_nc_ht=scontent-lax3-2.xx&_nc_gid=omkISsDjSHCExSYcWdQHQA&_nc_ss=7b289&oh=00_AQJS54OP32bAxp-Pgg0tDWxbOCmNdMBS-vRUvXpdEFoitw&oe=6AB89782) + +#### Using your own app + +If you already have your own [app](https://developers.facebook.com/docs/apps) and your own [system user](https://developers.facebook.com/docs/marketing-api/system-users/create-retrieve-update), you can generate your token inside [Meta Business Suite⁠](https://business.facebook.com/). To do that: + +**Step 1** \- Go to your Business’ **Settings**. + +**Step 2** \- Assign a Pixel to your system user (you also have an option to create a new system user at this stage). + +**Step 3** \- Select the assigned system user and click **Generate Token**. + +_Your app does not need to go through App Review. You do not need to request any permissions_. + +Access tokens generated under the Conversions API settings tab in Events Manager are no longer restricted to using the newest Graph API version that was available at the time of token generation. [Starting with v12.0](https://developers.facebook.com/docs/graph-api/changelog/version12.0#conversions-api), newly created access tokens can be used with all available Graph API versions. + +## Resources + +Business Help Center: [About Meta Business Suite⁠](https://www.facebook.com/business/help/113163272211510) +Business Help Center: [About Meta Pixel⁠](https://www.facebook.com/business/help/742478679120153) +Meta Blueprint: [Get Started With the Conversions API⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219713-get-started-with-the-conversions-api%3Fcontent_id%3DQxA0x02819tjqUN&h=AUBjUp8Xc3pHmfgT_GRfJLmtyJJNR8Or0JQJw9YxIZU010a31UbHoBUxcbrApexbvYwW7IQLZOmQN4sV3glQVMo_ap8uN4ZjCQm8puQHYlCmzCILEXB6dzp-QE66fY8HOhJba680SYUxHA) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-main-body-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-main-body-parameters.md new file mode 100644 index 0000000..1039c5a --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-main-body-parameters.md @@ -0,0 +1,18 @@ + + +Ads and Commerce + +# Main Body Parameters + +Updated: Nov 10, 2021 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/main-body.md) + +| Parameter | Description | +| --- | --- | +| `data`
array | **Required.**
An array of server event objects. See [Server Event Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event) for more information. | +| `test_event_code`
string | **Optional.**
Code used to verify that your server events are received correctly by Facebook. Use this code to test your server events in the Test Events feature in Events Manager. See [Test Events Tool](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#testEvents) for an example. | + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-offline-events.md b/.agents/skills/meta-ads/references/conversions-api/capi-offline-events.md new file mode 100644 index 0000000..e23ea00 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-offline-events.md @@ -0,0 +1,180 @@ + + +Ads and Commerce + +Was this helpful? + +# Sending Offline Events Using the Conversions API + +Updated: Jan 5, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events.md) + +The Conversions API is Meta’s recommended integration method for sending offline and physical store events to Meta for use in ad measurement, attribution, and targeting. This page details how to send offline events via a Conversions API direct or partner integration. + +**Note**: This guide covers sending Offline events through the Conversions API, primarily for Omni Ads Optimization. If you’re looking for guidance on sending CRM events for Conversion Leads Optimization, refer to the development documentation [here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/conversion-leads-integration). + +## Prerequisites + +### Dataset + +Offline events sent through the Conversions API must be associated with a dataset. + +Datasets allow advertisers to connect and manage event data from web, app, store and business messaging event sources to the Conversions API. Datasets may show event data from any of these integrations that you choose to set up: + +Meta Pixel (website events) +App Events API (app events, including Facebook SDK for iOS or Android, mobile measurement partners (MMPs)) +Offline Conversions API (Meta’s legacy API for offline events) +Messaging Events API (messaging events) + +Datasets enable you to view all customer activities from a single interface. They also allow you to reduce the effort to build and maintain multiple API integrations. + +In Events Manager, advertisers have different [options⁠](https://www.facebook.com/business/help/5270377362999582?id=490360542427371) to create a dataset depending on their starting point. Or you can [create a brand new dataset⁠](https://www.facebook.com/business/help/5818684664831465?id=490360542427371) in Events Manager by linking during offline event set creation or through an existing mobile app or during messaging event set creation information. Note that linking a dataset to an application is required before sending mobile app events to the Conversions API and only one application can be linked to a dataset. See more [details⁠](https://www.facebook.com/business/help/768703235046938?locale=en_US) and instructions [here⁠](https://www.facebook.com/business/help/750785952855662?id=490360542427371). + +You can make the `GET` call to [https://graph.facebook.com/v16.0/{ads-pixel-id}/?fields=is\_consolidated\_container](https://developers.facebook.com/documentation/ads-commerce/marketing-api/reference/ads-pixel) to detect if the advertiser’s dataset is consolidated and thus eligible for passing offline events using the Conversions API. + +### Permissions + +To implement a direct integration as an advertiser, please follow the instructions [here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/get-started#integration-methods) for prerequisites and permissions. + +To implement a partner platform integration, please follow the instructions [here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/end-to-end-implementation#integration-as-a-platform) for prerequisites and permissions. + +## Configuration + +### 1\. Set Up Offline Event Parameters + +Advertisers can use the setup mentioned [here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/end-to-end-implementation) and refer to the [current set of parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) that can be sent over the Conversions API. For sending offline and store events, the following fields can be shared in the payload: + +Advertisers need to send [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) as `physical_store` for all offline and store events. Note that this parameter is required for all server event types. By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. +All required [server event fields](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event) for Conversions API must be respected. +[Customer information parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) (see below for appropriate list of parameters for offline and store events). +[Custom data parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data) (see below for appropriate list of parameters for offline and store events). +Optional parameter: the `upload_tag` parameter is still supported for offline event uploads for advertisers using legacy API for offline events. + +### Customer Information Parameters + +The following list contains customer information parameters that are typically used for offline and store events: + +| Parameter names | Parameter | Hashing required | +| --- | --- | --- | +| Email Address(es) | `email` | YES | +| Phone Number(s) | `phone` | YES | +| Gender | `gen` | YES | +| Date of Birth | `db` | YES | +| Last Name | `ln` | YES | +| First Name | `fn` | YES | +| City | `ct` | YES | +| US States | `st` | YES | +| Zip codes | `zip` | YES | +| Country | `country` | YES | +| Mobile Advertiser ID | `madid` | Do not hash
The advertising ID from an Android device or the Advertising Identifier (IDFA) from an Apple device. | +| Third-party user id | `external_id` | Highly recommended | +| The lead id from Lead Ads | `lead_id` | Do not hash | + +### Custom Data Parameters + +The following section contains common custom parameters used by offline and store events. For more custom data fields, please refer to the full list we accept for Conversions API in the following [link](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data). + +| Parameter | Description | +| --- | --- | +| `event_time`
type: integer | **Required**
The UNIX timestamp of the conversion event.
* * *
**Example:**`'1456870055'` | +| `event_name`
type: string | **Required**
Type of event.
* * *
**Example:**`ViewContent, Search, AddToCart, AddToWishlist, InitiateCheckout, AddPaymentInfo, Purchase, Lead, Other` | +| `store_data`
type: JSON dictionary | **Optional**
Store location data about conversion event.
* * *
**Example:**
```
"store_data":
{
"store_page_id": 8576093908, // FBID
"brand_page_id": 10236898932// FBID
"store_code": "64CharacterAlphaNumericString" // String
}
``` | +| `currency`
type: string | **Required**
Three-letter [ISO currency code⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.iso.org%2Fiso-4217-currency-codes.html%3Ffbclid%3DIwAR0xKRCr-IrwOUtAz9A8DkpNhv8Fdix5Z8FeofygygO6kBtdu-YLJccUlgk&h=AUAaOiXRWQlLPRC56vqC0JQe7-Tx2VEp_R2VGeL4Hv-vDDDn4s9RoZ54wEPf-r_GhuqyIatcr1EvRH4VOSDIQZ7mwsFYfwc7KwcESQQTfbhXl7umIpjoVX-tvVLy7IFvE2k3wuksFgBO6g) for this conversion event. Required for `Purchase` events.
* * *
**Example:**`USD` | +| `value`
type: double | **Required**
Value of conversion event. Required for `Purchase` events.
* * *
**Example:**`16.00` | +| `content_type`
type: string | **Optional**
Any valid [Advantage+ catalog ads](https://developers.facebook.com/docs/meta-pixel/get-started/advantage-catalog-ads)`content_type`.
* * *
**Example:**`product` | +| `contents`
type: JSON array | **Optional**. Required if you integrate your ads with [catalog](https://developers.facebook.com/documentation/ads-commerce/catalog).
Required: `id`, `quantity`
Recommended: `price`, `brand`, `category`
Required: `[ {id: "A", quantity: 1}, {id: "B", quantity: 2}, {id: "C", quantity: 1}]`
Recommended: `[ {id: "A", quantity: 1, brand: "Brand_A", category: "", price: 10.0}]` | +| `custom_data`
type: JSON dictionary | **Optional**.
Information about this conversion event.
**Example**: `{category: 'ICECREAM'}` | +| `order_id`
type: string | **Optional**.
Unique identifier for each transaction or order in an offline event set. For example, for retail this can be a receipt ID.
**Example**: `ATN10001`, `123456` | +| `item_number`
type: string | **Optional**.
Unique identifier to distinguish events within the same order or transaction.
**Example**: `1`, `a` | + +### 2\. Sending Events + +To send new events, make a `POST` request to the Conversions API from this path: `https://graph.facebook.com/{API_VERSION}/{DATASET_ID}/events?access_token={TOKEN}` + +When you post to this edge, Meta creates new offline and store events. For more details, please refer to the following [developer document](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api). + +Here is an overview of how the parameters fit into the overall schema in the payload: + +``` +curl -X POST \ + -F 'data=[\ + {\ + "event_name": "Purchase",\ + "event_time": 1674000041,\ + "user_data": {\ + "em": [\ + "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"\ + ],\ + "ph": [\ + "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",\ + "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"\ + ]\ + },\ + "custom_data": {\ + "currency": "usd",\ + "value": 123.45,\ + "contents": [{\ + "id": "product123",\ + "quantity": 1\ + }]\ + },\ + "action_source": "physical_store"\ +}\ +]' \ + -F 'access_token=' \ + https://graph.facebook.com/v15.0//events +``` + +We recommend uploading in real time or on a daily basis for optimal optimization results so that offline data can be effectively matched against the performance of any ads you’re running. + +The [`event_time`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-time) can be up to 7 days before you send an event to Meta. If any `event_time` in `data` is greater than 7 days in the past, we return an error for the entire request and process no events. For offline and physical store events with `physical_store` as `action_source`, you should upload transactions within 62 days of the conversion. + +The data you upload is processed in real time so you can usually view results as soon as you add it. You can refer to the Help Center document about [Best Practices for Offline events data⁠](https://www.facebook.com/business/help/1798506233494677?id=565900110447546). + +### 3\. Set Up Deduplication + +Unlike [deduplication set up across Conversions API and Meta Pixel events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events), offline events can be deduplicated against other offline events only. We support two methods of deduplication: **order\_id** based or **user** based. The deduplication uses the combination of fields: `dataset_id`, `event_time`, `event_name`, `item_number`, and the key field based on method in the given event’s payload. + +The default deduplication uses **order\_id** with a combination of the fields above. If **order\_id** is not present in the payload, the **user** based deduplication logic will be used. + +For example, where there are two orders with identical `event_time`, `event_name` having the same **order\_id** or same set of [Customer Information Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events#customer-information-parameters) without **order\_id**, we will consider them duplicate events and take the first event. The **user** based deduplication method only works with the same [Customer Information Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events#customer-information-parameters) fields in the two payloads. + +The maximum deduplication window is 7 days. + +### 4\. Troubleshooting Events + +You can use the [Payload Helper tool](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper) to generate payload data: + +Choose `physical_store` action source when applicable. By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. +Fill info for the events that will be sent to Meta +This will generate event payload, which can be used as a template for your Conversions API integration + +Use the [Test Events tool⁠](https://www.facebook.com/business/help/2040882565969969?id=1205376682832142) in Events Manager for testing your payload. + +## See Also + +[Dataset Quality API for Offline Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/dataset-quality-api/offline-events) +[Omni Optimal Setup Guide: Best Practices and Requirements](https://developers.facebook.com/documentation/ads-commerce/marketing-api/best-practices/omni-optimal-setup-guide) +[Conversions API Overview](https://developers.facebook.com/documentation/ads-commerce/conversions-api) +[Using the Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api) +[Conversions API Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) +[Best Practices](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices) + +### Business Help Center Articles + +[Create a dataset during offline event set creation⁠](https://www.facebook.com/business/help/5818684664831465?id=490360542427371) +[Best practices for offline events data⁠](https://www.facebook.com/business/help/1798506233494677?id=565900110447546) +[How advertisers can use offline conversions⁠](https://www.facebook.com/business/help/1142103235885551?id=565900110447546) +[How to view results of campaigns assigned to specific dataset⁠](https://www.facebook.com/business/help/154283205023788?id=565900110447546&ref=search_new_3) +[How event deduplication works for offline events⁠](https://www.facebook.com/business/help/1772588746090250?id=565900110447546&ref=search_new_9) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-original-event-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-original-event-parameters.md new file mode 100644 index 0000000..1e0d39d --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-original-event-parameters.md @@ -0,0 +1,30 @@ + + +Ads and Commerce + +Was this helpful? + +# Original Event Data Parameters + +Updated: Oct 28, 2024 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event.md) + +Use these parameters to share original event information you want to associate with the Conversions API. + +| Parameter | Description | +| --- | --- | +| `event_name`
string | **Optional.**
A [standard event](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#standard-events) or [custom event](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#custom-events) name. | +| `event_time`
integer | **Optional.**
A Unix timestamp in seconds indicating when the actual event occurred. The specified time may be earlier than the time you send the event to Facebook. You must send this date in the GMT time zone. | +| `order_id`
string | **Optional.**
The order ID for this transaction as a string. | +| `event_id`
string | **Optional.**
This ID can be any unique string chosen by the advertiser. The `event_id` and `event_name` parameters are used to deduplicate events sent by both web (via the Meta Pixel) or app (via SDK or App Events API) and the Conversions API. **Note that while**`event_id` **is marked optional, it is recommended for event deduplication**.
For deduplication, the `eventID` from a browser or app event must match the `event_id` in the corresponding server event. Learn more about [Handling Duplicate Pixel and Conversions API Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events).
An order number or transaction ID are two potential identifiers that can be used for `event_id`. For example, if a customer makes two purchases on your website with order numbers 123 and 456, each Conversions API call would need to include its respective order number for `event_id`. This allows us to properly distinguish these two purchase events as distinct orders. The two corresponding browser Pixel purchase events would need to also send the same order numbers in the `eventID` parameter for us to understand that there were only two events that took place, not four unique purchases.
For other events without an intrinsic ID number, a random number (so long as the same random number is sent between browser and server events) can be used. | + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-overview.md b/.agents/skills/meta-ads/references/conversions-api/capi-overview.md new file mode 100644 index 0000000..3ab2009 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-overview.md @@ -0,0 +1,67 @@ + + +Ads and Commerce + +Was this helpful? + +# Conversions API + +Updated: Jun 28, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api.md) + +The Conversions API is designed to create a connection between an advertiser’s marketing data (such as website events, app events, business messaging events and offline conversions) from an advertiser’s server, website platform, mobile app, or CRM to Meta systems that optimize ad targeting, decrease cost per result and measure outcomes. + +Rather than maintaining separate connection points for each data source, advertisers can use the Conversions API to send multiple event types and reduce the number of separate integrations they maintain. In the case of direct integrations, this entails establishing a connection between an advertiser’s server and Meta’s Conversions API endpoint. + +Server events are linked to a dataset ID and are processed like events sent using the Meta Pixel, Facebook SDK for iOS or Android, mobile measurement partner SDK, offline event set, or .csv upload. This means that server events may be used in measurement, reporting, or optimization in a similar way as other connection channels. Offline events may be used for attributed offline events measurement, offline custom audience creation or measurement. + +For optimal ad performance and measurement, follow the [Conversions API best practices](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices). + +### Recommended steps + +[**Get Started**](https://developers.facebook.com/documentation/ads-commerce/conversions-api/get-started): Choose the integration method that works best for you, see prerequisites for using the API, and understand where to begin. +[**Implement the API and start sending requests**](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api): Start making `POST` requests and learn more about dropped events, batch requests, and event transaction time. +[**Verify your setup**](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup): Confirm that Meta has received your events and that events are deduplicated and matched correctly. + +## Documentation + +### [API Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) + +Required and optional parameters you can use to improve ads attribution and delivery optimization. + +### [Payload Helper](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper) + +See how your payload should be structured when it is sent to Meta from your server. + +### [Troubleshooting](https://developers.facebook.com/documentation/ads-commerce/conversions-api/support) + +Learn how to handle error codes returned by the Conversions API. + +## Resources + +### Meta Pixel Events + +Learn more about the Meta Pixel’s [Standard Events](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#standard-events) and [Custom Events](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#custom-events). + +### Business Help Center + +From our Help Center, see [About Conversions API⁠](https://www.facebook.com/business/help/2041148702652965) and [Test Your Server Events⁠](https://www.facebook.com/business/help/1624255387706033). + +### Playbook + +View the [Direct Integration Playbook for Developers (PDF)⁠](https://www.facebook.com/gms_hub/share/conversions-api-direct-integration-playbook_english.pdf). + +### [Data Processing Options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options) + +Learn more about the Limited Data Use feature and how to implement it for Conversions API. + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-parameters.md new file mode 100644 index 0000000..718f150 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-parameters.md @@ -0,0 +1,119 @@ + + +Ads and Commerce + +Was this helpful? + +# Parameters + +Updated: Jun 30, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters.md) + +This page groups the Conversions API parameters by family, covering the required event data parameters and the additional parameters that support ads attribution and ads delivery optimization. + +[The Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api) now supports web, app, offline, and business messaging events. + +Website events shared using the Conversions API require the [`client_user_agent`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#client-user-agent), [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source), and [`event_source_url`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-source-url) parameters, while non-web events **require only** [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source). These parameters contribute to improving the quality of events used for ad delivery and may improve campaign performance. + +By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. + +### [Main Body Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/main-body) + +[`data`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/main-body#data) +[`test_event_code`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/main-body#test-event-code) + +### [Customer information parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) + +[`em`: Email](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#em) — Hashing required +[`ph`: Phone Number](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ph) — Hashing required +[`fn`: First Name](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#fn) — Hashing required +[`ln`: Last Name](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ln) — Hashing required +[`ge`: Gender](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ge) — Hashing required +[`db`: Date of Birth](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#db) — Hashing required +[`ct`: City](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ct) — Hashing required +[`st`: State](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#st) — Hashing required +[`zp`: Zip Code](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#zp) — Hashing required +[`country`: Country](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#country) — Hashing required +[`external_id`: External ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#external-id) — Hashing recommended +[`client_ip_address`: Client IP Address](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#client_ip_address) — Do not hash +[`client_user_agent`: Client User Agent](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#client-user-agent) — Do not hash +[`fbc`: Click ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#fbc) — Do not hash +[`fbp`: Browser ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#fbp) — Do not hash +[`subscription_id`: Subscription ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#subscription_id) — Do not hash +[`fb_login_id`: Facebook Login ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#fb_login_id) — Do not hash +[`lead_id`: Lead ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#lead_id) — Do not hash +[`anon_id`: Install ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#anon_id) — Do not hash ( _**Note:** This parameter is for app events only_) +[`madid`: Mobile Advertiser ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#madid) — Do not hash ( _**Note:** This parameter is for app events only_) +[`page_id`: Page ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#page_id) — Do not hash +[`page_scoped_user_id`: Page scoped user ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#page_scoped_user_id) — Do not hash +[`ctwa_clid`: Click to WhatsApp ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ctwa_clid) — Do not hash +[`ig_account_id`: IG account ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ig_account_id) — Do not hash +[`ig_sid`: Click to Instagram ID](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#ig_sid) — Do not hash + +### [Server Event Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event) + +[`event_name`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-name) +[`event_time`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-time) +[`user_data`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#user-data) +[`custom_data`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#custom-data) +[`event_source_url`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-source-url) +[`opt_out`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#opt-out) +[`event_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-id) +[`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) +[`data_processing_options`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#data-processing-options) +[`data_processing_options_country`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#data-processing-options-country) +[`data_processing_options_state`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#data-processing-options-state) +[`referrer_url`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#referrer-url) +[`customer_segmentation`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#customer-segmentation) + +### [App data parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data) + +[`advertiser_tracking_enabled`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#advertiser-tracking-enabled) +[`application_tracking_enabled`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#application-tracking-enabled) +[`extinfo`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#extinfo) +[`campaign_ids`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#campaign-ids) +[`install_referrer`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#install-referrer) +[`installer_package`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#installer-package) +[`url_schemes`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#url-schemes) +[`windows_attribution_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#windows-attribution-id) +[`anon_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#anon_id) +[`madid`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters#madid) +[`vendor_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/app-data#vendor-id) + +_**Note**: See the [Conversions API for App Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/app-events) documentation for guidance on integrating app events._ + +### [Standard parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data) + +See a list of all [standard parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data) users can send to Meta. + +### [Original event data parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event) + +[`event_name`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event#event-name-oed) +[`event_time`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event#event-time-oed) +[`order_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event#order-id-oed) +[`event_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event#event-id-oed) + +### Conversions API for lead optimization + +If you integrate your CRM system with the Conversions API for lead events, refer to the [CRM Integration](https://developers.facebook.com/docs/marketing-api/conversions-api/guides/crm-integration) guide for the required fields. + +### See also + +Overview: [`fbp` and `fbc` Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/fbp-and-fbc) + +## Learn more + +[Conversions API: Documentation](https://developers.facebook.com/documentation/ads-commerce/conversions-api) +[Using the Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api) +[Meta Privacy and Data Use Guide⁠](https://www.facebook.com/business/m/privacy-and-data#Data-Use-&-Ads) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-payload-helper.md b/.agents/skills/meta-ads/references/conversions-api/capi-payload-helper.md new file mode 100644 index 0000000..4673826 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-payload-helper.md @@ -0,0 +1,202 @@ + + +Ads and Commerce + +# Payload Helper + +Updated: Jan 25, 2023 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper.md) + +Fill out the required and recommended data parameter fields to see how your payload should be structured when it’s sent to Facebook from your server. + +Web, app, and physical store events shared using the Conversions API require specific parameters. The list of [required parameters is available here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters). + +Selected Product + +selectedProduct + +Website + +​ + +Event Type Parameters + +The fields [event\_name](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#event-name), [event\_time](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#event-time), and [action\_source](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#action-source) + +are required for all events while event\_id is recommended for [deduplication](https://developers.facebook.com/docs/marketing-api/conversions-api/deduplicate-pixel-and-server-events). Additionally, the fields [client\_user\_agent](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters#client-user-agent) and [event\_source\_url](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/server-event#event-source-url) are required for website events. + +event\_name + +Type: string + +​ + +event\_time + +Type: int + +action\_source + +Type: string + +website + +​ + +Add Event Type Parameters + +* * * + +Customer Information Parameters + +Include at least one customer information parameter for each event you want to send. Facebook will use this data for the purposes described in its [Business Tools Terms](https://www.facebook.com/legal/technology_terms), including ads attribution and ads delivery optimization. + +All customer information parameters should be hashed as SHA256, except for client IP address, client user agent, click ID, and browser ID. Any other customer information parameters that are not hashed are automatically rejected by Facebook. + +Delete field + +Email (em)∙ Optional + +Type: string \| Must be hashed + +Close + +Normalize + +Hash + +[Add another value](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper#) + +Delete field + +Phone number (ph)∙ Optional + +Type: string \| Must be hashed + +Normalize + +Hash + +[Add another value](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper#) + +Add Customer Information Parameters + +* * * + +Custom Data Parameters + +Select custom parameters you want to use for ads attribution or ads delivery optimization, or create a new custom parameter. + +Delete field + +​ + +currency∙ Optional + +Type: string + +Close + +Delete field + +​ + +value∙ Optional + +Type: float + +Add Custom Data Parameters + +* * * + +Attribution Data Parameters + +Select attribution parameters you want to use for ads attribution or ads delivery optimization. + +Delete field + +​ + +attribution\_share∙ Optional + +Type: float + +Add Attribution Data Parameters + +* * * + +Original Event Data Parameters + +Select original event parameters you want to use for ads attribution or ads delivery optimization. + +Delete field + +​ + +event\_name∙ Optional + +Type: string + +Close + +Delete field + +​ + +event\_time∙ Optional + +Type: int + +Add Original Event Data Parameters + +* * * + +Generate Code + +Get Code + +`{ +"data": [\ +{\ +"event_name": "Purchase",\ +"event_time": 1788870274,\ +"action_source": "website",\ +"user_data": {\ +"em": [\ +"7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"\ +],\ +"ph": [\ +null\ +]\ +},\ +"attribution_data": {\ +"attribution_share": "0.3"\ +},\ +"custom_data": {\ +"currency": "USD",\ +"value": "142.52"\ +},\ +"original_event_data": {\ +"event_name": "Purchase",\ +"event_time": 1788870274\ +}\ +}\ +] +} +` + +You can add multiple values to most customer information parameters. +[Learn more](https://developers.facebook.com/docs/marketing-api/conversions-api/parameters/customer-information-parameters) + +Test this Payload + +Send to Test Events + +[Open Graph Explorer](https://developers.facebook.com/tools/explorer/?method=POST&path=%3CDATASET_ID%3E%2Fevents&data=[%7B%22event_name%22%3A%22Purchase%22%2C%22event_time%22%3A1788870274%2C%22action_source%22%3A%22website%22%2C%22user_data%22%3A%7B%22em%22%3A[%227b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068%22]%2C%22ph%22%3A[null]%7D%2C%22attribution_data%22%3A%7B%22attribution_share%22%3A%220.3%22%7D%2C%22custom_data%22%3A%7B%22currency%22%3A%22USD%22%2C%22value%22%3A%22142.52%22%7D%2C%22original_event_data%22%3A%7B%22event_name%22%3A%22Purchase%22%2C%22event_time%22%3A1788870274%7D%7D]) + +[Give feedback](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper#) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-server-event-parameters.md b/.agents/skills/meta-ads/references/conversions-api/capi-server-event-parameters.md new file mode 100644 index 0000000..9409aa7 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-server-event-parameters.md @@ -0,0 +1,56 @@ + + +Ads and Commerce + +Was this helpful? + +# Server Event Parameters + +Updated: Feb 12, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event.md) + +| Parameter | Description | +| --- | --- | +| `event_name`
string | **Required.**
A [standard event](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#standard-events) or [custom event](https://developers.facebook.com/docs/facebook-pixel/implementation/conversion-tracking#custom-events) name. This field is used to deduplicate events sent by both web (via Meta Pixel) or app (via SDK or App Events API) and the Conversions API. The `event_id` parameter is also used in deduplication.
For the same customer action, `event` from the browser or app event matches `event_name` from the server event. If we find a match between events sent within 48 hours of each other, we only consider the first one. If a server and browser/app event arrive at approximately the same time (that is, within 5 minutes of each other), we favor the browser/app event. Learn more about [Deduplicate Pixel and Server Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events). | +| `event_time`
integer | **Required.**
A Unix timestamp in seconds indicating when the actual event occurred. The specified time may be earlier than the time you send the event to Facebook. This is to enable batch processing and server performance optimization. You must send this date in GMT time zone.
The `event_time` can be up to 7 days before you send an event to Facebook. If any `event_time` in `data` is greater than 7 days in the past, we return an error for the entire request and process no events. | +| `user_data`
object | **Required.**
A map that contains customer information data. See [Customer Information Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) for options. See [Advanced Matching](https://developers.facebook.com/docs/facebook-pixel/advanced/advanced-matching) for comparable options available for data sent via Meta Pixel. | +| `custom_data`
object | **Optional.**
A map that includes additional business data about the event. See [Custom Data Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/custom-data) for more information. | +| `event_source_url`
string | **Optional.**
The browser URL where the event happened. The URL should match the verified domain.
**Note:** The `event_source_url` is required for website events shared using the Conversions API. | +| `opt_out`
boolean | **Optional.**
A flag that indicates we should not use this event for ads delivery optimization. If set to `true`, we only use the event for attribution. | +| `event_id`
string | **Optional.**
This ID can be any _unique_ string chosen by the advertiser. The `event_id` and `event_name` parameters are used to deduplicate events sent by both web (via the Meta Pixel) or app (via SDK or App Events API) and the Conversions API. Note that while `event_id` is marked optional, it is recommended for event deduplication.
For deduplication, the `eventID` from a browser or app event must match the `event_id` in the corresponding server event. Learn more about [Handling Duplicate Pixel and Conversions API Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events).
An order number or transaction ID are two potential identifiers that can be used for `event_id`. For example, if a customer makes two purchases on your website with order numbers 123 and 456, each Conversions API call would need to include its respective order number for `event_id`. This allows us to properly distinguish these two purchase events as distinct orders. The two corresponding browser Pixel purchase events would need to also send the same order numbers in the `eventID` parameter for us to understand that there were only two events that took place, not four unique purchases.
For other events without an intrinsic ID number, a random number (so long as the same random number is sent between browser and server events) can be used. | +| `action_source`
string | **Required.**
This field allows you to specify where your conversions occurred. Knowing where your events took place helps ensure your ads go to the right people. By using the Conversions API, you agree that the `action_source` parameter is accurate to the best of your knowledge.
The values you can send in the `action_source` field are as follows:
`email` — Conversion happened over email.
`website` — Conversion was made on your website.
`app` — Conversion was made on your mobile app.
`phone_call` — Conversion was made over the phone.
`chat` — Conversion was made via a messaging app, SMS, or online messaging feature.
`physical_store` — Conversion was made in person at your physical store.
`system_generated` — Conversion happened automatically, for example, a subscription renewal that’s set to auto-pay each month.
`business_messaging` — Conversion was made from ads that click to Messenger, Instagram or WhatsApp.
`other` — Conversion happened in a way that is not listed.
**Note**: All action source values enable ad measurement and custom audience creation capabilities. All action sources enable ad optimization capabilities. | +| `data_processing_options`
array | **Optional.**
Processing options you would like to enable for a specific event. Current accepted value is `LDU` for Limited Data Use. An empty array can be sent to explicitly specify that this event shouldn’t be processed with the Limited Data Use restrictions. Learn more about [Data Processing options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options). See [examples of Conversions API implementation](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options#conversions-api-and-offline-conversions-api). | +| `data_processing_options_country`
integer | **Required**, if you send `LDU` under `data_processing_options`.
A country that you want to associate to this data processing option. Current accepted values are `1`, for the United States of America, or `0`, to request that we geolocate that event. Learn more about [Data Processing options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options). See [examples of Conversions API implementation](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options#conversions-api-and-offline-conversions-api). | +| `data_processing_options_state`
integer | **Required** in some cases. (See note below for details.)
A state that you want to associate to this data processing option. Current accepted values are `1000`, for California, or `0`, to request that we geolocate that event.
**Note:**
If you set a country, you must also set a state. Otherwise, we apply our geolocation logic to the entire event.
This field is required if you send `LDU` under `data_processing_options` and do not provide an IP address.
Learn more about [Data Processing options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options). See [examples of Conversions API implementation](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options#conversions-api-and-offline-conversions-api). | +| `app_data`
object | **Required for app events**
Parameters for sharing app data and device information with the Conversions API.
`extinfo` is a sub-parameter of `app_data`. | +| `extinfo`
object | **Required for app events**
Extended device information, such as screen width and height. This parameter is an array and values are separated by commas. When using extinfo, **all values are required and must be in the order indexed below**. If a value is missing, fill with an empty string as a placeholder.
Note:
`version` must be `a2` for Android
`version` must be `i2` for iOS | +| ↳ `0`
string | **Required**
extinfo version
Example: `i2` | +| ↳ `1`
string | app package name
Example: `com.facebook.sdk.samples.hellofacebook` | +| ↳ `2`
string | short version (int or string)
Example: `1.0` | +| ↳ `3`
string | long version
Example: `1.0 long` | +| ↳ `4`
string | **Required**
OS version
Example: `13.4.1` | +| ↳ `5`
string | device model name
Example: `iPhone5,1` | +| ↳ `6`
string | locale
Example: `En_US` | +| ↳ `7`
string | timezone abbreviation
Example: `PDT` | +| ↳ `8`
string | carrier
Example: `AT&T` | +| ↳ `9`
int64 | screen width
Example: `320` | +| ↳ `10`
int64 | screen height
Example: `568` | +| ↳ `11`
string | screen density
Example: `2` | +| ↳ `12`
int64 | CPU cores
Example: `2` | +| ↳ `13`
int64 | external storage size in GB
Example: `13` | +| ↳ `14`
int64 | free space on external storage in GB
Example: `8` | +| ↳ `15`
string | device timezone
Example: `USA/New York` | +| `referrer_url`
string | **Optional.**
The HTTP referrer header as observed by the page triggering the Conversions API or Meta Pixel event. This is usually the preceding page in the browser. | +| `original_event_data`
object | **Optional.**
All metadata fields advertisers can use to specify how a “delayed” event should be associated with a past acquisition event.
We highly recommend using `original_event_data` when there’s a delay between when an event is sent and a past acquisition event it should be associated with.
See [Original Event Data Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/original-event) for more information. | +| `customer_segmentation`
enum | **Optional.**
Allows advertisers to specify the user segment that the user performing the event belongs to. It can be used to provide more context about the user’s relationship with the business.
This field accepts one of the following predefined enum values:
`new_customer_to_business`: The user is a new customer to the business.
`new_customer_to_business_line`: The user is a new customer to a specific business line (for example, product or service).
`new_customer_to_product_area`: The user is a new customer to a specific product area (for example, e-commerce, finance).
`new_customer_to_medium`: The user is a new customer to a specific marketing medium (for example, social media, email).
`existing_customer_to_business`: The user is an existing customer to the business.
`existing_customer_to_business_line`: The user is an existing customer to a specific business line (for example, product or service).
`existing_customer_to_product_area`: The user is an existing customer to a specific product area (for example, e-commerce, finance).
`existing_customer_to_medium`: The user is an existing customer to a specific marketing medium (for example, social media, email).
`customer_in_loyalty_program`: The user is part of a loyalty program.
Example JSON payload:
```
{
"event_name": "Purchase",
"event_time": 1643723400,
"user_data": {
"em": "user@example.com"
},
"custom_data": {
"currency": "USD",
"value": 100.00,
"customer_segmentation": "new_customer_to_business"
}
}
``` | + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-using-the-api.md b/.agents/skills/meta-ads/references/conversions-api/capi-using-the-api.md new file mode 100644 index 0000000..52d7422 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-using-the-api.md @@ -0,0 +1,511 @@ + + +Ads and Commerce + +Was this helpful? + +# Using the API - Conversions API + +Updated: Jul 17, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api.md) + +Once you have completed the prerequisites on the [Get Started](https://developers.facebook.com/documentation/ads-commerce/conversions-api/get-started) page, use this page to learn how to send events and use the Test Events tool. Once you’ve sent an event, [verify your setup](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup). + +The Conversions API is based on Facebook’s [Marketing API](https://developers.facebook.com/documentation/ads-commerce/marketing-api), which was built on top of our [Graph API](https://developers.facebook.com/docs/graph-api). Marketing and Graph APIs have different version deprecation schedules. Our release cycle is aligned with the [Graph API](https://developers.facebook.com/docs/graph-api/changelog), so every version is supported for at least two years. This exception is only valid for the Conversions API. + +[Conversions API: Overview](https://developers.facebook.com/documentation/ads-commerce/conversions-api) + +[Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) + +Web, app, and physical store events shared using the Conversions API require specific parameters. By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. The list of [required parameters is available here](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters). + +## Send Requests + +To send new events, make a `POST` request to this API’s `/events` edge from this path: `https://graph.facebook.com/{API_VERSION}/{PIXEL_ID}/events?access_token={TOKEN}`. When you post to this edge, Facebook creates new server events. + +``` +curl -X POST \ + -F 'data=[\ + {\ + "event_name": "Purchase",\ + "event_time": 1762902353,\ + "user_data": {\ + "em": [\ + "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"\ + ],\ + "ph": [\ + "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",\ + "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"\ + ],\ + "client_ip_address": "123.123.123.123",\ + "client_user_agent": "$CLIENT_USER_AGENT",\ + "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",\ + "fbp": "fb.1.1558571054389.1098115397"\ + },\ + "custom_data": {\ + "currency": "usd",\ + "value": 123.45,\ + "contents": [\ + {\ + "id": "product123",\ + "quantity": 1,\ + "delivery_category": "home_delivery"\ + }\ + ]\ + },\ + "event_source_url": "http://jaspers-market.com/product/123",\ + "action_source": "website"\ + }\ + ]' \ + -F 'access_token=' \ +https://graph.facebook.com/v26.0//events +``` + +Attach your generated secure access token using the `access_token` query parameter to the request. You can also use [Graph API Explorer](https://developers.facebook.com/tools/explorer/?method=POST&path=%7BPIXEL_ID%7D%2Fevents%2F&version=v3.2) to `POST` to the `//events` endpoint. + +An example request body looks like this: + +``` +{ + "data": [\ + {\ + "event_name": "Purchase",\ + "event_time": 1633552688,\ + "event_id": "event.id.123",\ + "event_source_url": "http:\/\/jaspers-market.com\/product\/123",\ + "action_source": "website",\ + "user_data": {\ + "client_ip_address": "192.19.9.9",\ + "client_user_agent": "test ua",\ + "em": [\ + "309a0a5c3e211326ae75ca18196d301a9bdbd1a882a4d2569511033da23f0abd"\ + ],\ + "ph": [\ + "254aa248acb47dd654ca3ea53f48c2c26d641d23d7e2e93a1ec56258df7674c4",\ + "6f4fcb9deaeadc8f9746ae76d97ce1239e98b404efe5da3ee0b7149740f89ad6"\ + ],\ + "fbc": "fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890",\ + "fbp": "fb.1.1558571054389.1098115397"\ + },\ + "custom_data": {\ + "value": 100.2,\ + "currency": "USD",\ + "content_ids": [\ + "product.id.123"\ + ],\ + "content_type": "product"\ + },\ + "opt_out": false\ + },\ + {\ + "event_name": "Purchase",\ + "event_time": 1633552688,\ + "user_data": {\ + "client_ip_address": "192.88.9.9",\ + "client_user_agent": "test ua2"\ + },\ + "custom_data": {\ + "value": 50.5,\ + "currency": "USD"\ + },\ + "opt_out": false\ + }\ + ] +} +``` + +### Upload Time versus Event Transaction Time + +[`event_time`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-time) is the event transaction time. It should be sent as a Unix timestamp in seconds indicating when the actual event occurred. The specified time **may be earlier than the time you send the event to Facebook**. This is to enable batch processing and server performance optimization. + +The [`event_time`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-time) can be up to 7 days before you send an event to Meta. If any `event_time` in `data` is greater than 7 days in the past, we return an error for the entire request and process no events. For offline and physical store events with `physical_store` as `action_source`, you should upload transactions within 62 days of the conversion. + +By using the Conversions API, you agree that the [`action_source`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#action-source) parameter is accurate to the best of your knowledge. + +### Batch Requests + +You can send up to 1,000 events in `data`. However, for optimal performance, we recommend you send events as soon as they occur and ideally within an hour of the event occurring. + +Send an [`event_id`](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/server-event#event-id) with every event so we can deduplicate: if we receive the same `event_id` and `event_name` more than once, we keep only the first copy. + +That makes batch retries safe. If any event in a batch is invalid, the request returns an error — but valid events with an `event_id` are still accepted. Fix the invalid events and resend the whole batch; the events we already stored are dropped as duplicates, with no double-counting. + +Learn more about [Handling Duplicate Pixel and Conversions API Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events). + +### Hashing + +Please check our [customer information parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/customer-information-parameters) page to see which parameters should be hashed before they are sent to Facebook. If you are using one of our [Business SDKs](https://developers.facebook.com/docs/business-sdk), the hashing is done for you by the SDK. + +### [Business SDK Features for Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/business-sdk-features) + +Learn more about three specific Business SDK features designed especially for Conversions API users: [Asynchronous Requests](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/business-sdk-features#asynchronous-requests), [Concurrent Batching](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/business-sdk-features#concurrent-batching), and [HTTP Service Interface](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/business-sdk-features#http-service-interface). Minimum language version required to use these features: + +PHP >= 7.2 +Node.js >= 7.6.0 +Java >= 8 +Python >= 2.7 +Ruby >= 2 + +Business SDK support for PHP 5 has been deprecated since January 2019. Please upgrade to PHP 7 to use the Business SDK. + +[Conversions API Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) + +## Verify Events + +After you send your events, confirm that we have received them in [Events Manager⁠](https://www.facebook.com/events_manager2/list): + +On the **Data Sources** page, click on the Pixel corresponding to the `PIXEL_ID` in your `POST` request. For more information see [Business Help Center: Navigate Events Manager⁠](https://www.facebook.com/business/help/898185560232180). +Then, click **Overview**. You see the number of raw, matched and attributed events we received. Under **Connection Method**, you see the channel in which that event was sent. + +![Events Manager Overview tab showing the All Activity chart and a list of events with connection method and total events](https://scontent-lax3-1.xx.fbcdn.net/v/t39.2365-6/585895230_1369493101576007_8389423454863825083_n.png?_nc_cat=102&ccb=1-7&_nc_sid=e280be&_nc_ohc=jWYqE-LO4isQ7kNvwHLl9BN&_nc_oc=Adr0EksZmiEZ7ItLWeQXk8K5OPG2zvGEIzQsVUvscxovXC6bxDbJE9gdguIYK1cBfa4&_nc_zt=14&_nc_ht=scontent-lax3-1.xx&_nc_gid=LUtI_psK8X8Iu8lkZMH8bg&_nc_ss=7b289&oh=00_AQJSdKv_DkgpkzSMeABA-98CMCcVmznNCckdPBNeSOM9DQ&oe=6AB9872F) + +You can click on each event to get more specific information. + +![Events Manager Overview with the PageView event expanded to show Advanced Matching Activity and event details](https://scontent-lax3-1.xx.fbcdn.net/v/t39.2365-6/587283254_1369493298242654_6933103126623895958_n.png?_nc_cat=108&ccb=1-7&_nc_sid=e280be&_nc_ohc=-oviJSAvbFYQ7kNvwFhRa3c&_nc_oc=AdqHGyylkE70eV6G2LFP3_T1oCNW5E3sSxzFaGH_31gBDog-3wJIEVkEwV4RvvU3HLk&_nc_zt=14&_nc_ht=scontent-lax3-1.xx&_nc_gid=LUtI_psK8X8Iu8lkZMH8bg&_nc_ss=7b289&oh=00_AQK9qFEUjK1Eo8WMQvGBAYSQ_5nXzrCJ9Ea8IRos_1o4Ig&oe=6AB99D14) + +After you start sending events, you should be able to verify them within 20 minutes. Now you can start sending events from your server. + +## Test Events Tool + +You can verify that your server events are received correctly by Facebook by using the Test Events feature in Events Manager. To find the tool, go to `Events Manager > Data Sources > Your Pixel > Test Events`. + +The Test Events tool generates a test ID. Send the test ID as a `test_event_code` parameter to start seeing event activity appear in the Test Events window. + +**Note**: The `test_event_code` field should be used only for testing. You need to remove it when sending your production payload. + +Events sent with `test_event_code` are not dropped. They flow into Events Manager and are used for targeting and ads measurement purposes. + +Here’s an example of how the request should be structured: + +``` +{ + "data": [\ + {\ + "event_name": "ViewContent",\ + "event_time": 1764975551,\ + "event_id": "event.id.123",\ + "event_source_url": "http:\/\/jaspers-market.com",\ + "user_data": {\ + "client_ip_address": "1.2.3.4",\ + "client_user_agent": "test user agent"\ + }\ + }\ + ], + "test_event_code": "TEST123" +} +``` + +Here’s an example of how the request appears in Graph API Explorer: + +You can generate this test payload using the [**Payload Helper tool**](https://developers.facebook.com/documentation/ads-commerce/conversions-api/payload-helper). Please note that the test event code is only for testing payload. + +![Graph API Explorer with a POST events request payload and an 'events_received: 1' JSON response](https://scontent-lax3-1.xx.fbcdn.net/v/t39.2365-6/586165220_1369493408242643_8604537139564087818_n.png?_nc_cat=102&ccb=1-7&_nc_sid=e280be&_nc_ohc=XKlLC-1pOocQ7kNvwF7CVtc&_nc_oc=Adpa8KpQMAGwJ9xKw04xXybVWQdCnYVCvxw6qkf6WuSS91Mkr-Fytv1Na_BfmCapsQI&_nc_zt=14&_nc_ht=scontent-lax3-1.xx&_nc_gid=LUtI_psK8X8Iu8lkZMH8bg&_nc_ss=7b289&oh=00_AQLhWUMPelD9u_ESs8NPt0Y8MihzlDIYeZ6Rwk0l5lVyMw&oe=6AB9A42F) + +Your server events appear in the Test Events window once the request is sent. +![Test Your Events Server tab showing a received View Content event with its URL and user data keys](https://scontent-lax7-1.xx.fbcdn.net/v/t39.2365-6/584405638_1369493194909331_6260232388306826635_n.png?_nc_cat=101&ccb=1-7&_nc_sid=e280be&_nc_ohc=u-94hoV2y4gQ7kNvwHBlLvA&_nc_oc=AdokIGczwf29hZ4QVBYLzsp503Sf8Mh7NLT1u-6fDfoVo0YBCTuDNiVGrdIK4GPs80I&_nc_zt=14&_nc_ht=scontent-lax7-1.xx&_nc_gid=LUtI_psK8X8Iu8lkZMH8bg&_nc_ss=7b289&oh=00_AQKo6lERQ6aYe0NXZUSVQOUhE99uG2NauVP34cBLiDGz6A&oe=6AB9971A) + +## [Data Processing Options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options) for US Users + +For these two APIs, implement data processing options by adding `data_processing_options`, `data_processing_options_country`, and `data_processing_options_state` inside each event within the [data parameter](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters/main-body#data) of your events. + +**Note:** The App Events and Offline Conversions APIs are no longer recommended for new integrations. Instead, it is recommended that you use the Conversions API as it now supports web, app, and offline events. See [Conversions API for App Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/app-events) and [Conversions API for Offline Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/offline-events) for more information. + +To explicitly not enable Limited Data Use (LDU), specify an empty array for each event or simply remove the field in the payload: + +``` +{ + "data": [\ + {\ + "event_name": "Purchase",\ + "event_time": ,\ + "user_data": {\ + "em": ""\ + },\ + "custom_data": {\ + "currency": "",\ + "value": ""\ + },\ + "data_processing_options": []\ + }\ + ] +} +``` + +To enable LDU and have Meta perform geolocation: + +``` +{ + "data": [\ + {\ + "event_name": "Purchase",\ + "event_time": ,\ + "user_data": {\ + "em": "",\ + "client_ip_address": "256.256.256.256"\ + },\ + "custom_data": {\ + "currency": "",\ + "value": ""\ + },\ + "data_processing_options": ["LDU"],\ + "data_processing_options_country": 0,\ + "data_processing_options_state": 0\ + }\ + ] +} +``` + +To enable LDU and manually specify the location, e.g., for California: + +``` +{ + "data": [\ + {\ + "event_name": "Purchase",\ + "event_time": ,\ + "user_data": {\ + "em": ""\ + },\ + "custom_data": {\ + "currency": "",\ + "value": ""\ + },\ + "data_processing_options": ["LDU"],\ + "data_processing_options_country": 1,\ + "data_processing_options_state": 1000\ + }\ + ] +} +``` + +#### Manual Upload UI + +The Offline Conversions API offers the option to manually upload your events from a `.csv` file. In this case, add Data Processing Options, Data Processing Country, and Data Processing State as columns inside your file. More information about this can be found in the upload user interface. + +Learn more about [Data Processing Options](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options). + +## API Limits + +The Marketing API has its own rate-limiting logic and is excluded from all the [Graph API rate limitations](https://developers.facebook.com/docs/graph-api/overview/rate-limiting). So if you make a Marketing API call, it won’t be calculated into the Graph API throttling. + +There is no specific rate limit for the Conversions API. Conversions API calls are counted as Marketing API calls. The only limitation is that you can send us up to 1,000 events at a time. See [Send Requests](https://developers.facebook.com/documentation/ads-commerce/conversions-api/using-the-api#send) for more information. + +[Marketing API Rate Limiting](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/rate-limiting) + +## Business SDK API Usage in the Conversions API Gateway + +This guide helps you navigate Meta Business SDK advanced features designed especially for Conversions API Gateway users. For basic Conversions API Gateway usage, refer to the [Conversions API Gateway documentation](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/gateway). + +### Send Events to Your Conversions API Gateway Instance + +#### Requirements + +Before using any of the features listed below, you need to have the Meta Business SDK installed. See [Get Started with the Meta Business SDK](https://developers.facebook.com/docs/business-sdk/getting-started) or follow the README instructions listed here: + +PHP: [facebook-php-business-sdk⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2Ffacebook%2Ffacebook-php-business-sdk%3Ffbclid%3DIwAR2vJ-EiBUbw1JPu_5euYtEhYs623NXvB1zAJXmG1hLZ-rWJgsgXYfX9Ifc&h=AUACSeyKYNi7DDNu0-doiK9BpiRQI-r2MzSShyd5Fb6Dq75hJGSTEcUMMncYWwVtDcpbjZSMELKgwIdDIUTcNz1ffvM1cS3ISKMYri7ifPfgfLD5uLzb_fe-r3xkgCtF76OGl3pPG9FwgQ) +Node.js: [facebook-nodejs-business-sdk⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2Ffacebook%2Ffacebook-nodejs-business-sdk%3Ffbclid%3DIwAR0exwvrLWId4V0vgFk0hy7I1BYVM3848uSu9Zy_yAoM1Gps1wEALEiFwiw&h=AUACSeyKYNi7DDNu0-doiK9BpiRQI-r2MzSShyd5Fb6Dq75hJGSTEcUMMncYWwVtDcpbjZSMELKgwIdDIUTcNz1ffvM1cS3ISKMYri7ifPfgfLD5uLzb_fe-r3xkgCtF76OGl3pPG9FwgQ) +Java: [facebook-java-business-sdk⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2Ffacebook%2Ffacebook-java-business-sdk%3Ffbclid%3DIwAR1nvNRCWXQxX4SaVTImz3ymEYKDM6Zppdc_Y5Szp34q_HbkOukhhWHxlSQ&h=AUACSeyKYNi7DDNu0-doiK9BpiRQI-r2MzSShyd5Fb6Dq75hJGSTEcUMMncYWwVtDcpbjZSMELKgwIdDIUTcNz1ffvM1cS3ISKMYri7ifPfgfLD5uLzb_fe-r3xkgCtF76OGl3pPG9FwgQ) +Python: [facebook-python-business-sdk⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2Ffacebook%2Ffacebook-python-business-sdk%3Ffbclid%3DIwAR3atWm9H8LVmHlMH-mGyfmwLf6WxkUmeG5Yh-h9l144lgNfGW3sRX2wDEg&h=AUACSeyKYNi7DDNu0-doiK9BpiRQI-r2MzSShyd5Fb6Dq75hJGSTEcUMMncYWwVtDcpbjZSMELKgwIdDIUTcNz1ffvM1cS3ISKMYri7ifPfgfLD5uLzb_fe-r3xkgCtF76OGl3pPG9FwgQ) +Ruby: [facebook-ruby-business-sdk⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fgithub.com%2Ffacebook%2Ffacebook-ruby-business-sdk%3Ffbclid%3DIwAR2SZqM8MOMHQQDaO9Urnn3TAqSH9SQOM3u6r3wHcWO_p81cFNVP-KHElsY&h=AUACSeyKYNi7DDNu0-doiK9BpiRQI-r2MzSShyd5Fb6Dq75hJGSTEcUMMncYWwVtDcpbjZSMELKgwIdDIUTcNz1ffvM1cS3ISKMYri7ifPfgfLD5uLzb_fe-r3xkgCtF76OGl3pPG9FwgQ) + +Currently, these features are only available on the PHP and Java business SDK. The other languages will be implemented by the end of 2023. + +The minimum language version required to use these features are: + +PHP >= 7.2 + +Java >= 8 + +**Note**: To dedupe events to the Conversions API endpoint, please pass the `eventId` in your request. This will help prevent duplicate events from showing up if Conversions API publishing is enabled. + +### Formatting the `CAPIGatewayIngressRequest` Parameters + +| Parameter | Description | +| --- | --- | +| `endpointUrl`
string | The Conversions API Gateway endpoint that events get sent to. No prevalidation will be done on the parameter other than checking if it is a valid url.
Example: https://test.example.com | +| `accessKey`
string | Conversions API Gateway access key that is needed to send events to the Conversions API Gateway events endpoint. These are [the instructions](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/gateway/non-web-server-events) for generating it. | + +### The `CAPIGatewayIngressRequest` Setters + +| Parameter | Description | +| --- | --- | +| `setSendToDestinationOnly`
Boolean | Boolean flag on whether the events get sent to the selected endpoint only.
Default: `False` | +| `setFilter`
CustomEndpointRequest.Filter() function | Filter function that processes each event. If the filtering logic returns true, the event gets passed through. Otherwise, the event gets dropped. You have to implement the shouldSendEvent function in the interface that has the parameter Event.
Default: `Null` | + +#### Migration Example: PHP + +For systems that already use the Business SDK, you just need to reference the new CAPIGatewayIngressRequest and attach it to the eventRequest’s customEndpoint object. + +``` +// this is the standard event request that we attach events to +$event_request = new EventRequest($this->pixel_id); +$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); +$event_request->setCustomEndpoint($capiIngressRequest); +// pass the events to this event Request object +$event_request->setEvents($events); +$event_request->execute() +``` + +#### Migration Example: Java + +For systems that already use the Business SDK, you just need to reference the new CAPIGatewayIngressRequest and attach it to the eventRequest’s customEndpoint object. + +``` +// this is the standard event request that we attach events to + +EventRequest eventRequest = new EventRequest(PIXEL_ID, context); + +CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); +eventRequest.setCustomEndpoint(capiSyncRequest); +eventRequest.addDataItem(testEvent); +eventRequest.execute(); +``` + +### Synchronous option + +#### PHP Code Example + +``` +$api = Api::init(null, null, $this->access_token); +$api->setLogger(new CurlLogger()); +$event_request = new EventRequest($this->pixel_id); +$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); +$event_request->setCustomEndpoint($capiIngressRequest); +$user_data = (new UserData()) + ->setEmails(array('joe@eg.com')) + ->setPhones(array('12345678901', '14251234567')) + ->setFbc('fb.1.1554763741205.AbCdEfGhIjKlMnOpQrStUvWxYz1234567890') + ->setFbp('fb.1.1558571054389.1098115397'); +$event1 = (new Event()) + ->setEventName('Purchase') + ->setEventId('125') + ->setEventTime(time()) + ->setEventSourceUrl('http://jaspers-market.com/product/123') + ->setUserData($user_data); +$events = array($event1, $event2); +$event_request->setEvents($events); +$response = $event_request->execute(); +print($response->__toString()); +``` + +#### Java Code Example + +``` +EventRequest eventRequest = new EventRequest(PIXEL_ID, context); +UserData userData = new UserData() + .email("abc@eg.com"); +CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); +eventRequest.setCustomEndpoint(capiSyncRequest); +Event testEvent = new Event(); +testEvent.eventId("125").eventName("Purchase") + .eventTime(System.currentTimeMillis() / 1000L) + .userData(userData) + .dataProcessingOptions(new String[]{}).setEventId("134423232"); +eventRequest.namespaceId("11") + .uploadId("22222") + .uploadTag("upload-tag-4") + .uploadSource("upload-source-4") + .testEventCode("test-event-code-5") + .partnerAgent("partner-agent-6"); +eventRequest.addDataItem(testEvent); +eventRequest.execute(); +``` + +### Asynchronous option + +#### PHP Code Example + +``` +$api = Api::init(null, null, $this->access_token); +$api->setLogger(new CurlLogger()); +$event_request = new EventRequestAsync($this->pixel_id); +$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); +$capiIngressRequest->setSendToDestinationOnly(true); +$event_request->setCustomEndpoint($capiIngressRequest); +$event1 = (new Event()) + ->setEventName('test Async Event') + ->setEventId('134423232') + ->setEventTime(time()) + ->setEventSourceUrl('http://jaspers-market.com/product/123'); +$events = array($event1, $event2); +$event_request->setEvents($events); +$response = $event_request->execute()->wait(); +``` + +#### Java Code Example + +``` +EventRequest eventRequest = new EventRequest(PIXEL_ID, context); +UserData userData = new UserData() + .email("abc@eg.com"); +CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); +capiSyncRequest.setSendToDestinationOnly(true); +eventRequest.setCustomEndpoint(capiSyncRequest); +Event testEvent = new Event(); +testEvent.eventName("test Async Event") + .eventTime(System.currentTimeMillis() / 1000L) + .userData(userData) + .dataProcessingOptions(new String[]{}).setEventId("134423232"); +eventRequest.namespaceId("11222") + .uploadId("22222") + .uploadTag("upload-tag-4") + .uploadSource("upload-source-4") + .testEventCode("test-event-code-5") + .partnerAgent("partner-agent-6"); +eventRequest.addDataItem(testEvent); +eventRequest.executeAsync(); +``` + +### Filter Functionality + +#### PHP Code Example + +``` +lass APIFilter implements Filter { + public function shouldSendEvent(Event $event): bool + { + if ($event->getEventId() === '125') { + return false; + } + return true; + } +} +$capiIngressRequest = new CAPIGatewayIngressRequest($this->cb_url, $this->access_key); +$event_request->setCustomEndpoint($capiIngressRequest); +$capiIngressRequest->setFilter(new APIFilter()); +``` + +#### Java Code Example + +``` +CAPIGatewayIngressRequest capiSyncRequest = new CAPIGatewayIngressRequest(CB_URL, CAPIG_ACCESS_KEY); +eventRequest.setCustomEndpoint(capiSyncRequest); + +capiSyncRequest.setFilter(new CustomEndpointRequest.Filter() { + @Override + public boolean shouldSendEvent(Event event) { + if (event.getEventId().equals("125")) { + return true; + } + return false; +} +}); +``` + +## Learn More + +[Conversions API Gateway](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/gateway) +[Conversions API Gateway for Multiple Accounts](https://developers.facebook.com/documentation/ads-commerce/conversions-api/guides/gateway-multiple-accounts) +[Conversions API Parameters](https://developers.facebook.com/documentation/ads-commerce/conversions-api/parameters) +[Best Practices](https://developers.facebook.com/documentation/ads-commerce/conversions-api/best-practices) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/conversions-api/capi-verifying-setup.md b/.agents/skills/meta-ads/references/conversions-api/capi-verifying-setup.md new file mode 100644 index 0000000..3be8bf0 --- /dev/null +++ b/.agents/skills/meta-ads/references/conversions-api/capi-verifying-setup.md @@ -0,0 +1,65 @@ + + +Ads and Commerce + +# Verifying Your Setup + +Updated: Nov 24, 2025 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup.md) + +This page details ways to verify that your setup is working correctly and is intended to help you to improve ad performance. The process of verifying your setup consists of: + +[Verifying that events are received correctly](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup#verifying-that-events-are-received-correctly) +[Verifying that events are being sent as close to real-time as possible](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup#monitoring-event-freshness) +[Verifying that events are deduplicated correctly](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup#verifying-that-events-are-deduplicated-correctly) +[Verifying that events are matched to users with high accuracy](https://developers.facebook.com/documentation/ads-commerce/conversions-api/verifying-setup#verifying-that-events-are-matched-to-users-with-high-accuracy) + +## Verifying that events are received correctly + +### Monitoring events received + +After you send your events, confirm that we have received them in the [Events Manager⁠](https://www.facebook.com/events_manager). You should be able to verify them within 20 minutes after they were sent. + +Meta Blueprint Course: [Set Up, Implement and Verify the Conversions API⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219714-set-up-implement-verify-conversions-api%3Fcontent_id%3Ddtl2XpttDSQh8wk&h=AUBR82Vg2qbLnFY4XmYHse6lHRCrQ8AS9m8No68rxf_CMrE_NgE9yhma2qa9mLSFi1oQlxdLZeP_lmVQN3XdiTI284QXCxf6HlpNbzhHOMjVu3DQXfprNVrrc-JYjEOmTWSJh7-Ifry-hA) + +To monitor events received in Events Manager, on the Data Sources page, click on the Pixel corresponding to the `PIXEL_ID` in your `POST` request. For more information, see [Business Help Center: Navigate Events Manager⁠](https://www.facebook.com/business/help/898185560232180). + +Then, click **Overview**. Here, you will see the number of events we received before they are deduplicated, discarded due to consent controls and other policies, or processed. Under **Connection Method**, you see the channel in which that event was sent. You can click on each event type to get more specific information. + +### Monitoring event freshness + +To help Facebook optimize your ads, we recommend that you minimize the time between when an event occurs (represented by the `event_time` parameter) and when it is shared with Facebook to be as close to real-time as possible. + +You can use Events Manager to monitor event freshness. In the **Overview** page for a given Pixel, click on the Event Details button for an event to get more specific information. On this page, navigate to the **Event Freshness** tab. In this tab, you can see the average event delay time on a scale from Real Time to Weekly. + +## Verifying that events are deduplicated correctly + +For optimal ad performance, we recommend that advertisers implement the Conversions API alongside their Meta Pixel. When advertisers do so, they must set up a deduplication method to help ensure that the ad delivery system is able to differentiate between distinct and overlapping events. Learn more about [deduplication](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events). + +You can use Events Manager to monitor the percentage of events that were deduplicated. In the **Overview** page for a given Pixel, click on the **Event Details** button for an event type to get more specific information. On this page, navigate to the **Event Deduplication** tab. + +This tab shows the following information: + +**Rate of Events Deduplicated**: This is the percentage of events that have been deduplicated from each event source. Higher percentages are better, and a warning will appear when your deduplication rate is too low. You may be able to improve deduplication rates by adding more deduplication parameters to the event. +**Rate of Deduplication Key Usage**: This is the percentage of events from each source that contained each dedupe key. Overlap is the percentage of events with a given dedupe key received from both sources (as a percentage of the source with the fewest events received). Having low Overlap means that the implementation is either sending non-unique dedupe keys from one/either source or sending events with a dedupe key from only one source. + +## Verifying that events are matched to users with high accuracy + +When your events are matched to people with a Facebook account, your events can be better utilized for ad attribution and optimization. In Events Manager, you can monitor Event Match Quality, a measure of how effective your server event’s customer information parameters may be at matching events to a Facebook account. + +Event Match Quality is scored from 1 to 10. You can monitor Event Match Quality in two ways: + +Navigate to the **Overview** page for a given Meta Pixel with the Conversions API +Use the [Setup Quality API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/dataset-quality-api) + +Having a high Event Match Quality score can help decrease your cost per action. Where possible, we typically recommend that you aim for an Event Match Quality score of 6.0 or higher. You can click on Event Match Quality score to view additional details and recommendations for improving Event Match Quality. Learn more about additional [best practices for Event Match Quality⁠](https://www.facebook.com/business/help/308855623839366?id=818859032317965). + +## See Also + +[Setup Quality API](https://developers.facebook.com/documentation/ads-commerce/conversions-api/dataset-quality-api) +Meta Blueprint: [Set Up, Implement and Verify the Conversions API⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219714-set-up-implement-verify-conversions-api%3Fcontent_id%3Ddtl2XpttDSQh8wk&h=AUBR82Vg2qbLnFY4XmYHse6lHRCrQ8AS9m8No68rxf_CMrE_NgE9yhma2qa9mLSFi1oQlxdLZeP_lmVQN3XdiTI284QXCxf6HlpNbzhHOMjVu3DQXfprNVrrc-JYjEOmTWSJh7-Ifry-hA) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-advanced-matching.md b/.agents/skills/meta-ads/references/pixel/pixel-advanced-matching.md new file mode 100644 index 0000000..788e38b --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-advanced-matching.md @@ -0,0 +1,82 @@ + + +Meta Pixel + +Was this helpful? + +# Advanced matching - Meta Pixel + +Updated: Dec 21, 2023 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/advanced/advanced-matching.md) + +This document explains how to manually implement advanced matching for [tracked conversion events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking) using the Meta Pixel. + +Please visit the [Privacy and Data Use Guide⁠](https://www.facebook.com/business/m/privacy-and-data#Data-Use-&-Ads) to learn what data is sent when using the Meta Pixel. + +To [automatically implement advanced matching⁠](https://www.facebook.com/business/help/1993001664341800) use the [Events Manager⁠](https://business.facebook.com/events_manager/). + +## Implementation + +To use advanced matching, format the visitor’s data as a JSON object and include it in the [pixel base code `fbq('init')` function call](https://developers.facebook.com/documentation/meta-pixel/get-started#base-code) as a third parameter. + +Be sure to place advanced matching parameters in the pixel base code or the values will not be treated as manual advanced matching values. + +For example, if your pixel ID was `283859598862258`, you could do this: + +``` +fbq('init', '283859598862258', { + em: 'email@email.com', //Values will be hashed automatically by the pixel using SHA-256 + fn: 'first_name', + ln: 'last_name' + ... +}); +``` + +**Note:** We accept both lowercase unhashed and normalized SHA-256 hashed email addresses in your function calls + +#### Sending More Hashed Values + +You can use the `` tag to pass your own visitor data if you format and hash your user data using a SHA-256 hashing algorithm. + +The following is an example of passing hashed user email, first name, and last name: + +``` + +``` + +## Reference + +| User Data | Parameter | Format | Example | +| --- | --- | --- | --- | +| Email | `em` | Unhashed lowercase or hashed SHA-256 | `jsmith@example.com` or `6e3913852f512d76acff15d1e402c7502a5bbe6101745a7120a2a4833ebd2350` | +| First Name | `fn` | Lowercase letters | `john` | +| Last Name | `ln` | Lowercase letters | `smith` | +| Phone | `ph` | Digits only including country code and area code | `16505554444` | +| External ID | `external_id` | Any unique ID from the advertiser, such as loyalty membership ID, user ID, and external cookie ID. | `a@example.com` | +| Gender | `ge` | Single lowercase letter, `f` or `m`, if unknown, leave blank | `f` | +| Birthdate | `db` | Digits only with birth year, month, then day | `19910526` for May 26, 1991. | +| City | `ct` | Lowercase with any spaces removed | `menlopark` | +| State or Province | `st` | Lowercase two-letter state or province code | `ca` | +| Zip or Postal Code | `zp` | String | `94025` | +| Country | `country` | Lowercase two-letter country code | `us` | + +## Learn More + +Meta Blueprint course: [Advanced Matching for Websites⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F211540-advanced-matching-for-websites%3Fcontent_id%3DXmPXIuAmW8z20zl&h=AUD30n1e6Osun6LR8vOP7Gq2gmJRPexEsQu9xHCWfFpOrXRzGvoqLFFBvNu7M7eDjIEA8ohW1VMMc9STZAOnF9bQ5W2T1BkS4q0zY2Ya0oNsSgYMJB1gGjS3wGRo5ZQ1tRwpmcUOoLWLtA). + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-conversion-tracking.md b/.agents/skills/meta-ads/references/pixel/pixel-conversion-tracking.md new file mode 100644 index 0000000..78fcb48 --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-conversion-tracking.md @@ -0,0 +1,322 @@ + + +Meta Pixel + +Was this helpful? + +# Conversion Tracking + +Updated: Jun 30, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking.md) + +You can use the Meta Pixel to track your website visitors’ actions also known as conversion tracking. Tracked conversions appear in the [Facebook Ads Manager⁠](https://www.facebook.com/adsmanager) and the [Facebook Events Manager⁠](https://www.facebook.com/events_manager2), where they can be used to analyze the effectiveness of your conversion funnel and to calculate your return on ad investment. You can also use tracked conversions to define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences) for ad optimization and [Advantage+ catalog ads](https://developers.facebook.com/docs/facebook-pixel/implementation/dynamic-ads) campaigns. Once you have defined custom audiences, we can use them to identify other Facebook users who are likely to convert and target them with your ads. + +There are three ways to track conversions with the Pixel: + +[standard events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#standard-events), which are visitor actions that we have defined and that you report by calling a Pixel function +[custom events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#custom-events), which are visitor actions that you have defined and that you report by calling a Pixel function +[custom conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#custom-conversions), which are visitor actions that are tracked automatically by parsing your website’s referrer URLs + +Beginning September 2, 2025, we will start to roll out more proactive restrictions on custom conversions that may suggest information not permitted under [our terms⁠](https://www.facebook.com/legal/terms/businesstools?_rdr). For example, any custom conversion suggesting specific health conditions (e.g., “arthritis”, “diabetes”) or financial status (e.g., “credit score”, “high income”) will be flagged and prevented from being used to run ad campaigns. + +**What these restrictions mean for your campaigns:** + +You won’t be able to use flagged custom conversions when creating new campaigns. +If you have an active campaign using flagged custom conversions, you should either create a new campaign or duplicate your campaign and use a non-impacted custom conversion to avoid performance and optimization issues. + +**For API developers:** + +Beginning September 2, 2025, the field `is_unavailable` will return `true` to signal if your custom conversions have been flagged. + +More information on this update and how to resolve flagged custom conversions can be found [here⁠](https://www.facebook.com/business/help/2455915321411996). + +### Requirements + +The Pixel’s [base code](https://developers.facebook.com/documentation/meta-pixel/get-started#base-code) must already be installed on every page where you want to track conversions. + +## Standard Events + +[Standard events](https://developers.facebook.com/documentation/meta-pixel/reference#standard-events) are predefined visitor actions that correspond to common, conversion-related activities, such as searching for a product, viewing a product, or purchasing a product. Standard events support [parameters](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#parameters), which allow you to include an object containing additional information about an event, such as product IDs, categories, and the number of products purchased. + +For a full list of [Standard events](https://developers.facebook.com/documentation/meta-pixel/reference#standard-events) visit the [Pixel Standard Events Reference](https://developers.facebook.com/documentation/meta-pixel/reference#standard-events). Learn more about conversion tracking and standard events with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUAIz3AMlNryd-V2gnFMVsYcrYCKp_hWWm-cfuTpQrkXBSQzOk-XP5vANTBK8Yv_HsPhcutdfIUo97IIvQlMaC-H7XaUef2DgmBisXoLZKTiR0cHmMwX0iUqXCLph-DncZUytwTYL0sK-A). + +### Tracking Standard Events + +All standard events are tracked by calling the Pixel’s `fbq('track')` function, with the event name, and (optionally) a JSON object as its parameters. For example, here’s a function call to track when a visitor has completed a purchase event, with currency and value included as a parameter: + +``` +fbq('track', 'Purchase', {currency: "USD", value: 30.00}); +``` + +If you called that function, it would be tracked as a purchase event in the Events Manager: + +![Events Manager Events tab charting PageView and Purchase events over time, with a tooltip showing one tracked Purchase event](https://scontent-lax3-1.xx.fbcdn.net/v/t39.2365-6/39949625_1790839247617931_4027789432194072576_n.png?_nc_cat=110&ccb=1-7&_nc_sid=e280be&_nc_ohc=CQGKwCd-MRYQ7kNvwEDognz&_nc_oc=AdrtSLv86bvro2QLFBGLpaDYp08vjg-edDQ2LJWZo019ZAmPy3Rl5Go7Ba0tmsikS94&_nc_zt=14&_nc_ht=scontent-lax3-1.xx&_nc_gid=67ycXgYe3y2hnJu3_SiT0Q&_nc_ss=7b289&oh=00_AQIu0DVLPPN-HEK_fj39c99yadkzeivJaYsWzw4U2i4ngg&oe=6ABA3D1C) + +You can call the `fbq('track')` function anywhere between your web page’s opening and closing `` tags, either when the page loads, or when a visitor completes an action, such as clicking a button. + +For example, if you wanted to track a standard purchase event _after a visitor has completed the purchase_, you could call the `fbq('track')` function on your _purchase confirmation page_, like this: + +``` + + ... + + ... + +``` + +If instead you wanted to track a standard purchase event _when the visitor clicks a purchase button_, you could tie the `fbq('track')` function call to the purchase button _on your checkout page_, like this: + +``` + + +``` + +Note that the example above uses jQuery to trigger the function call, but you could trigger the function call using any method you wish. + +## Custom Events + +If our predefined standard events aren’t suitable for your needs, you can track your own custom events, which also can be used to define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences) for ad optimization. Custom events also support [parameters](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#parameters), which you can include to provide additional information about each custom event. + +Learn more about conversion tracking and custom events with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUAIz3AMlNryd-V2gnFMVsYcrYCKp_hWWm-cfuTpQrkXBSQzOk-XP5vANTBK8Yv_HsPhcutdfIUo97IIvQlMaC-H7XaUef2DgmBisXoLZKTiR0cHmMwX0iUqXCLph-DncZUytwTYL0sK-A). + +### Tracking Custom Events + +You can track custom events by calling the Pixel’s `fbq('trackCustom')` function, with your custom event name and (optionally) a JSON object as its parameters. Just like standard events, you can call the `fbq('trackCustom')` function anywhere between your webpage’s opening and closing `` tags, either when your page loads, or when a visitor performs an action like clicking a button. + +For example, let’s say you wanted to track visitors who share a promotion in order to get a discount. You could track them using a custom event like this: + +``` +fbq('trackCustom', 'ShareDiscount', {promotion: 'share_discount_10%'}); +``` + +Custom event names must be strings, and cannot exceed 50 characters in length. + +## Custom Conversions + +Each time the Pixel loads, it automatically calls `fbq('track', 'PageView')` to track a PageView standard event. PageView standard events record the referrer URL of the page that triggered the function call. You can use these recorded URLs in the Events Manager to define visitor actions that should be tracked. + +For example, let’s say that you send visitors who subscribe to your mailing list to a thank you page. You could set up a custom conversion that tracks website visitors who have viewed any page that has `/thank-you` in its URL. Assuming your thank you page is the only page with `/thank-you` in its URL, and you’ve installed the Pixel on that page, anyone who views it will be tracked using that custom conversion. + +Once tracked, custom conversions can be used to optimize your ad campaigns, to define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences), and to further refine custom audiences that rely on standard or custom events. Learn more about custom conversions with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUAIz3AMlNryd-V2gnFMVsYcrYCKp_hWWm-cfuTpQrkXBSQzOk-XP5vANTBK8Yv_HsPhcutdfIUo97IIvQlMaC-H7XaUef2DgmBisXoLZKTiR0cHmMwX0iUqXCLph-DncZUytwTYL0sK-A). + +Since custom conversions rely on complete or partial URLs, you should make sure that you can define visitor actions exclusively based on unique strings in your website URLs. + +### Creating Custom Conversions + +Custom conversions are created entirely within the Events Manager. Refer to our [Advertiser Help document⁠](https://www.facebook.com/business/help/434245993430255) to learn how. + +### Rule-Based Custom Conversions + +Optimize for actions and track them without adding anything to your Meta Pixel base code. You can do this beyond the 17 standard events. + +Create a custom conversion at `/{AD_ACCOUNT_ID}/customconversions`. +Specify a URL, or partial URL, representing an event in `pixel_rule`. For example, `thankyou.html` is a page appearing after purchase. + +This records a `PURCHASE` conversion when `'thankyou.html'` displays: + +You can then create your campaign using the `CONVERSIONS` objective. + +At the ad set level, specify the same custom conversion (`pixel_id`, `pixel_rule`, `custom_event_type`) in `promoted_object`. + +### Custom Conversions Insights + +[Ads Insights](https://developers.facebook.com/docs/marketing-api/insights-api) returns information about Custom Conversions: + +``` +curl -i -G \ +-d 'fields=actions,action_values' \ +-d 'access_token=' \ +https://graph.facebook.com/v2.7//insights +``` + +Returns both standard and custom conversions: + +``` +{ + "data": [\ + {\ + "actions": [\ + {\ + "action_type": "offsite_conversion.custom.17067367629523",\ + "value": 1225\ + },\ + {\ + "action_type": "offsite_conversion.fb_pixel_purchase",\ + "value": 205\ + }\ + ],\ + "action_values": [\ + {\ + "action_type": "offsite_conversion.custom.1706736762929507",\ + "value": 29390.89\ + },\ + {\ + "action_type": "offsite_conversion.fb_pixel_purchase",\ + "value": 29390.89\ + }\ + ],\ + "date_start": "2016-07-28",\ + "date_stop": "2016-08-26"\ + }\ + ], + "paging": { + "cursors": { + "before": "MAZDZD", + "after": "MjQZD" + }, + "next": "https://graph.facebook.com/v2.7//insights?access_token=&pretty=0&fields=actions%2Caction_values&date_preset=last_30_days&level=adset&limit=25&after=MjQZD" + } +} +``` + +Custom conversions have unique IDs; query it for a specific conversion, such as a rule-based one: + +``` +curl -i -G \ +-d 'fields=name,pixel,pixel_aggregation_rule' \ +-d 'access_token=ACCESS-TOKEN' \ +https://graph.facebook.com/v2.7/ +``` + +### Custom Conversions Limitations + +The maximum number of custom conversions per ad account is 100. If you use Ads Insights API to get metrics on custom conversions: + +Getting product ID breakdowns are not supported. +Getting unique action counts are not supported. + +### Flagged custom conversions + +If a custom conversion is flagged, the `is_unavailable` field will be set to `true`. + +``` +{ + "is_unavailable": true, + "id": "30141209892193360" +} +``` + +#### To resolve flagged custom conversions + +If any of your custom conversions are flagged for suggesting information that is not allowed under our terms, you may want to consider the following options: + +To resolve a flagged custom conversion in a new campaign creation: + +**Create new custom conversion**: Use a new custom conversion and make sure that it does not include information that is not allowed under our terms. +**Choose a different custom conversion**: Select a different existing custom conversion and make sure it does not include information that is not allowed under our terms. + +To resolve a flagged custom conversion in an existing campaign: + +**Duplicate your campaign and select an existing custom conversion**: If you have a running campaign that is flagged due to a flagged custom conversion, consider duplicating the campaign and selecting a different custom conversion that is not flagged before publishing the new duplicated campaign. **Note:** Once the campaign is published, you cannot remove or select a different custom conversion. + +#### Request a review + +If you believe your custom conversion has been flagged in error and doesn’t include non-permitted information, you can request a review via Ads Manager under the campaigns table, or in Events Manager under the custom conversions page. + +## Track Offsite Conversions + +Track offsite conversions with your Pixels by adding the `fb_pixel` field to the `tracking_spec` parameter of your ad. [Learn more.](https://developers.facebook.com/documentation/ads-commerce/marketing-api/tracking-specs) + +## Parameters + +Parameters are optional, JSON-formatted objects that you can include when tracking standard and custom events. They allow you to provide additional information about your website visitors’ actions. Once tracked, parameters can be used to further define any custom audiences you create. Learn more about parameters with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUAIz3AMlNryd-V2gnFMVsYcrYCKp_hWWm-cfuTpQrkXBSQzOk-XP5vANTBK8Yv_HsPhcutdfIUo97IIvQlMaC-H7XaUef2DgmBisXoLZKTiR0cHmMwX0iUqXCLph-DncZUytwTYL0sK-A). + +To include a parameter object with a standard or custom event, format your parameter data as an object using JSON, then include it as the third function parameter when calling the `fbq('track')` or `fbq('trackCustom')` functions. + +For example, let’s say you wanted to track a visitor who purchased multiple products as a result of your promotion. You could do this: + +``` +fbq('track', 'Purchase', + // begin parameter object data + { + value: 115.00, + currency: 'USD', + contents: [\ + {\ + id: '301',\ + quantity: 1\ + },\ + {\ + id: '401',\ + quantity: 2\ + }], + content_type: 'product' + } + // end parameter object data +); +``` + +Note that if you want to use data included in event parameters when defining custom audiences, **key values must not contain any spaces**. + +### Object Properties + +You can include the following predefined object properties with any custom events and any [standard events that support them](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#standard-events). Format your parameter object data using JSON. + +| Property Key | Value Type | Parameter Description | +| --- | --- | --- | +| `content_category` | string | Category of the page or product. | +| `content_ids` | array of integers or strings | Product IDs associated with the event, such as SKUs. Example: `['ABC123', 'XYZ789']`. | +| `content_name` | string | Name of the page/product. | +| `content_type` | string | Can be `product` or `product_group` based on the `content_ids` or `contents` being passed. If the IDs being passed in the `content_ids` or `contents` parameter are IDs of products, then the value should be `product`. If product group IDs are being passed, then the value should be `product_group`. | +| `contents` | array of objects | Array of JSON objects that contains the International Article Number (EAN) when applicable or other product or content identifier(s) associated with the event, and quantities and prices of the products. **Required**: `id` and `quantity`.
Example: `[{'id': 'ABC123', 'quantity': 2}, {'id': 'XYZ789', 'quantity': 2}]` | +| `currency` | string | Currency for the `value` specified. | +| `delivery_category` | string | Category of the delivery. Supported values:
`in_store` — Purchase requires customer to enter to the store.
`curbside` — Purchase requires curbside pickup
`home_delivery` — Purchase is delivered to the customer. | +| `num_items` | integer | Number of items when checkout was initiated. Used with the `InitiateCheckout` event. | +| `predicted_ltv` | integer, float | Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value. | +| `search_string` | string | String entered by the user for the search. Used with the `Search` event. | +| `status` | Boolean | Used with the `CompleteRegistration` event, to show the status of the registration. | +| `value` | integer or float | Required for purchase events or any events that utilize value optimization. A numeric value associated with the event. This must represent a monetary amount. | + +### Custom Properties + +If our predefined object properties don’t suit your needs, you can include your own, custom properties. Custom properties can be used with both standard and custom events, and can help you further define custom audiences. + +For example, let’s say you wanted to track a visitor who purchased multiple products after having first compared them to other products. You could do this: + +``` +fbq('track', 'Purchase', + // begin parameter object data + { + value: 115.00, + currency: 'USD', + contents: [\ + {\ + id: '301',\ + quantity: 1\ + },\ + {\ + id: '401',\ + quantity: 2\ + }], + content_type: 'product', + compared_product: 'recommended-banner-shoes', // custom property + delivery_category: 'in_store' + } + // end parameter object data +); +``` + +## Next Steps + +Now that you’re tracking conversions, we recommend that you use them to define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences), so you can optimize your ads for website conversions. + +## Learn More + +Learn more about conversion tracking with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUAIz3AMlNryd-V2gnFMVsYcrYCKp_hWWm-cfuTpQrkXBSQzOk-XP5vANTBK8Yv_HsPhcutdfIUo97IIvQlMaC-H7XaUef2DgmBisXoLZKTiR0cHmMwX0iUqXCLph-DncZUytwTYL0sK-A). + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-custom-audiences.md b/.agents/skills/meta-ads/references/pixel/pixel-custom-audiences.md new file mode 100644 index 0000000..1e0f6d0 --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-custom-audiences.md @@ -0,0 +1,40 @@ + + +Meta Pixel + +Was this helpful? + +# Custom Audiences + +Updated: Jan 27, 2022 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences.md) + +If you are [tracking conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking), you can segment your website visitors into groups based on the actions they have taken on your website. These groups are called **custom audiences**. Once you have defined a custom audience, you can [optimize your ad sets⁠](https://www.facebook.com/business/help/1082085278508457) to target other Facebook users who match that audience’s criteria. + +### Requirements + +The Pixel’s [base code](https://developers.facebook.com/documentation/meta-pixel/get-started#base-code) must already be installed and tracking [standard events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#standard-events), [custom events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#custom-events), or [custom conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#custom-conversions). +You must have access to the [Facebook Ads Manager⁠](https://www.facebook.com/adsmanager). + +## Defining Custom Audiences + +Before you can define a custom audience, make sure the Events Manager is tracking your events or custom conversions correctly, otherwise you will not be able to select them in the Events Manager when setting up a custom audience. + +### Standard and Custom Events + +To define a custom audience from a standard or custom event, follow the instructions in our [About Custom Audiences from your website⁠](https://www.facebook.com/business/help/1474662202748341) Business Manager help document. + +### Custom Conversions + +To create an audience from a [custom conversion](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#custom-conversions), follow the instructions in our [About Custom Audiences from your website⁠](https://www.facebook.com/business/help/1474662202748341) Business Manager help document, but select **People who visited specific webpages** at step #4. Use the same URL criteria that you used to define your custom conversion. + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-data-processing-options.md b/.agents/skills/meta-ads/references/pixel/pixel-data-processing-options.md new file mode 100644 index 0000000..b949c5a --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-data-processing-options.md @@ -0,0 +1,37 @@ + + +Meta Pixel + +Was this helpful? + +# Data processing options for US users - Meta Pixel + +Updated: May 1, 2023 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/implementation/data-processing-options.md) + +Starting June 1, 2023, Limited Data Use for people in Colorado and Connecticut via Meta Business Tools and Meta Audience Network will be effective. Starting June 1, 2023, Limited Data Use for people in California via customer list custom audiences will also be effective. To give businesses time to prepare, Limited Data Use’s expanded features are available to explore as of May 1, 2023, but won’t go into effect until June 1, 2023. Please note that any Limited Data Use flag sent for these updated states and products prior to June 1, 2023, will not be implemented. + +Limited Data Use is a data processing option that gives you more control over how your data is used in Meta’s systems and better supports your compliance efforts with various US state privacy regulations. +To utilize this feature, you must proactively enable Limited Data Use. When Meta receives data with Limited Data Use enabled from people in the states where Limited Data Use applies, we will process that data in accordance with our role as a service provider or processor, as applicable, and limit the use of that data as specified in our [State-Specific Terms⁠](https://www.facebook.com/legal/terms/state-specific). + +For [Business Tools⁠](https://www.facebook.com/help/331509497253087) and Audience Network, Limited Data Use is available only for people in California, Colorado or Connecticut. If a business enables Limited Data Use but does not set the location parameters to US and California, Colorado or Connecticut, we will determine if the event is from one of those states. If Limited Data Use is enabled for an event in California, Colorado or Connecticut, we will process data in accordance with our role as a service provider or processor and limit the use of that data in accordance with our [State-Specific Terms⁠](https://www.facebook.com/legal/terms/state-specific). + +Businesses may notice an impact to campaign performance and effectiveness, and retargeting and measurement capabilities will be limited when Limited Data Use is enabled. + +## Implementation + +| Implementation | Adding Data Processing Options | +| --- | --- | +| Browser Pixel | Update Pixel initialization code to specify the `dataProcessingOptions` method before you call `fbq('init')`.
To explicitly not enable Limited Data Use (LDU):
```
fbq('dataProcessingOptions', []);
fbq('init', '{pixel_id}');
fbq('track', 'PageView');
```
To enable LDU and have Meta perform geolocation:
```
fbq('dataProcessingOptions', ['LDU'], 0, 0);
```
To enable LDU and specify the location, e.g., for California:
```
fbq('dataProcessingOptions', ['LDU'], 1, 1000);
``` | +| Image tag | Add the following to the Pixel image tag:
`dpo`: data processing options
`dpoco`: data processing options country
`dpost`: data processing options state
See [Reference](https://developers.facebook.com/documentation/ads-commerce/marketing-api/overview/data-processing-options#reference) for accepted values.
To explicitly not enable LDU, pass an empty value for the `dpo` parameter:
```

```
To enable LDU and have Meta perform geolocation:
```

```
To enable LDU and manually specify the location, e.g., for California:
```

``` | + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-gdpr.md b/.agents/skills/meta-ads/references/pixel/pixel-gdpr.md new file mode 100644 index 0000000..8d1fc1a --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-gdpr.md @@ -0,0 +1,65 @@ + + +Meta Pixel + +Was this helpful? + +# General Data Protection Regulation + +Updated: Jul 14, 2023 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/implementation/gdpr.md) + +The General Data Protection Regulation (GDPR) creates consistent data protection rules across Europe. It applies to companies (regardless of where they are based) who process personal data about individuals in the EU. + +While many of the principles build on current EU data protection rules, the GDPR has a wider scope, more prescriptive standards and substantial fines. For example, it requires a higher standard of consent for using some types of data and broadens individuals’ rights with respect to accessing and porting their data. + +Businesses who advertise with the Facebook companies can continue to use Facebook platforms and solutions in the same way they do today. Each company is responsible for ensuring their own compliance with the GDPR, just as they are responsible for compliance with the laws that apply to them today. + +## Cookie Consent + +Businesses may want to implement code that creates a banner and requires affirmative consent (for example, an “I agree” checkbox at the top of the page) to use the Pixel. If you already have a system in place that addresses this need, such as a tag manager, you can make this code optional. + +Use the following API to pause sending Pixel fires to Facebook, and once cookie consent is granted, send Pixel fires to Facebook. You need to call revoke on every page. + +``` +fbq('consent', 'revoke'); +fbq('consent', 'grant'); +``` + +For example: + +``` +// Revoke consent before 'init' is called +fbq('consent', 'revoke'); +fbq('init', ''); +fbq('track', 'PageView'); +``` + +``` +// Once affirmative consent has been granted +fbq('consent', 'grant'); +``` + +See our [Cookie Policy⁠](https://www.facebook.com/policies/cookies/) for details about the cookies used and the data received. The Meta Pixel receives these types of data: + +**Http Headers** – Anything that is generally present in HTTP headers, a standard web protocol sent between any browser request and any server on the internet. This information may include data like IP addresses, information about the web browser, page location, document, referrer and person using the website. +**Pixel-specific Data** – Includes Pixel ID and the Facebook Cookie. +**Button Click Data** – Includes any buttons clicked by site visitors, the labels of those buttons and any pages visited as a result of the button clicks. +**Optional Values** – Developers and marketers can optionally choose to send additional information about the visit through [conversion tracking](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking). Example custom data events are conversion value, page type, and more. +**Form Field Names** – Includes website field names like ‘email’, ‘address’, ‘quantity’ for when you purchase a product or service. We don’t capture field values unless you include them as part of [Advanced Matching](https://developers.facebook.com/documentation/meta-pixel/advanced/advanced-matching), or [conversion tracking](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking). + +## Learn more + +[Advertiser Help⁠](https://www.facebook.com/business/help/225009134722945) +[Facebook’s GDPR microsite⁠](https://www.facebook.com/business/gdpr) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-get-started.md b/.agents/skills/meta-ads/references/pixel/pixel-get-started.md new file mode 100644 index 0000000..835d45a --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-get-started.md @@ -0,0 +1,112 @@ + + +Meta Pixel + +Was this helpful? + +# Get started with the Meta Pixel + +Updated: Jun 30, 2026 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/get-started.md) + +The Meta Pixel is a snippet of JavaScript code that loads a small library of functions you can use to track Facebook ad-driven visitor activity on your website. It relies on [Facebook cookies⁠](https://www.facebook.com/policies/cookies/), which enable us to match your website visitors to their respective Facebook User accounts. Once matched, we can tally their actions in the Facebook Ads Manager so you can use the data to analyze your website’s conversion flows and optimize your ad campaigns. + +By default, the Pixel will track URLs visited, domains visited, and the devices your visitors use. In addition, you can use the Pixel’s library of functions to: + +[track conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking), so you can measure ad effectiveness +define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences), so you can target visitors who are more likely to convert +set up [Advantage+ catalog ads](https://developers.facebook.com/docs/facebook-pixel/implementation/dynamic-ads) campaigns + +### Requirements + +In order to implement the Pixel, you will need: + +access to your website’s code base +your Pixel’s [base code](https://developers.facebook.com/documentation/meta-pixel/get-started) or its ID +access to the [Facebook Ads Manager⁠](https://www.facebook.com/adsmanager) + +In addition, depending on where you conduct business, you may have to comply with [General Data Protection Regulation](https://developers.facebook.com/documentation/meta-pixel/implementation/gdpr). + +Ready? [Let’s get started](https://developers.facebook.com/documentation/meta-pixel/get-started). + +## Base Code + +Before you can install the Pixel, you will need your Pixel’s base code, which you can find in the [Ads Manager > Events Manager⁠](https://business.facebook.com/events_manager). If you have not created a Pixel, [follow these instructions⁠](https://www.facebook.com/business/help/952192354843755) to create one — all you will need is the Pixel’s base code (step 1). + +The base Pixel code contains your Pixel’s ID in two places and looks like this: + +``` + + + + +``` + +When run, this code will download a library of functions which you can then use for [conversion tracking](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking). It also automatically tracks a single `PageView` conversion by calling the `fbq()` function each time it loads. _We recommend that you leave this function call intact_. + +## Installing The Pixel + +To install the Pixel, we highly recommend that you add its base code between the opening and closing `` tags on every page where you will be tracking website visitor actions. Most developers add it to their website’s persistent header, so it can be used on all pages. + +Placing the code within your `` tags reduces the chances of browsers or third-party code blocking the Pixel’s execution. It also executes the code sooner, increasing the chance that your visitors are tracked before they leave your page. + +Once you have added it to your website, load a page that has the Pixel. This should call `fbq('track', 'PageView')`, which will be tracked as a `PageView` event in the Events Manager. + +![Events Manager events chart showing a single tracked PageView event spike, confirming the Pixel is installed](https://scontent-lax3-1.xx.fbcdn.net/v/t39.2365-6/40918111_2211034969153925_7326281962849566720_n.png?_nc_cat=102&ccb=1-7&_nc_sid=e280be&_nc_ohc=BJcnekmn86sQ7kNvwEtNuCS&_nc_oc=AdoJHv7tlo3n3yfX23AnCYYtns-0rWdTTqucfjH-zWukio6_v88qgH4WmOzpseX018E&_nc_zt=14&_nc_ht=scontent-lax3-1.xx&_nc_gid=GuNoEVEAwlKlz-xrJfBPoQ&_nc_ss=7b289&oh=00_AQItcP5R9LZa1wNBtzbnscNrBk9emrjdivj7JndApxrHMg&oe=6AB9F4E5) + +Verify that this event was tracked by going to your Events Manager. Locate your Pixel and click its details — if you see a new `PageView` event, you have successfully installed the Pixel. If you do not see it, wait a few minutes and refresh the page. If your Pixel is still not working, use the [Meta Ads Data Advisor](https://developers.facebook.com/documentation/meta-pixel/get-started#meta-ads-data-advisor) to track down the problem. + +### Installing Using a Tag Manager + +Although we recommend adding the Pixel directly to your website’s `` tags, the Pixel will work in most tag management and tag container solutions. For specific advice on implementing the Pixel using your tag manager, please refer to your tag manager’s documentation. + +### Installing Using an IMG Tag + +Although not recommended, you can alternately [install the Pixel using an `` tag](https://developers.facebook.com/documentation/meta-pixel/advanced#install-the-pixel-using-an-img-tag). + +### Mobile Websites + +If your mobile website is separate from your desktop website, we recommend that you add the Pixel to both. This will allow you to easily remarket to your mobile visitors, exclude them, or create lookalikes audiences. + +## Meta Ads Data Advisor + +We highly recommend that you install our [Meta Ads Data Advisor](https://developers.facebook.com/documentation/meta-pixel/support/meta-ads-data-advisor) Chrome extension. Data Advisor provides extremely valuable feedback that can help you verify that your Pixel is working correctly, especially when you start tracking conversions, where you can easily encounter formatting errors. + +## Next Steps + +Once you have verified that the Pixel is installed and tracking the `PageView` event correctly, you can use the Pixel to: + +[track conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking) +create [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences) +set up [Advantage+ catalog ads](https://developers.facebook.com/docs/facebook-pixel/implementation/dynamic-ads) + +Learn more about implementing the Pixel with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fcollection%2F240330%2Fpath%2F210139%3Fcontent_id%3DyyTGMzFI48JBDxv&h=AUBryvhw9PQVErmxM5D4Erl3PfGoCbrQNus7gHVtTcc8Xh6fkvcTYR_1cJbjX6W0iAxAU3TfMOcACCiEFgsBA1bBKcyHhZ4rWdb2a-tFSHTMDubhKG1B27qYvlR7A_TVwldd5w9bBryz4A). + +## Resources + +Meta Blueprint: [Learn more about implementing the pixel⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fpath%2F219710-technical-implementation-meta-pixel%3Fcontent_id%3Den4RqCL2PfBZrUU&h=AUBryvhw9PQVErmxM5D4Erl3PfGoCbrQNus7gHVtTcc8Xh6fkvcTYR_1cJbjX6W0iAxAU3TfMOcACCiEFgsBA1bBKcyHhZ4rWdb2a-tFSHTMDubhKG1B27qYvlR7A_TVwldd5w9bBryz4A) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-overview.md b/.agents/skills/meta-ads/references/pixel/pixel-overview.md new file mode 100644 index 0000000..39e1684 --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-overview.md @@ -0,0 +1,54 @@ + + +Meta Pixel + +Was this helpful? + +# Meta Pixel + +Updated: Nov 15, 2023 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel.md) + +The Meta Pixel is a snippet of JavaScript code that allows you to track visitor activity on your website. It works by loading a small library of functions which you can use whenever a site visitor takes an action (called an **event**) that you want to track (called a **conversion**). [Tracked conversions](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking) appear in the [Ads Manager⁠](https://www.facebook.com/adsmanager) where they can be used to measure the effectiveness of your ads, to define [custom audiences](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences) for ad targeting, for [Advantage+ catalog ads](https://developers.facebook.com/docs/facebook-pixel/implementation/dynamic-ads) campaigns, and to analyze that effectiveness of your website’s conversion funnels. + +The Meta Pixel can collect the following data: + +**Http Headers** – Anything that is generally present in HTTP headers, a standard web protocol sent between any browser request and any server on the internet. This information may include data like IP addresses, information about the web browser, page location, document, referrer and person using the website. +**Pixel-specific Data** – Includes Pixel ID and the Facebook Cookie. +**Button Click Data** – Includes any buttons clicked by site visitors, the labels of those buttons and any pages visited as a result of the button clicks. +**Optional Values** – Developers and marketers can optionally choose to send additional information about the visit through Custom Data events. Example custom data events are [conversion value, page type and more](https://developers.facebook.com/documentation/meta-pixel/implementation/custom-audiences). +**Form Field Names** – Includes website field names like `email`, `address`, `quantity`, etc., for when you purchase a product or service. We don’t capture field values unless you include them as part of [Advanced Matching](https://developers.facebook.com/documentation/meta-pixel/advanced/advanced-matching) or optional values. + +## Documentation Contents + +### [Get Started](https://developers.facebook.com/documentation/meta-pixel/get-started) + +A short tutorial on adding the Pixel base code to your webpages. + +### [Guides](https://developers.facebook.com/documentation/meta-pixel/guides) + +Use case based guides to help you perform specific actions. + +### [Reference](https://developers.facebook.com/documentation/meta-pixel/reference) + +Product specifications and endpoint references. + +### [Support](https://developers.facebook.com/documentation/meta-pixel/support) + +Solutions to common problems, troubleshooting tips, and tools. + +## Learn more + +Track User activity in a mobile app using [Facebook App Events](https://developers.facebook.com/documentation/app-events) +[Apple’s iOS 14 Requirements for Meta Pixel⁠](https://www.facebook.com/business/help/721422165168355) + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-reference-standard-events.md b/.agents/skills/meta-ads/references/pixel/pixel-reference-standard-events.md new file mode 100644 index 0000000..25242ab --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-reference-standard-events.md @@ -0,0 +1,65 @@ + + +Meta Pixel + +Was this helpful? + +# Meta Pixel API reference + +Updated: Jul 16, 2024 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/reference.md) + +## Standard Events + +You can use the Meta Pixel’s `fbq('track')` function to track the following [standard events](https://developers.facebook.com/documentation/meta-pixel/implementation/conversion-tracking#standard-events). Standard events also support [parameter](https://developers.facebook.com/documentation/meta-pixel/reference#object-properties) objects with specific object properties, which allow you to include detailed information about an event. + +If you’re implementing the Meta Pixel alongside the [Conversions API](https://developers.facebook.com/documentation/ads-commerce/conversions-api), we recommend you include the `eventID` parameter as a fourth parameter to the `fbq('track')` function. See the [Deduplicate Pixel and Server Events](https://developers.facebook.com/documentation/ads-commerce/conversions-api/deduplicate-pixel-and-server-events) documentation for more information. + +| Event Name | Event Description | Object Properties | Promoted Object custom\_event\_type value | +| --- | --- | --- | --- | +| `AddPaymentInfo` | When payment information is added in the checkout flow. _A person clicks on a save billing information button._ | `content_ids`, `contents`, `currency`, `value`
_Optional._ | ADD\_PAYMENT\_INFO | +| `AddToCart` | When a product is added to the shopping cart.
_A person clicks on an add to cart button._ | `content_ids`, `content_type`, `contents`, `currency`, `value`
_Optional._
_Required for Advantage+ catalog ads:_
_`contents`_ | ADD\_TO\_CART | +| `AddToWishlist` | When a product is added to a wishlist.
_A person clicks on an add to wishlist button._ | `content_ids`, `contents`, `currency`, `value`
_Optional._ | ADD\_TO\_WISHLIST | +| `CompleteRegistration` | When a registration form is completed.
_A person submits a completed subscription or signup form._ | `currency`, `value`
_Optional._ | COMPLETE\_REGISTRATION | +| `Contact` | When a person initiates contact with your business via telephone, SMS, email, chat, etc.
_A person submits a question about a product._ | _Optional._ | CONTACT | +| `CustomizeProduct` | When a person customizes a product.
_A person selects the color of a t-shirt._ | _Optional._ | CUSTOMIZE\_PRODUCT | +| `Donate` | When a person donates funds to your organization or cause.
_A person adds a donation to the Humane Society to their cart._ | _Optional._ | | +| `FindLocation` | When a person searches for a location of your store via a website or app, with an intention to visit the physical location.
_A person wants to find a specific product in a local store._ | _Optional._ | FIND\_LOCATION | +| `InitiateCheckout` | When a person enters the checkout flow prior to completing the checkout flow.
_A person clicks on a checkout button._ | `content_ids`, `contents`, `currency`, `num_items`, `value`
_Optional._ | INITIATE\_CHECKOUT | +| `Lead` | When a sign up is completed.
_A person clicks on pricing._ | `currency`, `value`
_Optional._ | LEAD | +| `Purchase` | When a purchase is made or checkout flow is completed.
_A person has finished the purchase or checkout flow and lands on thank you or confirmation page._ | `content_ids`, `content_type`, `contents`, `currency`, `num_items`, `value`
_**Required:**`currency` and `value`_
_Required for Advantage+ catalog ads:_
_`contents` or `content_ids`_ | PURCHASE | +| `Schedule` | When a person books an appointment to visit one of your locations.
_A person selects a date and time for a tennis lesson._ | _Optional._ | SCHEDULE | +| `Search` | When a search is made.
_A person searches for a product on your website._ | `content_ids`, `content_type`, `contents`, `currency`, `search_string`, `value`
_Optional._
_Required for Advantage+ catalog ads:_
_`contents` or `content_ids`_ | SEARCH | +| `StartTrial` | When a person starts a free trial of a product or service you offer.
_A person selects a free week of your game._ | `currency`, `predicted_ltv`, `value`
_Optional._ | START\_TRIAL | +| `SubmitApplication` | When a person applies for a product, service, or program you offer.
_A person applies for a credit card, educational program, or job._ | _Optional._ | SUBMIT\_APPLICATION | +| `Subscribe` | When a person applies to a start a paid subscription for a product or service you offer.
_A person subscribes to your streaming service._ | `currency`, `predicted_ltv`, `value`
_Optional._ | SUBSCRIBE | +| `ViewContent` | A visit to a web page you care about (for example, a product page or landing page). `ViewContent` tells you if someone visits a web page’s URL, but not what they see or do on that page.
_A person lands on a product details page._ | `content_ids`, `content_type`, `contents`, `currency`, `value`
_Optional._
_Required for Advantage+ catalog ads:_
_`contents` or `content_ids`_ | VIEW\_CONTENT | + +## Object Properties + +You can include the following predefined object properties with any custom events, and any standard events that support them. Format your parameter object data using JSON. Learn more about event parameters with [Blueprint⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fwww.facebookblueprint.com%2Fstudent%2Fcollection%2F240330%2Fpath%2F210140%3Fcontent_id%3D9yCDpJgXbYOg8OK&h=AUAl3lb85HIJtMfiMG6F3O6n6cVm73kdLZ561aG9VnIGMkmlLyt-z-mEHvogBoT2a-huqv8Rwm68Dp9e3T25MGA4rbbWM-cdzRFFkKEsX2QoxD5-Axv-o-0cJxryDDnrZxaqRHyrDsMt_g). + +| Property Key | Value Type | Parameter Description | +| --- | --- | --- | +| `content_category` | String | Category of the page/product.
_Optional._ | +| `content_ids` | Array of integers or strings | Product IDs associated with the event, such as SKUs (e.g. `['ABC123', 'XYZ789']`). | +| `content_name` | String | Name of the page/product.
_Optional._ | +| `content_type` | String | Either `product` or `product_group` based on the `content_ids` or `contents` being passed. If the IDs being passed in `content_ids` or `contents` parameter are IDs of products, then the value should be `product`. If product group IDs are being passed, then the value should be `product_group`.
If no `content_type` is provided, Meta will match the event to every item that has the same ID, independent of its type. | +| `contents` | Array of objects | An array of JSON objects that contains the quantity and the International Article Number (EAN) when applicable, or other product or content identifier(s). `id` and `quantity` are the required fields. e.g. `[{'id': 'ABC123', 'quantity': 2}, {'id': 'XYZ789', 'quantity': 2}]`. | +| `currency` | String | The currency for the `value` specified. | +| `num_items` | Integer | Used with `InitiateCheckout` event. The number of items when checkout was initiated. | +| `predicted_ltv` | Integer, float | Predicted lifetime value of a subscriber as defined by the advertiser and expressed as an exact value. | +| `search_string` | String | Used with the `Search` event. The string entered by the user for the search. | +| `status` | Boolean | Used with the `CompleteRegistration` event, to show the status of the registration.
_Optional._ | +| `value` | Integer or float | The value of a user performing this event to the business. | + +Did you find this page helpful? + +![Thumbs up icon](https://static.xx.fbcdn.net/rsrc.php/yR/r/OEXJ0_DJeZv.svg) + +![Thumbs down icon](https://static.xx.fbcdn.net/rsrc.php/yb/r/qKPgNVNeatU.svg) + +* * * \ No newline at end of file diff --git a/.agents/skills/meta-ads/references/pixel/pixel-single-page-apps.md b/.agents/skills/meta-ads/references/pixel/pixel-single-page-apps.md new file mode 100644 index 0000000..1b781f9 --- /dev/null +++ b/.agents/skills/meta-ads/references/pixel/pixel-single-page-apps.md @@ -0,0 +1,88 @@ + + +Meta Pixel + +# Meta Pixel Implementation for Single Page Applications + +Updated: Jan 27, 2022 + +Copy for LLM + +[View as Markdown](https://developers.facebook.com/documentation/meta-pixel/implementation/tag_spa.md) + +Single Page Applications (SPA) does not require a page to be reloaded when the URL changes therefore a different approach to event tracking with the Meta Pixel has to be followed. + +### Requirements + +The Pixel’s [base code](https://developers.facebook.com/documentation/meta-pixel/get-started) must already be installed on the webpage where you will be tracking events. + +**Note:** You can set `disablePushState` to `true` to stop sending `PageView` events on history state changes but it is not recommended. + +## Track a an Action + +Track a specific area where an action it taking place using the History State API. There is no one one-size fits all solution to this as it highly depends on the framework and the implementation details. The general idea is to track the event whenever there is a URL change in the SPA. Hooking it into the routing system of the framework or application is required. + +#### Example Code + +``` +... + + +... + + + +... +``` + +## Learn More + +Visit [Google’s Tag Manager documentation⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fmarketingplatform.google.com%2Fabout%2Ftag-manager%2F&h=AUAdgUkgbOdZYBiOs3eFovE8XO1wkoXdZEC3pibkHSUmtZhO8MTkPnI8-dIpu4V1cK0zKA_cVM6TkoSqXJwNbsE-R-8ux6Zaqn0zITjVRxjvL6nckgVqYJlEOagoWQ7_Qb44YKQra6Q82Q) to track events using a tag manager +Debug using [DataLayer plugins⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fchrome.google.com%2Fwebstore%2Fdetail%2Fdatalayer-checker%2Fffljdddodmkedhkcjhpmdajhjdbkogke&h=AUAdgUkgbOdZYBiOs3eFovE8XO1wkoXdZEC3pibkHSUmtZhO8MTkPnI8-dIpu4V1cK0zKA_cVM6TkoSqXJwNbsE-R-8ux6Zaqn0zITjVRxjvL6nckgVqYJlEOagoWQ7_Qb44YKQra6Q82Q) or the [Meta Ads Data Advisor⁠](https://l.facebook.com/l.php?u=https%3A%2F%2Fchrome.google.com%2Fwebstore%2Fdetail%2Ffacebook-pixel-helper%2Ffdgfkebogiimcoedlicjlajpkdmockpc&h=AUAdgUkgbOdZYBiOs3eFovE8XO1wkoXdZEC3pibkHSUmtZhO8MTkPnI8-dIpu4V1cK0zKA_cVM6TkoSqXJwNbsE-R-8ux6Zaqn0zITjVRxjvL6nckgVqYJlEOagoWQ7_Qb44YKQra6Q82Q) to see event tracking + +* * * \ No newline at end of file