GA4 Custom Dimensions

Overview

Custom dimensions and metrics enable transformation of event parameters into reportable fields in GA4. This skill covers the complete workflow: sending parameters in events, registering them as dimensions, selecting correct scopes, and troubleshooting missing data.

All custom parameters remain invisible in GA4 reports until registered as custom dimensions. Registration requires understanding three scope types (event, user, item), following naming conventions, and accounting for the 24-48 hour processing delay.

When to Use This Skill

Invoke this skill when:

• Registering custom event parameters as event-scoped dimensions
• Setting up user properties as user-scoped custom dimensions
• Creating item-scoped dimensions for ecommerce tracking
• Implementing custom metrics for numerical tracking
• Building calculated metrics from existing metrics
• Troubleshooting why custom parameters don't appear in reports
• Planning dimension strategy within account limits (50 event/25 user/10 item)
• Understanding scope differences for specific business needs
• Dealing with the 24-48 hour data population delay

Core Concepts: Understanding Scopes

GA4 uses three scopes that determine what data the parameter applies to:

Event Scope (Single Event Only)

Applies To: Individual event occurrence Lifespan: That specific event only Use: Event-specific information

Event-scoped dimensions track data unique to each event. Once registered, they appear only for that event type in reports.

gtag('event', 'button_click', {
  'button_name': 'Subscribe',        // Event-scoped
  'button_location': 'header',       // Event-scoped
  'button_id': 'btn_subscribe_01'    // Event-scoped
});

Examples: Which form was submitted? What video was watched? Which page in sequence? Which button was clicked?

User Scope (All User Events)

Applies To: All events from that user Lifespan: Session persistence (until cleared) Use: User attributes that persist

User-scoped dimensions (user properties) apply to every event from that user during the session. Set once, they persist across multiple events.

gtag('set', {
  'subscription_tier': 'premium',         // User-scoped
  'customer_lifetime_value': 5000,        // User-scoped
  'preferred_language': 'en'              // User-scoped
});

Examples: What subscription level? What's customer lifetime value? What language preference? What company size?

Item Scope (Product-Level Data)

Applies To: Individual items in ecommerce events Lifespan: That transaction only Use: Product-specific information

Item-scoped dimensions apply only to products in purchase, add_to_cart, and related ecommerce events.

gtag('event', 'purchase', {
  'items': [
    {
      'item_id': 'SKU_123',
      'item_name': 'Blue T-Shirt',
      'item_color': 'blue',         // Item-scoped
      'item_size': 'large',         // Item-scoped
      'supplier': 'Vendor A'        // Item-scoped
    }
  ]
});

Examples: Which color was purchased? What size items sell best? Which supplier's products? Product quality rating?

Registration Workflow

Step 1: Send Parameter in Event Code

Send the parameter in either gtag.js event call, gtag('set') for user properties, or in items array:

// Event parameter
gtag('event', 'watch_video', {
  'video_duration': 1200,
  'video_quality': 'hd'
});

// User parameter
gtag('set', {
  'customer_segment': 'enterprise'
});

// Item parameter
gtag('event', 'purchase', {
  'items': [{
    'item_id': 'SKU_123',
    'supplier': 'Vendor A'  // NEW parameter
  }]
});

Step 2: Verify in DebugView

Before registration, confirm the parameter appears in DebugView:

1. Go to Admin → DebugView
2. Enable Google Analytics Debugger Chrome extension
3. Trigger the event that sends parameter
4. See parameter in DebugView event details
5. Note exact parameter name (case-sensitive)

Step 3: Register as Custom Dimension

Navigate to Admin → Data Display → Custom Definitions:

1. Click "Create Custom Dimension"
2. Fill form:
   • Dimension Name: Human-friendly name (appears in reports, e.g., "Video Quality")
   • Scope: Select Event, User, or Item
   • Event Parameter: Exact parameter name from code (case-sensitive, e.g., "video_quality")
   • Description: Optional notes
