Lesson 7.8 · 60 minClosing the loop: CRM results back to the ad platforms

Purpose: when a lead reaches the qualified or won stage in the CRM, report that
result to Meta and to Google Ads, so both platforms can count and learn from good
leads instead of all form submissions.

Context: brightside-site at lesson-7.7. Status changes go through one server path
and are recorded in lead_status_history. Leads store email, phone, gclid, fbclid,
created_at and ad_consent. The Meta Conversions API module from lesson 7.3 exists.
Before coding, read the current official documentation and follow it, not memory:
Meta "Server Event Parameters" and "fbp and fbc Parameters"; Google Data Manager API
"Send events" for Google Ads offline conversions, and its events.ingest reference.

Do this:
1. Add a migration for a table ad_conversion_log: lead id, platform, stage, sent_at,
   outcome (sent, skipped, failed), reason, platform request id. No personal data.
2. On a status change to qualified or won, after the change is saved:
   - Meta: send a custom event (QualifiedLead or CustomerWon) through the existing
     module with action_source "system_generated", event_time now, event_id
     "<stage>-<lead id>", user_data with hashed em and ph and fbc built from fbclid
     and the lead's created_at.
   - Google: send one event to the Data Manager API ingest endpoint for the matching
     conversion action, with the gclid when present, the SHA-256 hashed normalised
     email, the event timestamp, a transactionId "<stage>-<lead id>", and the
     consent fields.
3. Rules: send nothing for a lead whose ad_consent is false - log "skipped: no
   consent". Send to Google only if the lead has a gclid or an email; to Meta only
   if it has an fbclid, email or phone. Send each stage at most once per lead per
   platform, even if the status is moved back and forth - check the log first.
4. Environment: META_* as before; GOOGLE_ADS_CUSTOMER_ID,
   GOOGLE_ADS_QUALIFIED_ACTION_ID, GOOGLE_ADS_WON_ACTION_ID,
   GOOGLE_SERVICE_ACCOUNT_KEY. A variable AD_CONVERSIONS_DRY_RUN=true makes the
   Google call use validateOnly and adds META_TEST_EVENT_CODE to the Meta call.
5. Show the log entries for a lead on its lead card ("Reported to ad platforms").

Constraints: a failed or slow platform call must never block or undo the status
change; log it as failed with the platform's error message, without secrets or
contact data. Secrets come only from the environment; do not print them. Never send
unhashed contact data.

Done when: the build and tests pass; with dry run on, moving a consented test lead
to qualified logs "sent" for both platforms with a success response from each;
moving a non-consented lead logs "skipped" twice and makes no network call; moving
the first lead back and to qualified again sends nothing new. Report the evidence.

Purpose: show cost per lead and cost per qualified lead for each campaign on the
admin dashboard, using ad spend I enter by hand.

Context: leads carry utm_source and utm_campaign; qualified means the lead reached
qualified or won at any time (see lead_status_history).

Do this: add a table ad_spend (period start, period end, utm_source, utm_campaign,
amount) with a small form on the dashboard to add, edit and delete entries. Add a
dashboard table per campaign for a chosen date range: spend, leads, cost per lead,
qualified leads, cost per qualified lead, won, cost per customer. Show the target
cost per lead from docs/ads-plan.md as a note above it.

Constraints: campaign names must match utm_campaign exactly - offer the existing
values in a dropdown. Show a dash, not zero or an error, when there are no leads.
Exclude leads marked as test. Admin only.

Done when: the build passes, and with sample spend entered for two campaigns you
have verified each figure in the table by hand calculation. Report the working.