--- name: improve-event-match-quality description: >- Raises the 0-10 Event Match Quality score Events Manager assigns per event, how confidently Meta ties a pixel or CAPI event to a real person, because a higher score directly improves both auction optimization and attribution credit. Covers auditing current EMQ per event, then adding match keys from BOTH the browser pixel and the server CAPI call: hashed em, ph, fn, ln, ct, st, zp, country, external_id, plus unhashed fbp, fbc, client_ip_address, and client_user_agent. Every PII field is normalized first, lowercase/trim, phone to E.164, then SHA-256 hashed before it ever leaves the client or server; raw PII is never transmitted. Reach for it once CAPI is live and deduplicating but the score still sits low, or when delivery/cost looks worse than volume alone explains. It ends at a measured EMQ improvement, the CAPI plumbing is implement-conversions-api and the pixel plumbing is set-up-pixel-and-standard-events. --- # Improve Event Match Quality (EMQ) ## Purpose EMQ is Events Manager's 0-10 confidence score for how well an event's data ties to a real Meta user. Higher EMQ means the auction can find that exact person to optimize toward, and reported conversions get credited more accurately. It's raised by sending more of the right match keys from BOTH the pixel and CAPI, they see different data (browser has `fbp`/`fbc`/client hints, checkout often has verified email/phone/address) so the highest score comes from combining them, not from maxing out either channel alone. ## When to run - CAPI is live and deduplicating (`implement-conversions-api` done) but EMQ per event is still low relative to the account's best-performing event. - A cost or delivery regression coincides with no obvious targeting or budget change, thin match data is a common quiet cause. - Checkout or lead-form data includes fields (phone, address, name) not yet passed as hashed match keys. - Before scaling spend on a campaign, a better-matched event compounds, so it's cheaper to fix before scale than after. ## When NOT to run - No CAPI yet → `implement-conversions-api` first; this skill assumes both channels exist to enrich. - No pixel or standard events yet → `set-up-pixel-and-standard-events` first. - The real problem is event volume, not match quality (under the ~50/week learning threshold) → that's an objective/optimization-event problem, see `select-campaign-objective`. ## Prerequisites - A live pixel (`set-up-pixel-and-standard-events`) and live, deduplicating CAPI (`implement-conversions-api`). - Access to Events Manager's per-event EMQ breakdown (which keys are present vs missing, and each one's contribution). - A source for each additional match key: checkout/form data for em/ph/fn/ln/address, session data for fbp/fbc/client_ip_address/client_user_agent, a stable internal id for external_id. - Server-side (or build-time) SHA-256 hashing, plus a normalization step ahead of it. ## Procedure 1. **Read current EMQ per event.** HUMAN STEP: in Events Manager, open the event detail view for Purchase/Lead (or whichever event optimization depends on) and note the score plus which match keys are present vs missing. 2. **Inventory available-but-unused data.** Check checkout/form/session data for fields not yet mapped: email, phone, first/last name, city/state/zip/country, a stable customer/user id (`external_id`), and the browser-only `fbp`/`fbc` cookies plus `client_ip_address`/ `client_user_agent`. 3. **Normalize before hashing.** Lowercase and trim email and name; convert phone to E.164 (digits only, with country code); strip inconsistent casing/whitespace from city/state, Meta matches the normalized string exactly, so inconsistent normalization silently fails to match even with a technically-correct hash. 4. **Hash before transmission, every time.** SHA-256 each of em, ph, fn, ln, ct, st, zp, country, external_id. Never send a raw value "just this once" for debugging, treat that as a compliance violation, not a shortcut. 5. **Add the keys to both channels, not just one.** Pixel gets what the browser already has (`fbp`/`fbc` are automatic; add hashed em/ph via advanced matching). CAPI gets the same hashed keys plus `client_ip_address`/`client_user_agent` from the server request and, when available, richer checkout data the browser event never saw. 6. **Add `external_id` where a stable identifier exists.** A logged-in user id or persistent customer id, hashed, gives Meta a consistent cross-session match key independent of cookies, send it identically from both pixel and CAPI when the user is known on both. 7. **Re-check EMQ after a data cycle.** HUMAN STEP: after a few days of volume, reopen the event detail view and compare the score and per-key contribution against the step-1 baseline. 8. **Iterate on the highest-value gap.** Prioritize whichever the Events Manager breakdown flags as the biggest available gain, not an arbitrary key. ## Decision rules - IF a match key is available in checkout/form data but absent from either pixel or CAPI THEN add it, free EMQ, no new data collection needed. - IF normalization differs between pixel and CAPI (e.g., phone with country code on one side, without on the other) THEN fix normalization before adding more keys, mismatched formatting silently caps the match rate. - IF a field is sensitive or prohibited (health, financial account numbers, government id) or the person is under 13 THEN exclude it, never hash and send a prohibited category to raise a score. - IF EMQ is high on one channel and low on the other for the same event THEN the weaker channel is missing keys the stronger one already proves are available, copy the key set across. - IF `external_id` is available for logged-in users THEN send it identically from both channels, the most durable match key across cookie churn and ITP. - **Done means:** a re-measured EMQ score, higher than the step-1 baseline, on both the pixel and CAPI sides of the account's primary optimization event. ## Common failure modes - Hashing an un-normalized value (mixed-case email, phone with symbols), produces a technically-valid hash that never matches. - Adding match keys to CAPI only and forgetting the pixel side (advanced matching) still has room to improve. - Sending a raw, unhashed field "temporarily" for debugging in a shared or logged environment. - Treating `external_id` as optional when a stable logged-in id already exists in the account's data. - Chasing EMQ on a low-volume event where the real constraint is the ~50/week signal floor, not match quality. - Declaring victory at "CAPI is live" without ever opening the EMQ breakdown to check whether it actually improved. ## Related skills - Prerequisite: `set-up-pixel-and-standard-events`, `implement-conversions-api` (both channels must exist before enriching them). - Related: `configure-attribution-settings` (better-matched events make attributed credit more trustworthy, though not more incremental, see `run-incrementality-and-lift-tests`). - Feeds: `select-campaign-objective` (delivery quality for OFFSITE_CONVERSIONS optimization depends on match quality).