GA4 Custom Events

GA4 Custom Events

Expert guidance for creating business-specific custom events beyond Google's recommended events.

Overview

Custom events enable measurement of unique business goals, industry-specific actions, and contextual behaviours not covered by Google's recommended events. This reference covers event naming conventions, parameter design strategies, and implementation across all platforms.

When to Use Custom Events

Create custom events when:

• Business action not covered by recommended events
• Industry-specific tracking requirements
• Unique user interactions to measure
• Business-specific conversion points
• Detailed behavioural analysis needs

Event Naming Conventions

Format and Constraints

Naming Framework

[action]_[object]_[context]

Examples:

• product_comparison_viewed
• pricing_calculator_used
• whitepaper_downloaded
• trial_signup_completed
• support_ticket_created

Good Event Names

Anti-Patterns (Avoid)

Event Parameter Design

Parameter Strategy

For each custom event, identify:

1. What is the action? The user behaviour being measured
2. What context is needed? Information to analyse the action
3. What parameters provide context? Data points to collect
4. What are the constraints? Length limits, data types

Parameter Limits

Parameter Examples

demo_requested Event:

gtag('event', 'demo_requested', {
  'demo_type': 'product_walkthrough',
  'industry': 'technology',
  'company_size': 'enterprise',
  'lead_source': 'organic_search',
  'product_interest': 'analytics_suite'
});

course_enrollment Event:

gtag('event', 'course_enrollment', {
  'course_id': 'COURSE_101',
  'course_name': 'Advanced GA4',
  'instructor': 'Jane Smith',
  'price': 99.99,
  'currency': 'USD',
  'level': 'advanced',
  'duration_hours': 8
});

support_ticket_created Event:

gtag('event', 'support_ticket_created', {
  'ticket_type': 'bug_report',
  'product': 'mobile_app',
  'severity': 'high',
  'department': 'engineering',
  'resolution_time_expected': 24
});

Industry-Specific Patterns

SaaS Events

Education Events

Media Events

E-commerce (Beyond Recommended)

Implementation Examples

gtag.js Implementation

// Simple event
gtag('event', 'demo_requested', {
  'demo_type': 'product_walkthrough',
  'industry': 'technology'
});

// Event with multiple parameters
gtag('event', 'subscription_changed', {
  'change_type': 'upgrade',
  'from_plan': 'basic',
  'to_plan': 'professional',
  'price_difference': 50,
  'currency': 'USD',
  'billing_cycle': 'monthly'
});

GTM Data Layer Implementation

// Push event to data layer
dataLayer.push({
  'event': 'demo_requested',
  'demo_type': 'product_walkthrough',
  'industry': 'technology',
  'company_size': 'enterprise'
});

// In GTM:
// 1. Create Data Layer Variables for each parameter
// 2. Create Custom Event trigger for 'demo_requested'
// 3. Create GA4 Event tag with mapped parameters

Measurement Protocol (Server-Side)

import requests
import json

MEASUREMENT_ID = "G-XXXXXXXXXX"
API_SECRET = "your_api_secret"

def send_custom_event(client_id, event_name, params):
    url = f"https://www.google-analytics.com/mp/collect?measurement_id={MEASUREMENT_ID}&api_secret={API_SECRET}"

    payload = {
        "client_id": client_id,
        "events": [{
            "name": event_name,
            "params": params
        }]
    }

    response = requests.post(
        url,
        headers={"Content-Type": "application/json"},
        data=json.dumps(payload)
    )

    return response.status_code == 204

# Example usage
send_custom_event(
    client_id="123.456",
    event_name="subscription_renewed",
    params={
        "plan_type": "professional",
        "renewal_value": 299.00,
        "currency": "USD",
        "renewal_count": 3
    }
)

Registering Custom Dimensions

Custom parameters won't appear in GA4 reports until registered as custom dimensions.

Registration Process

1. Send parameter in event (any platform)
2. Verify in DebugView (Admin -> DebugView)
3. Register dimension:
   • Admin -> Data Display -> Custom Definitions
   • Create Custom Dimension
   • Dimension Name: Human-friendly (e.g., "Demo Type")
   • Scope: Event, User, or Item
   • Event Parameter: Exact name from code (e.g., "demo_type")
4. Wait 24-48 hours for data to populate
5. Use in reports (Explorations, Standard Reports)

Scope Selection

Testing Custom Events

DebugView Workflow

1. Enable debug mode:

   • Chrome extension: Google Analytics Debugger
   • URL parameter: ?debug_mode=true
   • gtag config: debug_mode: true

2. Trigger custom event

3. Check DebugView:

   • Event appears with correct name
   • All parameters present
   • Parameter values correct
   • No errors or warnings

Validation Checklist

• Event name follows snake_case
• Event name under 40 characters
• All parameters present
• Parameter names under 40 characters
• Parameter values under 100 characters
• Correct data types (string vs number)
• No PII in parameters

Common Issues

Event Not Appearing

Causes:

• Debug mode not enabled
• Wrong Measurement ID
• JavaScript error before gtag call
• Ad blocker blocking

Solutions:

1. Enable Google Analytics Debugger extension
2. Verify Measurement ID
3. Check browser console for errors
4. Test in incognito mode

Parameters Missing

Causes:

• Parameter name typo
• Value is undefined/null
• Data layer variable not populated

Solutions:

1. Check exact parameter name
2. Validate value before sending
3. Debug data layer in GTM Preview

Wrong Data Type

Causes:

• Sending string instead of number
• Array where string expected

Solutions:

1. Validate data type before sending
2. Convert values appropriately
3. Test with DebugView

Best Practices

Design Guidelines

1. Be consistent - Same event name everywhere
2. Be descriptive - Clear, action-oriented names
3. Be specific - Avoid generic catch-all events
4. Plan parameters - Document required vs optional
5. Validate values - Check before sending

Documentation

Document each custom event:

## Event: demo_requested

**Description:** User requested a product demonstration

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| demo_type | string | Yes | Type of demo requested |
| industry | string | No | User's industry |
| company_size | string | No | Size category |

**Example:**
gtag('event', 'demo_requested', {
  'demo_type': 'product_walkthrough',
  'industry': 'technology'
});

Version Control

Track event changes:

• Document when events added/modified
• Include in code review process
• Update documentation on changes