3. Click Save

Step 4: Wait for Data Population

Critical: Custom dimensions don't appear in reports immediately. Wait 24-48 hours for:

• Historical data retroactively processed
• New incoming data to populate
• Dimension to appear in dimension selectors

Do not create duplicate dimensions while waiting.

Step 5: Use in Reports

After 24-48 hours, access custom dimensions:

• Standard Reports: Add custom dimension as column
• Explorations: Select from Dimension picker
• Filters/Segments: Filter by custom dimension values
• Google Ads: Export for audience building (if linked)

Dimension Limits & Quotas

Standard GA4 Property limits:

• User-scoped: 25 custom dimensions
• Event-scoped: 50 custom dimensions
• Item-scoped: 10 custom dimensions
• Custom metrics: 50
• Calculated metrics: 5

GA4 360 properties have higher limits (100 user, 125 event, 25 item). Plan dimensions strategically.

Custom Metrics Implementation

Standard Custom Metrics

Create metrics for numerical tracking:

gtag('event', 'video_watched', {
  'video_title': 'GA4 Tutorial',
  'minutes_watched': 45,      // METRIC
  'completion_rate': 85       // METRIC
});

Register in Custom Definitions:

1. Click "Create Custom Metric"
2. Metric Name: "Minutes Watched"
3. Type: Standard
4. Measurement Unit: Minutes (optional)
5. Event Parameter: "minutes_watched"
6. Save and wait 24-48 hours

Calculated Metrics

Create metrics derived from mathematical operations on existing metrics:

Calculated Metric: "Revenue per User"
= revenue / users

Calculated Metric: "Conversion Rate"
= conversions / sessions * 100

Create in Custom Definitions:

1. Click "Create Custom Metric"
2. Metric Name: "Revenue per User"
3. Type: Calculated
4. Formula: revenue / users
5. Save (no processing delay)

Common Troubleshooting

Custom dimension doesn't appear after 48 hours:

• Verify parameter name matches exactly (case-sensitive)
• Confirm new events are actually sending parameter
• Check DebugView to see current events with parameter
• Ensure scope selection was correct
• Not all parameter values may appear if threshold not met

Parameter appears in DebugView but not in reports:

• Normal during first 24-48 hours
• Check Realtime reports first (available sooner)
• Verify at least 1000 events with that parameter for visibility
• Low-traffic parameters may not appear

Dimension quota exceeded:

• Standard GA4: Maximum 50 event-scoped dimensions
• Plan which dimensions are essential
• Delete unused dimensions if needed
• Consider GA4 360 for higher limits

Multiple users show same custom dimension value:

• For user-scoped: Expected (applies to all user events)
• For event-scoped: Normal if multiple events send same value
• For item-scoped: Normal across products

Integration with Other Skills

• ga4-events-fundamentals - Understand event structure and parameter basics
• ga4-custom-events - Create parameters to register as dimensions
• ga4-user-tracking - User properties (user-scoped dimensions)
• ga4-reporting - Use custom dimensions in standard reports and explorations

References

• references/scopes-complete-guide.md - Detailed scope examples and decision framework
• references/dimension-registration-steps.md - Step-by-step Admin UI walkthrough
• references/custom-metrics-guide.md - Standard and calculated metrics
• references/dimension-limits-quotas.md - Account limits and best practices
• references/dimension-troubleshooting.md - Solutions for common issues

Quick Reference

Scope Selection Matrix:

• Event-specific data → Event scope
• User attributes → User scope
• Product data in ecommerce → Item scope

Registration Process:

1. Send parameter in event code
2. Verify in DebugView
3. Admin → Custom Definitions → Create
4. Wait 24-48 hours
5. Use in reports

Parameter Limits:

• Parameter name: 40 characters max
• Parameter value: 100 characters max (exceptions: page_location 1000, page_title 300)
• Parameters per event: 25 max
• Items array max: 27 items