Lesson 7.3 · 60 minMeta Conversions API

What you will have

When a lead is saved, the server sends a Lead event to Meta with hashed contact data and the same event ID as the browser event, only for visitors who consented. Meta shows the lead received from both sources and counted once.

Video

The video for this lesson is not recorded yet.

Prompts used in this lesson

Part 6 — Demonstration: the server call

Purpose: send each new lead to Meta from the server through the Conversions API, so
leads are counted even when the visitor's browser blocks the Meta Pixel, without
counting any lead twice.

Context: brightside-site at lesson-7.2. The form already sends event_id to
/api/leads and the browser pixel sends a Lead event with the same eventID. Before
writing code, read Meta's current Conversions API documentation: "Using the API",
"Server Event Parameters", "Customer Information Parameters", "fbp and fbc
Parameters" and "Deduplicate Pixel and Server Events". Follow the documentation, not
memory, for the endpoint, the API version and the hashing rules.

Do this:
1. Add a migration: a boolean column ad_consent on leads, default false.
2. The form sends ad_consent = true only if the visitor has granted both ad_storage
   and ad_user_data in the consent banner. The endpoint validates and stores it.
3. Create one server-only module for Meta events. After a lead is saved, and only if
   ad_consent is true, it sends one Lead event with: event_name, event_time,
   event_id (from the form), action_source "website", event_source_url, and
   user_data containing hashed em and ph (normalised as documented), hashed fn and
   ln if the name splits cleanly, client_ip_address and client_user_agent from the
   request, fbp and fbc from the request cookies, and fbc built from the stored
   fbclid when the cookie is absent. If the phone cannot be normalised with a
   country code, leave it out.
4. Read META_PIXEL_ID and META_CAPI_ACCESS_TOKEN from the environment. If
   META_TEST_EVENT_CODE is set, add it to the request as test_event_code.
5. Show ad consent (yes/no) on the lead card in the CRM.

Constraints: the Meta call must never delay or break lead capture - if it fails or
times out, the lead is still saved and notifications still go out; log the failure
without logging the token or any unhashed contact data. Never send unhashed email,
phone or name. Never expose the token to the browser. I have put the values in
.env.local myself; do not ask me to paste them and do not print them.

Done when: the build passes; a unit test proves the email hash by reproducing the
example in Meta's documentation (the page gives an input email and its expected
SHA-256 output); a test lead with consent returns a success response from Meta; a
test lead without consent makes no call to Meta. Report the evidence for each.

Do along

Pause the video where told and do each step on your own project.

1. After Part 5, pause: from lesson-7.2, generate the access token and put the variables in .env.local and in Vercel yourself.
2. After Part 6, pause: run the prompt from Part 6. Review the checks named in that part. Apply the migration and deploy.
3. Ask Claude to propose one or two sentences for /privacy describing hashed data sharing with ad platforms; edit them to fit your business.
4. After Part 7, pause: set the test event code, run the three tests (normal, ad blocker, consent rejected), then remove the test code everywhere.
5. Record the results in docs/tracking-qa.md under "Meta Conversions API".
6. Commit and tag.

Check your work

1. Normal test lead: Test events shows Lead from browser and from server, with one marked deduplicated. Expected: counted once.
2. Ad-blocker lead: one server event only.
3. Consent-rejected lead: no event; lead card shows ad consent "no"; the lead is still saved and notified.
4. Search the repository for the token's first characters: no matches. git status does not list .env.local.
5. META_TEST_EVENT_CODE is absent from Vercel's production variables after testing.
6. A day later, the dataset's overview shows Lead events with both browser and server as sources.

Common problems

• Server event missing in Test events → the test code is not set where the code runs, or it has changed; the tool can issue a new one. Copy it again and restart or redeploy.
• Both events shown, neither deduplicated → the IDs or names differ. Compare the browser's eventID with the server's event_id; check both names are exactly Lead.
• Meta answers with an error about the access token → the token was pasted with a space or belongs to another dataset. Generate a new one and replace it in both places.
• Error mentioning a missing required field → for website events event_source_url and client_user_agent are required. Give Claude the full error text.
• Lead saving became slow or fails when Meta is down → the call is blocking the response. Tell Claude: "The Meta call must not block or fail the lead response; show me the test that proves it."

Homework

About 30 minutes, on your own; the first task waits until the next day. No later lesson depends on it.

1. Day-after check. Tomorrow, open the dataset in Events Manager and look at the Lead event. Deliverable: a dated line in docs/tracking-qa.md saying whether browser and server are both shown as sources. Done when: the line states what you saw and, if one source is missing, which entry in Common problems you will follow.
2. Phone format audit. The server leaves out a phone number it cannot normalise with a country code. Look at the phone numbers on your last ten leads, or on ten customer contacts you already hold, and count how many include a country code. Deliverable: the count and one decision in docs/tracking-qa.md: leave it, or add a hint to the form later. Do not change the form now. Done when: both are written.
3. Failure drill. On your computer only, add one character to the end of META_CAPI_ACCESS_TOKEN in .env.local, restart the local site and submit a consented test lead. Then remove the character and restart. Deliverable: one line in docs/tracking-qa.md. Done when: the lead was saved and you were notified although the Meta call failed, the lead is marked as a test, and the token line is back as it was.

If a task changed files in the project, commit and push without a tag: git add -A, git commit -m "Homework 7.3", git push.

Save your work

git add -A
git commit -m "Lesson 7.3: Meta Conversions API with consent and deduplication"
git tag lesson-7.3
git push
git push --tags