RFC: Google Tag Manager and gtag in next/third-parties

[housseindjirdeh]

Goal

Improve the performance and developer experience of loading Google tag (gtag.js) and Google Tag Manager in a Next.js application.

Background

We recently launched next/third-parties (still experimental and in early development), which provides components and utilities that improve the performance and developer experience of loading popular third-party libraries. In the original RFC discussion, we proposed the inclusion of Google Analytics as a component:

import { GoogleAnalytics } from 'next/third-parties/google'

export default function Page() {
  return (
    <>
      <GoogleAnalytics />
    </>
  );
}

After further consideration, we realized that this may not be the best approach for the following reasons:

• Google Analytics does not add any visible content to a page. A component may not make this clear.
• GA4 requires users to load gtag.js in order to include Google Analytics to their page. It can be counterintuitive to provide a GoogleAnalytics export since this can confuse developers if they need to include other Google tag dependencies (e.g. Google Ads)
• Many developers use the gtag() command to send data to their products when using Google tag. A component model does not make it easy for developers to understand how to do this at the page/component/layout level.

This RFC proposes a different approach to support Google Analytics (via Google tag) as well as Google Tag Manager in next/third-parties using React hooks instead of components.

Proposal

Google tag (gtag.js)

We suggest providing a useGoogleTag hook with an init method to initialize a Google tag on a page. Although GTM can also be used to load Google Analytics, this will be the recommended approach in the documentation to include Google Analytics on a page:

import { useGoogleTag } from "@next/third-parties/google";

export default function Page() {
  const { init } = useGoogleTag();
  const gtagParams = {
    id: "G-XXXXXXXXX",
    dataLayer: { ... },
  };

  useEffect(() => init(gtagParams), []);

  return <p>This page has Google Tag initialized</p>;
}

By default, this will load gtag and all subsequent child scripts after the page has finished loading and become interactive (akin to next/script’s afterInteractive strategy).

In addition, we can provide a send method to send events:

import { useGoogleTag } from "@next/third-parties/google";

export default function Page() {
  const { sendEvent } = useGoogleTag();

  return (
    <button
      onClick={() =>
        sendEvent({ type: "buttonClicked", { value: "randomValue" } })
      }
    >
      Click Me!
    </button>
  );
}

We can similarly provide methods for each of the commands (config, get, set, event, and consent).

Google Tag Manager

We suggest a useGoogleTagManager hook with an init method to initialize GTM on a page:

import { useGoogleTagManager } from "@next/third-parties/google";

export default function Page() {
  const { init } = useGoogleTagManager();
  const gtmParams = {
    id: "GTM-XXXXXXX",
    dataLayer: { ... },
  };

  useEffect(() => init(gtmParams), []);

  return <p>This page has Google Tag Manager initialized</p>;
}

By default, this will load the GTM container and all subsequent child scripts after the page has finished loading and become interactive (akin to next/script’s afterInteractive strategy).

Web worker support

We can provide developers with the option to opt-in to process their Google tag or GTM container in a web worker (via Partytown) through a different initialization method. Note that this is just an idea and the final API can change:

import { useGoogleTag } from "@next/third-parties";

export default function Page() {
  const { initWorker } = useGoogleTag(); // process gtag in a web worker
  
  //...

  useEffect(() => initWorker(gtagParams), []);

  //...
 }

import { useGoogleTagManager } from "@next/third-parties";

export default function Page() {
  const { initWorker } = useGoogleTagManager(); // process GTM in a web worker

  //...

  useEffect(() => initWorker(gtmParams), []);

  //...
 }

This feature will also likely be released in a later update.

Why include a web worker mode?

We conducted some initial tests to compare the impact on performance of loading Google Tag Manager with different loading techniques. Overall, offloading to a web worker was, by far, the most effective method.

The graphs below show the results of an experiment that measured the impact of a 22-tag GTM container on the performance of a Next.js application. Seven different loading methods were used to load the same number of GTM tags, while all other variables were kept constant¹.

¹ See Appendix for experiment details

