gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-custom-dimensions/references/dimension-registration-steps.md

Complete Dimension Registration Walkthrough

Pre-Registration Checklist

Before registering a custom dimension in GA4 Admin:

• Parameter is being sent in event code
• Parameter name is finalized (case-sensitive)
• Scope is determined (event/user/item)
• Parameter verified in DebugView
• Dimension name is approved by team
• Not exceeding quota for scope type

---

Method 1: Event-Scoped Dimension Registration

Scenario: Tracking Which Forms Users Submit

Step 1: Implement in Code

Place the custom parameter in gtag event:

// On form submission
document.getElementById('contact-form').addEventListener('submit', function() {
  gtag('event', 'form_submit', {
    'form_name': 'Contact Form',
    'form_id': 'contact-form-v1',
    'form_destination': '/thank-you'
  });
});

Step 2: Verify in DebugView

1. Open GA4 property → Admin → DebugView
2. Install Google Analytics Debugger Chrome extension (if not installed)
3. Enable the extension (click icon, ensure enabled)
4. Refresh website page
5. Perform action that triggers event (submit form)
6. In DebugView left panel, click the "form_submit" event
7. Expand event details on right panel
8. Verify "form_name" parameter appears with correct value

Expected DebugView Output:

Event: form_submit
Timestamp: 2024-11-10 10:30:45.123

Parameters:
  - form_name: "Contact Form"
  - form_id: "contact-form-v1"
  - form_destination: "/thank-you"
  - (other auto-collected parameters)

Step 3: Navigate to Custom Definitions

1. In GA4 property interface, click Admin (bottom left)
2. Under "Data Display" section, click Custom Definitions

Step 4: Create Custom Dimension

1. Click "Create Custom Dimension" button (blue button, top right)
2. Fill the form that appears:

Field	Entry	Example
Dimension Name	Human-friendly name (appears in reports)	"Form Name"
Scope	Select "Event"	Event
Event Parameter	Exact parameter name from code (case-sensitive)	form_name
Description	Optional explanation	"Name of form submitted"

3. Click Save button

Step 5: Wait 24-48 Hours

• First 24 hours: DebugView may show parameter (if debug mode enabled)
• 24-48 hours: Reports begin showing dimension
• Retroactive population: Previous events reprocessed with dimension

Step 6: Verify in Reports

After 24-48 hours:

1. Go to Analytics → Reports → any report
2. Click + Customize or + Add dimension
3. Search for "Form Name"
4. Add to report
5. Dimension values appear in data

---

Method 2: User-Scoped Dimension Registration

Scenario: Tracking Customer Subscription Tier

Step 1: Implement in Code

Set user property after user authentication:

// After successful login
function handleLoginSuccess(user) {
  gtag('set', {
    'subscription_tier': user.planType,  // 'free', 'pro', 'enterprise'
    'customer_id': user.id,
    'account_created_date': user.createdDate
  });

  gtag('event', 'login', {
    'method': 'email'
  });
}

Important: Set user properties BEFORE sending events to ensure properties apply to all events.

Step 2: Verify in DebugView

1. GA4 property → Admin → DebugView
2. Click any event after login (page_view, button_click, etc.)
3. Expand event details
4. Scroll to "User properties" section
5. Verify "subscription_tier" appears with correct value

Expected DebugView Output:

Event: page_view

User properties:
  - subscription_tier: "pro"
  - customer_id: "CUST_12345"
  - account_created_date: "2020-05-15"

Step 3: Navigate to Custom Definitions

1. Click Admin → Custom Definitions

Step 4: Create Custom Dimension

1. Click "Create Custom Dimension"
2. Fill the form:

Field	Entry	Example
Dimension Name	Human-friendly name	"Subscription Tier"
Scope	Select "User"	User
User Property	Exact property name from code	subscription_tier
Description	Optional	"Customer's plan type"

3. Click Save

Step 5: Wait 24-48 Hours

Same as event-scoped dimensions.

Step 6: Verify in Reports

After 24-48 hours:

1. Analytics → Reports
2. Add dimension "Subscription Tier"
3. See all events grouped by subscription tier

---

Method 3: Item-Scoped Dimension Registration

