# blueprint-toolkit.com – Tracking implementation brief

**Purpose:** Brief for GA4/GTM tracking on the Blueprint product site. Use for scoping, implementation, and handoff.

---

## Project

- **Name / client:** Blueprint (blueprint-toolkit.com)
- **Site / product:** Blueprint – implementation toolkit for consultants and teams (cross-domain GA4, measurement frameworks, guides, GTM integration, checklists, stakeholder interviews, snippet library, deliverable export).
- **Environment:** Production (Vercel). Single-page app; no cross-domain to other properties.

---

## Domains & scope

- **Primary domain:** `blueprint-toolkit.com` (and `www` if used; list both if both serve traffic).
- **External / cross-domain:** Stripe (checkout), Supabase (auth/API), Brevo (email) – outbound only; no linker needed for same-session attribution to these.
- **Notes:** App is client-side SPA; section changes are in-app navigation (tracked as events, not page_view URLs). No subdomain rollout; single origin.

---

## GA4 / GTM

- **GA4 Measurement ID:** G-XXXXXXXXXX *(set in Admin → Tracking when using client/server delivery)*
- **GTM Container ID:** Optional. Events push to `window.dataLayer`; GTM or gtag can consume.
- **Server-side:** Optional. `ga4-measurement` Edge Function (Supabase) can forward to Measurement Protocol; API secret in Supabase secrets.
- **Delivery options (Admin → Tracking):** dataLayer only | Client-side (gtag) | Server-side (Measurement Protocol) | Both.

---

## Events (catalog summary)

**Full reference:** [docs/TRACKING.md](TRACKING.md) – event names, parameters, and GTM implementation.

**Event name prefix:** Configurable (default `blueprint_`), e.g. `blueprint_section_view`, `blueprint_code_copy`.

### Navigation & engagement
| Event | When | Typical use |
|-------|------|-------------|
| `section_view` | User opens a section (sidebar or overview card) | Engagement depth, content consumption |
| `tab_switch` | User switches tabs (e.g. Cross Domain → Configurations) | In-section engagement |
| `overview_card_click` | User clicks a card on Blueprint Overview | Entry points to sections |
| `traffic_source` | Session start with UTM params (once per session) | Campaign/source attribution |
| `code_copy` | User copies a snippet, guide step, or code block | Value delivery, copy_type (snippet, guide_step_code, code_block, etc.) |
| `button_click` | Button/link-like click (when track_buttons on) | General engagement |
| `outbound_click` | Click to external domain (when track_links on) | Outbound to Stripe, docs, etc. |
| `form_submit` | Form submit (when track_forms on) | Sign-in, contact, admin forms |

### Promo & conversion
| Event | When | Typical use |
|-------|------|-------------|
| `promo_cta_click` | Sidebar promo CTA (e.g. “View plans”) | Upgrade intent |
| `pricing_cta_click` | Pricing card CTA (Get started / Subscribe) | Plan interest; use `plan_slug`, `pricing_cta_type` |
| `contact_click` | Nav or footer Contact | Support intent |
| `welcome_banner_view` / `welcome_banner_dismiss` | URL-triggered welcome banner show/close | Campaign-triggered UX |

### Product & power use
| Event | When | Typical use |
|-------|------|-------------|
| `project_create` | New project created (e.g. from New button) | Project creation (non–quick-start path) |
| `project_quick_start_create` | Project created from overview quick-start | Onboarding funnel |
| `project_quick_start_select` | Existing project selected from overview dropdown | Return usage |
| `gtm_import` | GTM container JSON imported | GTM integration adoption |
| `gtm_export` | GTM export from project | GTM workflow |
| `gtm_clear` | GTM import cleared | Workflow cleanup |
| `ai_extract` | AI requirements extraction run successfully | AI feature use |
| `ai_extract_apply` | Extract results applied (merge/replace) | AI → project workflow |
| `ai_generate_guide` | Guide generated from framework gaps | AI guide adoption |
| `ai_import_url` | Doc imported from URL for extraction | AI import use |
| `file_download` | Export deliverable, scripts, checklist, framework CSV, guide, backup, etc. | Value delivery; use `download_type`, `file_name` |
| `ga_audit_run` | GA4 Configuration Audit run | GA Audit feature use |
| `ga4_audit_history_view` / `ga4_audit_history_delete` / `ga4_audit_export` | Audit history view/delete/export | Audit workflow |

