gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-gtm-integration/references/gtm-data-layer-ga4.md

GTM Data Layer Implementation for GA4

Data Layer Fundamentals

The data layer is a JavaScript object that acts as a bridge between your website and Google Tag Manager, holding structured data that GTM can access and send to GA4.

Data Layer Structure

window.dataLayer = window.dataLayer || [];

Key Concepts:

• Global JavaScript array
• Holds events and data
• GTM reads from this automatically
• Must exist BEFORE GTM container code

Basic Data Layer Push

dataLayer.push({
  'event': 'event_name',
  'parameter_key': 'parameter_value'
});

Components:

• event: Trigger name for GTM Custom Event triggers
• Additional keys: Data accessible via Data Layer Variables

Event Tracking Patterns

Pattern 1: Simple Event

On Website:

dataLayer.push({
  'event': 'button_click',
  'button_name': 'Subscribe Now',
  'button_location': 'header'
});

In GTM:

1. Create Trigger:

   • Type: Custom Event
   • Event name: button_click

2. Create Variables:

   • Name: "DL - Button Name"
   • Type: Data Layer Variable
   • Variable Name: button_name

3. Create GA4 Tag:

   • Event Name: button_click
   • Parameters: button_name → {{DL - Button Name}}

Pattern 2: E-commerce Event

On Website:

dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {
    'items': [
      {
        'item_id': 'SKU_123',
        'item_name': 'Blue T-Shirt',
        'price': 29.99,
        'quantity': 1,
        'item_category': 'Apparel'
      }
    ],
    'value': 29.99,
    'currency': 'USD'
  }
});

In GTM:

1. Create Variable for items:

   • Name: "DL - Ecommerce Items"
   • Type: Data Layer Variable
   • Variable Name: ecommerce.items

2. Create GA4 Event Tag:

   • Event Name: add_to_cart
   • Parameters:
     • items → {{DL - Ecommerce Items}}
     • value → {{DL - Ecommerce Value}}
     • currency → {{DL - Ecommerce Currency}}

Pattern 3: Purchase Event (Complete)

On Website:

dataLayer.push({
  'event': 'purchase',
  'ecommerce': {
    'transaction_id': 'T_12345',
    'affiliation': 'Online Store',
    'value': 99.98,
    'currency': 'USD',
    'tax': 8.00,
    'shipping': 5.00,
    'coupon': 'SUMMER20',
    'items': [
      {
        'item_id': 'SKU_123',
        'item_name': 'Blue T-Shirt',
        'price': 29.99,
        'quantity': 2,
        'item_category': 'Apparel',
        'item_brand': 'MyBrand'
      },
      {
        'item_id': 'SKU_124',
        'item_name': 'Black Hat',
        'price': 20.00,
        'quantity': 2,
        'item_category': 'Accessories'
      }
    ]
  }
});

In GTM:

Create Data Layer Variables for:

• ecommerce.transaction_id
• ecommerce.value
• ecommerce.currency
• ecommerce.tax
• ecommerce.shipping
• ecommerce.items

Create GA4 Event Tag mapping all parameters.

Pattern 4: Form Submission

On Website:

document.getElementById('contact-form').addEventListener('submit', function(e) {
  e.preventDefault();

  dataLayer.push({
    'event': 'form_submit',
    'form_name': 'Contact Form',
    'form_id': 'contact-form',
    'form_destination': '/thank-you',
    'user_email_domain': document.getElementById('email').value.split('@')[1]
  });

  // Then submit form
  this.submit();
});

Pattern 5: Video Tracking

On Website:

// When video starts
dataLayer.push({
  'event': 'video_start',
  'video_title': 'Product Demo',
  'video_duration': 180,
  'video_id': 'demo_v1'
});

// When video completes
dataLayer.push({
  'event': 'video_complete',
  'video_title': 'Product Demo',
  'video_percent': 100,
  'video_id': 'demo_v1'
});

Advanced Patterns

Pattern 6: User Authentication

On Login:

dataLayer.push({
  'event': 'login',
  'method': 'email',
  'user_id': 'user_12345',
  'user_tier': 'premium',
  'years_customer': 3
});

On Logout:

dataLayer.push({
  'event': 'logout',
  'user_id': null  // Clear user ID
});

Pattern 7: Page Data (For SPAs)

On Route Change (Single Page Apps):

// React example
useEffect(() => {
  dataLayer.push({
    'event': 'virtual_page_view',
    'page_path': window.location.pathname,
    'page_title': document.title,
    'page_category': 'products'
  });
}, [location]);

Pattern 8: Search Tracking

On Search:

