9.5 KiB
9.5 KiB
GA4 Event Design Framework
Comprehensive Guide to Custom Event Architecture
Event Design Philosophy
Custom events should answer business questions:
- What action is the user taking?
- Why does it matter to the business?
- What context makes it meaningful?
- How will it be analyzed?
Effective events provide actionable insights about user behavior, feature adoption, and business metrics.
Event Discovery Process
Step 1: Identify Business Goals
List objectives that matter to the business:
- User acquisition and activation
- Feature adoption and engagement
- Conversion and monetization
- Retention and churn prevention
- Support and satisfaction
Step 2: Map User Actions to Goals
Connect specific user behaviors to each business goal:
| Business Goal | User Action | Event Needed |
|---|---|---|
| Feature adoption | User explores premium feature | feature_explore |
| Conversion | User upgrades from trial | upgrade_start |
| Retention | User invites teammates | user_invite_send |
| Support | User opens help article | help_article_view |
| Churn prevention | User pauses subscription | subscription_pause |
Step 3: Determine Required Context
For each action, identify what context makes analysis meaningful:
Example: Feature Adoption
Event: feature_explore
Context needed:
- feature_name: Which feature?
- feature_category: Premium, beta, experimental?
- source: Where did they find it? (help, notification, suggestion)
- result: Did they stay on feature?
Step 4: Design Event Structure
Finalize event name and parameters:
gtag('event', 'feature_explore', {
'feature_name': 'advanced_reporting',
'feature_category': 'premium',
'discovery_source': 'help_article',
'user_tier': 'free'
});
Parameter Scoping Strategy
GA4 uses three scopes. Choose correctly:
Event-Scoped Parameters (Single Event)
Use When: Data is specific to this event occurrence
Examples:
button_clickedevent: which button_name?video_watchedevent: which video_title?form_submitevent: which form_name, form_destination?
gtag('event', 'video_watched', {
'video_title': 'GA4 Fundamentals', // Event-scoped
'video_duration': 600, // Event-scoped
'completion_percent': 100 // Event-scoped
});
Registration: Event-Scoped Custom Dimension in Admin
User-Scoped Parameters (User Properties)
Use When: Data applies to ALL events from user
Examples:
- subscription tier (free, pro, enterprise)
- company size (startup, mid-market, enterprise)
- customer segment (high-value, at-risk, churned)
- geographic region (EMEA, APAC, Americas)
gtag('set', {
'subscription_tier': 'premium', // User-scoped
'customer_segment': 'high_value', // User-scoped
'onboarding_complete': true // User-scoped
});
When to Use: Set once, applies to all subsequent events
Registration: User-Scoped Custom Dimension in Admin
Item-Scoped Parameters (Ecommerce Items)
Use When: Data applies to individual products in transaction
Only used with items array in ecommerce events.
gtag('event', 'purchase', {
'items': [
{
'item_id': 'SKU_001',
'item_name': 'Premium Widget',
'item_color': 'blue', // Item-scoped
'supplier': 'Vendor A', // Item-scoped
'quantity': 2,
'price': 49.99
}
]
});
Parameter Design Best Practices
Rule 1: Keep Parameters Meaningful
✅ Good:
gtag('event', 'trial_start', {
'trial_days': 30,
'trial_plan': 'professional',
'source_utm': 'google_ads'
});
❌ Bad:
gtag('event', 'trial_start', {
'random_id': '12345',
'session_date': '2024-11-10',
'browser': 'Chrome' // These are auto-collected
});
Rule 2: Use Consistent Values
✅ Good:
Always use 'free', 'pro', 'enterprise'
(case consistent, lowercase)
❌ Bad:
Mix of 'free', 'Free', 'FREE', 'standard'
(inconsistent capitalization)
Rule 3: Avoid High-Cardinality Parameters
✅ Good:
'plan_type': 'pro' (5 possible values)
❌ Bad:
'user_email': 'user@example.com' (millions of values)
'session_id': '12345abc...' (unique per session)
Rule 4: Store IDs as Parameters, Not in Event Name
✅ Good:
gtag('event', 'video_watched', {
'video_id': 'VID_12345',
'video_title': 'Learning GA4'
});
❌ Bad:
gtag('event', 'video_watched_VID_12345')
gtag('event', 'video_watched_learning_ga4')
Rule 5: Use Numeric Types for Metrics
✅ Good:
'price': 99.99 (number)
'quantity': 5 (integer)
'duration_seconds': 1200 (integer)
❌ Bad:
'price': '$99.99' (string with currency)
'quantity': 'five' (string)
'duration': '20 minutes' (string)
Event Documentation Template
Document every custom event:
### Event: demo_request
**Description:** User requests product demonstration
**When Fired:**
- User clicks "Request Demo" button on pricing page
- User submits demo request form
**Parameters:**
| Parameter | Type | Values | Purpose |
|-----------|------|--------|---------|
| demo_type | string | walkthrough, personalized | Type of demo requested |
| industry | string | tech, finance, healthcare | User's industry |
| company_size | string | startup, mid-market, enterprise | Company size |
| source | string | pricing_page, landing_page, email | Where request originated |
**Implementation:**
- gtag.js: Yes
- GTM: Yes
- Measurement Protocol: Yes
**Custom Dimension:** Yes (demo_type, industry, company_size as event-scoped)
**Frequency:** ~50-100 per month (estimated)
**Related Events:** demo_attend, demo_skip, upgrade_after_demo
Parameter Validation
Type Validation
Ensure parameters use correct types:
// ✅ Correct types
gtag('event', 'purchase', {
'value': 99.99, // Number
'currency': 'USD', // String
'quantity': 3, // Integer
'is_gift': true, // Boolean
'items': [...] // Array
});
// ❌ Wrong types
gtag('event', 'purchase', {
'value': '99.99', // String instead of number
'quantity': '3', // String instead of integer
'is_gift': 'true' // String instead of boolean
});
Value Length Validation
// ✅ Good (under limits)
gtag('event', 'form_submit', {
'form_name': 'Contact Form', // OK (14 chars)
'company_name': 'Acme Corp', // OK (9 chars)
'email_body': 'Long message...' // OK (100 chars max)
});
// ❌ Bad (too long)
gtag('event', 'form_submit', {
'form_description': '...[200 chars]...' // Exceeds 100 char limit
});
Complex Event Examples
Example 1: Video Engagement Tracking
gtag('event', 'video_engagement', {
'video_id': 'VID_2024_001',
'video_title': 'GA4 Advanced Features',
'video_duration': 1200, // seconds
'time_watched': 845, // seconds
'completion_percent': 70,
'quality_selected': 'hd',
'interaction_type': 'pause', // pause, seek, quality_change, fullscreen
'engagement_score': 8 // 1-10 scale
});
Example 2: SaaS Onboarding Tracking
gtag('event', 'onboarding_step_complete', {
'step_number': 3,
'step_name': 'team_invite',
'total_steps': 5,
'time_on_step': 245, // seconds
'users_invited': 2,
'skip_attempted': false
});
// User-level context
gtag('set', {
'onboarding_progress': 'step_3_of_5',
'onboarding_started_date': '2024-11-10'
});
Example 3: E-commerce Product Discovery
gtag('event', 'product_discovery_complete', {
'discovery_method': 'search', // search, recommendation, browse, email
'search_term': 'running shoes',
'filters_applied': 3,
'results_viewed': 24,
'products_liked': 5,
'add_to_cart_from_discovery': 2
});
Event Consolidation vs Proliferation
When to Consolidate Events
Use one event with parameters instead of multiple events:
❌ Too many events:
- button_click_signin
- button_click_signup
- button_click_demo
- button_click_contact
✅ One consolidated event:
- button_click (with parameter: button_name)
When to Separate Events
Create separate events for distinct user journeys:
✅ Separate events (correct):
- feature_explore (user discovered feature)
- feature_adopt (user started using feature)
- feature_abandon (user stopped using feature)
❌ One event (not enough context):
- feature_interaction (ambiguous: explore or use?)
Decision Rule
- Same event type + just different context: Use parameters
- Different action sequences or business flows: Use separate events
- Different analysis needs: Consider separate events
Event Limits and Quotas
Standard GA4 Property Limits
- Maximum event names: 500 event types per property
- Maximum 25 parameters per event
- Parameter name: 40 characters max
- Parameter value: 100 characters max (with exceptions)
Custom Dimension Limits
- Event-scoped: 50 per property
- User-scoped: 25 per property
- Item-scoped: 10 per property
Planning for Scale
When designing events, consider:
- How many unique custom events will be needed?
- What parameters will each event require?
- How many custom dimensions are needed?
- What's the growth trajectory?
If approaching limits, prioritize:
- Events that directly impact business decisions
- Parameters that enable key analyses
- Dimensions needed for audience segmentation