claude-skills-reference/marketing-skill/analytics-tracking/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

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:

window.dataLayer.push({
  event: 'checkout_completed',
  schema_version: 'v2',
  value: 99,
  currency: 'USD',
  // ...
});

This allows filtering old vs. new schema during migrations.