Initial commit

skills/gtm-best-practices/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: gtm-best-practices
+description: Expert guidance for Google Tag Manager best practices including naming conventions, performance optimization, security, privacy compliance, container organization, and deployment strategies. Use when optimizing GTM performance, implementing security best practices, setting up naming conventions, auditing GTM containers, or ensuring privacy compliance.
+---
+
+# GTM Best Practices
+
+## Overview
+This skill provides best practices for Google Tag Manager including naming conventions, performance optimization, security, privacy, and deployment strategies.
+
+## When to Use This Skill
+Invoke this skill when:
+- Optimizing GTM container performance
+- Implementing security best practices
+- Setting up naming conventions
+- Auditing GTM containers
+- Ensuring privacy compliance
+- Planning deployment strategies
+- Reviewing GTM implementations
+
+## Naming Conventions
+
+### Tags
+Format: `[Platform] - [Type] - [Description]`
+Examples:
+- `GA4 - Event - Form Submit`
+- `Google Ads - Conversion - Purchase`
+- `FB - Pixel - Page View`
+
+### Triggers
+Format: `[Event Type] - [Description]`
+Examples:
+- `Click - CTA Button`
+- `Page View - Homepage`
+- `Form Submit - Contact Form`
+
+### Variables
+Format: `[Type] - [Description]`
+Examples:
+- `DL - User ID`
+- `CJS - Format Price`
+- `Cookie - Session ID`
+
+## Performance Optimization
+
+### Minimize Tag Load Time
+- Use native tag templates instead of custom HTML
+- Minimize custom JavaScript
+- Implement async loading
+- Configure appropriate timeouts
+- Remove unused elements
+
+### Container Optimization
+- Regular container audits
+- Remove duplicate tags
+- Consolidate similar tags
+- Minimize trigger complexity
+- Use tag sequencing wisely
+
+### Page Performance
+- Defer non-critical tags
+- Use async snippet
+- Minimize container size
+- Optimize custom HTML
+- Monitor loading time
+
+## Security Best Practices
+
+### Tag Security
+- Vet all custom HTML tags
+- Review third-party templates
+- Use template permissions
+- Restrict custom JavaScript
+- Validate input data
+
+### Data Privacy
+- Avoid PII in data layer
+- Implement consent mode
+- Block tags based on consent
+- Hash sensitive identifiers
+- Review data collection policies
+
+### Access Control
+- Use appropriate permission levels
+- Review user access regularly
+- Limit container admin access
+- Audit permission changes
+- Use workspaces for isolation
+
+## Deployment Strategies
+
+### Environment Setup
+- Development environment for testing
+- Staging environment for validation
+- Production environment for live traffic
+- Use container versions properly
+
+### Version Management
+- Create versions with detailed notes
+- Test thoroughly before publishing
+- Maintain version history
+- Document changes clearly
+- Enable quick rollback capability
+
+### Publishing Workflow
+1. Make changes in workspace
+2. Test in Preview mode
+3. Validate in development environment
+4. Create version with notes
+5. Publish to production
+6. Monitor for issues
+7. Document deployment
+
+## Container Organization
+
+### Folder Structure
+- Group related tags by platform or purpose
+- Use folders for triggers by type
+- Organize variables by category
+- Keep structure logical and consistent
+
+### Documentation
+- Add notes to complex configurations
+- Document custom JavaScript logic
+- Maintain change log
+- Share knowledge with team
+
+## Audit Checklist
+- [ ] Naming conventions followed
+- [ ] No unused tags, triggers, or variables
+- [ ] Performance optimized
+- [ ] Security reviewed
+- [ ] Privacy compliance verified
+- [ ] Proper version management
+- [ ] Documentation complete
+
+## References
+- **references/best-practices.md** - Naming conventions, organization, deployment strategies
+
+## Integration with Other Skills
+## Integration with Other Skills
+- **gtm-general** - General GTM guidance and concepts
+- **gtm-setup** - Proper container setup and installation
+- **gtm-tags** - Efficient tag configuration practices
+- **gtm-triggers** - Trigger optimization and best practices
+- **gtm-variables** - Variable naming and structure best practices
+- **gtm-debugging** - Testing and validation workflows
+- **gtm-datalayer** - Data layer naming and structure best practices
+- **gtm-custom-templates** - Template development best practices
+- **gtm-api** - API automation best practices

