Initial commit

skills/ga4-debugview/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ga4-debugview
+description: Comprehensive guide to testing and validating GA4 implementation using DebugView, Preview mode, and real-time monitoring. Use when verifying GA4 tracking, troubleshooting events not firing, validating event parameters, testing GTM implementations, checking DebugView data, or debugging implementation issues. Covers enabling debug mode, reading DebugView interface, common validation patterns, and troubleshooting workflows.
+---
+
+# GA4 DebugView Testing and Validation
+
+## Overview
+
+DebugView is GA4's real-time debugging tool for validating implementation, testing events, and troubleshooting tracking issues before data appears in standard reports.
+
+## When to Use This Skill
+
+Invoke this skill when:
+
+- Testing new GA4 implementation or tracking changes
+- Verifying events fire correctly with expected parameters
+- Troubleshooting events not appearing in GA4
+- Validating GTM tag configurations before publishing
+- Checking event parameter values and data types
+- Testing e-commerce tracking implementation
+- Debugging duplicate or missing events
+- Verifying custom dimensions and user properties
+- Testing cross-device tracking with User ID
+- Validating consent mode implementation
+- Confirming measurement protocol server-side events
+
+## Core Capabilities
+
+### Enabling DebugView
+
+**Method 1: Browser Extension (Recommended)**
+
+1. Install **Google Analytics Debugger** Chrome extension
+2. Navigate to your website
+3. Events automatically appear in DebugView
+
+**Method 2: URL Parameter**
+
+Add `?debug_mode=true` to URL:
+```
+https://yourwebsite.com?debug_mode=true
+```
+
+**Method 3: gtag.js Configuration**
+
+```javascript
+gtag('config', 'G-XXXXXXXXXX', {
+  'debug_mode': true
+});
+```
+
+**Method 4: GTM Configuration**
+
+In GA4 Configuration tag, add parameter:
+- Parameter: `debug_mode`
+- Value: `true`
+
+### Accessing DebugView
+
+**Steps:**
+1. Open GA4 property
+2. Navigate to **Admin** (bottom-left)
+3. Click **DebugView** (under Property column)
+4. View real-time debug events
+
+**Requirements:**
+- Debug mode enabled on website
+- Events sent within last 30 minutes
+- Active user session
+
+### DebugView Interface
+
+**Main Sections:**
+
+**1. Device Stream (Left Panel)**
+- Shows active debug sessions
+- Displays device type and identifier
+- Lists user_pseudo_id or user_id
+- Shows session timing
+
+**2. Event Stream (Center Panel)**
+- Real-time event list
+- Event names and timestamps
+- Event count per event type
+- Event selection for details
+
+**3. Event Details (Right Panel)**
+- Selected event parameters
+- User properties
+- Event timestamp
+- Device and session information
+
+### Reading Event Data
+
+**Event Card Shows:**
+- **Event Name:** (e.g., `page_view`, `purchase`, `button_click`)
+- **Timestamp:** When event fired
+- **Event Parameters:** All parameters sent with event
+- **User Properties:** Set at user level
+- **Event Count:** Number of times this event fired in session
+
+**Example Event:**
+```
+Event: purchase
+Timestamp: 14:23:45
+Parameters:
+  transaction_id: "T_12345"
+  value: 99.99
+  currency: "USD"
+  items: [Array with 2 items]
+User Properties:
+  user_tier: "premium"
+```
+
+### Validating Events
+
+**Page View Validation:**
+
+**Expected Events:**
+1. `first_visit` (new users only)
+2. `session_start` (new sessions)
+3. `page_view` (every page)
+
+**Check:**
+- `page_location` parameter (full URL)
+- `page_title` parameter (page title)
+- `page_referrer` (previous page)
+
+**Purchase Event Validation:**
+
+**Required Parameters:**
+- `transaction_id` (unique ID)
+- `value` (number, total revenue)
+- `currency` (3-letter ISO code)
+- `items` (array of products)
+
+**Check:**
+- All parameters present
+- Correct data types (number vs string)
+- Items array structure correct
+- No duplicate transaction_id
+
+**Custom Event Validation:**
+
+**Check:**
+- Event name follows naming conventions (lowercase, underscores)
+- Event name ≤40 characters
+- Event parameters are descriptive
+- Parameter values are correct types
+- Custom parameters appear (not just default)
+
+### Common Validation Patterns
+
+**E-commerce Flow:**
+
+1. **view_item_list** → Items array populated
+2. **select_item** → Item ID and name present
+3. **view_item** → Item details correct
+4. **add_to_cart** → Items, value, currency present
+5. **begin_checkout** → Items and value present
+6. **purchase** → All required parameters, unique transaction_id
+
+**Form Tracking:**
+
+1. User loads page → `page_view`
+2. User starts form → `form_start` (if tracked)
+3. User submits form → `form_submit`
+4. Parameters: `form_name`, `form_id`, `form_destination`
+
+**Video Tracking:**
+
+1. `video_start` → video_title, video_id
+2. `video_progress` → video_percent (25, 50, 75)
+3. `video_complete` → video_percent: 100
+
+### Troubleshooting with DebugView
+
+**Issue: Events Not Appearing**
+
+**Checks:**
+1. Debug mode enabled?
+2. Correct GA4 property selected?
+3. Events sent in last 30 minutes?
+4. Measurement ID correct?
+5. Browser blocking GA4 (ad blockers)?
+
+**Issue: Missing Parameters**
+
+**Checks:**
+1. Parameter name spelled correctly?
+2. Data layer includes parameter?
+3. GTM variable populated?
+4. Parameter value not empty/undefined?
+
+**Issue: Wrong Parameter Values**
+
+**Checks:**
+1. Data type correct (string vs number)?
+2. Variable mapping correct in GTM?
+3. JavaScript providing correct value?
+4. Encoding issues (special characters)?
+
+**Issue: Duplicate Events**
+
+**Checks:**
+1. Multiple tags firing for same event?
+2. Both gtag.js and GTM installed?
+3. Trigger firing multiple times?
+4. Event pushed to data layer twice?
+
+### Testing Workflows
+
+**Workflow 1: New Implementation Test**
+
+1. Enable debug mode
+2. Open DebugView
+3. Load website page
+4. Verify automatic events:
+   - `session_start`
+   - `page_view`
+   - `first_visit` (if new user)
+5. Navigate to second page
+6. Verify `page_view` fires again
+7. Check parameters correct on all events
+
+**Workflow 2: Custom Event Test**
+
+1. Enable debug mode
+2. Open DebugView
+3. Trigger custom event (click button, submit form)
+4. Verify event appears with correct name
+5. Check all expected parameters present
+6. Verify parameter values correct
+7. Check data types (number vs string)
+
+**Workflow 3: E-commerce Test**
+
+1. Enable debug mode
+2. Complete purchase flow
+3. Verify each step fires correct event
+4. Check items array structure:
+   - `item_id` present
+   - `item_name` present
+   - `price` is number
+   - `quantity` is integer
+5. Verify `purchase` event has unique `transaction_id`
+6. Check `value` matches cart total
+
+**Workflow 4: GTM Integration Test**
+
+1. Enable GTM Preview mode
+2. Enable debug mode
+3. Trigger GTM tag
+4. Verify in GTM Preview:
+   - Tag fires
+   - Variables populated
+5. Verify in DebugView:
+   - Event appears
+   - Parameters match GTM
+6. Cross-reference both tools
+
+### User Properties Testing
+
+**Set User Properties:**
+
+```javascript
+gtag('set', 'user_properties', {
+  'user_tier': 'premium',
+  'account_age_days': 365
+});
+```
+
+**Verify in DebugView:**
+1. Click any event in stream
+2. Scroll to **User Properties** section
+3. Verify properties appear:
+   - `user_tier`: "premium"
+   - `account_age_days`: "365"
+4. Check properties persist across events
+
+### Testing Best Practices
+
+**Before Launch:**
+- Test all critical events (purchase, sign_up, etc.)
+- Verify parameters on multiple browsers
+- Test on mobile devices
+- Check events in incognito/private mode
+- Verify with multiple user types (new/returning)
+
+**During Development:**
+- Test each new tag/event immediately
+- Use DebugView alongside GTM Preview
+- Document expected vs actual behavior
+- Share DebugView screenshots with team
+
+**After Launch:**
+- Monitor DebugView for first 30 minutes
+- Check for unexpected duplicate events
+- Verify event volumes match expectations
+- Confirm events appear in standard reports (24-48 hours)
+
+## Integration with Other Skills
+
+- **ga4-setup** - Initial property setup before testing
+- **ga4-gtag-implementation** - Testing gtag.js implementation
+- **ga4-gtm-integration** - Testing GTM implementation (use Preview + DebugView together)
+- **ga4-recommended-events** - Validating recommended event structures
+- **ga4-custom-events** - Testing custom event implementations
+- **ga4-measurement-protocol** - Validating server-side events
+- **ga4-user-tracking** - Testing User ID and user properties
+- **ga4-privacy-compliance** - Verifying consent mode implementation
+
+## References
+
+- **references/debugview-interface-complete.md** - Detailed DebugView UI walkthrough
+- **references/validation-checklists.md** - Event-specific validation checklists
+- **references/troubleshooting-guide.md** - Common issues and solutions
+- **references/testing-workflows.md** - Step-by-step testing procedures
+- **references/ecommerce-validation.md** - E-commerce event testing guide
+
+## Quick Reference
+
+**Enable Debug Mode:**
+- Chrome extension: Google Analytics Debugger (easiest)
+- URL parameter: `?debug_mode=true`
+- gtag.js: `debug_mode: true`
+- GTM: Add debug_mode parameter to Configuration tag
+
+**Access DebugView:**
+Admin → DebugView
+
+**Key Checks:**
+- Event names ≤40 characters, lowercase, underscores
+- Required parameters present
+- Correct data types (string, number, array)
+- No PII in parameters
+- Unique transaction_id for purchases
+- Items array properly formatted for e-commerce

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

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