A while back, we rolled out an experimental worker strategy to the Script component to allow anyone to move the processing of a third-party script to a web worker. This feature, which uses Partytown, is especially useful when used for tag managers but it can be tricky to set up.

There are a number of things that need to be done in order for Partytown to work with tag managers like GTM and gtag.js. We can automate and/or simplify this as much as possible for developers who decide to use initWorker. This includes:

• Forwarding all required calls to Partytown
• Applying correct CORs headers
• Setting up redirects
• Switching any scripts back to the main thread if they’ve been tested to fail in a web worker

Appendix

Experiment Details:

1. For each loading method, three different throttling experiments were used.

   • Lighthouse Simulated Throttling: Final values = Average value across 6 Lighthouse runs
   • Lighthouse DevTools Throttling: Final values = Average across 6 runs
   • WebPageTest (Packet-level Throttling): Final values = Median across 6 runs (Moto G4 + Fast 3G)

   The accuracy and variance of each throttling mechanism differs. For this experiment, the exact measured values are not as important as the differences observed when switching between scenarios. If you would like to read more details about each type of throttling, please refer to “Network Throttling”.

2. In this experiment, Total Blocking Time (TBT) is used as a measure to evaluate whether background GTM activity would prevent user interactions and have a negative impact on INP.

[petekip]

This is definitely a great resource. I wish it were available for other applications that are non next.js based

[alexandreferreirafr]

It's a client side hook. This should work on any React app.

[philwolstenholme]

My team would love this – especially anything that can get GTM working in a web worker more easily!

[AlexOla-NG]

Same here @philwolstenholme

[ariesclark]

To what extent would this third-parties packages accept integrations, and how would we ensure they are accurately maintained?

[housseindjirdeh]

That's a great question. I'm planning to write a set of minimum criteria that we'd include in the contributing guidelines for accepting new integrations from the community. The crux will likely be that they must be adopted to a certain degree (used in X% of sites) and the method used in next/third-parties must be clearly shown to improve performance and/or developer experience.

[ariesclark]

I feel like this would cause the burden of maintenance to fall on Next.js and the community around it, rather than those platforms. If a package can be maintained outside of this, Next.js should encourage or make PRs to their packages instead of having this package be the source of truth per per say.

[housseindjirdeh]

Yeah we've had some discussions about this for a while. It was this exact concern that gave me the idea to create Third Party Capital as the source of truth.

Currently, the loading logic for the two third-party examples that we've landed already in next/third-parties (GoogleMapsEmbed and YouTubeEmbed) comes from Third Party Capital. I'm hoping we can do the same for gtag and GTM just so we can limit as much custom logic in Next.js as possible. Ideally, next/third-parties should be the glue and wrapper code but the inherent third-party loading technique will live upstream in Third Party Capital.

[TxHawks]

Seeing as strategy="worker" isn't supported in the app dir yet, is the plan for this to support the App Router and also do the work to generally support loading scripts in a worker?

[housseindjirdeh]

Yep. I may write another RFC for this, and the work will likely happen in tandem, but we'll aim to roll out better support for strategy="worker" (easier config, full support in the App router) before providing a web worker version for these utilities.

[karlhorky]

Oh I think I may have opened such a discussion just now:

• next/script strategy="worker" in App Router #54431

If I should close and link to your new RFC, let me know :)

[rafde]

Should using web worker fallback to non-web worker be a use case?

[slorber]

That looks like an interesting improvement.

Also a init() method makes it clearer when the script gets loaded: that might be a better more explicit API to make sure that script is not inserted before cookie consent is given.

I was wondering: how is this coupled to Next.js, couldn't it run in other React apps as well?

[alexandreferreirafr]

It's a client side hook. This should work on any React app. IMO there's no reason to not work.

[demiters]

Sounds fantastic! This is a burning issue for my client, we’ve had trouble getting GTM to load in a worker with the docs/advice currently available. Any currently working example would be much appreciated!

[AlexOla-NG]

@housseindjirdeh, awesome writeup
please how can I test this on a Next 9 version?

[it-spectre-ru]

package json: - "next": "13.4.20-canary.15",

