alirezarezvani/claude-skills / marketing-skill/skills/analytics-tracking
analytics-tracking
VerifiedUse for any GA4, Google Tag Manager, event-tracking or conversion-tracking setup, audit or broken-event debug, before touching tags. Generates the event taxonomy and tracking plan with tracking_plan_generator.py. Campaign performance analysis: campaign-analytics.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 14.7 KB |
| references/debugging-playbook.md | markdown | 7.9 KB |
| references/event-taxonomy-guide.md | markdown | 7.7 KB |
| references/gtm-patterns.md | markdown | 8.2 KB |
| scripts/tracking_plan_generator.py | script | 14.4 KB |
references/event-taxonomy-guide.md
View on GitHub# Event Taxonomy Guide
Complete reference for naming conventions, event structure, and parameter standards.
---
## Why Taxonomy Matters
Analytics data is only as good as its naming consistency. A tracking system with `FormSubmit`, `form_submit`, `form-submitted`, and `formSubmitted` as four separate "events" is useless for aggregation. One naming standard, enforced from day one, avoids months of cleanup later.
This guide is the reference for that standard.
---
## Naming Convention: Full Specification
### Format
```
[object]_[action]
```
**Object** = the thing being acted upon (noun)
**Action** = what happened (verb, past tense or gerund)
### Casing & Characters
| Rule | ✅ Correct | ❌ Wrong |
|------|-----------|---------|
| Lowercase only | `video_started` | `Video_Started`, `VIDEO_STARTED` |
| Underscores only | `form_submit` | `form-submit`, `formSubmit` |
| Noun before verb | `plan_selected` | `selected_plan` |
| Past tense or clear state | `checkout_completed` | `checkout_complete`, `checkoutDone` |
| Specific > generic | `trial_started` | `event_triggered` |
| Max 4 words | `onboarding_step_completed` | `user_completed_an_onboarding_step_in_the_flow` |
### Action Vocabulary (Standard Verbs)
Use these verbs consistently — don't invent synonyms:
| Verb | Use for |
|------|---------|
| `_started` | Beginning of a multi-step process |
| `_completed` | Successful completion of a process |
| `_failed` | An attempt that errored out |
| `_submitted` | Form or data submission |
| `_viewed` | Passive view of a page, modal, or content |
| `_clicked` | Direct click on a specific element |
| `_selected` | Choosing from options (plan, variant, filter) |
| `_opened` | Modal, drawer, chat window opened |
| `_closed` | Modal, drawer, chat window closed |
| `_downloaded` | File download |
| `_activated` | Feature turned on for first time |
| `_upgraded` | Plan or feature upgrade |
| `_cancelled` | Intentional termination |
| `_dismissed` | User explicitly closed/ignored a prompt |
| `_searched` | Search query submitted |
---
## Complete SaaS Event Catalog
### Acquisition Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `ad_clicked` | `utm_source`, `utm_campaign` | `utm_content`, `utm_term` |
| `landing_page_viewed` | `page_location`, `utm_source` | `variant` (A/B) |
| `pricing_viewed` | `page_location` | `referrer_page` |
| `demo_requested` | `source` (page slug or section) | `plan_interest` |
| `content_downloaded` | `content_name`, `content_type` | `gated` (boolean) |
### Acquisition → Registration
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `signup_started` | — | `plan_name`, `method` |
| `signup_completed` | `method` | `user_id`, `plan_name` |
| `email_verified` | — | `method` |
| `trial_started` | `plan_name` | `trial_length_days` |
| `invitation_accepted` | `inviter_user_id` | `plan_name` |
### Onboarding Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `onboarding_started` | — | `onboarding_variant` |
| `onboarding_step_completed` | `step_name`, `step_number` | `time_spent_seconds` |
| `onboarding_completed` | `steps_total` | `time_to_complete_seconds` |
| `onboarding_skipped` | `step_name` | `step_number` |
| `feature_activated` | `feature_name` | `activation_method` |
| `integration_connected` | `integration_name` | `integration_type` |
| `team_member_invited` | — | `invite_method` |
### Conversion Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `plan_selected` | `plan_name`, `billing_period` | `previous_plan` |
| `checkout_started` | `plan_name`, `value`, `currency` | `billing_period` |
| `checkout_completed` | `plan_name`, `value`, `currency`, `transaction_id` | `billing_period`, `coupon_code` |
| `checkout_failed` | `plan_name`, `error_reason` | `value`, `currency` |
| `upgrade_completed` | `from_plan`, `to_plan`, `value`, `currency` | `trigger` |
| `coupon_applied` | `coupon_code`, `discount_value` | `plan_name` |
### Engagement Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `feature_used` | `feature_name` | `feature_area`, `usage_count` |
| `search_performed` | `search_term` | `results_count`, `search_area` |
| `filter_applied` | `filter_name`, `filter_value` | `result_count` |
| `export_completed` | `export_type`, `export_format` | `record_count` |
| `report_generated` | `report_name` | `date_range` |
| `notification_clicked` | `notification_type` | `notification_id` |
### Retention Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `subscription_cancelled` | `cancel_reason` | `plan_name`, `save_offer_shown`, `save_offer_accepted` |
| `save_offer_accepted` | `offer_type` | `plan_name`, `discount_pct` |
| `subscription_paused` | `pause_duration_days` | `pause_reason` |
| `subscription_reactivated` | — | `plan_name`, `days_since_cancel` |
| `churn_risk_detected` | — | `risk_score`, `risk_signals` |
### Support / Help Events
| Event | Required Parameters | Optional Parameters |
|-------|-------------------|-------------------|
| `help_article_viewed` | `article_name` | `article_id`, `source` |
| `chat_opened` | — | `page_location`, `trigger` |
| `support_ticket_submitted` | `ticket_category` | `severity` |
| `error_encountered` | `error_type`, `error_message` | `page_location`, `feature_name` |
---
## Custom Dimensions & Metrics
GA4 limits: 50 custom dimensions (event-scoped), 25 user-scoped, 50 item-scoped.
Prioritize the ones that matter for segmentation.
### Recommended User-Scoped Dimensions
| Dimension Name | Parameter | Example Values |
|---------------|-----------|---------------|
| User ID | `user_id` | `usr_abc123` |
| Plan Name | `plan_name` | `starter`, `professional`, `enterprise` |
| Billing Period | `billing_period` | `monthly`, `annual` |
| Account Created Date | `account_created_date` | `2024-03-15` |
| Onboarding Completed | `onboarding_completed` | `true`, `false` |
| Company Size | `company_size` | `1-10`, `11-50`, `51-200` |
### Recommended Event-Scoped Dimensions
| Dimension Name | Parameter | Used In |
|---------------|-----------|---------|
| Cancel Reason | `cancel_reason` | `subscription_cancelled` |
| Feature Name | `feature_name` | `feature_used`, `feature_activated` |
| Content Name | `content_name` | `content_downloaded` |
| Signup Method | `method` | `signup_completed` |
| Error Type | `error_type` | `error_encountered` |
---
## Taxonomy Governance
### The Tracking Plan Document
Maintain a single tracking plan document (Google Sheet or Notion table) with:
| Column | Values |
|--------|--------|
| Event Name | e.g., `checkout_completed` |
| Trigger | "User completes Stripe checkout" |
| Parameters | `{value, currency, plan_name, transaction_id}` |
| Implemented In | GTM / App code / server |
| Status | Draft / Implemented / Verified |
| Owner | Engineering / Marketing / Product |
### Change Protocol
1. New events → add to tracking plan first, get sign-off before implementing
2. Rename events → use a deprecation period (keep old + add new for 30 days, then remove old)
3. Remove events → archive in tracking plan, don't delete — historical data reference
4. Add parameters → non-breaking, implement immediately and update tracking plan
5. Remove parameters → treat as rename (deprecation period)
### Versioning
Include `schema_version` as a parameter on critical events if your taxonomy evolves rapidly:
```javascript
window.dataLayer.push({
event: 'checkout_completed',
schema_version: 'v2',
value: 99,
currency: 'USD',
// ...
});
```
This allows filtering old vs. new schema during migrations.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |