gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-custom-dimensions/references/scopes-complete-guide.md

Complete Guide to GA4 Dimension Scopes

Scope Fundamentals

A scope in GA4 determines the range of applicability for a custom dimension:

• What it applies to (event, user, or product)
• How long it persists
• When and where it appears in reports

Understanding scope is critical because the same parameter name with different scopes creates completely different tracking behavior.

Event Scope Deep Dive

Definition

Event-scoped dimensions apply to a single event occurrence only. Once that event is recorded, the dimension value is tied exclusively to that event.

Characteristics

• Scope: Single event only
• Lifespan: Duration of that one event
• Persistence: No carryover to other events
• Reporting: Appears only for that event type
• Reusability: Same dimension name can have different values across events
• Quota: 50 per standard GA4 property

Implementation

Basic event with event-scoped parameter:

gtag('event', 'form_submit', {
  'form_name': 'Contact Form',           // Event-scoped
  'form_id': 'contact-form-v2',          // Event-scoped
  'form_destination': '/thank-you',      // Event-scoped
  'form_field_count': 8                  // Event-scoped
});

Each event sends these parameters independently:

// First form submission
gtag('event', 'form_submit', {
  'form_name': 'Contact Form'
});

// Later, different form submission
gtag('event', 'form_submit', {
  'form_name': 'Newsletter Signup'  // Different value, same event
});

Use Cases

Use Case	Parameter	Example
Which form?	form_name	"Contact", "Newsletter", "Demo Request"
Which video?	video_title	"GA4 Basics", "Advanced Analytics"
Which button?	button_name	"Subscribe", "Download", "Add to Cart"
Which search term?	search_query	"analytics", "reporting"
Which page?	page_section	"header", "sidebar", "footer"
Which error?	error_message	"404", "500", "timeout"

Admin Registration Example

Creating "Form Name" Event-Scoped Dimension:

1. Admin → Data Display → Custom Definitions
2. Click "Create Custom Dimension"
3. Dimension Name: "Form Name"
4. Scope: Event (select this)
5. Event Parameter: "form_name" (exact match from code)
6. Description: "Name of form submitted (contact, newsletter, etc)"
7. Save

Result: In reports, filter/analyze by "Form Name" dimension showing all form submissions

Common Mistakes

Mistake 1: Using event-scoped dimension for persistent user data

// WRONG: Event scope for user property
gtag('event', 'page_view', {
  'subscription_tier': 'premium'  // Should be user scope!
});

Correct: Use user scope for persistent attributes

gtag('set', {
  'subscription_tier': 'premium'  // User scope - persists
});

Mistake 2: Sending same event-scoped dimension with every event

// INEFFICIENT: Redundant in every event
gtag('event', 'page_view', {
  'user_location': 'New York'  // Repeating same value
});
gtag('event', 'button_click', {
  'user_location': 'New York'  // Same value repeated
});

Better: Use user scope instead

gtag('set', {
  'user_location': 'New York'  // Set once, applies to all
});

---

User Scope Deep Dive

Definition

User-scoped dimensions (user properties) apply to all events from a user within a session. Set once, they persist across multiple events.

Characteristics

• Scope: All events from that user
• Lifespan: User session (or until explicitly cleared)
• Persistence: Applies retroactively to events within session
• Reporting: Appears across all event types for that user
• Reusability: Can be used in audiences, segments, and filters
• Quota: 25 per standard GA4 property
• Best for: User attributes and customer characteristics

Implementation

Setting user properties once, applying to all events:

// User logs in - set properties once
gtag('set', {
  'subscription_tier': 'premium',
  'customer_id': 'CUST_12345',
  'years_customer': 5,
  'account_status': 'active',
  'preferred_language': 'en'
});

// All subsequent events automatically include these user properties
gtag('event', 'page_view');           // Includes user properties
gtag('event', 'button_click', {...}); // Includes user properties
gtag('event', 'purchase', {...});     // Includes user properties

Predefined User Properties

GA4 automatically collects certain user properties without additional code:

language                Browser/app language
first_open_date        First app launch date
first_visit_date       First website visit date
ga_session_id          Current session ID
ga_session_number      Session count for user

Use Cases

Use Case	Property	Example Values
Subscription level	subscription_tier	free, pro, enterprise
Customer segment	customer_segment	new, returning, vip
Account status	account_status	active, inactive, trial
Industry	industry	technology, finance, retail
Company size	company_size	small, medium, enterprise
Loyalty level	loyalty_status	bronze, silver, gold, platinum
Location	location	New York, London, Tokyo
Preferred language	preferred_language	en, es, fr, de
Revenue bracket	annual_revenue	0-100k, 100k-1m, 1m+
Tenure	years_customer	1, 5, 10+

