/gtm-setup

name: gtm-setup
description: GTM Event Tracking & Setup Reference — dataLayer fundamentals, trigger types, variable types, GA4 tag configuration, debug mode, and best practices
version: "1.1.1"
author: Cogny AI
platforms: []
user-invocable: true
argument-hint: "<topic or question>"
allowed-tools:
  - WebFetch
  - WebSearch
  - Bash
  - Read
  - Write
  # GTM tools (when connected via Cogny MCP)
  - mcp__cogny__list_integrations
  - mcp__cogny__refresh_mcp_discovery
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_accounts
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_containers
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_tags
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_triggers
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_variables
  - mcp__cogny__mcp__Google_Tag_Manager__tool_get_tag
  - mcp__cogny__mcp__Google_Tag_Manager__tool_get_trigger
  - mcp__cogny__mcp__Google_Tag_Manager__tool_get_variable
  - mcp__cogny__mcp__Google_Tag_Manager__tool_get_workspace_status
  - mcp__cogny__mcp__Google_Tag_Manager__tool_search_tags
  - mcp__cogny__mcp__Google_Tag_Manager__tool_list_workspaces
  - mcp__cogny__mcp__Google_Tag_Manager__tool_audit_container_privacy
  # Verification when connected (read-only)
  - mcp__cogny__mcp__Google_Analytics_4__tool_list_account_summaries
  - mcp__cogny__mcp__Google_Analytics_4__tool_run_realtime_report
  - mcp__cogny__mcp__Microsoft_Clarity__get_live_insights

GTM Event Tracking & Setup Reference

Complete reference guide to Google Tag Manager event tracking, including dataLayer fundamentals, trigger and variable types, GA4 tag configuration, debug mode, and implementation best practices.

Full docs: https://cogny.com/docs/gtm-event-tracking

Usage

/gtm-setup                              # Full GTM reference overview
/gtm-setup dataLayer                    # dataLayer fundamentals and syntax
/gtm-setup purchase                     # Show purchase event dataLayer.push()
/gtm-setup triggers                     # All trigger types explained
/gtm-setup variables                    # All variable types explained
/gtm-setup tags                         # GA4 tag configuration
/gtm-setup debug                        # Debug mode and troubleshooting
/gtm-setup best practices               # Naming conventions, organization
/gtm-setup common mistakes              # Race conditions, missing data, duplicates

Instructions

You are a Google Tag Manager expert. Use this reference to help users implement event tracking, configure tags/triggers/variables, debug GTM issues, and follow best practices.

When the user asks a question, find the relevant section below and provide precise, actionable answers with ready-to-use code snippets.

If the user provides a specific topic as an argument, focus on that area. Otherwise, provide an overview of GTM concepts and ask what they need help with.

If Cogny GTM MCP tools are available, use them to inspect the user's actual GTM container, list their tags/triggers/variables, and provide recommendations based on their real configuration.

Works with

Works with zero accounts: everything below is reference and copy-paste code.

| Job | Without accounts | Enhanced when connected | |-----|------------------|-------------------------| | Read the real container | — | GTM `tool_list_tags`, `tool_list_triggers`, `tool_list_variables`, `tool_audit_container_privacy` | | Build tags / triggers / variables | user clicks it in GTM | GTM write tools (asks first; see "Building in the connected container") | | Verify the event arrives | GTM Preview + DebugView | GA4 `tool_run_realtime_report` | | Check a Custom HTML tag didn't break pages | Console | Microsoft Clarity `get_live_insights` (Script Error Count) |

---

dataLayer Fundamentals

What Is the dataLayer?

The `dataLayer` is a JavaScript array that acts as a message bus between your website and GTM. When you push objects onto the dataLayer, GTM reads them to fire triggers and populate variables.

Initialization

Declare the dataLayer before the GTM snippet to capture early pushes:

<script>
  window.dataLayer = window.dataLayer || [];
</script>
<!-- GTM snippet follows -->

dataLayer.push() Syntax

// Push data AND fire a trigger (event key is required for trigger evaluation)
dataLayer.push({
  'event': 'custom_event_name',
  'key1': 'value1',
  'key2': 'value2'
});

// Push data without firing a trigger (no 'event' key)
dataLayer.push({
  'user_type': 'premium',
  'user_id': '12345'
});

Object Persistence and Merging

Later pushes override earlier values for the same key. GTM's data model merges nested objects (and arrays, by index) **recursively**: only the keys you push are updated, everything else is kept.

dataLayer.push({ 'user': { 'name': 'John', 'plan': 'free' } });
dataLayer.push({ 'user': { 'plan': 'premium' } });
// Result: user = { name: 'John', plan: 'premium' } — user.name survives

That recursive merge is why stale e-commerce data leaks from one event into the next, and why you push `{ ecommerce: null }` first.

Clearing Stale Data (Critical for E-Commerce)

Always push `null` before e-commerce events to prevent stale data contamination:

dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'view_item',
  'ecommerce': {
    'items': [{ 'item_id': 'SKU-001', 'item_name': 'Blue T-Shirt', 'price': 29.99 }]
  }
});

Common dataLayer Events

page_view

dataLayer.push({
  'event': 'page_view',
  'page_location': window.location.href,
  'page_title': document.title,
  'page_referrer': document.referrer,
  'content_group': 'blog'
});

For SPAs (React, Next.js, Vue), fire on route change:

useEffect(() => {
  dataLayer.push({
    'event': 'page_view',
    'page_location': window.location.href,
    'page_title': document.title
  });
}, [location.pathname]);

purchase

dataLayer.pu