references/event-taxonomy-guide.md
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
- New events → add to tracking plan first, get sign-off before implementing
- Rename events → use a deprecation period (keep old + add new for 30 days, then remove old)
- Remove events → archive in tracking plan, don't delete — historical data reference
- Add parameters → non-breaking, implement immediately and update tracking plan
- Remove parameters → treat as rename (deprecation period)
Versioning
Include schema_version as a parameter on critical events if your taxonomy evolves rapidly:
window.dataLayer.push({
event: 'checkout_completed',
schema_version: 'v2',
value: 99,
currency: 'USD',
// ...
});
This allows filtering old vs. new schema during migrations.