meta-ads-tracking-setup

Files (2)

• SKILL.md
• capi-event-parameters.md · references/

SKILL.md (first lines)

## Why This Matters

Meta's Andromeda deep learning architecture uses signal quality as its primary input for ad delivery optimization. Weak tracking = weak signals = poor delivery = wasted spend. Getting Pixel + CAPI right is foundational — do this before any campaign optimization.

## Process

1. **Audit current state** — Check Events Manager for active Pixel, CAPI status, EMQ scores, event volume, and deduplication status
2. **Choose implementation path** — Select CAPI method based on technical resources and budget (see Decision Tree below)
3. **Implement CAPI** — Deploy server-side tracking alongside existing Pixel
4. **Configure event deduplication** — Match `event_id` between Pixel and CAPI to prevent double-counting
5. **Optimize EMQ** — Add all matching keys to maximize user match rate
6. **Validate** — Use Test Events tool to confirm both Pixel and CAPI fire correctly
7. **Monitor** — Track EMQ scores, event volumes, and deduplication rates weekly for 30 days

## CAPI Implementation Decision Tree

Ask these questions in order:

**Q1: What platform runs the website?**
- Shopify → Use **native Shopify integration** (free, built-in CAPI, minimal setup)
- WordPress/WooCommerce → Use **CAPI Gateway** or **server-side GTM**
- Custom-built site → Use **server-side GTM** or **manual API**
- No website (CRM/offline events only) → Use **manual API** with `action_source: system_generated`

**Q2: What's the technical budget?**

| Method | Cost | Dev Effort | Best For |
|--------|------|-----------|----------|
| Native platform integration (Shopify, WooCommerce plugins) | Free–$50/mo | Low | Ecommerce on supported platforms |
| CAPI Gateway | $10–$400/mo hosting | Low–Medium | Teams wanting managed solution |
| Server-side GTM | $10–$50/mo (GCP) | Medium | Teams already using GTM |
| Manual API implementation | $500–$5K+ dev time | High | Custom platforms, maximum control |

**Q3: Are there offline/CRM conversions?**
- Yes → Must implement CAPI with stored `fbc` values (see fbclid Capture Workflow below)
- **CRITICAL (May 2025):** Meta permanently discontinued the Offline Conversions API. All offline tracking now flows through standard CAPI with `action_source` set to `physical_store` or `system_generated`

## Pixel vs CAPI Comparison

| Dimension | Meta Pixel (Client-Side) | Conversions API (Server-Side) |
|-----------|------------------------|------------------------------|
| How it fires | JavaScript in browser | Server-to-server HTTP POST |
| Blocked by ad blockers | Yes | No |
| Blocked by iOS ATT | Partially | No (server-side) |
| Blocked by cookie restrictions | Yes (3P cookies) | No |
| Data freshness | Real-time | Near real-time (seconds) |
| Data quality control | Limited | Full (you control the payload) |
| Events supported | Web events only | Web + offline + CRM + in-store |
| Required for | Baseline tracking | Signal recovery + offline events |
| Typical signal recovery | Baseline | Recovers 20–30% of events lost to browser restrictions |

**Both are required.** Pixel alone misses 20-30% of events. CAPI alone misses real-time behavioral signals. Together they give Meta's algorithm the fullest picture.

## Event Deduplication Setup

When both Pixel and CAPI fire for the same event, Meta must know they're the same event to avoid double-counting.

**How it works:**
1. Generate a unique `event_id` on your server or in the browser (UUID or timestamp-based)
2. Pass the same `event_id` to both the Pixel event AND the CAPI event
3. Both events must share the same `event_name` (e.g., both say `Purchase`)
4. Meta deduplicates by matching `event_id` + `event_name`

**Implementation pattern:**
```
// Browser: Pixel fires with event_id
fbq('track', 'Purchase', {value: 99.99, currency: 'USD'}, {eventID: 'order_abc123'});

// Server: CAPI fires with same event_id
POST to graph.facebook.com with event_id: 'order_abc123'
```

**Validation:** In Events Manager, check "Overview" tab → deduplication should show matched events. If CAPI event count far exceeds Pixel, deduplication may be failing.

## EMQ Optimization Checklist

Event Match Quality (EMQ) measures how well Meta can match your sent events to Meta user profiles. Higher EMQ = better attribution = better ad delivery.

**Targets:**
- 6.0+ = Good (minimum acceptable)
- 8.0+ = Excellent (target this)
- Below 6.0 = Degraded performance — fix immediately

**Matching keys to send (priority order):**

| Key | Parameter | Impact | Notes |
|-----|-----------|--------|-------|
| Email (hashed) | `em` | Highest | SHA-256 hash, lowercase, trimmed |
| Phone (hashed) | `ph` | High | SHA-256 hash, include country code, digits only |
| fbc (click ID) | `fbc` | High | Captured from `fbclid` URL parameter — critical for offline conversions |
| fbp (browser ID) | `fbp` | Medium | Read from `_fbp` first-party cookie |
| IP address | `client_ip_address` | Medium | User's IP, not server IP |
| User agent | `client_user_agent` | Medium | Browser user agent string |
| First name (hashed) | `fn` | Lower | SHA-256 hash, lowercase |
| Last name (hashed) | `ln` | Lower | SHA-256 hash, lowercase |
| City (hashed) | `ct` | Lower | SHA-256 hash, lowercase |
| State (hashed) | `st` | Lower | SHA-256 hash, lowercase, 2-char code |
| Zip code (hashed) | `zp` | Lower | SHA-256 hash |
| Country (hashed) | `country` | Lower | SHA-256 hash, 2-char ISO code |
| Date of birth (hashed) | `db` | Lower | SHA-256 hash, YYYYMMDD format |
| Gender (hashed) | `ge` | Lower | SHA-256 hash, 'm' or 'f' |
| External ID (hashed) | `external_id` | Lower | Your system's user ID, hashed |

**Rules:**
- ALL customer data must be SHA-256 hashed before leaving your server — Meta never receives raw PII
- Send as many keys as you have — more keys = higher match rate = higher EMQ
- Email alone typically gets EMQ to ~5-6. Email + phone + fbc gets to 7-8+
- Read `references/capi-event-parameters.md` for full parameter specifications and hashing requirements

## fbclid Capture & Storage Workflow

For CRM and offline events sent hours/days/weeks after the ad click, the `fbc` value is the critical link connecting the downstream conversion to the original ad.

**Step-by-step:**
1. User clicks ad → lands on your site with `?fbclid=xyz` in URL
2. Your landing page JavaScript captures `fbclid` from the URL
3. Store `fbclid` alongside the lead record in your CRM/database
4. Also read and store the `_fbp` cookie value
5. Construct the `fbc` parameter: `fb.1.{timestamp}.{fbclid_value}`

From narayan-metaflow/metaflow-marketing-skills, MIT.

More from narayan-metaflow/metaflow-marketing-skills