Initial commit

2025-11-29 18:32:40 +08:00
commit 0ea8352871
72 changed files with 30043 additions and 0 deletions
--- a/skills/ga4-events-fundamentals/references/event-parameters-guide.md
+++ b/skills/ga4-events-fundamentals/references/event-parameters-guide.md
@@ -0,0 +1,660 @@
+# Event Parameters Complete Guide
+
+## Overview
+
+Event parameters provide context and detail about user interactions in GA4. Understanding parameter structure, limits, and best practices is essential for effective event tracking.
+
+## What Are Event Parameters?
+
+**Definition:** Additional data points attached to events that provide context about user actions.
+
+**Structure:**
+```javascript
+gtag('event', 'event_name', {
+  'parameter_name_1': 'value',
+  'parameter_name_2': 123,
+  'parameter_name_3': true
+});
+```
+
+## Parameter Types
+
+### 1. Automatically Collected Parameters
+
+Parameters GA4 collects without additional configuration.
+
+#### Web Stream Standard Parameters
+
+**Page Parameters:**
+- `page_location` - Full page URL (max 1000 chars)
+- `page_referrer` - Previous page URL (max 420 chars)
+- `page_title` - Page title from `<title>` tag (max 300 chars)
+
+**User/Device Parameters:**
+- `language` - Browser language (e.g., en-us)
+- `screen_resolution` - Device screen size (e.g., 1920x1080)
+- `client_id` - Anonymous user identifier
+
+**Engagement Parameters:**
+- `engagement_time_msec` - Time engaged in milliseconds
+- `session_id` - Current session identifier
+- `session_number` - Count of sessions for user
+
+#### App Stream Standard Parameters
+
+- `app_version` - Current application version
+- `firebase_screen_id` - Unique screen identifier
+- `firebase_screen_class` - Screen class name
+- `platform` - iOS or Android
+
+### 2. Enhanced Measurement Parameters
+
+Parameters automatically collected with enhanced measurement events.
+
+#### Scroll Event Parameters
+- `engagement_time_msec` - Time engaged before scroll
+
+#### Click Event Parameters
+- `link_classes` - CSS classes on link
+- `link_domain` - Destination domain
+- `link_id` - Element ID
+- `link_url` - Full destination URL
+- `outbound` - true (for outbound links)
+
+#### File Download Parameters
+- `file_extension` - File type (.pdf, .xlsx)
+- `file_name` - Name of file
+- `link_classes` - CSS classes
+- `link_id` - Element ID
+- `link_text` - Link text
+- `link_url` - Download URL
+
+#### Video Engagement Parameters
+- `video_title` - YouTube video title
+- `video_url` - YouTube video URL
+- `video_duration` - Total length (seconds)
+- `video_current_time` - Playback position
+- `video_percent` - Milestone reached (10, 25, 50, 75)
+- `video_provider` - youtube.com
+- `visible` - Viewport visibility (true/false)
+
+#### Form Interaction Parameters
+- `form_id` - HTML form ID
+- `form_name` - HTML form name
+- `form_destination` - Form action URL
+- `form_submit_text` - Submit button text
+
+#### Search Parameters
+- `search_term` - User's search query
+- `unique_search_term` - First occurrence flag
+
+### 3. Recommended Event Parameters
+
+Standardized parameters for Google-defined recommended events.
+
+#### Authentication Parameters
+
+**login event:**
+- `method` - Authentication method (email, google, facebook, phone)
+
+**sign_up event:**
+- `method` - Registration method (email, google, facebook)
+
+#### Ecommerce Parameters
+
+**Required for purchase event:**
+- `transaction_id` - Unique transaction identifier (CRITICAL - must be unique)
+- `value` - Total transaction value (numeric)
+- `currency` - ISO 4217 currency code (USD, EUR, GBP)
+
+**Recommended for purchase:**
+- `tax` - Tax amount (numeric)
+- `shipping` - Shipping cost (numeric)
+- `items` - Array of product objects (see Items Array section)
+- `coupon` - Coupon code applied (string)
+- `affiliation` - Store/affiliate name (string)
+
+**Item-level parameters (in items array):**
+- `item_id` - Product SKU/ID
+- `item_name` - Product name
+- `price` - Unit price
+- `quantity` - Number of units
+- `item_category` - Primary category
+- `item_category2` through `item_category5` - Hierarchical categories
+- `item_brand` - Brand name
+- `item_variant` - Size, color, variant
+- `coupon` - Item-level coupon
+- `discount` - Discount amount
+- `affiliation` - Store name
+- `index` - Position in list (0-based)
+- `item_list_id` - List identifier
+- `item_list_name` - List name
+- `location_id` - Physical location ID
+
+#### Search Parameters
+- `search_term` - User's search query
+
+#### Content Selection Parameters
+- `content_type` - Type of content (article, video, product)
+- `item_id` - Content identifier
+
+#### Promotion Parameters
+- `promotion_id` - Promotion identifier
+- `promotion_name` - Promotion name
+- `creative_name` - Creative asset name
+- `creative_slot` - Position (banner_slot_1)
+
+### 4. Custom Parameters
+
+Business-specific parameters created for custom events.
+
+**Examples:**
+
+```javascript
+// Video tutorial tracking
+gtag('event', 'video_tutorial_watched', {
+  'tutorial_id': 'VID_123',
+  'tutorial_name': 'GA4 Basics',
+  'tutorial_duration': 1200,  // seconds
+  'completion_percent': 100,
+  'difficulty_level': 'beginner',
+  'language': 'en'
+});
+
+// SaaS feature usage
+gtag('event', 'feature_activated', {
+  'feature_name': 'advanced_reporting',
+  'feature_tier': 'enterprise',
+  'activation_source': 'settings_page',
+  'first_time_use': true
+});
+
+// E-learning course
+gtag('event', 'course_enrollment', {
+  'course_id': 'COURSE_101',
+  'course_name': 'Advanced Analytics',
+  'instructor': 'John Doe',
+  'price': 99.99,
+  'currency': 'USD',
+  'level': 'advanced',
+  'enrollment_method': 'direct'
+});
+```
+
+## Parameter Limits and Constraints
+
+### Critical Limits
+
+| Limit Type | Standard GA4 | GA4 360 |
+|------------|-------------|---------|
+| Parameters per event | 25 | 25 |
+| Event-scoped custom dimensions | 50 | 125 |
+| User-scoped custom dimensions | 25 | 100 |
+| Item-scoped custom dimensions | 10 | 25 |
+
+### Character Limits
+
+| Element | Maximum Characters |
+|---------|-------------------|
+| Parameter name | 40 |
+| Parameter value (standard) | 100 |
+| `page_title` parameter | 300 |
+| `page_referrer` parameter | 420 |
+| `page_location` parameter | 1000 |
+
+### Data Type Constraints
+
+**Supported Types:**
+- String (text)
+- Number (integer or float)
+- Boolean (true/false)
+- Array (for items parameter)
+
+**Not Supported:**
+- Objects (except items array)
+- Nested objects
+- Functions
+- Null values (use for clearing only)
+
+## Parameter Naming Conventions
+
+### Best Practices
+
+**DO:**
+- Use snake_case (lowercase with underscores)
+- Be descriptive but concise
+- Use consistent naming across events
+- Keep under 40 characters
+
+**DON'T:**
+- Use spaces or special characters
+- Use camelCase or PascalCase
+- Use generic names (param1, value, data)
+- Include personally identifiable information (PII)
+
+### Naming Patterns
+
+**Recommended Patterns:**
+
+```
+[object]_[attribute]
+Examples: product_id, user_tier, video_duration
+
+[action]_[attribute]
+Examples: purchase_value, scroll_depth, form_name
+
+[category]_[subcategory]_[attribute]
+Examples: ecommerce_item_price, video_completion_percent
+```
+
+### Reserved Parameter Names
+
+GA4 reserves certain parameter names. Avoid using these for custom parameters:
+
+- `client_id`
+- `session_id`
+- `session_number`
+- `page_location`
+- `page_referrer`
+- `page_title`
+- `language`
+- `screen_resolution`
+- All recommended event parameter names (transaction_id, value, currency, etc.)
+
+## Items Array Structure
+
+### Overview
+
+The `items` parameter is a special array structure for ecommerce events containing product information.
+
+### Required Fields
+
+At minimum, each item must have:
+- `item_id` OR `item_name` (at least one required)
+
+### Complete Item Object
+
+```javascript
+{
+  // Required (at least one)
+  'item_id': 'SKU_12345',
+  'item_name': 'Stan and Friends Tee',
+
+  // Highly Recommended
+  'price': 10.01,
+  'quantity': 3,
+  'item_category': 'Apparel',
+
+  // Optional but Useful
+  'item_brand': 'Google',
+  'item_variant': 'green',
+  'item_category2': 'Adult',
+  'item_category3': 'Shirts',
+  'item_category4': 'Crew',
+  'item_category5': 'Short sleeve',
+
+  // Ecommerce Context
+  'affiliation': 'Google Merchandise Store',
+  'coupon': 'SUMMER_FUN',
+  'discount': 2.22,
+  'index': 0,
+  'item_list_id': 'related_products',
+  'item_list_name': 'Related Products',
+  'location_id': 'L_12345',
+
+  // Custom Item Parameters
+  'item_color': 'green',
+  'item_size': 'large',
+  'supplier': 'Vendor_A'
+}
+```
+
+### Items Array Limits
+
+- Maximum 27 items per event
+- Maximum 10 item-scoped custom dimensions per property (standard GA4)
+- Maximum 25 item-scoped custom dimensions per property (GA4 360)
+
+### Items Array Example
+
+```javascript
+gtag('event', 'purchase', {
+  'transaction_id': 'TXN_12345',
+  'value': 142.52,
+  'currency': 'USD',
+  'items': [
+    {
+      'item_id': 'SKU_001',
+      'item_name': 'Product A',
+      'price': 49.99,
+      'quantity': 2,
+      'item_category': 'Electronics'
+    },
+    {
+      'item_id': 'SKU_002',
+      'item_name': 'Product B',
+      'price': 29.99,
+      'quantity': 1,
+      'item_category': 'Accessories'
+    }
+  ]
+});
+```
+
+## Parameter Value Formatting
+
+### Currency Values
+
+**Format:** Numeric (not string)
+
+```javascript
+// ✅ CORRECT
+'value': 99.99,
+'currency': 'USD'
+
+// ❌ WRONG
+'value': '$99.99',
+'currency': '$'
+```
+
+**ISO 4217 Currency Codes:**
+- USD - US Dollar
+- EUR - Euro
+- GBP - British Pound
+- JPY - Japanese Yen
+- CAD - Canadian Dollar
+- AUD - Australian Dollar
+- CHF - Swiss Franc
+
+### Boolean Values
+
+**Format:** true/false (not string)
+
+```javascript
+// ✅ CORRECT
+'first_time_user': true,
+'promotional_email_opt_in': false
+
+// ❌ WRONG
+'first_time_user': 'true',
+'promotional_email_opt_in': 'false'
+```
+
+### Numeric Values
+
+**Format:** Number (integer or float)
+
+```javascript
+// ✅ CORRECT
+'quantity': 5,
+'duration_seconds': 120,
+'rating': 4.5
+
+// ❌ WRONG
+'quantity': '5',
+'duration_seconds': '120',
+'rating': '4.5'
+```
+
+### String Values
+
+**Format:** Text within character limits
+
+```javascript
+// ✅ CORRECT
+'product_name': 'Blue Widget',
+'category': 'Widgets',
+'description': 'High-quality blue widget'
+
+// ⚠️ WARNING - Will be truncated
+'very_long_description': 'This is an extremely long description that exceeds the 100 character limit and will be truncated in GA4 reports which may cause data loss'
+```
+
+## Parameter Scopes
+
+Parameters have different scopes determining their application. See **references/parameter-scopes.md** for complete details.
+
+### Quick Reference
+
+**Event Scope:**
+Applies to single event occurrence.
+Example: `button_name`, `form_id`, `video_title`
+
+**User Scope:**
+Applies to all events from user across sessions.
+Example: `subscription_tier`, `customer_segment`, `account_type`
+
+**Item Scope:**
+Applies to products in ecommerce items array.
+Example: `item_color`, `item_size`, `supplier_name`
+
+## Registering Parameters as Custom Dimensions
+
+### Why Register
+
+Custom parameters won't appear in GA4 reports until registered as custom dimensions.
+
+### Registration Process
+
+1. **Send Parameter in Event:**
+```javascript
+gtag('event', 'video_watched', {
+  'video_quality': 'hd',  // Custom parameter
+  'video_duration': 300
+});
+```
+
+2. **Navigate to GA4 Admin:**
+Admin → Data Display → Custom Definitions
+
+3. **Create Custom Dimension:**
+- Dimension Name: "Video Quality"
+- Scope: Event
+- Event Parameter: "video_quality"
+- Description: "Quality setting of watched videos"
+- Click Save
+
+4. **Wait 24-48 Hours:**
+Data will populate in reports after processing delay
+
+### Registration Best Practices
+
+**DO:**
+- Use descriptive dimension names (appear in reports)
+- Match parameter name exactly (case-sensitive)
+- Choose correct scope
+- Plan dimensions before hitting quota limits
+- Document all custom dimensions
+
+**DON'T:**
+- Register high-cardinality parameters (unique IDs, timestamps)
+- Use dimension names with special characters
+- Change scope after creation (not possible)
+- Expect immediate data (24-48hr delay)
+- Register parameters you won't analyze
+
+## Common Parameter Mistakes
+
+### 1. Missing Currency Parameter
+
+```javascript
+// ❌ WRONG - Missing currency
+gtag('event', 'purchase', {
+  'transaction_id': 'TXN_123',
+  'value': 99.99
+});
+
+// ✅ CORRECT
+gtag('event', 'purchase', {
+  'transaction_id': 'TXN_123',
+  'value': 99.99,
+  'currency': 'USD'
+});
+```
+
+### 2. Using Currency Symbols
+
+```javascript
+// ❌ WRONG - Currency symbol
+'currency': '$'
+
+// ✅ CORRECT - ISO code
+'currency': 'USD'
+```
+
+### 3. Exceeding Parameter Limit
+
+```javascript
+// ❌ WRONG - 30 parameters (exceeds 25 limit)
+gtag('event', 'custom_event', {
+  'param_1': 'value1',
+  'param_2': 'value2',
+  // ... 28 more parameters
+  'param_30': 'value30'  // This won't be collected
+});
+```
+
+### 4. Parameter Name Too Long
+
+```javascript
+// ❌ WRONG - 52 characters
+'this_is_a_very_long_parameter_name_that_exceeds_limit': 'value'
+
+// ✅ CORRECT - 28 characters
+'descriptive_param_name': 'value'
+```
+
+### 5. Sending PII
+
+```javascript
+// ❌ WRONG - Contains PII
+gtag('event', 'form_submit', {
+  'user_email': 'john@example.com',
+  'user_phone': '555-1234',
+  'user_name': 'John Doe'
+});
+
+// ✅ CORRECT - No PII
+gtag('event', 'form_submit', {
+  'email_domain': 'example.com',
+  'form_type': 'contact',
+  'form_location': 'footer'
+});
+```
+
+### 6. Wrong Data Types
+
+```javascript
+// ❌ WRONG - Numeric values as strings
+'quantity': '5',
+'price': '99.99',
+'in_stock': 'true'
+
+// ✅ CORRECT - Proper types
+'quantity': 5,
+'price': 99.99,
+'in_stock': true
+```
+
+## Parameter Testing Checklist
+
+Before deploying event parameters:
+
+- [ ] Parameter names follow snake_case convention
+- [ ] Parameter names are under 40 characters
+- [ ] Parameter values are under 100 characters (or applicable limit)
+- [ ] Total parameters per event ≤ 25
+- [ ] Correct data types used (number, string, boolean)
+- [ ] Currency uses ISO codes (not symbols)
+- [ ] No PII included in parameters
+- [ ] Parameters visible in DebugView
+- [ ] Custom parameters registered as custom dimensions (if needed)
+- [ ] Scope correctly assigned (event/user/item)
+- [ ] Documentation created for custom parameters
+
+## Advanced Parameter Patterns
+
+### Conditional Parameters
+
+```javascript
+// Only include parameter if value exists
+const eventParams = {
+  'event_category': 'engagement'
+};
+
+if (couponCode) {
+  eventParams.coupon = couponCode;
+}
+
+if (userTier) {
+  eventParams.user_tier = userTier;
+}
+
+gtag('event', 'purchase', eventParams);
+```
+
+### Dynamic Parameter Values
+
+```javascript
+// Calculate parameter values dynamically
+gtag('event', 'video_complete', {
+  'video_id': videoId,
+  'video_duration': Math.round(duration),
+  'completion_time': Date.now(),
+  'engagement_rate': Math.round((watchedTime / totalTime) * 100)
+});
+```
+
+### Merging Parameter Objects
+
+```javascript
+// Combine multiple parameter sources
+const baseParams = {
+  'event_category': 'ecommerce',
+  'currency': 'USD'
+};
+
+const productParams = {
+  'product_id': 'SKU_123',
+  'product_name': 'Widget',
+  'price': 29.99
+};
+
+gtag('event', 'view_item', {
+  ...baseParams,
+  ...productParams
+});
+```
+
+## Parameter Debugging
+
+### Using DebugView
+
+1. Enable debug mode (Google Analytics Debugger extension)
+2. Navigate to Admin → DebugView
+3. Trigger event
+4. Click event in left panel
+5. Inspect parameters in right panel
+
+**What to Check:**
+- All expected parameters present
+- Parameter names correct (case-sensitive)
+- Parameter values correct type and format
+- No truncation of values
+- Parameters within limits (≤25)
+
+### Common DebugView Issues
+
+| What You See | Problem | Solution |
+|-------------|---------|----------|
+| Parameter missing | Not sent in event | Check event code |
+| Parameter value wrong | Incorrect data source | Verify variable/value |
+| Parameter truncated | Exceeds character limit | Shorten value |
+| Too many parameters | >25 sent | Reduce parameter count |
+| Parameter not in reports | Not registered as dimension | Register in Admin |
+
+## Additional Resources
+
+- Official GA4 Event Parameters: https://support.google.com/analytics/answer/9267735
+- Custom Dimensions Guide: https://support.google.com/analytics/answer/10075209
+- Items Array Reference: https://developers.google.com/analytics/devguides/collection/ga4/ecommerce