gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-custom-events/references/naming-conventions-guide.md

GA4 Custom Event Naming Conventions Guide

Complete Reference for Event Naming Strategy

Core Naming Rules

Rule 1: Use snake_case

✅ Correct: video_tutorial_watched
❌ Wrong: VideoTutorialWatched, video-tutorial-watched

Rule 2: Maximum 40 Characters

✅ Correct: product_demo_request_submitted (34 chars)
❌ Wrong: product_demo_request_submitted_by_enterprise_user (57 chars)

Rule 3: Start with Action Verb When Possible

✅ Correct: file_downloaded, calculator_used, video_started
❌ Wrong: download_file, use_calculator, start_video

Rule 4: Be Descriptive to Business Context

✅ Correct: api_key_generated, subscription_upgraded, refund_requested
❌ Wrong: action, event, click, data

Rule 5: Maintain Consistency

✅ Correct: Always "video_completed" (never video_done, video_finished)
❌ Wrong: Mixing "cart_abandoned", "cartAbandoned", "cart_left"

---

Naming Framework: [Action][Object][Context]

Pattern Breakdown

Action: What the user is doing

• view, create, update, delete, submit, download, watch, listen
• click, scroll, hover, focus, select, open, close
• start, complete, pause, resume, skip, error
• upgrade, downgrade, cancel, refund, return

Object: What entity is being acted upon

• video, article, product, course, trial, subscription
• button, form, popup, modal, notification
• cart, order, invoice, receipt, account
• dashboard, report, export, import, setting

Context: Qualifier or category (optional)

• _free, _premium, _enterprise, _trial
• _mobile, _desktop, _tablet
• _email, _social, _referral
• _failed, _success, _error, _retry

Framework Examples

E-commerce Context:

• product_view (user viewed product)
• product_compare_viewed (comparison page opened)
• add_to_cart (item added to shopping cart)
• wishlist_add (item added to saved list)
• review_submit (product review posted)
• add_to_cart_mobile (mobile-specific cart action)

SaaS Context:

• trial_start (free trial activated)
• trial_end (trial period ended)
• feature_unlock (premium feature accessed)
• api_key_create (authentication token generated)
• integration_connect (third-party service linked)
• upgrade_click (upgrade button clicked)

Content Context:

• video_start (video playback began)
• video_complete (video finished)
• article_read (article fully read)
• podcast_skip (podcast episode skipped)
• download_start (resource download initiated)
• whitepaper_request (lead magnet requested)

SaaS Trial Context:

• trial_signup (trial account created)
• trial_feature_use (premium feature tested during trial)
• trial_extend (trial period extended)
• trial_convert (trial upgraded to paid)
• trial_abandon (trial left unused)

---

Industry Naming Patterns

SaaS Specific

Onboarding & Activation:

• onboarding_start, onboarding_step_completed, onboarding_complete
• welcome_tour_start, tutorial_lesson_completed
• first_data_entry, first_report_generated

Feature Engagement:

• feature_discover, feature_explore, feature_adopt
• integration_setup, integration_test, integration_activate
• api_call_success, api_error_encountered

Monetization:

• upgrade_modal_view, upgrade_click, upgrade_complete
• plan_comparison_view, pricing_page_visit
• subscription_pause, subscription_resume, subscription_cancel

Support & Help:

• help_article_search, help_article_view, help_article_helpful
• support_ticket_open, support_chat_start
• feature_request_submit, bug_report_submit

Education Specific

Course Engagement:

• course_enroll, course_start, course_complete
• lesson_view, lesson_complete, lesson_retry
• quiz_attempt, quiz_submit, quiz_pass

Learning Progress:

• certificate_earn, badge_unlock, milestone_reach
• study_streak_start, study_streak_end
• resource_download, note_create, bookmark_add

Social & Collaboration:

• discussion_post_create, discussion_reply, discussion_helpful_vote
• peer_review_submit, study_group_join

