ad_conversion_tracking v1.0.0

name: "ad_conversion_tracking" description: "Verify paid campaign conversion tracking before launch: prove each event fires once, check browser and server deduplication on Meta, TikTok, and Google, test consent denied and granted paths, run test purchases per channel, and sign a go or no go record with evidence per event. Use before launching or scaling a paid campaign, after any tag, pixel, server event, checkout, or consent change, or when reported conversions do not match orders or leads in the source system."

Ad Conversion Tracking

Purpose

Prove, with evidence, that a paid campaign will count each real conversion once, with the right value, in the platform that will optimize against it, before money is spent. The output is a filled event test sheet and a signed launch gate, not an opinion that tracking looks fine.

Workflow

1. Freeze the event plan before testing. List every event the campaign will optimize on or report, one row per event per platform, in assets/event-test-sheet.csv. For each: the exact standard event name, the business action that creates it (order paid, lead accepted, booking confirmed), the value rule, the currency rule, and the stable business ID behind it (order ID, lead ID). If two names describe the same action on one platform, that is a defect to fix before testing, not a row to keep.

1. Test in the platform test tools, never on live reports alone. Meta: Events Manager, open the dataset, use Test events, and send server events with the test event code or they will not appear there. TikTok: Events Manager Test Events with its test code. Google: Tag Manager Preview connected to Tag Assistant to see which tags fired and in which order, plus GA4 DebugView for the analytics copy. Live reports lag and mix in real traffic, so a clean live number is not evidence.

1. Run one clean test action per event and count fires. Use a fresh browser profile with ad blockers off. Do the exact action once: one test purchase, one lead submit, one booking. Record in the sheet how many times each platform received the event. Expected is exactly one deduplicated conversion per platform. Two browser fires for one action means a duplicate trigger, a page reload firing again, or two tools (for example a platform app plus a tag manager tag) both sending it, and deduplication between browser and server copies does not rescue two copies from the same source.

1. Run the deduplication check for every event sent both ways. Follow references/deduplication-checks.md. The rule on Meta and TikTok is the same in shape: the browser copy and the server copy must carry the identical event name and the identical event ID, and on TikTok the pixel ID must match too. Confirm in the test tool that the pair shows as deduplicated, not as two received events. A server response code of 200 proves delivery only. It proves nothing about deduplication.

1. Check parameter quality on the surviving event. Value matches the test order total under the stated value rule (gross or net of tax and shipping, pick one and write it down). Currency is present and correct. Content or product IDs match the catalog IDs the ads use. The order or lead ID is present where the platform accepts it. For Google enhanced conversions, check in Chrome DevTools Network on the conversion request to googleadservices.com/pagead/conversion/ that the payload carries the hashed user data parameter with a long hash after its prefix; the prefix alone with no hash means the tag sent empty user data.

1. Test the consent paths separately and record both. Run the same action once with consent denied at the banner and once with consent granted. Granted: the full event should arrive with its identifiers. Denied: state what actually happened per platform in the sheet, either no event, a restricted or cookieless ping on Google under Advanced consent mode, or a server event sent under the consent basis the business relies on. What matters for the gate is that denied behaviour matches the written consent design, and that no platform receives full identifiers from a user who denied. Check Google consent state in Tag Assistant: the four signals ad_storage, analytics_storage, ad_user_data, and ad_personalization should read denied before a choice and granted after acceptance where the design grants them.

1. Test every channel and entry point that can convert. Repeat the core event test for each real path: desktop web, mobile web, in-app browser if ads open there, and each checkout or form variant. A thank-you page event that fires on web checkout but not on the one-page checkout is a launch blocker for any campaign sending traffic to the broken path.

1. Reconcile against the source of truth. Match the test IDs in the sheet to records in the store, CRM, or booking system. One order in the source, one conversion per platform, same value. Then check the last full day of real data where it exists: platform purchase count against order count. A platform count persistently above the source count points at duplicates. A count far below points at lost browser events, wrong dataset or account, or consent loss the design did not expect.

1. Score the sheet and sign the gate. Run bin/check_test_sheet.py <filled-sheet.csv>. It flags count mismatches, browser and server event ID mismatches, and missing evidence fields, and prints GO or NO GO under the rule in assets/launch-gate-template.md: any failed critical event is NO GO. Attach the test tool screenshots or exports, the tester name, the date, and the environment (staging or production, tag container version) to the gate record.

1. Retest after any change that can touch firing. Tag container publish, checkout deploy, consent banner change, ecommerce platform app update, or server event release. A gate signed before the change does not cover the change. Note that some platform diagnostics are slow: Google enhanced conversions diagnostics can take about 48 to 72 hours to populate after implementation, so schedule that check as a dated follow-up on the gate instead of blocking launch on a report that cannot exist yet, provided the live DevTools check in step 5 passed.

Output Contract

A filled event test sheet (CSV, from assets/event-test-sheet.csv) with one row per event per platform per channel, observed counts, browser and server event IDs, value and currency seen, consent behaviour for denied and granted runs, and an evidence pointer per row. Plus a launch gate record from assets/launch-gate-template.md stating GO or NO GO, the failed rows if any, the tester, the date, the environment and container version, and any dated follow-up checks. NO GO is a valid, complete output.

Operating Rules

1. One action, one count. Any event that fires twice for one real action fails, whatever the platform total looks like after attribution.
2. Same name, same ID, or it is two events. Browser and server copies with different event names or different event IDs will count as two conversions on Meta and TikTok. Generate the ID once, at the business action, and pass the same value both ways.
3. Know the deduplication windows. Meta deduplicates matching browser and server events within 48 hours and generally keeps the first event received. TikTok merges duplicates arriving within 5 minutes and removes duplicates within 48 hours. A server copy sent later than the window, for example a batch CRM upload two days after the browser event, needs its own plan and does not get assumed deduplicated.
4. The fallback is weaker than the ID. Meta can fall back to browser parameters such as fbp or external_id when no event ID is sent, but that path only works when the browser event arrives first and does not deduplicate two browser events or two server events. Treat fallback deduplication as a fail on the gate for any event the campaign optimizes on.
5. HTTP success is not tracking success. A 200 from a server events endpoint, a tag firing in Preview, or a pixel helper turning green each prove one hop. The gate needs the platform test tool showing the received, deduplicated event with correct parameters.
6. Test purchases must be real end to end and clearly marked. Use the smallest real product or a test mode the payment provider supports, use a test identifier in name or email where the form allows it, and refund or cancel after. Record the order ID so finance and fulfillment can exclude it. Never let a test order ship or a test lead reach sales unmarked.
7. Value rules are part of tracking. Two platforms reporting different values for the same order will optimize differently and confuse every later readout. One written value rule, applied everywhere, checked on the test order.
8. Consent denied is a test case, not an afterthought. If the denied path was never run, the gate is incomplete. Campaigns aimed at regions with consent banners lose or misreport conversions exactly there.
9. Wrong destination is a common silent failure. Confirm the pixel or dataset ID, the Google tag destination, and the ad account match the account the campaign will run in. Events landing in a test dataset or an old account look like zero conversions in the place that matters.
10. Do not launch on a partial funnel. Upper funnel events firing cleanly do not compensate for a broken purchase or lead event. The gate is per event, and the optimization event decides.
11. Keep the evidence with the gate. Test tool screenshots or exports, the filled sheet, and the container version, stored together. Memory of a test is not evidence when a dispute starts two weeks into spend.
12. Report mismatches in counts, not adjectives. Write platform count, source count, and the difference for the test actions and for the last full day checked. A reader should be able to redo the arithmetic from the sheet alone.