Scenario: Tracking Product Colors in Purchases

Step 1: Implement in Code

Place parameter in items array of ecommerce event:

gtag('event', 'purchase', {
  'transaction_id': 'TXN_' + Math.random(),
  'value': 149.98,
  'currency': 'USD',
  'items': [
    {
      'item_id': 'SKU_SHIRT_BLUE',
      'item_name': 'Blue T-Shirt',
      'price': 29.99,
      'quantity': 2,
      'item_category': 'Apparel',
      'item_color': 'blue'  // CUSTOM DIMENSION
    },
    {
      'item_id': 'SKU_PANTS_BLACK',
      'item_name': 'Black Pants',
      'price': 49.99,
      'quantity': 1,
      'item_category': 'Apparel',
      'item_color': 'black'  // CUSTOM DIMENSION - DIFFERENT VALUE
    }
  ]
});

Step 2: Verify in DebugView

1. GA4 property → Admin → DebugView
2. Find "purchase" event
3. Click to expand event details
4. Scroll to "Items" section
5. Verify each item shows "item_color" parameter

Expected DebugView Output:

Event: purchase

Items:
  [0]:
    - item_id: "SKU_SHIRT_BLUE"
    - item_name: "Blue T-Shirt"
    - item_color: "blue"
  [1]:
    - item_id: "SKU_PANTS_BLACK"
    - item_name: "Black Pants"
    - item_color: "black"

Step 3: Navigate to Custom Definitions

1. Click Admin → Custom Definitions

Step 4: Create Custom Dimension

1. Click "Create Custom Dimension"
2. Fill the form:

Field	Entry	Example
Dimension Name	Human-friendly name	"Item Color"
Scope	Select "Item"	Item
Event Parameter	Parameter name from items array	item_color
Description	Optional	"Color variant of product"

3. Click Save

Step 5: Wait 24-48 Hours

Same delay as other scope types.

Step 6: Verify in Reports

After 24-48 hours:

1. Analytics → Reports → Monetization → Items
2. Items report shows "Item Color" dimension
3. Analyze which colors have best revenue, quantity, etc.

---

Custom Dimension Registration Form - Field Reference

Dimension Name Field

What to enter: Human-friendly name that will appear in reports and UI

Best practices:

• Descriptive (not "custom1" or "data")
• Title case ("Form Name", not "form name")
• Under 50 characters
• No special characters (use underscores if needed)
• Avoid jargon unfamiliar to team

Good examples:

• "Form Name"
• "Video Quality"
• "Customer Segment"
• "Item Color"
• "Error Type"

Poor examples:

• "custom_param_1"
• "data"
• "x"
• "param123"

Scope Field

What to select:

Three radio button options:

1. Event - Single event occurrence

   • Use for event-specific context
   • Each event sends its own value
   • Examples: button_name, form_id, video_title

2. User - All user events

   • Use for user attributes
   • Set once, applies to all events
   • Examples: subscription_tier, customer_segment

3. Item - Products in ecommerce events

   • Use for product-level data
   • Goes in items array
   • Examples: item_color, item_size

Cannot be changed after creation - Choose carefully.

Event Parameter / User Property Field

What to enter: Exact parameter or property name from code

Critical requirements:

• Case-sensitive (subscription_tier ≠ subscription_Tier)
• Must match exactly as sent in code
• No spaces or special characters (use underscores)
• Under 40 characters

How to find exact name:

1. Look at DebugView parameter/property name
2. Copy parameter name exactly
3. Paste into this field

Example matching:

Code sends:

gtag('event', 'video_watch', {
  'video_quality': 'hd'
});

Registration field should contain:

video_quality

