react-gtm-module-overide

React Google Tag Manager Module

A JS module for React-based apps that implements Google Tag Manager (GTM). It is designed so that the GTM snippet can be injected and used with minimal effort.

Features:

• Support for Content Security Policy (nonce)
• Custom GTM script URL for server-side tagging
• URL parameter renaming via paramMapping to mask GTM fingerprints
• TypeScript definitions included

Getting Started

npm install react-gtm-module-overide
# OR
yarn add react-gtm-module-overide

In your React application's entry file (src/index.js or src/index.ts):

import React from 'react'
import ReactDOM from 'react-dom/client'
import App from './App'
import TagManager from 'react-gtm-module-overide'

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
})

const root = ReactDOM.createRoot(document.getElementById('root'))
root.render(
    <React.StrictMode>
        <App />
    </React.StrictMode>,
)

Interact with the dataLayer

import TagManager from 'react-gtm-module-overide'

TagManager.dataLayer({
    dataLayer: {
        event: 'home_viewed',
    },
})

If you are using multiple dataLayers you can specify which one to use:

TagManager.dataLayer({
    dataLayer: {
        event: 'identified',
        userId: 'dc26b3de-5186-4fa5-a89a-60762111a5b4',
    },
    dataLayerName: 'personalInformation',
})

Configuration

| Value | Type | Required | Notes | | ------------------------------------------ | ------------------ | -------- | ----------------------------------------------------------------------------- | | gtmId | String | Yes | The ID of your GTM Container. | | dataLayer | Object | No | Information added to the dataLayer before initialization. | | dataLayerName | String | No | Customize the name of the dataLayer object. | | events | Array of Objects | No | Additional events added to the dataLayer during initialization. | | auth | String | No | The gtm_auth query parameter for GTM environments. | | preview | String | No | The gtm_preview query parameter for GTM environments. | | nonce | String | No | Set the nonce for Content Security Policy. | | source | String | No | Custom GTM script URL for server-side tagging. | | paramMapping | Object | No | Rename URL query parameters to mask GTM fingerprints. |

dataLayer

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    dataLayer: {
        currency: 'USD',
        language: 'en',
    },
})

dataLayerName

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    dataLayerName: 'personalInformation',
})

events

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    events: [
        {
            event: 'consent_loaded',
            consentAnalytics: true,
            consentAds: false,
        },
    ],
})

auth & preview (Environments)

Both properties must be set together. Extract the values from your GTM container: Admin -> Environments -> Actions -> Get Snippet.

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    auth: '6sBOnZx1hqPcO01xPOytLK',
    preview: 'env-staging',
})

nonce

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    nonce: 'KCenr5lELncZ6JJlHmerd9aIjddJfBEZ',
})

source

Overwrite the default GTM script URL (https://googletagmanager.com/gtm.js) with a custom one, typically for server-side tagging.

TagManager.initialize({
    gtmId: 'GTM-xxxxxx',
    source: 'https://gtm.example.com/gtm.js',
})

paramMapping

Rename the URL query parameters used in the GTM script and iframe URLs. Only specify the keys you want to rename — others keep their defaults.

Available keys: id, gtm_auth, gtm_preview, gtm_cookies_win, l, noscriptPath.

TagManager.initialize({
    gtmId: '544PSS2',
    source: 'https://acq.example.com/script.js',
    paramMapping: {
        id: 'awl',
        gtm_auth: 'a',
        gtm_preview: 'p',
        gtm_cookies_win: 'c',
        l: 'dl',
        noscriptPath: '/collect',
    },
})

This generates URLs like https://acq.example.com/script.js?awl=544PSS2 instead of the default ?id=GTM-xxxxxx, helping to mask GTM fingerprints.

License

MIT