skills/gtm-best-practices/references/best-practices.md

@@ -0,0 +1,597 @@
+# Google Tag Manager - Best Practices
+
+## Foundational Technical Constraints
+
+### JavaScript in Google Tag Manager (ES5 Requirement)
+
+**Critical:** Google Tag Manager primarily uses **ECMAScript 5 (ES5)** for JavaScript code, not modern ES6+.
+
+#### Where ES5 is Required
+
+1. **Custom JavaScript Variables** - Must use ES5 syntax only
+2. **Custom HTML Tags** - Standard `<script>` tags must use ES5
+3. **Trigger conditions using JavaScript** - ES5 only
+
+#### ES6 Features NOT Supported in Standard GTM
+
+```javascript
+// ❌ WILL FAIL - ES6 syntax
+const myVar = 'value';
+let count = 0;
+const arrow = () => console.log('test');
+const template = `Hello ${name}`;
+
+// ✅ CORRECT - ES5 syntax
+var myVar = 'value';
+var count = 0;
+var regularFunc = function() { console.log('test'); };
+var concatenated = 'Hello ' + name;
+```
+
+#### Custom Templates Exception
+
+**Custom Templates** (Sandboxed JavaScript) support some ES6 features:
+- `const` and `let` declarations
+- Template literals
+- Limited modern JavaScript features
+
+Running in a controlled sandboxed environment based on ECMAScript 5.1 with selective ES6 support.
+
+#### Workarounds for Modern JavaScript
+
+**Option 1: Transpilation (Recommended)**
+
+Use BabelJS to transpile ES6+ to ES5 before pasting into GTM:
+
+```javascript
+// Write in ES6
+const getData = () => {
+  const data = dataLayer.filter(item => item.event === 'purchase');
+  return data;
+};
+
+// Transpile to ES5 with Babel, then paste into GTM
+var getData = function() {
+  var data = dataLayer.filter(function(item) {
+    return item.event === 'purchase';
+  });
+  return data;
+};
+```
+
+**Option 2: text/gtmscript Tag**
+
+Bypass GTM's syntax checking (use with caution):
+
+```html
+<script type="text/gtmscript">
+  // Modern JavaScript here - no syntax validation in GTM UI
+  const myModernCode = () => {
+    // ...
+  };
+</script>
+```
+
+**Caveats:**
+- No syntax highlighting in GTM interface
+- No error checking until runtime
+- Harder to debug
+- Only use when absolutely necessary
+
+### Regular Expressions in Google Tag Manager (RE2 Format)
+
+**Critical:** GTM uses **RE2 (GoLang regex)**, NOT standard JavaScript/PCRE regex.
+
+#### Key Differences from Standard Regex
+
+**NOT Supported in RE2:**
+- ❌ Backreferences: `\1`, `\2`, `\g{name}`
+- ❌ Lookahead assertions: `(?=...)`, `(?!...)`
+- ❌ Lookbehind assertions: `(?<=...)`, `(?<!...)`
+- ❌ Conditional expressions: `(?(condition)yes|no)`
+- ❌ Possessive quantifiers: `*+`, `++`
+
+**Supported in RE2:**
+- ✅ Character classes: `[abc]`, `[^abc]`, `[a-z]`
+- ✅ Quantifiers: `*`, `+`, `?`, `{n,m}`
+- ✅ Anchors: `^`, `$`, `\A`, `\z`
+- ✅ Perl character classes: `\d`, `\w`, `\s` (and negations)
+- ✅ Groups: `(...)`, `(?:...)` (non-capturing)
+- ✅ Named groups: `(?P<name>...)`
+- ✅ Alternation: `|`
+- ✅ Case-insensitive flag: `(?i)`
+
+#### Common RE2 Patterns for GTM
+
+**Match URLs:**
+
+```regex
+# Exact match
+^https://example\.com/page$
+
+# Contains path
+/checkout/
+
+# Query parameter present
+\?utm_source=
+
+# Multiple domains
+^https://(www\.)?example\.(com|net)
+```
+
+**Match Page Paths:**
+
+```regex
+# Product pages
+^/products/[^/]+$
+
+# Category with ID
+^/category/\d+
+
+# Blog posts
+^/blog/[\w-]+$
+```
+
+**Case-Insensitive Matching:**
+
+```regex
+# Case-insensitive flag at start
+(?i)^/checkout
+
+# Matches: /checkout, /Checkout, /CHECKOUT, etc.
+```
+
+**Character Classes:**
+
+```regex
+# Digits only
+^\d+$
+
+# Alphanumeric
+^[\w-]+$
+
+# Specific characters
+^[A-Z]{2,3}$
+```
+
+#### Where Regex is Used in GTM
+
+1. **Trigger Conditions** - Page URL, Click URL, etc.
+2. **Variable Formatting** - Regex Table variables
+3. **Filter Conditions** - Various matching rules
+
+#### Full RE2 Syntax Reference
+
+Complete RE2 regex syntax is available in:
+`.claude/skills/gtm-core/gtm-core/references/google-rew-regular-expressions-syntax.txt`
+
+## Naming Conventions
+
+### Tag Naming
+
+Use descriptive, consistent naming patterns:
+
+```
+[Platform] - [Type] - [Purpose] - [Trigger Condition]
+```
+
+**Examples:**
+- `GA4 - Event - Purchase Complete - Thank You Page`
+- `Google Ads - Conversion - Form Submit - Contact Form`
+- `Facebook - Pixel - Page View - All Pages`
+- `Custom - LinkedIn Insight - Page View - Career Pages`
+
+**Benefits:**
+- Easy to find tags in large containers
+- Clear purpose at a glance
+- Sortable and filterable
+- Easier collaboration
+
+### Trigger Naming
+
+```
+[Type] - [Condition] - [Description]
+```
+
+**Examples:**
+- `Pageview - URL Contains - Checkout`
+- `Click - Element ID - CTA Button`
+- `Custom Event - purchase_complete`
+- `Form Submit - Contact Form`
+
+### Variable Naming
+
+```
+[Type] - [Purpose]
+```
+
+**Examples:**
+- `DLV - User ID`
+- `JS - Page Category`
+- `Constant - GA4 Measurement ID`
+- `Regex Table - Page Type Mapping`
+
+**Prefixes:**
+- `DLV` - Data Layer Variable
+- `JS` - Custom JavaScript
+- `Constant` - Constant value
+- `1P Cookie` - First Party Cookie
+- `URL` - URL variable
+
+### Folder Organization
+
+Group related items:
+
+```
+├── Analytics
+│   ├── GA4 Tags
+│   ├── GA4 Triggers
+│   └── GA4 Variables
+├── Advertising
+│   ├── Google Ads
+│   ├── Facebook
+│   └── LinkedIn
+├── Utilities
+│   ├── Error Tracking
+│   └── Performance Monitoring
+└── Testing
+    └── Development Tags
+```
+
+## Container Organization
+
+### Workspace Management
+
+**Development Workflow:**
+
+1. Create workspace for each feature/change
+2. Name workspace descriptively: `Add GA4 Ecommerce Tracking`
+3. Work in isolation
+4. Test thoroughly in Preview mode
+5. Submit for review
+6. Merge and publish
+
+**Workspace Best Practices:**
+
+- One feature per workspace
+- Regular cleanup of abandoned workspaces
+- Clear workspace descriptions
+- Resolve conflicts promptly
+- Use descriptive workspace names
+
+### Version Control
+
+**Version Naming:**
+
+```
+v[Major].[Minor] - [Description]
+```
+
+**Examples:**
+- `v1.0 - Initial GTM Setup`
+- `v1.1 - Add GA4 Ecommerce`
+- `v2.0 - Major Restructure`
+- `v2.1 - Fix Checkout Tracking`
+
+**Version Notes:**
+
+Include detailed notes:
+```
+Changes:
+- Added GA4 purchase event tracking
+- Updated data layer structure for checkout
+- Fixed duplicate page view issue
+
+Testing:
+- Verified in dev environment
+- Tested all checkout flows
+- Confirmed data in GA4 DebugView
+
+Tags Added:
+- GA4 - Event - Purchase Complete
+
+Tags Modified:
+- GA4 - Event - Add to Cart (updated parameters)
+```
+
+### Multi-User Collaboration
+
+**Permissions:**
+
+- **No Access** - External users
+- **Read** - Stakeholders, analysts (view only)
+- **Edit** - Developers, marketers
+- **Approve** - Senior developers, managers
+- **Publish** - Select trusted users only
+
+**Collaboration Best Practices:**
+
+- Communicate workspace usage
+- Regular team syncs
+- Document changes thoroughly
+- Use workspace approval workflow
+- Maintain change log
+
+## Performance Optimization
+
+### Tag Load Order
+
+**Priority System:**
+
+Use tag firing priority (higher numbers fire first):
+
+```
+100 - Critical tags (error tracking, consent)
+50  - Analytics tags (GA4, Adobe)
+25  - Marketing tags (ads pixels)
+10  - Third-party tags
+0   - Default
+```
+
+**Tag Sequencing:**
+
+Set up tag firing order:
+1. Tag that must fire first
+2. Configure "Tag Sequencing" in advanced settings
+3. Setup tag fires after cleanup tag completes
+
+### Minimize Custom HTML
+
+**Prefer:**
+1. Built-in tags (GA4, Google Ads)
+2. Community Gallery templates
+3. Custom templates
+4. Custom HTML (last resort)
+
+**Why:**
+- Built-in tags are optimized
+- Less maintenance
+- Better performance
+- Reduced security risk
+
+### Async vs Sync Loading
+
+**Asynchronous Loading (Default - Recommended):**
+
+```javascript
+// GTM loads async by default
+<script async src="https://www.googletagmanager.com/gtm.js?id=GTM-XXXXXX"></script>
+```
+
+**Benefits:**
+- Non-blocking
+- Better page performance
+- Parallel loading
+
+**Synchronous (Use Sparingly):**
+
+Only when tag MUST execute before page renders.
+
+### Tag Timeout
+
+**Configure Timeout:**
+
+Admin → Container Settings → Tag Settings
+- Default: 2000ms (2 seconds)
+- Recommended: 3000-5000ms for complex tags
+
+**Prevent:**
+- Tags blocking page indefinitely
+- Poor user experience
+- False abandonment metrics
+
+## Security Best Practices
+
+### Custom HTML Security
+
+**Review All Custom HTML:**
+
+```javascript
+// ❌ DANGEROUS - Eval and dynamic script loading
+eval(userInput);
+document.write('<script src="' + untrustedURL + '"></script>');
+
+// ✅ SAFE - Controlled execution
+var allowedScripts = {
+  'analytics': 'https://analytics.trusted.com/script.js'
+};
+```
+
+**Security Checklist:**
+- [ ] No `eval()` with user input
+- [ ] No `document.write()` with external sources
+- [ ] Validate all external script sources
+- [ ] Review third-party tag code
+- [ ] Use CSP (Content Security Policy) headers
+
+### Data Layer Security
+
+**Never Push PII to Data Layer:**
+
+```javascript
+// ❌ NEVER DO THIS
+dataLayer.push({
+  'email': 'user@example.com',
+  'phone': '+1234567890',
+  'ssn': '123-45-6789'
+});
+
+// ✅ HASH OR PSEUDONYMIZE
+dataLayer.push({
+  'userIdHash': sha256('user@example.com'),
+  'hasPhone': true
+});
+```
+
+### Template Permissions
+
+**Custom Template Security:**
+
+Review template permissions:
+- Access to APIs
+- Access to global variables
+- Access to local storage
+- Network requests
+
+Grant minimum necessary permissions.
+
+## Quality Assurance
+
+### Testing Checklist
+
+**Before Publishing:**
+
+- [ ] Preview mode testing completed
+- [ ] All triggers fire correctly
+- [ ] Data layer variables populate
+- [ ] Tags send expected data
+- [ ] No console errors
+- [ ] Cross-browser testing
+- [ ] Mobile testing
+- [ ] Edge case scenarios tested
+
+### Debug Workflow
+
+1. **Enable Preview Mode**
+2. **Navigate to test page**
+3. **Verify in Debug Panel:**
+   - Tags Fired
+   - Tags Not Fired
+   - Data Layer
+   - Variables
+4. **Check receiving platform** (GA4, Google Ads, etc.)
+5. **Test edge cases**
+
+### Automated Testing
+
+**Tag Manager API + Testing Framework:**
+
+```python
+# Pseudo-code
+def test_purchase_tag():
+    trigger_purchase_event()
+    assert ga4_tag_fired()
+    assert correct_parameters_sent()
+```
+
+## Deployment Best Practices
+
+### Publishing Workflow
+
+1. **Development** → Test in development workspace
+2. **Staging** → Test in staging environment
+3. **Preview** → Final check in preview mode
+4. **Publish** → Publish to live container
+5. **Monitor** → Watch for errors/issues
+
+### Emergency Rollback
+
+**Quick Rollback:**
+
+Versions → Previous Version → Actions → Publish
+
+**Keep:**
+- Last 3 working versions readily accessible
+- Emergency contact list
+- Rollback documentation
+
+### Production Deployment Checklist
+
+- [ ] Workspace approved by team lead
+- [ ] All tests passing
+- [ ] Change documented in version notes
+- [ ] Stakeholders notified
+- [ ] Monitoring in place
+- [ ] Rollback plan ready
+
+## Maintenance
+
+### Regular Audits
+
+**Quarterly Review:**
+
+- Remove unused tags/triggers/variables
+- Update deprecated features
+- Review tag performance
+- Check for duplicate tracking
+- Verify naming consistency
+
+### Performance Monitoring
+
+**Monitor:**
+- Page load time impact
+- Tag load time
+- Failed tags
+- Timeout events
+- Error rates
+
+**Tools:**
+- Google Tag Assistant
+- Chrome DevTools
+- GTM Debug Panel
+- GA4 DebugView
+
+### Version Cleanup
+
+**Retention Policy:**
+
+- Keep last 10-15 versions
+- Archive old versions
+- Document reason for major changes
+- Maintain change history
+
+## Documentation
+
+### External Documentation
+
+**Maintain:**
+
+1. **GTM Implementation Guide**
+   - Container architecture
+   - Tag inventory
+   - Trigger mapping
+   - Variable dictionary
+   - Data layer specification
+
+2. **Change Log**
+   - Date of change
+   - Description
+   - Who made the change
+   - Reason for change
+
+3. **Troubleshooting Guide**
+   - Common issues
+   - Solutions
+   - Contact information
+
+### Version Notes Template
+
+```markdown
+## Version X.X - [Description]
+
+### Changes Made
+- List of changes
+
+### Tags Added
+- Tag names and purposes
+
+### Tags Modified
+- What changed and why
+
+### Tags Removed
+- What was removed and why
+
+### Testing Completed
+- Test scenarios
+- Results
+
+### Known Issues
+- Any limitations or issues
+```
+
+## Resources
+
+- [GTM Developer Documentation](https://developers.google.com/tag-platform/tag-manager)
+- [GTM Help Center](https://support.google.com/tagmanager)
+- [GTM Community](https://support.google.com/tagmanager/community)
+- [RE2 Regex Syntax Reference](.claude/skills/gtm-core/gtm-core/references/google-rew-regular-expressions-syntax.txt)