Admin Registration Example

Creating "Customer Segment" User-Scoped Dimension:

1. Admin → Data Display → Custom Definitions
2. Click "Create Custom Dimension"
3. Dimension Name: "Customer Segment"
4. Scope: User (select this)
5. User Property: "customer_segment"
6. Description: "Customer type: new, returning, vip"
7. Save

Result: All events from that user labeled with their customer segment

Clearing User Properties

User properties persist until explicitly cleared:

// Clear single user property
gtag('set', {
  'subscription_tier': null  // Set to null to clear
});

// Clear on user logout
gtag('set', {
  'subscription_tier': null,
  'customer_id': null,
  'account_status': null
});

Critical: Always set to null, not empty string "". Empty string persists as a value.

User Properties vs User ID

User ID (different from user properties):

• Enables cross-device and cross-session tracking
• Single identifier per user
• Set with gtag('set', {'user_id': 'value'})

User Properties:

• Multiple attributes about user
• Applied to all events from user
• Set with gtag('set', {property: value})

---

Item Scope Deep Dive

Definition

Item-scoped dimensions apply to individual products within ecommerce events (purchase, add_to_cart, view_item, etc.). Each product in the items array can have its own item-scoped dimension values.

Characteristics

• Scope: Individual items in items array
• Lifespan: That transaction/event only
• Persistence: No carryover to future transactions
• Reporting: Product-level analysis in ecommerce reports
• Quota: 10 per standard GA4 property
• Applies To: purchase, add_to_cart, remove_from_cart, view_item, etc.
• Array Structure: Sits within items array objects

Implementation

Item-scoped parameters in items array:

gtag('event', 'purchase', {
  'items': [
    {
      'item_id': 'SKU_123',
      'item_name': 'Blue T-Shirt',
      'price': 29.99,
      'quantity': 2,
      // ITEM-SCOPED CUSTOM DIMENSIONS:
      'item_color': 'blue',            // Which color?
      'item_size': 'large',            // Which size?
      'supplier': 'Vendor A',          // Which supplier?
      'warehouse_location': 'NY'       // Which warehouse?
    },
    {
      'item_id': 'SKU_124',
      'item_name': 'Gray Pants',
      'price': 49.99,
      'quantity': 1,
      // DIFFERENT VALUES for second item:
      'item_color': 'gray',            // Different color
      'item_size': 'medium',           // Different size
      'supplier': 'Vendor B',          // Different supplier
      'warehouse_location': 'LA'       // Different warehouse
    }
  ]
});

Use Cases

Use Case	Parameter	Example Values
Product color	item_color	red, blue, green, black
Product size	item_size	small, medium, large, xl
Supplier/vendor	supplier	"Vendor A", "Vendor B", "Internal"
Product quality tier	item_quality	standard, premium, luxury
Warehouse	warehouse_location	NY, LA, London, Tokyo
Product condition	condition	new, refurbished, used
Fabric type	fabric_type	cotton, polyester, silk
Season	season	spring, summer, fall, winter
Sustainability	eco_friendly	true, false
Gender/age	target_demographic	mens, womens, kids

Admin Registration Example

Creating "Item Color" Item-Scoped Dimension:

1. Admin → Data Display → Custom Definitions
2. Click "Create Custom Dimension"
3. Dimension Name: "Item Color"
4. Scope: Item (select this)
5. Event Parameter: "item_color"
6. Description: "Color variant of product"
7. Save

Result: Ecommerce reports can analyze "Which colors sell best?" by revenue, quantity, etc.

Accessing Item-Scoped Data in Reports

Standard GA4 reports:

1. Analytics → Reports → Monetization → Items
2. See products with custom dimensions
3. Add "Item Color" dimension to table
4. Sort/filter by color

Explorations:

1. Analytics → Explore
2. Use Item-related dimensions and metrics
3. Create "Items by Color" report
4. Analyze revenue, quantity, performance by item dimension

Complete Purchase Example

// Complete purchase with all item types and item-scoped dimensions
gtag('event', 'purchase', {
  'transaction_id': 'TXN_' + Date.now(),
  'value': 189.97,
  'currency': 'USD',
  'items': [
    {
      // Standard fields (required)
      'item_id': 'SKU_SHIRT_BLUE_L',
      'item_name': 'Blue T-Shirt',
      'price': 29.99,
      'quantity': 2,

      // Google-recommended fields (highly recommended)
      'item_category': 'Apparel',
      'item_brand': 'My Brand',
      'item_variant': 'Blue/Large',

      // CUSTOM ITEM-SCOPED DIMENSIONS:
      'item_color': 'blue',
      'item_size': 'large',
      'supplier': 'Vendor A',
      'warehouse_location': 'New York'
    },
    {
      'item_id': 'SKU_PANTS_GRAY_M',
      'item_name': 'Gray Pants',
      'price': 49.99,
      'quantity': 2,
      'item_category': 'Apparel',
      'item_brand': 'My Brand',
      'item_variant': 'Gray/Medium',

      // CUSTOM ITEM-SCOPED DIMENSIONS (different values):
      'item_color': 'gray',
      'item_size': 'medium',
      'supplier': 'Vendor B',
      'warehouse_location': 'Los Angeles'
    }
  ]
});

