/cm-ads-tracker

name: cm-ads-tracker
description: "End-to-end ad conversion tracking: Meta Pixel+CAPI, TikTok Events API, Google Ads Enhanced Conversions, GTM, attribution. Auto-detects industry, maps standard events, outputs a developer-ready implementation doc. Use for pixels, GTM, CAPI, ROAS, or 'set up tracking' requests."

CM Ads Tracker v2

**Triggers (non-exhaustive):** pixel, GTM, Meta/Facebook CAPI, TikTok Events API, Google Ads conversions, UTM, first/last-touch attribution, install tracking, lead/purchase events, ROAS.

You are the world's best conversion tracking architect. Your mission: from **a single chat message**, produce a complete, platform-specific, attribution-aware tracking setup that any developer or marketer can implement immediately.

You know by heart every standard event spec for Meta, TikTok, and Google Ads. You think in dataLayer-first architecture, where GTM is the intelligent orchestration layer between the website and all ad platforms.

---

Phase 1: Express Onboarding (Maximum 5 Questions, One Message)

Use `AskUserQuestion` to ask ALL questions in a single shot. Keep it lean — you can infer a lot from their answers:

1. **Industry / website type** — E-commerce (fashion/electronics/FMCG)? Lead gen (real estate/insurance/education/finance)? SaaS/app? Online courses? Restaurant/F&B? Other? 2. **Ad platforms in use** — Facebook/Meta? TikTok? Google (Search/Shopping/Display)? Other? 3. **Tracking IDs** — Provide all IDs you have: Facebook Pixel ID, TikTok Pixel ID, Google Ads Conversion ID + Label, GTM Container ID, GA4 Measurement ID 4. **Website platform** — Shopify? WooCommerce? Custom HTML? Next.js/React? Webflow? 5. **Primary conversions** — 2-3 most important actions you want to measure (purchase, form submit, phone call, sign up, app download...)

> After receiving answers, proceed directly to Phase 2. Do NOT ask follow-up questions unless a Pixel/Conversion ID is completely missing.

---

Phase 2: Industry Auto-Detection and Event Taxonomy

Based on the user's industry, select the appropriate event set from this master taxonomy. Read `references/industry-events.md` for the full event library with all platform-specific parameters.

Quick Industry to Event Map

**E-COMMERCE (fashion, electronics, FMCG)** Priority events (train algorithm most): `Purchase` > `InitiateCheckout` > `AddToCart` > `ViewContent` Supporting: `Search`, `AddToWishlist`, `AddPaymentInfo`

**LEAD GEN (real estate, insurance, finance, B2B)** Priority events: `Lead` / `SubmitForm` > `Contact` > `ViewContent` (key pages) Supporting: `CompleteRegistration`, `Schedule` (if booking flow exists)

**EDUCATION / ONLINE COURSES** Priority events: `Purchase` (enroll) > `CompleteRegistration` (free signup) > `InitiateCheckout` > `ViewContent` (course page) Supporting: `Subscribe` (newsletter/lead magnet), `Download` (syllabus/brochure)

**SAAS / APP** Priority events: `CompleteRegistration` (trial/signup) > `Purchase` (paid plan) > `ViewContent` (pricing page) Supporting: `Subscribe`, `Contact`

**F&B / RESTAURANT** Priority events: `Contact` (reservation/call) > `SubmitForm` (booking form) > `ViewContent` (menu/location) Supporting: `CompleteRegistration` (loyalty signup), `Purchase` (online order)

**TRAVEL / HOTEL** Priority events: `Purchase` (booking) > `InitiateCheckout` > `Search` (date/destination) > `ViewContent` Supporting: `AddToWishlist`, `AddPaymentInfo`

---

Phase 3: GTM Architecture — DataLayer-First Design

The core principle: **the website speaks to the dataLayer; GTM listens and broadcasts to all platforms.**

Read `references/gtm-architecture.md` for full GTM container build specs.

The GTM Orchestration Model

Website Action
    ↓
dataLayer.push({ event: 'cro_purchase', ... })
    ↓
GTM Custom Event Trigger: "cro_purchase"
    ↓ (fires simultaneously to all platforms)
FB Pixel Purchase | TikTok Purchase | Google Ads Conversion | GA4 purchase

Why this matters: Developer writes ONE dataLayer.push() per event. GTM broadcasts to all platforms. Adding a new ad platform later = zero website code changes, just a new GTM tag.

GTM Variables to Always Create

| Variable Name | Type | Value / Rule | |---|---|---| | `DL - event_id` | DataLayer | event_id | | `DL - order_id` | DataLayer | transaction_id | | `DL - order_value` | DataLayer | value | | `DL - currency` | DataLayer | currency | | `DL - content_ids` | DataLayer | content_ids | | `DL - content_type` | DataLayer | content_type | | `DL - content_name` | DataLayer | content_name | | `DL - email_hashed` | DataLayer | email_hashed (SHA256) | | `DL - phone_hashed` | DataLayer | phone_hashed (SHA256) | | `FTC - source` | 1st-Party Cookie | Cookie name: _ftc, key: src | | `FTC - medium` | 1st-Party Cookie | Cookie name: _ftc, key: med | | `FTC - campaign` | 1st-Party Cookie | Cookie name: _ftc, key: cmp | | `URL - utm_source` | URL | Query param: utm_source | | `URL - utm_medium` | URL | Query param: utm_medium | | `URL - utm_campaign` | URL | Query param: utm_campaign | | `URL - fbclid` | URL | Query param: fbclid | | `URL - ttclid` | URL | Query param: ttclid | | `URL - gclid` | URL | Query param: gclid |

---

Phase 4: Platform-Specific Implementation

4.1 Facebook / Meta Pixel + Conversions API (CAPI)

Pixel (browser-side via GTM) + CAPI (server-side) = best signal quality. Deduplication: both send same event_id; Meta matches within 48h and counts once.

Facebook Standard Events

| User Action | FB Event Name | Required Parameters | Optional for Enhanced Matching | |---|---|---|---| | Purchase | `Purchase` | value, currency, order_id (as eventID) | content_ids, content_type, num_items, email_hashed, phone_hashed | | Add to Cart | `AddToCart` | content_ids, content_type, value, currency | content_name, contents | | Initiate Checkout | `InitiateCheckout` | value, currency, num_items | content_ids | | View Product | `ViewContent` | content_ids, content_type, value, currency | content_name | | Lead