Initial commit

2025-11-29 18:32:45 +08:00
commit c02dafae1d
41 changed files with 17283 additions and 0 deletions
--- a/skills/gtm-debugging/SKILL.md
+++ b/skills/gtm-debugging/SKILL.md
@@ -0,0 +1,113 @@
+---
+name: gtm-debugging
+description: Expert guidance for debugging and testing Google Tag Manager implementations using Preview mode, Tag Assistant, debug console, and troubleshooting common issues like tags not firing, undefined variables, or timing problems. Use when debugging GTM, troubleshooting why tags aren't firing, testing GTM configurations, or analyzing GTM issues.
+---
+
+# GTM Debugging & Testing
+
+## Overview
+This skill provides expertise for debugging and testing Google Tag Manager implementations using Preview mode, Tag Assistant, and systematic troubleshooting approaches.
+
+## When to Use This Skill
+Invoke this skill when:
+- Debugging why tags aren't firing
+- Testing GTM implementations
+- Troubleshooting undefined variables
+- Investigating timing or sequencing issues
+- Using GTM Preview mode
+- Working with Tag Assistant
+- Validating GTM configurations
+- Comparing GTM versions
+
+## Preview Mode & Debug Console
+
+### Enable Preview Mode
+1. Open GTM container
+2. Click "Preview" button
+3. Enter your website URL
+4. Debug window opens
+
+### Debug Console Sections
+- **Summary** - All events fired on page
+- **Tags** - Tags fired and not fired
+- **Variables** - All variable values
+- **Data Layer** - Data layer state at each event
+- **Errors** - JavaScript errors and issues
+
+## Common Debugging Workflows
+
+### Debug Tag Not Firing
+1. Enter Preview Mode
+2. Trigger the event
+3. Check "Tags Not Fired" section
+4. Review trigger conditions in Variables tab
+5. Inspect Data Layer
+6. Fix conditions and retest
+
+### Debug Undefined Variable
+1. Find the event where variable is needed
+2. Check Variables tab for the variable
+3. Verify data layer contains the value
+4. Check variable configuration (path, type)
+5. Verify timing (is data available when tag fires?)
+
+### Debug Data Layer Issues
+1. Open Data Layer tab in debug console
+2. Find the event where data should be pushed
+3. Verify data structure matches expectations
+4. Check for typos in variable names
+5. Validate data types (string, number, object)
+
+## Common Issues & Solutions
+
+### Tag Fires on Wrong Pages
+- Check trigger conditions
+- Verify Page URL or Page Path filters
+- Review trigger exceptions
+- Test with different URL patterns
+
+### Variable Returns Undefined
+- Check data layer path (dot notation)
+- Verify timing (pushed before tag fires?)
+- Check for typos in variable names
+- Validate data layer structure
+
+### Tag Fires Multiple Times
+- Check for duplicate triggers
+- Review History Change triggers on SPAs
+- Verify event deduplication
+- Check tag sequencing
+
+### Performance Issues
+- Review number of tags firing
+- Check custom HTML execution time
+- Audit unnecessary triggers
+- See gtm-best-practices skill for optimization
+
+## Tag Assistant
+- Chrome extension for GTM debugging
+- Real-time tag validation
+- HTTP request inspection
+- GA4 event validation
+
+## Testing Checklist
+- [ ] Tags fire on correct pages/events
+- [ ] Variables populate with correct values
+- [ ] No JavaScript errors in console
+- [ ] Data layer pushes correctly
+- [ ] Triggers activate as expected
+- [ ] No duplicate tag fires
+- [ ] Performance is acceptable
+
+## References
+- **references/debugging-testing.md** - Debug console, preview mode, testing workflows
+
+## Integration with Other Skills
+## Integration with Other Skills
+- **gtm-general** - General GTM guidance and concepts
+- **gtm-tags** - Understand tag configuration
+- **gtm-triggers** - Understand trigger setup
+- **gtm-variables** - Understand variable configuration
+- **gtm-datalayer** - Debug data layer implementation
+- **gtm-setup** - Verify container installation
+- **gtm-best-practices** - Testing and optimization best practices
--- a/skills/gtm-debugging/references/debugging-testing.md
+++ b/skills/gtm-debugging/references/debugging-testing.md
@@ -0,0 +1,642 @@
+# Google Tag Manager - Debugging and Testing
+
+**Sources**:
+- https://support.google.com/tagmanager/answer/6107056
+- https://developers.google.com/tag-platform/tag-manager/server-side/debug
+
+**Last Updated**: 2025-01-09
+
+## Overview
+
+Testing and debugging are critical components of any Google Tag Manager implementation. GTM provides comprehensive tools to help you verify that tags fire correctly, triggers activate as expected, and data flows accurately to your analytics platforms.
+
+## Preview Mode
+
+Preview mode (formerly called Debug mode) allows you to test your GTM container configuration before publishing it to production. When enabled, you can browse your website with the unpublished container draft and see exactly how tags behave.
+
+### Enabling Preview Mode
+
+1. **Navigate to GTM** at https://tagmanager.google.com
+2. **Open your container** workspace
+3. **Click "Preview"** in the top right corner
+4. **Tag Assistant launches** in a new tab
+5. **Enter your website URL**
+6. **Optional**: Uncheck "Include debug signal in the URL" if it breaks your site
+7. **Click "Connect"**
+8. **Your website opens** in a new window with "Connected" indicator
+9. **Return to Tag Assistant** and click "Continue"
+
+The debug interface appears, showing detailed information about tag firing, triggers, variables, and the data layer.
+
+### Tag Assistant Companion
+
+Installing the [Tag Assistant Companion Chrome extension](https://chrome.google.com/webstore/detail/tag-assistant-companion/jmekfmbnaedfebfnmakmokmlfpblbfdm) improves the preview experience by opening your website in a new tab instead of a popup window.
+
+### Previewing Older Versions
+
+To test a previously published version:
+
+1. Go to **Versions** in your workspace navigation
+2. Find the version to preview
+3. Click **More Actions** (three dots)
+4. Select **Preview**
+
+## Using the Debug Interface
+
+### Interface Overview
+
+The debug interface consists of several key areas:
+
+- **Summary Panel**: Overview of the current event and tag firing status
+- **Tags Panel**: Lists which tags fired and which didn't
+- **Data Layer Panel**: Shows the data layer state and events
+- **Variables Panel**: Displays variable values for the current event
+- **Errors Panel**: Lists JavaScript errors and tag failures
+
+### Summary View
+
+Shows a timeline of events as you interact with your website:
+
+```
+Container Loaded
+   Page View
+   DOM Ready
+   Window Loaded
+   Click (Button)
+   Custom Event (form_submit)
+```
+
+Click any event to see:
+- Which tags fired
+- Which triggers activated
+- Current data layer state
+- Variable values at that moment
+
+### Tags View
+
+**Tags Fired:**
+- Green indicators show successfully fired tags
+- Red indicators show failed tags
+- Number shows how many times the tag fired
+- Click a tag to see:
+  - Tag configuration
+  - Triggering conditions
+  - Blocking triggers
+  - Execution order
+
+**Tags Not Fired:**
+- Shows tags that didn't fire for this event
+- Click to see why (trigger conditions not met, blocking triggers, etc.)
+
+### Data Layer View
+
+Displays the data layer's state:
+
+```javascript
+{
+  "gtm.start": 1704844800000,
+  "event": "gtm.js",
+  "gtm.uniqueEventId": 1
+}
+```
+
+Shows:
+- All pushes to the data layer
+- Current state of the data layer
+- Event sequence
+- Custom data layer variables
+
+### Variables View
+
+Lists all variables and their current values:
+
+| Variable Name | Value | Type |
+|--------------|-------|------|
+| Page URL | https://example.com/products | Built-in |
+| Page Path | /products | Built-in |
+| Product Name | Blue Widget | Data Layer Variable |
+| User ID | 12345 | Data Layer Variable |
+
+Helps verify:
+- Variables resolve to expected values
+- Data layer variables capture correct data
+- Custom JavaScript variables execute properly
+
+### Errors View
+
+Shows JavaScript errors and tag execution failures:
+
+```
+Tag: GA4 Event - Purchase
+Error: sendBeacon failed - network error
+
+Tag: Facebook Pixel
+Error: fbq is not defined
+```
+
+Critical for identifying:
+- Missing vendor libraries
+- JavaScript syntax errors
+- Network failures
+- Configuration issues
+
+## Sharing Preview Mode
+
+### Share with Colleagues
+
+To let others view your debug session:
+
+1. **In Tag Assistant**, click **More Actions** (three dots)
+2. **Select "Share"**
+3. **Enter your website domain**
+4. **Copy the preview URL**
+5. **Send to colleagues**
+
+The recipient can:
+- Connect to your site in preview mode
+- View the Tag Assistant debug interface
+- See the same container draft you're testing
+
+**Note**: The preview URL is temporary and expires after the debug session ends.
+
+### Share Specific Versions
+
+From the Versions tab:
+
+1. Click **More Actions** on any version
+2. Select **Share Preview**
+3. Enter target website domain
+4. Copy and share the preview URL
+
+## Debugging Common Scenarios
+
+### Tag Not Firing
+
+**Checklist:**
+
+1. **Check the trigger**
+   - Is the trigger configured correctly?
+   - Are the trigger conditions being met?
+   - Check trigger variables resolve correctly
+
+2. **Check for blocking triggers**
+   - Does the tag have any exception/blocking triggers?
+   - Are those triggers inadvertently activating?
+
+3. **Check tag priority/sequencing**
+   - Does another tag need to fire first?
+   - Is tag sequencing configured correctly?
+
+4. **Check the data layer**
+   - Is required data present when trigger evaluates?
+   - Are data layer variables returning expected values?
+
+### Trigger Not Activating
+
+**Debugging Steps:**
+
+1. **Verify trigger conditions**
+   ```
+   Example: Click trigger on CSS selector
+   - Check selector syntax
+   - Verify element exists on page
+   - Test with simpler selector
+   ```
+
+2. **Check built-in variables**
+   - Are required built-in variables enabled?
+   - Click Variables > Configure
+   - Enable missing variables
+
+3. **Test variable values**
+   - Check Variables panel
+   - Verify trigger conditions match actual values
+   - Look for type mismatches (string vs number)
+
+### Variable Returning Undefined
+
+**Common Causes:**
+
+1. **Data layer variable not found**
+   ```javascript
+   // Data layer:
+   { "product_name": "Widget" }
+
+   // Variable configured as:
+   productName  // Wrong - case sensitive!
+
+   // Should be:
+   product_name  // Correct
+   ```
+
+2. **Timing issue**
+   - Data pushed after tag fires
+   - Use Custom Event trigger to wait for data
+
+3. **Incorrect data layer version**
+   - Check Data Layer Version setting
+   - Version 2 vs Version 1 syntax differs
+
+### Data Layer Issues
+
+**Debug Pattern:**
+
+```javascript
+// In browser console, inspect data layer
+console.log(window.dataLayer);
+
+// Check for specific event
+window.dataLayer.filter(item => item.event === 'purchase');
+
+// Watch for new pushes
+var originalPush = window.dataLayer.push;
+window.dataLayer.push = function() {
+  console.log('DataLayer push:', arguments[0]);
+  return originalPush.apply(this, arguments);
+};
+```
+
+### JavaScript Errors
+
+**Investigation Steps:**
+
+1. **Check browser console** (F12 > Console)
+2. **Look for errors** before tag execution
+3. **Verify vendor scripts** load correctly
+4. **Check for conflicts** between tags
+5. **Test with tags disabled** one at a time
+
+## Server-Side Debugging
+
+For server-side GTM containers, the debug interface differs:
+
+### Server Preview Layout
+
+**Left Panel**: Incoming HTTP requests
+```
+collect?v=2&tid=G-XXXXXX&en=page_view...
+  └─ page_view
+  └─ scroll
+  └─ add_to_cart
+```
+
+**Right Panel Tabs**:
+- Request
+- Tags
+- Variables
+- Event Data
+- Console
+
+### Request Tab
+
+**Client Box**: Shows which client claimed the request
+
+**Incoming HTTP Request**: Full request details
+- Headers
+- Query parameters
+- Request body
+- Should match what's in Chrome Network tab
+
+**Outgoing HTTP Requests**: Requests sent to vendors
+- Tag that generated the request
+- Request details (URL, headers, body)
+- HTTP response from vendor
+- Status code and response body
+
+### Debugging Server Tags
+
+**Tags Fired**:
+- Success/failure status
+- Number of times fired
+- Click to see:
+  - Tag properties
+  - Outgoing HTTP requests
+  - Firing triggers
+
+**Tags Not Fired**:
+- Available tags that didn't fire
+- Reason they didn't fire
+
+### Server Variables
+
+Shows:
+- Variable type
+- Return type
+- Current value
+
+Example:
+```
+var_screen_resolution: "1536x864"
+var_user_agent: "Mozilla/5.0..."
+var_client_id: "123456.789012"
+```
+
+### Event Data Tab
+
+Full event data object:
+```json
+{
+  "event_name": "purchase",
+  "value": 129.99,
+  "currency": "USD",
+  "transaction_id": "T_12345",
+  "items": [...]
+}
+```
+
+This data populates variable values.
+
+### Server Console
+
+Shows errors from fired tags:
+```
+Tag: GA4 Server Tag
+Error: Invalid endpoint URL
+
+Tag: Facebook Conversions API
+Error: HTTP 401 - Invalid access token
+```
+
+## Testing Workflows
+
+### Pre-Publishing Checklist
+
+Before publishing any container version:
+
+- [ ] Enable preview mode
+- [ ] Test on all key pages:
+  - [ ] Homepage
+  - [ ] Product pages
+  - [ ] Category pages
+  - [ ] Cart/checkout
+  - [ ] Confirmation page
+- [ ] Verify all critical tags fire
+- [ ] Check data layer on each page
+- [ ] Test all conversion events
+- [ ] Verify cross-domain tracking
+- [ ] Test with ad blockers disabled and enabled
+- [ ] Check mobile experience (responsive design mode)
+- [ ] Verify no JavaScript errors
+- [ ] Confirm data in vendor platforms (GA4, Ads, etc.)
+
+### Testing Different Environments
+
+Use GTM Environments for staged testing:
+
+1. **Development Environment**
+   - Test unstable/experimental changes
+   - Break things without consequence
+   - Rapid iteration
+
+2. **Staging Environment**
+   - Test on staging server
+   - QA team validation
+   - Stakeholder review
+
+3. **Production Environment**
+   - Live site
+   - Real user data
+   - Careful change management
+
+### Cross-Domain Testing
+
+When testing cross-domain tracking:
+
+1. **Enable preview** on primary domain
+2. **Navigate to secondary** domain
+3. **Verify preview mode** persists
+4. **Check data layer** for linker parameters
+5. **Confirm client IDs** match across domains
+
+### Version Comparison
+
+Compare container versions:
+
+1. Go to **Versions**
+2. Select two versions
+3. Click **Compare**
+4. Review differences:
+   - Tags added/removed/modified
+   - Trigger changes
+   - Variable updates
+
+## Browser Developer Tools
+
+### Network Tab
+
+Monitor tag requests:
+
+1. **Open DevTools** (F12)
+2. **Go to Network tab**
+3. **Filter**: "analytics", "gtm", "google-analytics"
+4. **Trigger events** on your site
+5. **Inspect requests**:
+   - Check parameters sent
+   - Verify timing
+   - Look for errors (red status codes)
+
+### Console Tab
+
+Monitor JavaScript execution:
+
+```javascript
+// Check GTM loaded
+console.log(google_tag_manager);
+
+// Check dataLayer
+console.log(dataLayer);
+
+// Monitor events
+dataLayer.push = new Proxy(dataLayer.push, {
+  apply: function(target, thisArg, args) {
+    console.log('DataLayer event:', args[0]);
+    return target.apply(thisArg, args);
+  }
+});
+```
+
+### Application Tab
+
+Inspect cookies:
+
+1. **Open Application tab**
+2. **Go to Cookies**
+3. **Select your domain**
+4. **Check for**:
+   - `_ga` (GA client ID)
+   - `_gid` (GA session ID)
+   - Custom cookies
+
+## GA4 DebugView
+
+For GA4-specific debugging:
+
+1. **Enable debug mode** in GTM:
+   ```javascript
+   // Add to data layer
+   window.dataLayer.push({
+     'debug_mode': true
+   });
+   ```
+
+2. **Or use Chrome extension**: Google Analytics Debugger
+
+3. **Open GA4 DebugView**:
+   - Go to GA4 property
+   - Navigate to Configure > DebugView
+   - See real-time events from your debug session
+
+4. **Verify in DebugView**:
+   - Events appear immediately
+   - Parameters are correct
+   - Event sequence matches expectations
+
+## Common Debugging Patterns
+
+### Test Ecommerce Flow
+
+```javascript
+// 1. View item list
+dataLayer.push({
+  event: 'view_item_list',
+  ecommerce: { items: [...] }
+});
+
+// 2. Add to cart
+dataLayer.push({
+  event: 'add_to_cart',
+  ecommerce: { items: [...] }
+});
+
+// 3. Purchase
+dataLayer.push({
+  event: 'purchase',
+  ecommerce: {
+    transaction_id: 'T_12345',
+    value: 129.99,
+    items: [...]
+  }
+});
+
+// Verify each step in Preview Mode
+```
+
+### Test Conditional Logic
+
+```javascript
+// Test trigger with conditions
+if ({{Page Path}} contains '/products/') {
+  // Should fire: Product View tag
+  // Should not fire: Homepage tag
+}
+
+// Verify in Variables panel
+```
+
+### Test Tag Sequencing
+
+```javascript
+// Tag A must fire before Tag B
+// Tag A: Setup Tag
+//   - No sequencing
+
+// Tag B: Cleanup Tag
+//   - Setup Tag: Tag A
+//   - Firing: After Tag A
+
+// Verify firing order in Summary panel
+```
+
+## Troubleshooting Tips
+
+### Clear Browser Cache
+
+Sometimes old container versions cache:
+```
+1. Hard refresh: Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
+2. Clear cache completely
+3. Close and reopen preview mode
+```
+
+### Check Container Version
+
+Verify correct container loads:
+```javascript
+// In console:
+google_tag_manager['GTM-XXXXX'].dataLayer.get('gtm.version')
+```
+
+### Verify Container ID
+
+Ensure correct container on page:
+```html
+<!-- Check page source for -->
+<script>
+(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXXXX');
+</script>
+```
+
+### Multiple Containers
+
+If multiple containers exist:
+- Each fires independently
+- Check all containers in preview
+- Avoid duplicate tags across containers
+
+## Best Practices
+
+### Testing Best Practices
+
+1. **Test before publishing** - Always use preview mode
+2. **Test on real pages** - Not just homepage
+3. **Test user journeys** - Complete flows, not just individual pages
+4. **Document your tests** - Use version notes
+5. **Get peer review** - Have colleagues review in preview mode
+6. **Test with real data** - Use production-like scenarios
+
+### Debugging Best Practices
+
+1. **Start simple** - Test one thing at a time
+2. **Check the basics first** - Is GTM loading? Is the tag enabled?
+3. **Use the data layer** - Don't rely on page scraping
+4. **Log everything** - Use version notes to document changes
+5. **Keep containers clean** - Remove unused tags/triggers/variables
+
+### Documentation
+
+When testing, document:
+
+```
+Version: 123
+Changes:
+- Added GA4 purchase event
+- Modified product click trigger
+- Updated checkout flow
+
+Tests Performed:
+- ✅ Purchase event fires on confirmation page
+- ✅ Product clicks tracked correctly
+- ✅ Checkout funnel complete
+- ❌ Cross-domain tracking issue on subdomain (to fix)
+
+Tested By: Henrik
+Date: 2025-01-09
+```
+
+## Exit Preview Mode
+
+To stop debugging:
+
+1. **Click X** in Tag Assistant debug interface
+2. **Click "Stop debugging"** on Tag Assistant page
+3. **Close preview window**
+
+Preview mode only affects your browser - regular visitors don't see the debug interface.
+
+## Resources
+
+- [GTM Preview and Debug Containers](https://support.google.com/tagmanager/answer/6107056)
+- [Preview and Debug Server Containers](https://developers.google.com/tag-platform/tag-manager/server-side/debug)
+- [Tag Assistant](https://support.google.com/tagassistant/answer/10039345)
+- [GA4 DebugView](https://support.google.com/analytics/answer/7201382)
+- [GTM Troubleshooting](https://support.google.com/tagmanager/topic/9002003)