Initial commit
This commit is contained in:
Zhongwei Li
538
skills/ga4-custom-dimensions/references/scopes-complete-guide.md
Normal file
538
skills/ga4-custom-dimensions/references/scopes-complete-guide.md
Normal file
@@ -0,0 +1,538 @@
|
||||
# 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:**
|
||||
|
||||
```javascript
|
||||
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:**
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// WRONG: Event scope for user property
|
||||
gtag('event', 'page_view', {
|
||||
'subscription_tier': 'premium' // Should be user scope!
|
||||
});
|
||||
```
|
||||
|
||||
**Correct:** Use user scope for persistent attributes
|
||||
|
||||
```javascript
|
||||
gtag('set', {
|
||||
'subscription_tier': 'premium' // User scope - persists
|
||||
});
|
||||
```
|
||||
|
||||
**Mistake 2:** Sending same event-scoped dimension with every event
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
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:**
|
||||
|
||||
```javascript
|
||||
// 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:
|
||||
|
||||
```javascript
|
||||
// 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:**
|
||||
|
||||
```javascript
|
||||
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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
```javascript
|
||||
// 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
|
||||
|
||||
Reference in New Issue
Block a user