dont work for me ((

can i this way place code ?

[sturtus]

I am in process of doing this in a big NextJS rebuild and would be very helpful.

[philwolstenholme]

There are a number of things that need to be done in order for Partytown to work with tag managers like GTM and gtag.js. We can automate and/or simplify this as much as possible for developers who decide to use initWorker. This includes:

• Forwarding all required calls to Partytown
• Applying correct CORs headers
• Setting up redirects
• Switching any scripts back to the main thread if they’ve been tested to fail in a web worker

Does anyone know of any open codebases where any of this sort of work has been done already? I'm about to add GTM to a site and I know that if I don't use the worker route from the start it'll be much harder to add it later on.

[philwolstenholme]

https://nextjs.org/conf/speakers/houssein-djirdeh

Looking forward to this @housseindjirdeh :)

[kylemh]

Also recommend automating pageview event tracking on hook call so users of the package needn't worry about figuring out how to do that. In pages folder, it was easy with the router event listeners.

For App Dir, the only solution I've found is listed here: https://stackoverflow.com/a/76760064/7304377

Some people like to customize pageview events though, so maybe allow an opt-out as part of the passed params to the hook?

[kylemh]

Another suggestion: Use the minimal GA implementation that Jake Archibald once shared on Twitter for a small client-side impact for GA4 users.

[SouthLink]

(function () {
  var script = document.createElement('script')
  script.defer = true
  script.src = 'https://www.googletagmanager.com/gtag/js?id=G-xxx'
  document.head.append(script)
  script.onload = function () {
    window.dataLayer = window.dataLayer || [];

    function gtag() {
      window.dataLayer.push(arguments);
    }
    window.gtag = gtag
    gtag('js', new Date());
    gtag('config', 'G-xxx', {
      allow_enhanced_conversions: true
    });
    gtag('config', 'AW-xxx', {
      allow_enhanced_conversions: true
    });
    // console.log('fetchJson')
    // fetchJson(location.host)
  }
})();

Where should the code in script.onload be placed with this plugin

[mfanuzzi]

An important use case the current implementation does not support is Consent Mode. In a nutshell, it prevents GTM from actually collecting data until a user explicitly consents (via a cookie banner or other mechanism).

For this to work, similar to @SouthLink 's post above this, we'd need to be able to instantiate the dataLayer with some additional objects. The dataLayer prop is typed to string[] -- which itself doesn't really make sense as, for example, "event" tags are objects -- but even ignoring the type, the way this prop is implemented precludes the possibility of pushing multiple objects, as is required for Consent Mode. A typical implementation of which would look like this (from the excellent Osano documentation):

<script>
  window.dataLayer = window.dataLayer ||[];
  function gtag(){dataLayer.push(arguments);}
  gtag('consent','default',{
    'ad_storage':'denied',
    'analytics_storage':'denied',
    'ad_user_data':'denied',
    'ad_personalization':'denied',
    'personalization_storage':'denied',
    'functionality_storage':'granted',
    'security_storage':'granted',
    'wait_for_update': 500
  });
  gtag("set", "ads_data_redaction", true);
</script>

Ideally, I'd love to be able to set this like:

const gtmDefaultDataLayer = [
  [
    'consent',
    'default',
    {
      ad_storage: 'denied',
      analytics_storage: 'denied',
      ad_user_data: 'denied',
      ad_personalization: 'denied',
      personalization_storage: 'denied',
      functionality_storage: 'granted',
      security_storage: 'granted',
      wait_for_update: 500,
    },
  ],
  ['set', 'ads_data_redaction', true],
];

//...

<GoogleTagManager gtmId="GTM-XXXXXX" dataLayer={gtmDefaultDataLayer} />

Which would imply that dataLayer should have a type like [string, string, any?][] with a tuple array. But also the implementation is currently:

        ${dataLayer ? `w[l].push(${JSON.stringify(dataLayer)})` : ''}

Whereas instead it should spread into push to allow for multiple objects:

        ${dataLayer ? `w[l].push(...${JSON.stringify(dataLayer )})` : ''}