zhongwei/gh-henkisdabro-wookstar-claude-code-plugins-gtm-suite

Fork 0

Files

Zhongwei Li c02dafae1d Initial commit

2025-11-29 18:32:45 +08:00

15 KiB

Raw Permalink Blame History

Google Tag Manager - Debugging and Testing

Sources:

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

Navigate to GTM at https://tagmanager.google.com
Open your container workspace
Click "Preview" in the top right corner
Tag Assistant launches in a new tab
Enter your website URL
Optional: Uncheck "Include debug signal in the URL" if it breaks your site
Click "Connect"
Your website opens in a new window with "Connected" indicator
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 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:

Go to Versions in your workspace navigation
Find the version to preview
Click More Actions (three dots)
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:

{
  "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

To let others view your debug session:

In Tag Assistant, click More Actions (three dots)
Select "Share"
Enter your website domain
Copy the preview URL
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.

From the Versions tab:

Click More Actions on any version
Select Share Preview
Enter target website domain
Copy and share the preview URL

Debugging Common Scenarios

Tag Not Firing

Checklist:

Check the trigger
- Is the trigger configured correctly?
- Are the trigger conditions being met?
- Check trigger variables resolve correctly
Check for blocking triggers
- Does the tag have any exception/blocking triggers?
- Are those triggers inadvertently activating?
Check tag priority/sequencing
- Does another tag need to fire first?
- Is tag sequencing configured correctly?
Check the data layer
- Is required data present when trigger evaluates?
- Are data layer variables returning expected values?

Trigger Not Activating

Debugging Steps:

Verify trigger conditions

Example: Click trigger on CSS selector
- Check selector syntax
- Verify element exists on page
- Test with simpler selector

Check built-in variables
- Are required built-in variables enabled?
- Click Variables > Configure
- Enable missing variables
Test variable values
- Check Variables panel
- Verify trigger conditions match actual values
- Look for type mismatches (string vs number)

Variable Returning Undefined

Common Causes:

Data layer variable not found

// Data layer:
{ "product_name": "Widget" }

// Variable configured as:
productName  // Wrong - case sensitive!

// Should be:
product_name  // Correct

Timing issue
- Data pushed after tag fires
- Use Custom Event trigger to wait for data
Incorrect data layer version
- Check Data Layer Version setting
- Version 2 vs Version 1 syntax differs

Data Layer Issues

Debug Pattern:

// 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:

Check browser console (F12 > Console)
Look for errors before tag execution
Verify vendor scripts load correctly
Check for conflicts between tags
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:

{
  "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:

Development Environment
- Test unstable/experimental changes
- Break things without consequence
- Rapid iteration
Staging Environment
- Test on staging server
- QA team validation
- Stakeholder review
Production Environment
- Live site
- Real user data
- Careful change management

Cross-Domain Testing

When testing cross-domain tracking:

Enable preview on primary domain
Navigate to secondary domain
Verify preview mode persists
Check data layer for linker parameters
Confirm client IDs match across domains

Version Comparison

Compare container versions:

Go to Versions
Select two versions
Click Compare
Review differences:
- Tags added/removed/modified
- Trigger changes
- Variable updates

Browser Developer Tools

Network Tab

Monitor tag requests:

Open DevTools (F12)
Go to Network tab
Filter: "analytics", "gtm", "google-analytics"
Trigger events on your site
Inspect requests:
- Check parameters sent
- Verify timing
- Look for errors (red status codes)

Console Tab

Monitor JavaScript execution:

// 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:

Open Application tab
Go to Cookies
Select your domain
Check for:
- _ga (GA client ID)
- _gid (GA session ID)
- Custom cookies

GA4 DebugView

For GA4-specific debugging:

Enable debug mode in GTM:

// Add to data layer
window.dataLayer.push({
  'debug_mode': true
});

Or use Chrome extension: Google Analytics Debugger
Open GA4 DebugView:
- Go to GA4 property
- Navigate to Configure > DebugView
- See real-time events from your debug session
Verify in DebugView:
- Events appear immediately
- Parameters are correct
- Event sequence matches expectations

Common Debugging Patterns

Test Ecommerce Flow

// 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

// 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

// 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:

// In console:
google_tag_manager['GTM-XXXXX'].dataLayer.get('gtm.version')

Verify Container ID

Ensure correct container on page:

<!-- 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

Test before publishing - Always use preview mode
Test on real pages - Not just homepage
Test user journeys - Complete flows, not just individual pages
Document your tests - Use version notes
Get peer review - Have colleagues review in preview mode
Test with real data - Use production-like scenarios

Debugging Best Practices

Start simple - Test one thing at a time
Check the basics first - Is GTM loading? Is the tag enabled?
Use the data layer - Don't rely on page scraping
Log everything - Use version notes to document changes
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:

Click X in Tag Assistant debug interface
Click "Stop debugging" on Tag Assistant page
Close preview window

Preview mode only affects your browser - regular visitors don't see the debug interface.

15 KiB Raw Permalink Blame History