refactor(gtm-audit): Update desktop skill to use Chrome DevTools + DTM Agent MCP workflow
- Replace Playwright-based approach with Chrome DevTools MCP for browser inspection - Add DTM Agent MCP integration for GTM API operations - Document 4-phase workflow: Inspect → Diagnose → Configure → Verify - Add common issue patterns with diagnosis/fix guidance - Update audit checklist to reference specific MCP tools - Add .gitignore entries for pickle files and .claude/ directory 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
5
.gitignore
vendored
5
.gitignore
vendored
@@ -76,8 +76,13 @@ npm-debug.log*
|
|||||||
.env.local
|
.env.local
|
||||||
*.key
|
*.key
|
||||||
*.pem
|
*.pem
|
||||||
|
*.pickle
|
||||||
credentials.json
|
credentials.json
|
||||||
secrets.json
|
secrets.json
|
||||||
|
token.json
|
||||||
|
|
||||||
|
# Claude Code local config
|
||||||
|
.claude/
|
||||||
|
|
||||||
# Temporary files
|
# Temporary files
|
||||||
output/
|
output/
|
||||||
|
|||||||
@@ -5,201 +5,255 @@ description: Automated Google Tag Manager audit and validation toolkit. Use when
|
|||||||
|
|
||||||
# GTM Audit Skill
|
# GTM Audit Skill
|
||||||
|
|
||||||
Automated audit workflow for GTM containers using Playwright browser automation.
|
Automated audit workflow for GTM containers using **Chrome DevTools MCP** for browser inspection and **DTM Agent MCP** for GTM API operations.
|
||||||
|
|
||||||
## Workflow Overview
|
## Required MCP Servers
|
||||||
|
|
||||||
|
This skill requires the following MCP servers to be configured:
|
||||||
|
|
||||||
|
| MCP Server | Purpose | Tools Used |
|
||||||
|
|------------|---------|------------|
|
||||||
|
| **chrome-devtools** | Browser debugging & inspection | `navigate_page`, `evaluate_script`, `list_network_requests`, `list_console_messages`, `click`, `hover`, `take_screenshot`, `performance_start_trace` |
|
||||||
|
| **dtm-agent** | GTM API operations | `dtm_status`, `dtm_list_tags`, `dtm_get_tag`, `dtm_list_triggers`, `dtm_get_trigger`, `dtm_list_variables`, `dtm_debug_performance`, `dtm_debug_preview` |
|
||||||
|
|
||||||
|
## Critical Workflow Rule
|
||||||
|
|
||||||
|
**ALWAYS use Chrome DevTools MCP FIRST before making GTM configuration changes.**
|
||||||
|
|
||||||
|
GTM triggering and parameter capturing issues are highly dependent on:
|
||||||
|
- DOM structure and CSS selectors
|
||||||
|
- Dynamic element loading and timing
|
||||||
|
- DataLayer event sequences
|
||||||
|
- JavaScript execution order
|
||||||
|
- Network request timing
|
||||||
|
|
||||||
|
## Standard Debugging Workflow
|
||||||
|
|
||||||
```
|
```
|
||||||
1. Setup & Container Detection
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
2. DataLayer Validation & Monitoring
|
│ PHASE 1: INSPECT (Chrome DevTools MCP) │
|
||||||
3. Form Analysis & Submission Tracking
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
4. E-commerce Checkout Flow Testing
|
│ 1. navigate_page → Load target URL │
|
||||||
5. Tag Firing Verification
|
│ 2. evaluate_script → Check window.dataLayer state │
|
||||||
6. Issue Analysis & Recommendations
|
│ 3. list_network_requests → Identify GTM/tag requests │
|
||||||
7. Report Generation
|
│ 4. list_console_messages → Check for JS errors │
|
||||||
|
│ 5. click/hover → Simulate user interactions │
|
||||||
|
│ 6. take_screenshot → Document current state │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 2: DIAGNOSE │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ • Identify DOM/timing/selector issues from browser state │
|
||||||
|
│ • Compare expected vs actual dataLayer events │
|
||||||
|
│ • Check network request payloads for missing parameters │
|
||||||
|
│ • Review console for GTM/tag errors │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 3: CONFIGURE (DTM Agent MCP) │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ 1. dtm_status → Verify authentication │
|
||||||
|
│ 2. dtm_list_tags → Review current tag configuration │
|
||||||
|
│ 3. dtm_get_trigger → Inspect trigger conditions │
|
||||||
|
│ 4. dtm_list_variables → Check variable mappings │
|
||||||
|
│ 5. dtm_update_tag/trigger → Make configuration changes │
|
||||||
|
│ 6. dtm_create_version → Create version for testing │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
↓
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ PHASE 4: VERIFY (Chrome DevTools MCP) │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ • Repeat Phase 1 inspection steps │
|
||||||
|
│ • Confirm issue is resolved │
|
||||||
|
│ • Document before/after comparison │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
```
|
```
|
||||||
|
|
||||||
## Quick Start
|
## Chrome DevTools MCP Commands
|
||||||
|
|
||||||
```bash
|
### Essential Inspection Commands
|
||||||
# Full audit with all features
|
|
||||||
python scripts/gtm_audit.py --url "https://example.com" --journey full
|
|
||||||
|
|
||||||
# Form tracking audit
|
```javascript
|
||||||
python scripts/gtm_audit.py --url "https://example.com/contact" --journey form
|
// 1. Check dataLayer state
|
||||||
|
evaluate_script: "JSON.stringify(window.dataLayer || [], null, 2)"
|
||||||
|
|
||||||
# E-commerce checkout flow
|
// 2. Get GTM container info
|
||||||
python scripts/gtm_audit.py --url "https://example.com/cart" --journey checkout
|
evaluate_script: "Object.keys(window.google_tag_manager || {})"
|
||||||
|
|
||||||
# DataLayer deep inspection
|
// 3. Monitor dataLayer pushes (inject listener)
|
||||||
python scripts/gtm_audit.py --url "https://example.com" --journey datalayer
|
evaluate_script: `
|
||||||
|
window.__gtmPushLog = [];
|
||||||
|
const originalPush = window.dataLayer.push;
|
||||||
|
window.dataLayer.push = function(...args) {
|
||||||
|
window.__gtmPushLog.push({timestamp: Date.now(), data: args[0]});
|
||||||
|
return originalPush.apply(this, args);
|
||||||
|
};
|
||||||
|
`
|
||||||
|
|
||||||
# With expected container validation
|
// 4. Get captured pushes
|
||||||
python scripts/gtm_audit.py --url "https://example.com" --container "GTM-XXXXXX"
|
evaluate_script: "JSON.stringify(window.__gtmPushLog || [], null, 2)"
|
||||||
|
|
||||||
|
// 5. Check for GTM debug mode
|
||||||
|
evaluate_script: "window.google_tag_manager?.['GTM-XXXXXX']?.preview?.active"
|
||||||
```
|
```
|
||||||
|
|
||||||
## Core Components
|
### Network Request Patterns
|
||||||
|
|
||||||
### 1. Container Detection
|
| Tag Type | URL Pattern to Monitor |
|
||||||
|
|----------|------------------------|
|
||||||
Verify GTM installation:
|
|
||||||
- Check for `gtm.js` or `gtag/js` script presence
|
|
||||||
- Validate container ID format (GTM-XXXXXX)
|
|
||||||
- Detect multiple containers (potential conflicts)
|
|
||||||
- Check script placement (head vs body)
|
|
||||||
|
|
||||||
### 2. DataLayer Inspection
|
|
||||||
|
|
||||||
Monitor `window.dataLayer` array:
|
|
||||||
- Capture all push events
|
|
||||||
- Validate event structure against GA4 specs
|
|
||||||
- Check e-commerce object schemas
|
|
||||||
- Identify malformed or missing parameters
|
|
||||||
|
|
||||||
### 3. Form Analysis & Tracking
|
|
||||||
|
|
||||||
Comprehensive form validation:
|
|
||||||
- **Discovery**: Find all forms on page
|
|
||||||
- **Field Analysis**: Input types, required fields, validation rules
|
|
||||||
- **Interaction Simulation**: Focus, input, blur, submit
|
|
||||||
- **Event Verification**: form_start, form_submit, generate_lead
|
|
||||||
- **Error Tracking**: Validation failures, abandonment points
|
|
||||||
|
|
||||||
### 4. E-commerce Checkout Flow
|
|
||||||
|
|
||||||
Multi-step checkout simulation:
|
|
||||||
- **Cart**: view_cart, remove_from_cart
|
|
||||||
- **Checkout Start**: begin_checkout
|
|
||||||
- **Shipping**: add_shipping_info
|
|
||||||
- **Payment**: add_payment_info
|
|
||||||
- **Purchase**: purchase event validation
|
|
||||||
- **Funnel Analysis**: Drop-off detection between steps
|
|
||||||
|
|
||||||
### 5. DataLayer Deep Inspection
|
|
||||||
|
|
||||||
Advanced dataLayer validation:
|
|
||||||
- **Structure Validation**: Schema compliance checking
|
|
||||||
- **Real-time Monitoring**: Capture all pushes during journey
|
|
||||||
- **Event Sequencing**: Verify correct order of events
|
|
||||||
- **Parameter Validation**: Type checking, required fields
|
|
||||||
- **Diff Analysis**: Before/after state comparison
|
|
||||||
|
|
||||||
### 4. Network Monitoring
|
|
||||||
|
|
||||||
Capture outbound requests to:
|
|
||||||
| Destination | Endpoint Pattern |
|
|
||||||
|-------------|------------------|
|
|
||||||
| GA4 | `google-analytics.com/g/collect` |
|
| GA4 | `google-analytics.com/g/collect` |
|
||||||
|
| Google Ads | `googleads.g.doubleclick.net` |
|
||||||
| Meta Pixel | `facebook.com/tr` |
|
| Meta Pixel | `facebook.com/tr` |
|
||||||
| LinkedIn | `px.ads.linkedin.com` |
|
| LinkedIn | `px.ads.linkedin.com` |
|
||||||
| Google Ads | `googleads.g.doubleclick.net` |
|
|
||||||
| TikTok | `analytics.tiktok.com` |
|
| TikTok | `analytics.tiktok.com` |
|
||||||
|
| Kakao | `track.tiara.kakao.com` |
|
||||||
|
| Naver | `wcs.naver.net` |
|
||||||
|
|
||||||
### 5. Tag Verification
|
## DTM Agent MCP Commands
|
||||||
|
|
||||||
For each expected tag:
|
### Container Analysis
|
||||||
- Confirm firing on correct trigger
|
|
||||||
- Validate required parameters present
|
|
||||||
- Check parameter values match dataLayer
|
|
||||||
- Identify timing/sequencing issues
|
|
||||||
|
|
||||||
## Reference Files
|
```bash
|
||||||
|
# Check authentication and active container
|
||||||
|
dtm_status
|
||||||
|
|
||||||
- **references/ga4_events.md** - GA4 recommended event specifications
|
# List all tags with optional filter
|
||||||
- **references/ecommerce_schema.md** - E-commerce dataLayer structures
|
dtm_list_tags --name_filter "GA4"
|
||||||
- **references/form_tracking.md** - Form event specs and validation patterns
|
|
||||||
- **references/checkout_flow.md** - Checkout funnel event sequence
|
# Get specific tag details
|
||||||
- **references/datalayer_validation.md** - DataLayer schema validation rules
|
dtm_get_tag --tag_id "123"
|
||||||
- **references/common_issues.md** - Frequent problems and fixes
|
|
||||||
- **references/report_template.md** - Audit report format
|
# List triggers and their conditions
|
||||||
|
dtm_list_triggers
|
||||||
|
|
||||||
|
# Container performance analysis
|
||||||
|
dtm_debug_performance
|
||||||
|
|
||||||
|
# Validate container configuration
|
||||||
|
dtm_debug_preview
|
||||||
|
```
|
||||||
|
|
||||||
|
### Configuration Changes
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Update tag configuration
|
||||||
|
dtm_update_tag --tag_id "123" --config {...}
|
||||||
|
|
||||||
|
# Create new trigger
|
||||||
|
dtm_create_trigger --name "Button Click" --type "CLICK"
|
||||||
|
|
||||||
|
# Create version for testing
|
||||||
|
dtm_create_version --name "Debug Session 2025-01-03"
|
||||||
|
```
|
||||||
|
|
||||||
## Audit Checklist
|
## Audit Checklist
|
||||||
|
|
||||||
### Container Health
|
### Container Health
|
||||||
- [ ] GTM script loads without errors
|
- [ ] GTM script loads without errors (Chrome DevTools: console)
|
||||||
- [ ] Container ID matches expected
|
- [ ] Container ID matches expected (Chrome DevTools: evaluate_script)
|
||||||
- [ ] No duplicate containers
|
- [ ] No duplicate containers (Chrome DevTools: network requests)
|
||||||
- [ ] Script in correct position
|
- [ ] Script in correct position (Chrome DevTools: DOM inspection)
|
||||||
|
|
||||||
### DataLayer Quality
|
### DataLayer Quality
|
||||||
- [ ] dataLayer initialized before GTM
|
- [ ] dataLayer initialized before GTM (Chrome DevTools: evaluate_script)
|
||||||
- [ ] Event names follow conventions
|
- [ ] Event names follow conventions (Chrome DevTools: dataLayer inspection)
|
||||||
- [ ] Required parameters present
|
- [ ] Required parameters present (DTM Agent: dtm_get_tag to check expected params)
|
||||||
- [ ] Data types correct (string/number)
|
- [ ] Data types correct (Chrome DevTools: typeof checks)
|
||||||
- [ ] E-commerce objects cleared before new push
|
- [ ] E-commerce objects cleared before new push
|
||||||
- [ ] No duplicate events firing
|
- [ ] No duplicate events firing (Chrome DevTools: network request count)
|
||||||
|
|
||||||
### Form Tracking
|
### Tag Configuration
|
||||||
- [ ] form_start fires on first interaction
|
- [ ] Tags properly configured (DTM Agent: dtm_list_tags)
|
||||||
- [ ] form_submit fires on successful submission
|
- [ ] Triggers have correct conditions (DTM Agent: dtm_get_trigger)
|
||||||
- [ ] generate_lead fires with value (if applicable)
|
- [ ] Variables mapped correctly (DTM Agent: dtm_list_variables)
|
||||||
- [ ] Form field errors tracked
|
- [ ] Firing sequence appropriate (DTM Agent: dtm_debug_performance)
|
||||||
- [ ] Form abandonment detectable
|
|
||||||
|
|
||||||
### E-commerce Checkout
|
### Tag Firing Verification
|
||||||
- [ ] view_cart fires with correct items
|
- [ ] Pageview fires on all pages (Chrome DevTools: network requests)
|
||||||
- [ ] begin_checkout has all required params
|
- [ ] Events fire on correct triggers (Chrome DevTools: click + network)
|
||||||
- [ ] add_shipping_info includes shipping_tier
|
- [ ] E-commerce events have required params (Chrome DevTools: request payload)
|
||||||
- [ ] add_payment_info includes payment_type
|
- [ ] Conversion tags fire once (Chrome DevTools: request count)
|
||||||
- [ ] purchase has unique transaction_id
|
|
||||||
- [ ] purchase value matches cart total
|
|
||||||
|
|
||||||
### Tag Firing
|
## Common Issue Patterns
|
||||||
- [ ] Pageview fires on all pages
|
|
||||||
- [ ] Events fire on correct triggers
|
|
||||||
- [ ] E-commerce events have required params
|
|
||||||
- [ ] Conversion tags fire once (not duplicate)
|
|
||||||
|
|
||||||
### Performance
|
### Issue: Tag Not Firing
|
||||||
- [ ] Tags don't block page render
|
|
||||||
- [ ] No excessive network requests
|
**Diagnosis (Chrome DevTools MCP first)**:
|
||||||
- [ ] Tag sequencing optimized
|
1. `navigate_page` → Load the page
|
||||||
|
2. `list_network_requests` → Check if ANY request to tag endpoint
|
||||||
|
3. `evaluate_script` → Verify dataLayer event exists
|
||||||
|
4. `list_console_messages` → Check for errors
|
||||||
|
|
||||||
|
**Fix (DTM Agent MCP)**:
|
||||||
|
1. `dtm_get_trigger` → Review trigger conditions
|
||||||
|
2. `dtm_update_trigger` → Adjust selector/event name
|
||||||
|
3. `dtm_debug_preview` → Validate configuration
|
||||||
|
|
||||||
|
### Issue: Missing Parameters
|
||||||
|
|
||||||
|
**Diagnosis (Chrome DevTools MCP first)**:
|
||||||
|
1. `list_network_requests` → Capture the actual request
|
||||||
|
2. Parse request payload to see what's sent
|
||||||
|
3. `evaluate_script` → Check dataLayer for expected values
|
||||||
|
|
||||||
|
**Fix (DTM Agent MCP)**:
|
||||||
|
1. `dtm_list_variables` → Check variable configuration
|
||||||
|
2. `dtm_update_tag` → Fix parameter mappings
|
||||||
|
|
||||||
|
### Issue: Duplicate Firing
|
||||||
|
|
||||||
|
**Diagnosis (Chrome DevTools MCP first)**:
|
||||||
|
1. `list_network_requests` → Count requests to same endpoint
|
||||||
|
2. `evaluate_script` → Check dataLayer for duplicate pushes
|
||||||
|
|
||||||
|
**Fix (DTM Agent MCP)**:
|
||||||
|
1. `dtm_list_triggers` → Check for overlapping triggers
|
||||||
|
2. `dtm_get_tag` → Review tag firing options
|
||||||
|
|
||||||
|
## Performance Analysis
|
||||||
|
|
||||||
|
Use Chrome DevTools MCP for performance:
|
||||||
|
```
|
||||||
|
performance_start_trace → Run page load → Analyze trace
|
||||||
|
```
|
||||||
|
|
||||||
|
Compare with DTM Agent static analysis:
|
||||||
|
```
|
||||||
|
dtm_debug_performance → Get container complexity grade
|
||||||
|
```
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
Audit generates JSON report:
|
Audit generates structured report:
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"audit_metadata": {
|
"audit_metadata": {
|
||||||
"url": "https://example.com",
|
"url": "https://example.com",
|
||||||
"timestamp": "2025-01-15T10:30:00Z",
|
"timestamp": "2025-01-03T10:30:00Z",
|
||||||
"container_id": "GTM-XXXXXX"
|
"container_id": "GTM-XXXXXX",
|
||||||
|
"tools_used": ["chrome-devtools", "dtm-agent"]
|
||||||
},
|
},
|
||||||
"container_status": {
|
"browser_inspection": {
|
||||||
"installed": true,
|
"dataLayer_events": [...],
|
||||||
"valid": true,
|
"network_requests": [...],
|
||||||
"position": "head",
|
"console_errors": [...],
|
||||||
"issues": []
|
"performance_metrics": {...}
|
||||||
|
},
|
||||||
|
"gtm_configuration": {
|
||||||
|
"tags": [...],
|
||||||
|
"triggers": [...],
|
||||||
|
"variables": [...],
|
||||||
|
"container_grade": "B"
|
||||||
},
|
},
|
||||||
"tags_fired": [...],
|
|
||||||
"tags_not_fired": [...],
|
|
||||||
"issues": [...],
|
"issues": [...],
|
||||||
"recommendations": [...]
|
"recommendations": [...]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Common Fix Patterns
|
## Integration with Other Skills
|
||||||
|
|
||||||
**Tag Not Firing**
|
- **seo-core-web-vitals**: Use performance traces for Core Web Vitals impact analysis
|
||||||
1. Check trigger conditions in GTM
|
- **notion-writer**: Export audit reports to Notion database
|
||||||
2. Verify dataLayer event name matches exactly
|
- **seo-schema-validator**: Validate e-commerce structured data alongside GTM
|
||||||
3. Confirm trigger timing (DOM Ready vs Window Loaded)
|
|
||||||
4. Test in GTM Preview mode
|
|
||||||
|
|
||||||
**Missing Parameters**
|
|
||||||
1. Verify dataLayer.push() includes all required fields
|
|
||||||
2. Check variable configuration in GTM
|
|
||||||
3. Confirm data types match expectations
|
|
||||||
|
|
||||||
**Duplicate Firing**
|
|
||||||
1. Check for multiple triggers on same action
|
|
||||||
2. Verify tag firing options (once per event/page)
|
|
||||||
3. Look for duplicate GTM containers
|
|
||||||
|
|
||||||
## Integration Notes
|
|
||||||
|
|
||||||
Works with:
|
|
||||||
- Playwright MCP tools for browser automation
|
|
||||||
- Desktop Commander for local script execution
|
|
||||||
- Can export reports to Notion via MCP
|
|
||||||
|
|||||||
Reference in New Issue
Block a user