NOT: "Video Quality" (that's the dimension name), "video_Quality", or "videoQuality"

Description Field (Optional)

What to enter: Brief explanation of what dimension tracks

Good descriptions:

• "Quality setting of video watched (hd, sd, auto)"
• "Customer's plan type (free, pro, enterprise)"
• "Color variant of product in purchase"
• "Name of form submitted (contact, newsletter, demo)"

Poor descriptions:

• "custom data"
• "info"
• "tracking"

---

Post-Registration Verification Workflow

Hour 0-6: Immediate Post-Registration

1. Do NOT create duplicate dimension while waiting
2. Do NOT modify the custom definition (requires deletion and recreation)
3. Continue sending parameter in events (essential for population)

Hour 24: First 24-Hour Check

1. Go to DebugView
2. Verify current events still sending parameter
3. Check if any data appearing in reports (may show before 48 hours)
4. Do NOT assume failure if not visible yet

Hour 48: Full Population Expected

1. Go to Analytics → Reports
2. Add custom dimension to any report
3. If dimension appears: SUCCESS
4. If dimension doesn't appear: Troubleshoot

Verification Checklist

• Dimension appears in dimension picker (Admin → Custom Definitions)
• Current events show dimension values in DebugView
• After 48 hours, dimension appears in reports
• Dimension values are accurate
• No duplicate dimensions created by mistake

---

Editing & Deleting Custom Dimensions

Edit Custom Dimension

Cannot directly edit. To change dimension:

1. Note dimension settings (name, scope, parameter)
2. Delete existing dimension
3. Create new dimension with updated settings
4. Wait 24-48 hours for new data population

Why limited edits?

• Scope cannot change (event to user, etc.)
• Parameter name essentially permanent
• Dimension name can be edited, but best practices say don't

Delete Custom Dimension

When to delete:

• No longer tracking that parameter
• Exceeding quota limits
• Created by mistake
• Need to recreate with different settings

Process:

1. Admin → Custom Definitions
2. Find dimension in list
3. Click the dimension name
4. Click Delete button
5. Confirm deletion

After deletion:

• Historical data remains in reports (for 2-14 months per retention)
• New dimension can be created with same parameter name
• Takes 24-48 hours to remove from dimension picker

Do NOT delete and immediately recreate - Wait 24 hours to avoid conflicts.

---

Batch Registration Strategy

When registering many dimensions at once:

Prioritize by Quota

Standard GA4 limits:

• Event-scoped: 50 max
• User-scoped: 25 max
• Item-scoped: 10 max

Prioritize:

1. Essential for business reporting (register first)
2. Important but not critical (register second)
3. Nice-to-have (register if quota allows)

Register in Waves

Wave 1 (First): High-Priority Dimensions

• Register 5-10 critical dimensions
• Wait 24-48 hours for population
• Verify data accuracy

Wave 2 (Later): Medium-Priority Dimensions

• Register after Wave 1 verified
• Again wait 24-48 hours
• Continue verification

Wave 3 (Much Later): Low-Priority Dimensions

• Register final wave if quota allows
• Ensure no conflicts with existing

Why Wave Registration?

• Easier troubleshooting (fewer variables)
• Confirm code quality before scale
• Verify team understands process
• Catch quota issues early

---

Common Registration Issues & Solutions

Dimension Doesn't Appear After 48 Hours

Troubleshooting steps:

1. Verify code still sending parameter

   • Check DebugView
   • Confirm events have parameter
   • If missing: Fix code implementation

2. Check parameter name case-sensitivity

   • Go to DebugView
   • Look at exact parameter name shown
   • Compare to registered parameter name
   • Must be EXACT match

3. Confirm scope is correct

   • Go to Admin → Custom Definitions
   • Check scope: Event, User, or Item?
   • Verify matches implementation

4. Check quota not exceeded

   • Event-scoped: Are you over 50?
   • User-scoped: Are you over 25?
   • Item-scoped: Are you over 10?
   • If over quota: Delete unused dimensions

5. Check minimum traffic threshold

   • Dimension needs at least 1000 events with parameter
   • Low-traffic dimensions may not populate
   • Wait longer if very low traffic

Parameter Appears in DebugView But Not Reports

• Expected in first 24 hours - Normal, wait until 48
• After 48 hours - Troubleshoot above

Multiple Duplicates Created By Mistake

• Delete all but one copy
• Wait 24-48 hours between deletions
• Recreate if needed

Can't Find Parameter in DebugView

• Code may not be live - Verify changes deployed
• Parameter not sent - Check event fires on intended action
• Event not triggering - Test event manually
• DebugView device wrong - Select correct device from dropdown