@phntms/next-gtm
A lightweight Next library to implement custom Google Tag Manager events.
Introduction
Extends @phntms/react-gtm with native support for Next.JS 12, utilizing the new Script Component to automatically prioritize loading of third-party scripts to improve performance.
Installation
Install this package with npm.
npm i @phntms/next-gtm
Usage
<TrackingHeadScript />
| Property | Type | Default | Notes |
|---|
| id | string | undefined | ID that uniquely identifies GTM Container. Example format: GTM-xxxxxx. |
| disable | boolean | false | Used to disable tracking events (isGTM=false only). Use if you want user to consent to cookies first |
| isGTM | boolean | false | Loads the gtag.js script by default (legacy behaviour - compatible with UA/GA4/GTM), else, loads gtm.js. |
| GTMAuth | string | undefined | (isGTM = true required) Optional parameter to load a non-default GTM environment, e.g. for testing GTM. |
| GTMPreview | string | undefined | (isGTM = true required) Optional parameter to load a non-default GTM environment, e.g. for testing GTM. |
To initialize GTM, add TrackingHeadScript to the head of the page.
This package utilizes next/script, which means you can't place it inside a next/head. Further, TrackingHeadScript should not be used in pages/_document.js as next/script has client-side functionality to ensure loading order.
The isGTM, GTMAuth and GTMPreview optional properties are a backwards-compatible update to provide multiple GTM environment support to this library. Using multiple GTM container environments allow developers to test different GTM config versions on a preview codebase before publishing the change to the production GTM container.
- If the project is known to be using GTM - the
isGTM should be set to true regardless of the environment (the default false will continue to function though).
- Typically you want to set the
GTMAuth and GTMPreview properties (obtained from the GTM preview environment script snippet) via optional environment variables in the applications' preview environments - when left as undefined - GTM will default to the master (production) container config.
Example usage:
import type { AppProps } from "next/app";
import { TrackingHeadScript } from "@phntms/next-gtm";
const GA_TRACKING_ID = process.env.NEXT_PUBLIC_GA_TRACKING_ID || "";
const App = ({ Component }: AppProps) => (
<>
<TrackingHeadScript id={GA_TRACKING_ID} isGTM={true} />
<Component />
</>
);
export default App;
Note: If used alongside any cookie consent scripts, <TrackingHeadScript /> must be loaded after.
Using trackEvent() and enableTracking()
For how to use trackEvent(), enableTracking(), learn more about EventDataProps and how this library extends window.dataLayer, please reference @phntms/react-gtm.
🍰 Contributing
Want to get involved, or found an issue? Please contribute using the GitHub Flow. Create a branch, add commits, and open a Pull Request or submit a new issue.
Please read CONTRIBUTING for details on our CODE_OF_CONDUCT, and the process for submitting pull requests to us!
