DataLayer

The dataLayer is the contract between your website and your analytics tools. Every piece of tracking data — product impressions, cart actions, conversions, custom interactions — travels through it. Get the contract right and your analytics becomes a reliable foundation for business decisions. Get it wrong and you’re building dashboards on sand.

This section covers everything from naming conventions to platform-specific implementations. Whether you’re designing a new tracking specification, implementing GA4 ecommerce events, or validating what you’ve already built, you’ll find the definitive reference here.

Tip

New to the dataLayer? Start with the DataLayer Deep Dive in the Foundations section before diving into these specifications. It explains the core mechanics — push semantics, GTM’s merge model, the ecommerce null clear pattern — that everything here builds on.

Specification

Design your dataLayer right from the start. These articles cover the naming rules, data types, and versioning strategies that determine whether your implementation scales or collapses under its own complexity.

Naming Conventions The definitive naming rules for events and parameters — snake_case, reserved prefixes, consistency rules.

Event Naming Rules When to use GA4 recommended events vs. custom events, the 40-character limit, and anti-patterns to avoid.

Parameter Naming Rules Custom parameter conventions, GA4 limits, reserved names, and strategies for parameter reuse.

Data Types Standards for strings, numbers, booleans, arrays, and objects — including common mistakes with prices and currencies.

Versioning Strategy How to version your dataLayer spec, manage breaking changes, and support multiple versions simultaneously.

Designing Custom Events A systematic framework for designing new events — decision trees, documentation templates, and review processes.

Ecommerce Events

The GA4 ecommerce event specification defines a funnel from product discovery to purchase. Each event in this section maps directly to a stage in that funnel and connects to the next. Implement them in order — view_item_list feeds select_item, which feeds view_item, which feeds the cart and checkout events, which feed purchase.

Ecommerce Overview The complete GA4 ecommerce funnel — event flow, the items array structure, currency handling, and the ecommerce null clear pattern.

view_item_list Product list impressions — category pages, search results, recommendation widgets.

select_item User clicks a product in a list — linking list context to the product detail page.

view_item Product detail page views — the full item specification with variants.

add_to_cart Adding products to the cart — quantity handling, quick-add patterns.

remove_from_cart Removing products from the cart — full removal vs. quantity reduction.

view_cart Cart page views — full cart contents with total value calculation.

begin_checkout Checkout initiation — capturing cart contents and coupon codes at checkout start.

add_shipping_info Shipping step completion — shipping tier and full item details.

add_payment_info Payment step completion — payment method type and checkout totals.

purchase Order confirmation — the most critical event. Deduplication, transaction parameters, and validation.

refund Full and partial refunds — server-side implementation and Measurement Protocol.

view_promotion / select_promotion Internal promotion tracking — banners, featured offers, recommendation modules.

Custom Events

Beyond ecommerce, you’ll need events that reflect your specific product interactions. These articles cover the standard patterns for authentication, search, forms, content engagement, and errors — plus a guide to designing your own events from scratch.

Login & Sign Up GA4 recommended login and sign_up events — method parameter, user_id, and privacy considerations.

Search Site search tracking — search_term, results count, zero-result queries, and filter interactions.

Form Submission Form tracking across types — contact, lead gen, newsletter, multi-step forms, and error events.

Content Engagement Article reads, video plays, content shares — events for content-heavy properties.

Error Events Application errors, 404s, API failures, and JS errors — structured error tracking for debugging.

Custom Event Design Hands-on guide to building new events — when to create, how to document, how to test.

Platform Guides

Platform-specific implementation guides. Each covers the quirks, hooks, and patterns specific to that platform — from Shopify’s Custom Pixels sandbox to WooCommerce’s AJAX cart to Next.js App Router route tracking.

Shopify GTM installation, theme.liquid dataLayer, Customer Events API, checkout limitations.

Shopify Custom Pixels The sandboxed Custom Pixel environment — what GTM can and can't do inside it.

Shopify Checkout Extensibility How the checkout.liquid deprecation changes your tracking strategy.

Shopify Headless Tracking on Hydrogen, Next.js, and other headless Shopify storefronts.

Shopify Advanced Post-purchase upsells, subscriptions, multi-currency, B2B, and server-side tracking.

WooCommerce PHP hooks, AJAX cart, checkout events, and thank you page deduplication.

WooCommerce Advanced GTM4WP deep configuration, variable products, subscriptions, HPOS compatibility.

Magento / Adobe Commerce Magento 2 frontend architecture, layout XML, JavaScript mixins, full page cache.

Next.js App Router vs Pages Router, route tracking, Server/Client Components, typed dataLayer.

Nuxt.js Nuxt 3 plugin, route middleware, composable-based tracking, TypeScript support.

WordPress Plugin options, manual implementation via functions.php, WP hooks, form integrations.

Validation

Bad data in equals bad decisions out. These articles cover every layer of the validation stack — from TypeScript compile-time checks to runtime Zod schemas to automated Playwright tests running in CI.

Validation Approaches The validation pyramid — development, staging, production. Which tools for which layer.

TypeScript Schemas Complete TypeScript types for the GA4 ecommerce dataLayer — discriminated unions, type-safe push wrappers.

Runtime Validation Zod schemas, dataLayer interceptor pattern, error reporting, dev vs. production modes.

Automated Testing Playwright and Cypress tests for the complete ecommerce funnel — CI/CD integration.