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
- 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.
- Never break the dedup equality (browser eventID === server
event_id, matching names) — silent double-counting or
double-sending is the #1 tracking bug class.
- 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.
capi_event_log is the idempotency ledger — anything that can fire
twice (webhook retries, status toggles) must be guarded through it.- Test Mode (
test_event_code) exists for verification — use
capi-verifying-setup.md's flow before claiming an event works.
- 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:
firecrawl scrape "https://developers.facebook.com/documentation/<path>" --only-main-content
Keep the source header (URL + fetch date) on every file so staleness is
auditable. Content below the header stays unaltered.
1---2name: meta-ads3description: 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).4---56# Meta Ads — Pixel & Conversions API Official Documentation78CodFlow's tracking stack (Meta Pixel in theme01 + Conversions API in9cod-server) must always match **Meta's official behavior**. This skill10vendors the official documentation so every change — ours or a11contributor's — can be grounded against the real spec instead of guesses,12blog posts, or AI memory.1314**Rule for agents and contributors: any tracking change must be verified15against these docs before review.** When replying to a tracking PR, read16the relevant reference here first and cite it.1718## The docs (all unaltered official content, fetched from developers.facebook.com)1920### Pixel — browser side (`fbq()`)2122| File | What it covers |23|---|---|24| `references/pixel/pixel-overview.md` | What the Pixel is, redundant setup with CAPI |25| `references/pixel/pixel-get-started.md` | Installing the base code, the `fbq` queue |26| `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?" |27| `references/pixel/pixel-conversion-tracking.md` | Firing events on actions vs page load, purchase-confirmation-page pattern |28| `references/pixel/pixel-advanced-matching.md` | `em`, `ph` etc. customer params on `fbq('init')` |29| `references/pixel/pixel-single-page-apps.md` | SPA pitfalls (irrelevant to our full-page loads — know why) |30| `references/pixel/pixel-custom-audiences.md` | Audience creation from Pixel data |31| `references/pixel/pixel-gdpr.md` | GDPR/Limited Data Use reasoning |32| `references/pixel/pixel-data-processing-options.md` | `_fbp` cookie + data processing options |3334### Conversions API — server side (`/events` endpoint)3536| File | What it covers |37|---|---|38| `references/conversions-api/capi-overview.md` | What CAPI is, redundant setup recommendation |39| `references/conversions-api/capi-get-started.md` | System user tokens, access, first request |40| `references/conversions-api/capi-using-the-api.md` | Endpoint mechanics, payloads, batching, error handling |41| `references/conversions-api/capi-parameters.md` | Parameters index |42| `references/conversions-api/capi-server-event-parameters.md` | **`event_name`, `event_time`, `event_id`, `event_source_url`, `action_source`** — the per-event field contract |43| `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 |44| `references/conversions-api/capi-custom-data-parameters.md` | `value`, `currency`, `contents`, `content_ids`, `order_id`, `num_items` |45| `references/conversions-api/capi-original-event-parameters.md` | Original-event dedup fields (aggregated/merged events) |46| `references/conversions-api/capi-main-body-parameters.md` | `data[]`, `test_event_code` wrapper |47| `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 |48| `references/conversions-api/capi-best-practices.md` | Meta's recommended architecture, timing, and matching quality guidance |49| `references/conversions-api/capi-verifying-setup.md` | Events Manager validation, Test Events |50| `references/conversions-api/capi-offline-events.md` | Offline conversion semantics (delayed events — the category our purchase-on-delivery model lives in) |51| `references/conversions-api/capi-payload-helper.md` | Meta's interactive payload builder (for debugging shapes) |5253## How CodFlow maps onto these docs (quick orientation)5455- **Browser:** theme01's `BaseHead.astro` loads the canonical `fbevents.js`56 snippet (PageView on load); `thank-you.astro` fires the conversion event57 with `{ eventID: orderId }` — the fourth `fbq` argument, per the dedup doc.58- **Server:** `cod-server/src/workflows/capi.ts` (Cloudflare Workflow)59 sends the mirrored event via `/events` with `event_id: orderId`;60 `capi-helpers.ts` gates which status transitions trigger it;61 `capi_event_log` records what was sent (and powers idempotency).62- **Config:** `store_pixel_config` (pixel id, access token, test event63 code, conversion event choice, test mode) — Settings → Tracking.64- **Dedup contract:** browser `eventID` === CAPI `event_id` === orderId,65 same `event_name` on both sides. Any tracking change that breaks this66 equality double-counts conversions (see capi-deduplication.md).67- **Standard-event semantics:** which CodFlow moment maps to which Meta68 event is governed by pixel-reference-standard-events.md — notably69 `Purchase` is defined as at-checkout ("lands on thank you or70 confirmation page") and `Lead` as a completed sign-up. COD71 purchase-on-delivery is an offline-style delayed Purchase (see72 capi-offline-events.md) — legitimate, but it must be a deliberate73 merchant choice, not a silent default.7475## Working rules for tracking changes76771. **Ground first.** Read the relevant reference file(s) above before78 writing or reviewing a single line of tracking code. Cite the doc in79 the PR/review when a decision hinges on Meta behavior.802. **Never break the dedup equality** (browser eventID === server81 event_id, matching names) — silent double-counting or82 double-sending is the #1 tracking bug class.833. **A new conversion-event mode must fire from BOTH sides** (browser +84 CAPI mirror) or from exactly ONE side deliberately, never accidentally.85 PR #103's lesson: a mode that exists only in the settings enum is not a86 feature.874. **`capi_event_log` is the idempotency ledger** — anything that can fire88 twice (webhook retries, status toggles) must be guarded through it.895. **Test Mode** (`test_event_code`) exists for verification — use90 capi-verifying-setup.md's flow before claiming an event works.916. **Docs are read-only reference.** These files are unaltered Meta92 content (only a source header is prepended). Never edit them to match93 code — if code and docs disagree, the CODE changes (or Meta did, and94 we re-fetch).9596## Refreshing the docs9798Meta updates its docs; when a tracking question can't be answered from99these files (or the content looks outdated), re-fetch with Firecrawl:100101```sh102firecrawl scrape "https://developers.facebook.com/documentation/<path>" --only-main-content103```104105Keep the source header (URL + fetch date) on every file so staleness is106auditable. Content below the header stays unaltered.
bighadj22