### Mobile (if used)
| Event | When |
|-------|------|
| `project_type_change` | Project type set to web / mobile / both |
| `mobile_field_update` | Firebase/iOS/Android/GTM mobile fields updated |
| `mobile_config_upload` / `mobile_config_parsed` / `mobile_config_parse_error` | Mobile config file upload and parse result |
| `mobile_firebase_code_generated` / `mobile_gtm_code_generated` / `mobile_cross_platform_code_generated` | Mobile code generation used |

### Admin (excluded from analytics)
Admin section and admin-targeting actions do not push events (e.g. Admin overview card, plan edit). Keeps admin behavior out of product analytics.

---

## Measurement framework (seed)

**Use:** Import this brief (paste or URL) in the Framework section → Extract. The app will parse the table below and create one framework row per line so the full event set is available for planning and testing. Single source of truth: this doc.

| Objective | Key metric | Events | Params | Priority |
|-----------|------------|--------|--------|----------|
| Navigation & engagement | Section and tab usage | section_view, tab_switch, overview_card_click | event_category, event_label, section, tab | P0 |
| Attribution | Campaign/source capture | traffic_source | utm_* params once per session | P0 |
| Value delivery (copy) | Code and snippet copies | code_copy | copy_type (snippet, guide_step_code, code_block), file_name | P0 |
| General engagement | Button and link interactions | button_click, outbound_click, form_submit | track_buttons, track_links, track_forms | P1 |
| Promo & conversion | Upgrade and support intent | promo_cta_click, pricing_cta_click, contact_click | plan_slug, pricing_cta_type | P0 |
| Welcome / campaign UX | Banner visibility and dismiss | welcome_banner_view, welcome_banner_dismiss | URL-triggered | P2 |
| Project creation | New and quick-start projects | project_create, project_quick_start_create, project_quick_start_select | onboarding funnel | P0 |
| GTM integration | GTM workflow adoption | gtm_import, gtm_export, gtm_clear | GTM container | P0 |
| AI feature use | Extract and apply workflow | ai_extract, ai_extract_apply, ai_import_url | section, ai_action | P0 |
| AI guide adoption | Guide from framework gaps | ai_generate_guide | section | P1 |
| File delivery | Exports and downloads | file_download | download_type, file_name | P0 |
| GA Audit use | Audit run and history | ga_audit_run, ga4_audit_history_view, ga4_audit_history_delete, ga4_audit_export | section | P0 |
| Mobile (optional) | Project type and config | project_type_change, mobile_field_update, mobile_config_upload, mobile_config_parsed, mobile_config_parse_error, mobile_firebase_code_generated, mobile_gtm_code_generated, mobile_cross_platform_code_generated | web/mobile/both | P2 |

---

## Implementation status

- **DataLayer:** App pushes to `window.dataLayer` when tracking enabled (Admin → Tracking). No cross-domain linker on blueprint-toolkit.com.
- **Key events:** As above; full list and parameters in [TRACKING.md](TRACKING.md).
- **Config toggles (Admin → Tracking):** Enable tracking, event prefix, track_buttons, track_forms, track_links, track_sections, track_downloads.
- **Conversions (suggested):** `promo_cta_click`, `pricing_cta_click`, `contact_click`, `form_submit` (filter by form for sign-up/contact).

---

## Handoff & context

- **Stakeholder / dev contact:** *(fill as needed)*
- **Go-live or key dates:** *(fill as needed)*
- **Decisions:** dataLayer-only vs client/server GA4 delivery; event prefix; which events to mark as conversions in GA4.
- **Links:** [TRACKING.md](TRACKING.md) (event catalog, schema, GTM triggers, GA4 tags), [TRACKING_SETUP_NOTES.md](TRACKING_SETUP_NOTES.md) (template for per-project notes).

---

## Changelog (optional)

- YYYY-MM-DD: Brief created; events aligned with docs/TRACKING.md and app pushToDataLayer usage.