Google Tag Manager Integration

Learn how to integrate Google Tag Manager (GTM) for advanced tracking flexibility and easier tag management without code deployments.

🎯 Why Use Google Tag Manager?

Current Setup: Direct GA4 implementation via gtag.js
With GTM: Centralized tag management platform

Benefits

✅ No Code Deployments - Add/modify tags without changing code
✅ Multiple Tools - Manage GA4, ads, heatmaps, A/B testing in one place
✅ Version Control - Track all tag changes
✅ Testing Environment - Preview before publishing
✅ Team Collaboration - Multiple users with permissions
✅ Advanced Triggers - Complex tracking conditions
✅ Data Layer - Structured event data

When to Use GTM

Use GTM if you:

• Need to frequently add/modify tracking
• Want to add multiple analytics tools
• Have non-technical team members managing tags
• Need advanced e-commerce tracking
• Want sophisticated trigger conditions
• Need A/B testing or heatmap tools

Stick with gtag.js if you:

• Only use GA4
• Rarely modify tracking
• Prefer simpler implementation
• Have small team/solo developer
• Want minimal page weight

---

🚀 GTM Setup Guide

Step 1: Create GTM Account

1. Go to Google Tag Manager
2. Click Create Account
3. Fill in:
   • Account Name: 4SCH Documentation
   • Country: Nigeria (or your location)
   • Container Name: docs.4sch.com
   • Target Platform: Web
4. Click Create
5. Accept Terms of Service

Step 2: Install GTM Container

You'll receive two code snippets:

Head Snippet

