React Google Tag Manager with Server-Side Tagging

Common errors

• ReferenceError: TagManager is not defined

  cause The `TagManager` object was not correctly imported or the library was not installed.
  fix Ensure you have `npm install react-server-side-gtm` and use `import TagManager from 'react-server-side-gtm';` at the top of your file.

• GTM events are not appearing in Google Analytics, Tag Manager Debugger, or your GTM server container.

  cause Incorrect `gtmId`, missing `src` for server-side tagging, or events are not correctly pushed to the dataLayer.
  fix Double-check your `gtmId` for typos. If using server-side tagging, ensure the `src` parameter in `TagManager.initialize` points to your active GTM server container URL. Verify that `TagManager.dataLayer` calls include an `event` key and necessary parameters.

• Custom dataLayer values (e.g., `userId`, `userProject`) are not present or are overwritten in GTM.

  cause The initial `TagManager.initialize` call didn't include the custom dataLayer, or a subsequent `TagManager.initialize` call overwrote it instead of pushing new data.
  fix Ensure all initial `dataLayer` variables are passed in the `dataLayer` object during the initial `TagManager.initialize` call. For subsequent updates, use `TagManager.dataLayer({ dataLayer: { /* new data */ } })` to merge new data without overwriting.

Warnings

• breaking This library is a fork of `react-gtm-module`. While the API is largely compatible, users migrating from the original package should review documentation for potential behavioral changes, new features, or slight API discrepancies introduced in `v3.0.0` and later.
  Fix: Thoroughly review the `react-server-side-gtm` README and API documentation for specific differences when migrating from `react-gtm-module`. Test your GTM integrations comprehensively after upgrading.
• gotcha For server-side tagging to function correctly, your Google Tag Manager container and Google Cloud Platform setup must be configured specifically for server-side GTM. Simply installing this library is not sufficient.
  Fix: Ensure your Google Tag Manager container has a server-side client, and that your GTM server-side endpoint (e.g., `src` parameter in `TagManager.initialize`) points to your deployed GTM server container URL (e.g., `https://your-custom-gtm-server.com`). Refer to Google's official server-side tagging documentation.
• gotcha Calling `TagManager.initialize` multiple times with different dataLayer configurations can lead to unexpected behavior or data loss, as it re-initializes the GTM script and dataLayer.
  Fix: Call `TagManager.initialize` only once, typically at your application's root component or entry point. For subsequent data pushes or event triggers, use `TagManager.dataLayer` method to update the dataLayer safely.

Install

• npm install react-server-side-gtm npm
• yarn add react-server-side-gtm yarn
• pnpm add react-server-side-gtm pnpm

Imports

• TagManager
  wrong:

  const TagManager = require('react-server-side-gtm');

  correct:

  import TagManager from 'react-server-side-gtm';

  The library primarily uses ES Module syntax. CommonJS `require` is not officially supported and may lead to issues, especially in modern React build environments.
• TagManager.initialize
  wrong:

  TagManager.init({ gtmId: 'GTM-XXXXXX' });

  correct:

  TagManager.initialize({ gtmId: 'GTM-XXXXXX' });

  Ensure you call `initialize` only once, typically at your application's entry point. Subsequent data pushes should use `TagManager.dataLayer`.
• TagManager.dataLayer
  wrong:

  TagManager.initialize({ dataLayer: { event: 'my_event' } });

  correct:

  TagManager.dataLayer({ dataLayer: { event: 'my_event' } });

  After initial setup, use `dataLayer` to push new events or data to the GTM dataLayer. Do not call `initialize` again for subsequent pushes.

Quickstart

This quickstart initializes Google Tag Manager upon component mount, pushes initial page view data to the dataLayer, and demonstrates how to push custom events triggered by user actions or asynchronous operations, incorporating environment variables for GTM ID.

import React, { useEffect } from 'react';
import TagManager from 'react-server-side-gtm';

const GtmInitializer = () => {
  useEffect(() => {
    const gtmId = process.env.NEXT_PUBLIC_GTM_ID ?? 'GTM-XXXXXX'; // Use env var or default

    if (gtmId === 'GTM-XXXXXX') {
      console.warn('GTM ID is not configured. Using placeholder GTM-XXXXXX. Please set NEXT_PUBLIC_GTM_ID.');
    }

    // Initialize GTM when the component mounts
    TagManager.initialize({
      gtmId: gtmId,
      dataLayer: {
        event: 'page_view',
        pagePath: window.location.pathname,
        pageTitle: document.title,
        userId: 'USER_12345', // Example custom user ID
        userProject: 'web_application',
      },
      // Optional: Specify a custom dataLayer name if needed
      // dataLayerName: 'myCustomDataLayer',
      // Optional: Configure custom GTM server-side container endpoint
      // src: 'https://your-custom-gtm-server.com',
    });

    // Simulate a user action after some time
    const timer = setTimeout(() => {
      TagManager.dataLayer({
        dataLayer: {
          event: 'promo_view',
          promotionId: 'SUMMER_SALE',
          position: 'top_banner'
        },
      });
      console.log('Pushed a simulated promo_view event to dataLayer.');
    }, 3000);

    return () => clearTimeout(timer);
  }, []);

  const handleProductClick = (productId) => {
    TagManager.dataLayer({
      dataLayer: {
        event: 'product_click',
        productId: productId,
        category: 'Electronics',
        list: 'Search Results'
      },
    });
    alert(`Product ${productId} clicked! Event sent to GTM.`);
  };

  return (
    <div>
      <h1>Welcome to your Application!</h1>
      <p>This page integrates Google Tag Manager for analytics and server-side tagging.</p>
      <button onClick={() => handleProductClick('P1001')}>View Product P1001</button>
      <p>Open your browser's developer tools and check the Network tab or GTM Debugger for dataLayer events.</p>
    </div>
  );
};

export default GtmInitializer;