Initial commit

2025-11-29 18:32:40 +08:00
commit 0ea8352871
72 changed files with 30043 additions and 0 deletions
--- a/skills/ga4-debugview/references/debugview-complete-guide.md
+++ b/skills/ga4-debugview/references/debugview-complete-guide.md
@@ -0,0 +1,434 @@
+# Complete DebugView Guide
+
+## Enabling Debug Mode
+
+### Method 1: Google Analytics Debugger Extension (Recommended)
+
+**Installation:**
+1. Open Chrome Web Store
+2. Search "Google Analytics Debugger"
+3. Install extension
+4. Click extension icon to enable (icon turns blue)
+5. Reload website
+
+**Benefits:**
+- Easiest method
+- Works immediately
+- No code changes needed
+- Toggle on/off easily
+
+### Method 2: URL Parameter
+
+Add `?debug_mode=true` to any URL:
+```
+https://example.com/products?debug_mode=true
+```
+
+**Limitations:**
+- Only debugs pages with parameter
+- Lost on navigation (unless preserved)
+- Must add to each test URL
+
+### Method 3: gtag.js Code
+
+Add to gtag.js configuration:
+```javascript
+gtag('config', 'G-XXXXXXXXXX', {
+  'debug_mode': true
+});
+```
+
+**Important:** Remove before production!
+
+### Method 4: Google Tag Manager
+
+In GA4 Configuration tag:
+1. Expand **Configuration Settings**
+2. Add parameter:
+   - Name: `debug_mode`
+   - Value: `true`
+
+**OR** use conditional debug mode:
+```
+debug_mode: {{Debug Mode Variable}}
+```
+Create variable that returns `true` in test environments only.
+
+## DebugView Interface
+
+### Main Components
+
+**1. Device Stream (Left Sidebar)**
+
+Shows active debug sessions:
+- **Device icon:** Desktop/Mobile/Tablet
+- **User identifier:** user_pseudo_id or user_id
+- **Session timing:** How long ago session started
+- **Event count:** Total events in session
+
+**Click device** to see its event stream.
+
+**2. Event Stream (Center Panel)**
+
+Lists all events chronologically:
+- **Event name:** (e.g., page_view, purchase)
+- **Timestamp:** When event fired
+- **Event icon:** Visual indicator by type
+- **Event count badge:** Times this event fired
+
+**Color coding:**
+- Blue: Standard events
+- Purple: E-commerce events
+- Orange: Custom events
+
+**3. Event Details (Right Panel)**
+
+**When event selected, shows:**
+
+**Event Parameters:**
+- All parameters sent with event
+- Parameter names and values
+- Data types indicated
+
+**User Properties:**
+- Properties set at user level
+- Persist across events
+- Show value and set time
+
+**Device & Geo:**
+- Device category, brand, model
+- Operating system, browser
+- Country, region, city
+
+**Event Context:**
+- Event timestamp (precise)
+- Session ID
+- Event count in session
+
+## Interpreting Events
+
+### Automatic Events
+
+**session_start**
+- Fires: First event in new session
+- Parameters:
+  - `session_id`: Unique session identifier
+  - `ga_session_id`: Session timestamp
+  - `engagement_time_msec`: 0 (initial)
+
+**first_visit**
+- Fires: Only for brand new users
+- Indicates: First time user visits site
+- Parameters: Basic device/geo info
+
+**page_view**
+- Fires: Every page load (automatic with GA4 config)
+- Parameters:
+  - `page_location`: Full URL
+  - `page_referrer`: Previous page URL
+  - `page_title`: Document title
+  - `engagement_time_msec`: Engagement time
+
+**user_engagement**
+- Fires: When user actively engages (1 second foreground)
+- Parameters:
+  - `engagement_time_msec`: Total engagement time
+
+### Recommended Events
+
+**purchase**
+
+**Required Parameters:**
+- `transaction_id`: Unique order ID
+- `value`: Total revenue (number)
+- `currency`: 3-letter ISO code
+- `items`: Array of purchased items
+
+**Optional Parameters:**
+- `tax`: Tax amount
+- `shipping`: Shipping cost
+- `coupon`: Coupon code used
+
+**Item Structure (in items array):**
+```javascript
+{
+  "item_id": "SKU_123",
+  "item_name": "Blue T-Shirt",
+  "price": 29.99,
+  "quantity": 1,
+  "item_category": "Apparel",
+  "item_brand": "MyBrand"
+}
+```
+
+**add_to_cart**
+
+**Required:**
+- `currency`: "USD", "EUR", etc.
+- `value`: Item value
+- `items`: Array with item details
+
+**begin_checkout**
+
+**Required:**
+- `currency`: Currency code
+- `value`: Cart total
+- `items`: Items array
+
+### Custom Events
+
+**Identification:**
+- Event name not in Google's recommended list
+- Typically follows business-specific naming
+- Should use snake_case convention
+
+**Validation:**
+- Name ≤40 characters
+- Lowercase with underscores
+- Descriptive parameters
+- Correct data types
+
+## Validation Checklists
+
+### Page View Validation
+
+- [ ] `page_view` fires on every page load
+- [ ] `page_location` contains full URL
+- [ ] `page_title` matches document.title
+- [ ] `page_referrer` shows previous page (if applicable)
+- [ ] `engagement_time_msec` increases over time
+
+### E-commerce Validation
+
+**For purchase Event:**
+- [ ] `transaction_id` is unique string
+- [ ] `value` is number (not string "99.99")
+- [ ] `currency` is 3-letter code (USD, EUR, GBP)
+- [ ] `items` is array (not empty)
+- [ ] Each item has `item_id` and `item_name`
+- [ ] Item `price` is number
+- [ ] Item `quantity` is integer
+- [ ] Total matches sum of items
+- [ ] No duplicate `transaction_id` in session
+
+**For add_to_cart Event:**
+- [ ] Fires when user adds item
+- [ ] `items` array populated correctly
+- [ ] `value` and `currency` present
+- [ ] Item details match product added
+
+### User Properties Validation
+
+- [ ] Properties appear in User Properties section
+- [ ] Properties persist across multiple events
+- [ ] Property values correct type
+- [ ] No PII (email, name, address)
+- [ ] Custom properties prefixed appropriately
+
+### Custom Dimensions Validation
+
+- [ ] Custom dimensions appear as event parameters
+- [ ] Values populate correctly
+- [ ] Data type matches configuration in GA4
+- [ ] Dimension name matches Admin setup exactly (case-sensitive)
+
+## Troubleshooting
+
+### Events Not Appearing in DebugView
+
+**Checklist:**
+1. **Debug mode enabled?**
+   - Chrome extension active (icon blue)
+   - URL has `?debug_mode=true`
+   - gtag debug_mode set to true
+
+2. **Correct property selected?**
+   - Check property ID in top-left dropdown
+   - Verify Measurement ID in code matches
+
+3. **Events recent?**
+   - DebugView shows last 30 minutes only
+   - Reload page to send new events
+
+4. **Tracking blocked?**
+   - Disable ad blockers
+   - Check browser privacy settings
+   - Try incognito mode
+
+5. **Implementation correct?**
+   - Measurement ID format: G-XXXXXXXXXX
+   - gtag.js or GTM installed correctly
+   - No JavaScript errors blocking execution
+
+### Missing Event Parameters
+
+**Causes & Solutions:**
+
+**Cause:** Parameter not sent from code
+- **Solution:** Check dataLayer push includes parameter
+- **Solution:** Verify GTM variable populated
+
+**Cause:** Variable undefined in GTM
+- **Solution:** Check Data Layer Variable configuration
+- **Solution:** Verify data layer key spelling (case-sensitive)
+
+**Cause:** Parameter name typo
+- **Solution:** Check parameter name matches exactly
+- **Solution:** Use consistent naming (snake_case)
+
+**Cause:** Empty value filtered out
+- **Solution:** Ensure variable has value before event fires
+- **Solution:** Set default value if appropriate
+
+### Wrong Data Types
+
+**Issue:** String instead of number
+
+**Example:**
+```javascript
+// WRONG
+'value': '99.99'  // String
+
+// CORRECT
+'value': 99.99    // Number
+```
+
+**Detection in DebugView:**
+- Parameter value appears in quotes: "99.99" (string)
+- No quotes: 99.99 (number)
+
+**Fix:**
+- Use `parseInt()` or `parseFloat()` in JavaScript
+- Remove quotes from literal values
+- Check GTM variable format
+
+### Duplicate Events
+
+**Causes:**
+
+1. **Multiple tags firing**
+   - Check GTM for duplicate tags
+   - Review trigger conditions
+
+2. **Both gtag.js and GTM**
+   - Remove gtag.js if using GTM
+   - Use only one implementation method
+
+3. **Trigger firing multiple times**
+   - Check trigger limits in GTM
+   - Use "Once per Event" firing option
+
+4. **Multiple dataLayer pushes**
+   - Review JavaScript for duplicate push calls
+   - Check SPA route change handling
+
+## Testing Workflows
+
+### Complete Implementation Test
+
+**Steps:**
+
+1. **Enable debug mode** (Chrome extension)
+2. **Open DebugView** (GA4 Admin → DebugView)
+3. **Clear browser cache and cookies**
+4. **Open website in incognito/private mode**
+5. **Verify first-time user events:**
+   - `first_visit` fires
+   - `session_start` fires
+   - `page_view` fires
+   - All parameters present
+
+6. **Navigate to second page**
+   - `page_view` fires
+   - `page_referrer` shows previous page
+   - Session ID consistent
+
+7. **Test custom events**
+   - Trigger each custom event
+   - Verify event name correct
+   - Check all parameters present
+   - Validate parameter values
+
+8. **Test e-commerce flow (if applicable)**
+   - View product → `view_item`
+   - Add to cart → `add_to_cart`
+   - Begin checkout → `begin_checkout`
+   - Complete purchase → `purchase`
+   - Verify all required parameters
+
+9. **Check user properties**
+   - Set user properties (if implemented)
+   - Verify in User Properties section
+   - Confirm persistence across events
+
+10. **Test on mobile device**
+    - Repeat key tests on mobile
+    - Verify device_category: "mobile"
+
+### GTM + DebugView Combined Testing
+
+**Workflow:**
+
+1. **Enable GTM Preview mode**
+2. **Enable debug mode**
+3. **Open both:**
+   - GTM Tag Assistant (connected to site)
+   - GA4 DebugView (separate tab)
+
+4. **For each event:**
+   - **In GTM:** Verify tag fires, variables populate
+   - **In DebugView:** Verify event appears with parameters
+   - **Cross-check:** Parameters match between GTM and GA4
+
+5. **Troubleshoot discrepancies:**
+   - If tag fires in GTM but not in DebugView: Check Measurement ID
+   - If parameters missing: Check GTM variable mapping
+   - If wrong values: Check variable configuration
+
+## Best Practices
+
+**During Development:**
+- Test every new event immediately after implementation
+- Use DebugView constantly while building
+- Document expected vs actual behavior
+- Take screenshots for team review
+
+**Before Launch:**
+- Complete full implementation test
+- Test on multiple browsers (Chrome, Firefox, Safari)
+- Test on mobile and desktop
+- Test with ad blockers disabled and enabled
+- Verify critical e-commerce events thoroughly
+
+**After Launch:**
+- Monitor DebugView for first 30-60 minutes
+- Check for unexpected events or duplicates
+- Verify event volumes roughly match expectations
+- Confirm events appear in standard reports (wait 24-48 hours)
+
+**Regular Maintenance:**
+- Test after any website changes
+- Verify after GTM container updates
+- Check during CMS/platform upgrades
+- Test new features before launch
+
+## Advanced Tips
+
+**Testing Consent Mode:**
+1. Set consent to denied
+2. Verify events fire with consent status
+3. Check `ad_storage` and `analytics_storage` parameters
+4. Update consent to granted
+5. Verify parameters update
+
+**Testing User ID:**
+1. Implement User ID for logged-in users
+2. Verify `user_id` appears in event details
+3. Check persistence across sessions
+4. Test logout (user_id should clear)
+
+**Testing Server-Side Events:**
+1. Send event via Measurement Protocol
+2. Check DebugView for event appearance
+3. Verify parameters match API payload
+4. Confirm `client_id` consistency
--- a/skills/ga4-debugview/references/ecommerce-testing.md
+++ b/skills/ga4-debugview/references/ecommerce-testing.md
@@ -0,0 +1,288 @@
+# E-commerce Event Testing in DebugView
+
+## Complete E-commerce Flow
+
+### 1. view_item_list
+
+**Fires:** Product listing page loads
+
+**Required Parameters:**
+- `item_list_id`: "related_products", "search_results"
+- `item_list_name`: "Related Products", "Search Results"
+- `items`: Array of products shown
+
+**Validation:**
+- [ ] Items array populated
+- [ ] Each item has item_id and item_name
+- [ ] item_list_id and item_list_name present
+
+### 2. select_item
+
+**Fires:** User clicks product from list
+
+**Required Parameters:**
+- `item_list_id`: Same as view_item_list
+- `item_list_name`: Same as view_item_list
+- `items`: Array with selected item
+
+**Validation:**
+- [ ] Only selected item in items array
+- [ ] item_list matches where user clicked from
+
+### 3. view_item
+
+**Fires:** Product detail page loads
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Product price
+- `items`: Array with single product
+
+**Validation:**
+- [ ] currency present
+- [ ] value is number
+- [ ] items[0] contains full product details
+
+### 4. add_to_cart
+
+**Fires:** User adds item to cart
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Item total (price × quantity)
+- `items`: Array with added item(s)
+
+**Validation:**
+- [ ] value = price × quantity
+- [ ] currency matches site currency
+- [ ] items array has correct item
+- [ ] quantity is integer
+
+### 5. remove_from_cart (Optional)
+
+**Fires:** User removes item from cart
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Removed item value
+- `items`: Array with removed item
+
+### 6. view_cart (Optional)
+
+**Fires:** Cart page loads
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Total cart value
+- `items`: All items in cart
+
+### 7. begin_checkout
+
+**Fires:** Checkout process starts
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Cart total
+- `items`: All items in cart
+- `coupon` (if applicable)
+
+**Validation:**
+- [ ] value matches cart total
+- [ ] All cart items in items array
+- [ ] coupon code if applied
+
+### 8. add_payment_info (Optional)
+
+**Fires:** Payment method added
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Transaction value
+- `payment_type`: "credit_card", "paypal", etc.
+
+### 9. add_shipping_info (Optional)
+
+**Fires:** Shipping info added
+
+**Required Parameters:**
+- `currency`: "USD"
+- `value`: Transaction value
+- `shipping_tier`: "Ground", "Express", etc.
+
+### 10. purchase
+
+**Fires:** Transaction completes
+
+**Required Parameters:**
+- `transaction_id`: UNIQUE order ID
+- `currency`: "USD"
+- `value`: Total revenue
+- `items`: All purchased items
+
+**Optional Parameters:**
+- `tax`: Tax amount
+- `shipping`: Shipping cost
+- `coupon`: Coupon code
+- `affiliation`: Store name
+
+**Validation:**
+- [ ] transaction_id is unique (never reused)
+- [ ] value is total (items + tax + shipping - discounts)
+- [ ] All items have complete details
+- [ ] tax and shipping are numbers
+- [ ] No duplicate purchase events
+
+### 11. refund (Optional)
+
+**Fires:** Transaction refunded
+
+**Required Parameters:**
+- `transaction_id`: Original order ID
+- `currency`: "USD"
+- `value`: Refund amount
+
+## Items Array Structure
+
+**Complete Item Object:**
+
+```javascript
+{
+  "item_id": "SKU_12345",           // Required
+  "item_name": "Blue T-Shirt",      // Required
+  "affiliation": "Online Store",
+  "coupon": "SUMMER20",
+  "currency": "USD",
+  "discount": 2.00,
+  "index": 0,                        // Position in list
+  "item_brand": "MyBrand",
+  "item_category": "Apparel",
+  "item_category2": "Men",
+  "item_category3": "Shirts",
+  "item_category4": "T-Shirts",
+  "item_category5": "Short Sleeve",
+  "item_list_id": "related_products",
+  "item_list_name": "Related Products",
+  "item_variant": "Blue",
+  "location_id": "Warehouse_A",
+  "price": 29.99,                    // Required for most events
+  "quantity": 2                      // Required for cart/purchase events
+}
+```
+
+## Testing Purchase Event
+
+**Complete Test:**
+
+1. **Add items to cart** → Verify `add_to_cart` for each
+2. **Go to checkout** → Verify `begin_checkout`
+3. **Complete purchase** → Verify `purchase`
+
+**Purchase Event Checklist:**
+
+- [ ] Event name: `purchase`
+- [ ] `transaction_id` present and unique
+- [ ] `value` is number (not string)
+- [ ] `currency` is 3-letter code
+- [ ] `items` array not empty
+- [ ] Each item has `item_id`
+- [ ] Each item has `item_name`
+- [ ] Each item has `price` (number)
+- [ ] Each item has `quantity` (integer)
+- [ ] Optional: `tax` is number
+- [ ] Optional: `shipping` is number
+- [ ] Optional: `coupon` is string
+- [ ] No duplicate `transaction_id` in DebugView session
+
+**Common Issues:**
+
+**Issue:** Items array empty
+- **Cause:** Items not passed to event
+- **Fix:** Ensure dataLayer.push includes ecommerce.items
+
+**Issue:** Value is string "99.99"
+- **Cause:** Quotes around number
+- **Fix:** Remove quotes: `value: 99.99`
+
+**Issue:** transaction_id repeats
+- **Cause:** Page reload after purchase, or testing with same ID
+- **Fix:** Generate unique IDs, prevent double-submit
+
+**Issue:** Item missing price
+- **Cause:** Incomplete item object
+- **Fix:** Include price in every item object
+
+## Calculating Value
+
+**Formula:**
+```
+value = (sum of item prices × quantities) + tax + shipping - discount
+```
+
+**Example:**
+```javascript
+Item 1: $29.99 × 2 = $59.98
+Item 2: $19.99 × 1 = $19.99
+Subtotal: $79.97
+Tax: $6.40
+Shipping: $5.00
+Discount: -$10.00
+Total value: $81.37
+```
+
+**In DebugView:**
+```
+purchase event:
+  value: 81.37
+  currency: "USD"
+  tax: 6.40
+  shipping: 5.00
+  items: [item1, item2]
+```
+
+## Multi-Step Checkout Validation
+
+**Step 1: Cart Page**
+- `view_cart` event
+- Items match current cart
+- Value correct
+
+**Step 2: Shipping Info**
+- `add_shipping_info` event
+- shipping_tier parameter
+- Value includes shipping
+
+**Step 3: Payment Info**
+- `add_payment_info` event
+- payment_type parameter
+- Value matches total
+
+**Step 4: Review Order**
+- No specific event (or custom event)
+- Final verification before purchase
+
+**Step 5: Purchase Complete**
+- `purchase` event
+- Unique transaction_id
+- All parameters correct
+- Confirmation page loads
+
+## Testing with Test Transactions
+
+**Using GTM Preview + DebugView:**
+
+1. Enable GTM Preview mode
+2. Enable DebugView
+3. Add test product to cart
+4. Complete checkout with test payment
+5. Verify each event in real-time:
+   - **GTM Tag Assistant:** Tags fire
+   - **DebugView:** Events appear
+6. Cross-check parameters match
+7. Verify transaction_id is unique
+8. Test refund event (if implemented)
+
+**Best Practice:**
+- Use test payment gateway in development
+- Generate unique transaction_ids for each test
+- Document test transaction IDs
+- Clean up test data if it reaches production