Skip to main content

Google Tag Manager

This document explains how Google Tag Manager (GTM) integrates with our Hydrogen application, how analytics events flow through our system, and how to safely modify Heap-related tags in the GTM container.

Application Integration Overview​

Our GTM integration is handled through:

app/components/GoogleTagManager/googleTagManager.component.tsx

This file exports a GoogleTagManager component that listens for analytics events using the subscribe method from Hydrogen’s useAnalytics hook.

useAnalytics Subscription​

The application does not use a single enum for analytics events.
Instead, it uses multiple enums grouped by context, including:

  • CustomAnalyticsEvent
  • StandardAnalyticsEvent
  • CustomHomePageAnalyticsEvent
  • CustomLandingPageAnalyticsEvent
  • CustomPDPAnalyticsEvent
  • CustomLayoutAnalyticsEvent

Each enum represents a set of event names specific to a particular part of the application.
The GoogleTagManager component listens for all of them through the shared analytics subscription.

When an event occurs, the component calls our gtag function, which pushes an event into:

window.dataLayer

This allows GTM to receive and act on application-level analytics events.

Publishing Events From Components​

Components throughout the application publish events using:

publish(CustomAnalyticsEvent.SomeEventName, payload)

These must match the enum values exactly to be recognized by the GTM integration.

GTM Container Access​

You must have access to Birdy Grey’s GTM container.
Request access through management.

GTM Link - https://tagmanager.google.com

Container name: www.birdygrey.com

When you open it, your workspace will default to:

Default Workspace

This functions as GTM’s "main branch."

Workspace Limits​

GTM only allows 3 workspaces at a time.
Your workflow must be:

  1. Create a new workspace
  2. Make changes
  3. Publish changes
  4. Delete your workspace

GTM as the Gateway to Heap​

The flow of analytics is:

Application → gtag → window.dataLayer → GTM → Heap

GTM receives our application events and forwards them to Heap using tags configured inside the GTM UI.

Workflow for Updating Heap Events​

1. Create a Workspace​

Create a new workspace with a descriptive name for your changes.

2. Navigate to Tags​

Open the Tags tab in the left sidebar.

Heap event tags follow this naming format:

Heap - [Event Name]

3. Modify or Create a Tag​

Search for the tag you need.
Make your edits and click Save in the top-right corner.

4. Test Using Preview Mode​

Click Preview in the top header.
This launches Tag Assistant so you can verify tags are firing.

5. Publish to Staging​

Click Submit, select staging, and deploy changes.

Confirm the event works correctly on staging.

6. Deploy to Production​

After staging is verified:

  • Publish to production
  • Delete your workspace
  • GTM automatically creates a new version

Helpful Tips​

  • Install the Tag Assistant Chrome extension to view fired tags
  • Disable ad blockers to avoid blocking tracking
  • GTM custom JavaScript variable and tag scripts should avoid modern ES6+ syntax for maximum compatibility, meaning:
    • No arrow functions
    • No optional chaining
    • No trailing commas
  • You may create custom variables under: Variables → User-Defined Variables
    (Check for existing variables first.)

Summary​

  • GoogleTagManager listens to analytics events published by the app
  • Events must match the names in CustomAnalyticsEvent
  • Events push into window.dataLayer, which GTM uses to trigger Heap events
  • All GTM edits should occur in a temporary workspace
  • Test in Preview → publish to staging → publish to production → delete workspace