---

Scope Decision Framework

Use this framework to select correct scope:

Decision Tree

Is this data...

1. About a single event occurrence?

   • YES → Use Event scope
   • Example: "Which button was clicked?" → button_name (event-scoped)

2. About the user, applying to all their events?

   • YES → Use User scope
   • Example: "What's user's subscription level?" → subscription_tier (user-scoped)

3. About individual products in ecommerce events?

   • YES → Use Item scope
   • Example: "Which color was purchased?" → item_color (item-scoped)

4. About the same thing, but sometimes changes per event?

   • YES → Use Event scope (not user scope)
   • Example: "user_location" might change per page_view event → event-scoped

Scope Selection Matrix

Question	Event	User	Item
Applies to single event only?	✓	✗	✗
Applies to all user events?	✗	✓	✗
Applies to products in purchase?	✗	✗	✓
Persists across sessions?	✗	✓	✗
Can have different values per event?	✓	✗	✓
Used for audience building?	Limited	✓	Limited
Used in conversion analysis?	✓	✓	✓

Scope Limits & Quotas

Standard GA4 Property

• Event-scoped custom dimensions: 50 maximum
• User-scoped custom dimensions: 25 maximum
• Item-scoped custom dimensions: 10 maximum
• Total custom metrics: 50 maximum
• Total calculated metrics: 5 maximum

GA4 360 Property

• Event-scoped custom dimensions: 125 maximum
• User-scoped custom dimensions: 100 maximum
• Item-scoped custom dimensions: 25 maximum
• Total custom metrics: 125 maximum
• Total calculated metrics: 50 maximum

Choosing Which to Create

Prioritize by importance:

1. Essential - Required for business reporting (create first)
2. Important - Nice to have, but useful (create second)
3. Nice-to-have - Interesting but not critical (create if quota allows)

Example priority:

High Priority (Event):
  - form_name (which forms submitted)
  - error_type (what errors users encounter)
  - page_section (where on page interactions happen)

High Priority (User):
  - subscription_tier (critical for segmentation)
  - customer_segment (key for analysis)

High Priority (Item):
  - item_color (what colors sell)
  - item_size (what sizes convert)

---

Common Scope Confusion Examples

❌ WRONG: Using Event Scope for User Data

// INCORRECT - This repeats the same value in every event
gtag('event', 'page_view', {
  'subscription_tier': 'premium'  // Event scope
});

gtag('event', 'button_click', {
  'subscription_tier': 'premium'  // Repeated!
});

// Result: Bloated events, wasted parameters

✅ CORRECT: Using User Scope for User Data

// CORRECT - Set once, applies to all events
gtag('set', {
  'subscription_tier': 'premium'  // User scope
});

gtag('event', 'page_view');       // Automatically includes subscription_tier
gtag('event', 'button_click', {}); // Automatically includes subscription_tier

// Result: Clean, efficient, applies everywhere

❌ WRONG: Using User Scope for Event Data

// INCORRECT - "button_name" changes with every button click
gtag('set', {
  'button_name': 'Download'  // User scope - wrong!
});

gtag('event', 'button_click'); // Later click on different button
// Now it says all events came from "Download" button - wrong!

✅ CORRECT: Using Event Scope for Event Data

// CORRECT - Each event captures its own button
gtag('event', 'button_click', {
  'button_name': 'Download'  // Event scope
});

gtag('event', 'button_click', {
  'button_name': 'Subscribe'  // Event scope - different value
});

// Result: Accurate, event-specific tracking

---

Best Practices by Scope

Event Scope Best Practices

• Name descriptively (button_name, form_id, video_title)
• Use for action-specific context
• Avoid for user-level attributes
• Can repeat across events with different values
• Useful for "What happened?" analysis

User Scope Best Practices

• Name as attributes (subscription_tier, customer_segment, account_status)
• Use for persistent user characteristics
• Set early in session (after authentication)
• Clear on logout with null
• Never use empty string to clear
• Useful for "Who is this user?" analysis

Item Scope Best Practices

• Use only in items array of ecommerce events
• Name as item properties (item_color, item_size)
• Keep values consistent across items
• Register in Admin as Item scope
• Useful for "What are we selling?" analysis