dataLayer.push({
  'event': 'search',
  'search_term': searchQuery,
  'search_results_count': resultsCount,
  'search_category': selectedCategory
});

Data Layer Variable Types in GTM

Type 1: Simple Data Layer Variable

Configuration:

• Variable Type: Data Layer Variable
• Data Layer Variable Name: product_id
• Data Layer Version: Version 2

Usage: {{DL - Product ID}}

Type 2: Nested Object Access

For Nested Data:

dataLayer.push({
  'ecommerce': {
    'value': 99.99,
    'items': [...]
  }
});

Variable Configuration:

• Variable Name: "DL - Ecommerce Value"
• Type: Data Layer Variable
• Variable Name: ecommerce.value

Type 3: Array Access

For Array Elements:

dataLayer.push({
  'items': [
    {'item_id': 'SKU_123'},
    {'item_id': 'SKU_124'}
  ]
});

Variable for First Item:

• Variable Name: items.0.item_id (first array element)

Better: Pass entire items array to GA4 event parameter

Timing and Order

Rule 1: Data Layer BEFORE GTM Container

<script>
  window.dataLayer = window.dataLayer || [];
  // Can push initial page data here
  dataLayer.push({
    'page_type': 'product',
    'user_tier': 'premium'
  });
</script>

<!-- GTM Container Code -->
<script>(function(w,d,s,l,i){...})(window,document,'script','dataLayer','GTM-XXXXXXX');</script>

Rule 2: Event Push AFTER User Action

// CORRECT
button.addEventListener('click', function() {
  dataLayer.push({
    'event': 'button_click',
    'button_name': 'Subscribe'
  });
});

// WRONG - Fires on page load before click
dataLayer.push({
  'event': 'button_click',
  'button_name': 'Subscribe'
});

Rule 3: Clear ecommerce Before Push

For E-commerce Events:

// Clear previous ecommerce data
dataLayer.push({ ecommerce: null });

// Push new ecommerce data
dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {
    'items': [...]
  }
});

Why: Prevents old ecommerce data from persisting

SPA (Single Page Application) Patterns

React Example

import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';

function App() {
  const location = useLocation();

  useEffect(() => {
    // Track virtual page view on route change
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      'event': 'virtual_page_view',
      'page_path': location.pathname,
      'page_title': document.title
    });
  }, [location]);

  return <div>...</div>;
}

Vue.js Example

// In router/index.js
router.afterEach((to, from) => {
  window.dataLayer = window.dataLayer || [];
  window.dataLayer.push({
    'event': 'virtual_page_view',
    'page_path': to.path,
    'page_title': to.meta.title || document.title
  });
});

Debugging Data Layer

Console Debugging

// View entire data layer
console.log(window.dataLayer);

// View last event pushed
console.log(window.dataLayer[window.dataLayer.length - 1]);

// Listen for pushes
var originalPush = window.dataLayer.push;
window.dataLayer.push = function() {
  console.log('Data Layer Push:', arguments);
  return originalPush.apply(this, arguments);
};

GTM Preview Mode

Steps:

1. Click Preview in GTM
2. Interact with website
3. Tag Assistant shows:
   • Data Layer tab with all pushed events
   • Event details and parameters
   • Values of variables at time of event

Common Mistakes

Mistake 1: Pushing Empty Events

// BAD - No data
dataLayer.push({
  'event': 'button_click'
});

// GOOD - Include context
dataLayer.push({
  'event': 'button_click',
  'button_name': 'Subscribe',
  'button_location': 'header'
});

Mistake 2: Not Clearing ecommerce

// BAD - Old ecommerce data persists
dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {...}
});

// GOOD
dataLayer.push({ ecommerce: null });
dataLayer.push({
  'event': 'add_to_cart',
  'ecommerce': {...}
});

Mistake 3: Using Reserved Keys

Avoid These Keys:

• gtm (reserved by GTM)
• google_tag_manager (reserved)
• event (only for trigger names)

Mistake 4: Wrong Data Types

// BAD - String when should be number
dataLayer.push({
  'event': 'purchase',
  'value': '99.99'  // String
});

// GOOD
dataLayer.push({
  'event': 'purchase',
  'value': 99.99  // Number
});

Best Practices

1. Initialize Early: Create window.dataLayer before GTM container
2. Consistent Naming: Use snake_case for event and parameter names
3. Clear ecommerce: Always clear before pushing new ecommerce data
4. Document Events: Maintain documentation of all custom events
5. Test Thoroughly: Use GTM Preview mode to verify data layer pushes
6. Avoid PII: Don't push personal data (emails, names, addresses)
7. Use Structured Data: Follow GA4 recommended event structures