Media/Publishing Specific

Content Consumption:

• article_read_start, article_read_complete, article_scroll_depth_100
• video_play, video_pause, video_quality_change
• podcast_episode_start, podcast_episode_complete

Engagement:

• content_share, content_comment, content_like
• newsletter_signup, newsletter_open, newsletter_click
• bookmark_save, bookmark_view, bookmark_share

Creator Features:

• draft_create, article_publish, video_upload
• monetization_enable, subscriber_only_content_publish

E-commerce Specific

Product Discovery:

• search_submit, filter_apply, sort_change
• category_view, subcategory_view
• product_review_read, product_rating_view

Purchase Journey:

• product_add_to_cart, cart_view, cart_update_quantity
• checkout_start, shipping_option_select, payment_method_select
• apply_coupon, coupon_remove, gift_card_apply

Post-Purchase:

• order_confirmation_view, order_tracking_click
• product_return_initiate, refund_request_submit

---

Naming Checklist

Before finalizing custom event names:

• Event name is snake_case (lowercase, underscores)
• Event name is under 40 characters
• Event name is action-oriented (verb first when possible)
• Event name is specific to business domain
• Event name is consistent with existing naming scheme
• Event name doesn't duplicate a recommended event
• Event name would be understandable to business stakeholders
• Event name could be documented without parameters
• Event is documented in team's event dictionary
• Event follows organization's naming standards

---

Anti-Pattern Examples to Avoid

Generic Names

❌ Bad: click, event, action, user_action, interaction
✅ Good: button_click, demo_button_click, video_play_click

Vague Names

❌ Bad: data, info, tracking, send, request
✅ Good: customer_data_export, form_submit_request, contact_email_send

Inconsistent Names

❌ Bad: "user_signup", "registerUser", "SignUp", "sign_up_completed"
✅ Good: Always "user_signup" (consistent)

Over-specific Names

❌ Bad: "user_clicked_blue_button_in_hero_section_on_homepage_on_mobile"
✅ Good: "hero_cta_click" or "homepage_cta_click"

Parameters in Event Names

❌ Bad: "video_watched_hd", "trial_signup_30day", "user_from_google"
✅ Good: "video_watched" with parameter video_quality="hd"

---

Implementation Examples

Example 1: Complete Naming Decision

Business Goal: Track when users request product demo

Naming Process:

1. Action: request, submit
2. Object: demo, product_demo
3. Context: (none needed, already specific)

Decision: demo_request or demo_request_submit?

• demo_request (28 chars) - Better: action is implied in "request"
• Final name: demo_request

Example 2: SaaS Feature Adoption

Business Goal: Track when users enable an integration

Naming Process:

1. Action: enable, activate, setup, connect
2. Object: integration
3. Context: integration type

Decision: integration_enabled or integration_setup_complete?

• integration_enabled (21 chars) - Clean and action-oriented
• Final name: integration_enabled
• Parameter: integration_type (e.g., "slack", "zapier")

Example 3: Educational Progress

Business Goal: Track when students complete quiz

Naming Process:

1. Action: submit, complete, finish
2. Object: quiz
3. Context: (optional: pass/fail)

Decision: quiz_submit or quiz_complete?

• quiz_submit (11 chars) - User action
• Final name: quiz_submit
• Parameter: quiz_result (e.g., "pass", "fail"), score (numeric)

---

Team Naming Standards (Template)

Document your organization's naming conventions:

Event Naming Standard
====================

Format: [action]_[object]_[context]

Actions Used: create, update, delete, view, submit, download, upload, upload, share
Objects: product, course, video, article, user, team, workspace, settings
Context: Optional qualifiers like _mobile, _free, _premium, _failed

Examples Approved:
- product_view
- course_enroll
- quiz_submit
- integration_enabled
- support_ticket_create

Examples Not Approved:
- user_action
- click_event
- data_send