<!-- Google Tag Manager -->
<script>(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>
<!-- End Google Tag Manager -->

Body Snippet

<!-- Google Tag Manager (noscript) -->
<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX"
height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
<!-- End Google Tag Manager (noscript) -->

Step 3: Add GTM to Docusaurus

Option A: Keep Current GA4 + Add GTM (Recommended for transition)

Add to docusaurus.config.js headTags:

{
  tagName: 'script',
  innerHTML: `
    (function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
    new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
    j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
    'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
    })(window,document,'script','dataLayer','GTM-XXXXXXX');
  `,
},

Add noscript via plugin at end of config:

module.exports.plugins.push(function(context, options) {
  return {
    name: 'docusaurus-plugin-gtm-noscript',
    injectHtmlTags() {
      return {
        postBodyTags: [
          {
            tagName: 'noscript',
            innerHTML: '<iframe src="https://www.googletagmanager.com/ns.html?id=GTM-XXXXXXX" height="0" width="0" style="display:none;visibility:hidden"></iframe>',
          },
        ],
      };
    },
  };
});

Option B: Replace GA4 with GTM (After testing)

1. Remove existing GA4 scripts from headTags
2. Add GTM snippets as shown above
3. Configure GA4 tag inside GTM

---

🏷️ Configure Tags in GTM

Tag 1: Google Analytics 4

Purpose: Replace or supplement direct GA4 implementation

1. Tags → New
2. Tag Configuration → Google Analytics: GA4 Configuration
3. Measurement ID: G-9DY20V8FQD
4. Configuration Settings:

   send_page_view: true
   anonymize_ip: true
   cookie_flags: SameSite=None;Secure

5. Triggering: All Pages
6. Save and name: "GA4 - Configuration"

Tag 2: GA4 Event - Page View

Purpose: Track all page views

1. Tags → New
2. Tag Configuration → Google Analytics: GA4 Event
3. Configuration Tag: Select "GA4 - Configuration"
4. Event Name: page_view
5. Triggering: All Pages
6. Save as "GA4 - Page View"

Tag 3: GA4 Event - Guide View

Purpose: Track guide section views

1. Tags → New
2. Tag Configuration → Google Analytics: GA4 Event
3. Configuration Tag: GA4 - Configuration
4. Event Name: guide_view
5. Event Parameters:
   • guide_type: {{Page Path}} (extract with variable)
   • page_path: {{Page Path}}
6. Triggering: Custom trigger (Page Path contains /guides/)
7. Save as "GA4 - Guide View"

Tag 4: GA4 Event - Search Open

Purpose: Track documentation search

1. Tag Configuration → Google Analytics: GA4 Event
2. Event Name: search_open
3. Event Parameters:
   • event_category: engagement
   • event_label: documentation_search
4. Triggering: Click - Search elements (custom trigger)
5. Save as "GA4 - Search Open"

Tag 5: GA4 Event - Code Copy

Purpose: Track code snippet copies

1. Tag Configuration → Google Analytics: GA4 Event
2. Event Name: code_copy
3. Event Parameters:
   • event_category: engagement
   • event_label: code_snippet_copied
4. Triggering: Click - Copy Button (custom trigger)
5. Save as "GA4 - Code Copy"

---

🎛️ Create Custom Triggers

Trigger 1: Guide Page View

1. Triggers → New
2. Trigger Type: Page View - DOM Ready
3. This trigger fires on: Some DOM Ready Events
4. Condition: Page Path contains /guides/
5. Save as "Page - Guide View"

Trigger 2: Search Click

1. Trigger Type: Click - All Elements
2. This trigger fires on: Some Clicks
3. Condition:
   • Click Element matches CSS selector .DocSearch OR
   • Click Element matches CSS selector [class*="search"]
4. Save as "Click - Search"

Trigger 3: Code Copy Click

1. Trigger Type: Click - All Elements
2. This trigger fires on: Some Clicks
3. Condition:
   • Click Element matches CSS selector button[class*="copy"] OR
   • Click Element matches CSS selector .copyButton
4. Save as "Click - Copy Button"

Trigger 4: External Link Click

1. Trigger Type: Click - All Elements
2. This trigger fires on: Some Clicks
3. Condition:
   • Click URL does NOT contain docs.4sch.com
   • Click Element matches CSS selector a[href^="http"]
4. Save as "Click - External Link"

Trigger 5: Download Click

1. Trigger Type: Click - All Elements
2. This trigger fires on: Some Clicks
3. Condition:
   • Click URL contains /download OR
   • Click Element has attribute download
4. Save as "Click - Download"

Trigger 6: Video Play

1. Trigger Type: YouTube Video
2. Capture: Player Progress (25%, 50%, 75%, 100%)
3. Add JavaScript API support: Yes
4. This trigger fires on: All Videos
5. Save as "Video - Play Events"

Trigger 7: Scroll Depth

1. Trigger Type: Scroll Depth
2. Vertical Scroll Depths: 25, 50, 75, 100
3. This trigger fires on: All Pages
4. Save as "Scroll - Depth Tracking"

---

📦 Create Variables

Built-in Variables

Enable these in Variables → Configure:

• ✅ Page Path
• ✅ Page URL
• ✅ Referrer
• ✅ Click Element
• ✅ Click URL
• ✅ Click Text
• ✅ Form Element
• ✅ Form ID
• ✅ Video URL
• ✅ Video Status
• ✅ Scroll Depth Threshold

Custom Variables

Variable 1: Guide Type

1. Variables → New → User-Defined
2. Variable Type: Custom JavaScript
3. Code:

   function() {
     var path = {{Page Path}};
     if (path.includes('/guides/')) {
       var parts = path.split('/');
       var guideIndex = parts.indexOf('guides');
       return parts[guideIndex + 1] || 'unknown';
     }
     return 'not_a_guide';
   }

4. Save as "Guide Type"

Variable 2: Documentation Section

1. Variable Type: Custom JavaScript
2. Code:

   function() {
     var path = {{Page Path}};
     var sections = ['intro', 'guides', 'reference', 'support'];
     for (var i = 0; i < sections.length; i++) {
       if (path.includes('/' + sections[i] + '/')) {
         return sections[i];
       }
     }
     return 'other';
   }

3. Save as "Documentation Section"

Variable 3: User Type (via Cookie)

1. Variable Type: 1st Party Cookie
2. Cookie Name: user_role
3. Save as "User Role Cookie"

---

🧪 Testing & Debugging

Preview Mode

1. Click Preview in GTM workspace
2. Enter: http://localhost:3000 or https://docs.4sch.com
3. Click Connect
4. Tag Assistant opens showing:
   • Tags fired
   • Tags not fired
   • Variables
   • Data layer
   • Errors

Debug Checklist

• ✅ GTM container loads
• ✅ GA4 config tag fires on all pages
• ✅ Page view event fires
• ✅ Custom events fire on correct triggers
• ✅ Variables populate correctly
• ✅ No duplicate events (if using both GTM + direct GA4)

Common Issues

Issue: Tags not firing
Solution: Check trigger conditions, verify CSS selectors

Issue: Duplicate events
Solution: Choose either GTM OR direct implementation, not both

Issue: Variables empty
Solution: Ensure built-in variables are enabled

---

📊 Data Layer Implementation

What is Data Layer?

Structured JavaScript object for passing data to GTM:

window.dataLayer = window.dataLayer || [];
dataLayer.push({
  'event': 'custom_event',
  'eventCategory': 'category',
  'eventAction': 'action',
  'eventLabel': 'label'
});

Enhanced Data Layer for Documentation

Add to docusaurus.config.js:

{
  tagName: 'script',
  innerHTML: `
    // Initialize data layer
    window.dataLayer = window.dataLayer || [];
    
    // Push page data on load
    document.addEventListener('DOMContentLoaded', function() {
      var pagePath = window.location.pathname;
      var pageData = {
        'event': 'page_data_ready',
        'page': {
          'path': pagePath,
          'title': document.title,
          'section': getDocSection(pagePath),
          'guideType': getGuideType(pagePath)
        },
        'user': {
          'role': getCookie('user_role') || 'unknown',
          'newUser': !getCookie('returning_user'),
          'sessionNumber': parseInt(getCookie('session_count') || '1')
        }
      };
      
      dataLayer.push(pageData);
    });
    
    function getDocSection(path) {
      if (path.includes('/intro/')) return 'intro';
      if (path.includes('/guides/')) return 'guides';
      if (path.includes('/reference/')) return 'reference';
      if (path.includes('/support/')) return 'support';
      return 'other';
    }
    
    function getGuideType(path) {
      if (!path.includes('/guides/')) return null;
      var parts = path.split('/');
      return parts[parts.indexOf('guides') + 1] || 'unknown';
    }
    
    function getCookie(name) {
      var value = '; ' + document.cookie;
      var parts = value.split('; ' + name + '=');
      if (parts.length === 2) return parts.pop().split(';').shift();
    }
  `,
}

Accessing Data Layer in GTM

1. Variables → New
2. Variable Type: Data Layer Variable
3. Data Layer Variable Name: page.section
4. Save as "DL - Page Section"

Repeat for:

• page.guideType → "DL - Guide Type"
• user.role → "DL - User Role"
• user.newUser → "DL - New User"

---

🔧 Advanced GTM Features

Custom HTML Tags

Example: Hotjar Heatmaps

1. Tags → New
2. Tag Type: Custom HTML
3. HTML:

   <script>
     (function(h,o,t,j,a,r){
       h.hj=h.hj||function(){(h.hj.q=h.hj.q||[]).push(arguments)};
       h._hjSettings={hjid:YOUR_HOTJAR_ID,hjsv:6};
       a=o.getElementsByTagName('head')[0];
       r=o.createElement('script');r.async=1;
       r.src=t+h._hjSettings.hjid+j+h._hjSettings.hjsv;
       a.appendChild(r);
     })(window,document,'https://static.hotjar.com/c/hotjar-','.js?sv=');
   </script>

4. Triggering: All Pages
5. Save as "Hotjar Tracking"

Tag Sequencing

Fire tags in specific order:

1. Edit any tag
2. Advanced Settings → Tag Sequencing
3. Setup Tag: Select tag to fire before
4. Cleanup Tag: Select tag to fire after

Tag Templates

Use community templates:

1. Tags → New
2. Discover more tag types in Community Template Gallery
3. Search for tools (e.g., "LinkedIn Insight Tag", "Facebook Pixel")
4. Add and configure

---

📋 Migration Plan: gtag.js → GTM

Phase 1: Preparation (Week 1)

• Create GTM account and container
• Document current GA4 events
• Set up GTM alongside existing tracking
• Configure GA4 tag in GTM
• Test in Preview mode

Phase 2: Parallel Tracking (Week 2-3)

• Deploy GTM to production
• Run both implementations
• Compare data accuracy
• Verify all events tracked
• Fix any discrepancies

Phase 3: Migration (Week 4)

• Remove direct GA4 code
• Keep only GTM implementation
• Monitor for 7 days
• Verify data continuity
• Document new setup

Phase 4: Enhancement (Week 5+)

• Add additional tools (heatmaps, A/B testing)
• Create advanced triggers
• Implement enhanced data layer
• Train team on GTM

---

🎓 GTM Best Practices

Organization

1. Naming Convention: Category - Description

   • Tags: GA4 - Event - Code Copy
   • Triggers: Click - Copy Button
   • Variables: DL - User Role

2. Folders: Group related items

   • Analytics Tags
   • Marketing Tags
   • Triggers - Clicks
   • Triggers - Page Views
   • Variables - Data Layer
   • Variables - Custom

3. Version Control

   • Name versions clearly: "v1.2 - Added video tracking"
   • Add descriptions
   • Tag who made changes

Testing

• ✅ Always use Preview mode before publishing
• ✅ Test on staging environment first
• ✅ Verify in GA4 Realtime reports
• ✅ Check for JavaScript errors
• ✅ Test on multiple devices/browsers

Performance

• ⚡ Minimize custom HTML tags
• ⚡ Use built-in tag types when possible
• ⚡ Avoid synchronous tags
• ⚡ Use tag firing limits for scroll/timer events
• ⚡ Clean up unused tags/triggers/variables

Security

• 🔒 Limit GTM user permissions
• 🔒 Review tag changes before publishing
• 🔒 Avoid exposing sensitive data in data layer
• 🔒 Use environment-specific containers for testing
• 🔒 Enable 2-factor authentication

---

🔗 Resources

• GTM Documentation
• GTM Fundamentals
• Data Layer Guide
• GTM Best Practices
• Community Templates

Internal:

• Analytics Setup: /reference/analytics-setup
• Dashboard Guide: /reference/ga4-dashboard-guide
• Conversions Guide: /reference/ga4-conversions-funnels

---

✅ Quick Decision Guide

Stay with Direct GA4 if:

• ✅ Only using Google Analytics
• ✅ Infrequent tracking changes
• ✅ Small team
• ✅ Prefer simplicity

Switch to GTM if:

• ✅ Need multiple tracking tools
• ✅ Frequent tracking updates
• ✅ Non-technical team members
• ✅ Want advanced control
• ✅ Planning A/B testing
• ✅ Need marketing pixels

Current recommendation: Continue with direct GA4 implementation unless you need the advanced features GTM provides. Our current setup is working well and covers all documentation analytics needs.

---

💡 Next Steps

If you decide to implement GTM:

1. Week 1: Create account, set up container, test in Preview
2. Week 2: Deploy alongside existing tracking
3. Week 3: Verify data accuracy
4. Week 4: Remove direct implementation if GTM working well
5. Week 5+: Add additional tools and advanced features

Support: Need help with GTM setup? Contact the technical team or refer to this guide.