/partytown-gtm-plugin

Partytown GTM plugin

Primary LanguageTypeScriptMIT LicenseMIT

@superside-oss/partytown-gtm

This is a Google Tag Manager (GTM) integration for Partytown 🎉, a performance-focused library that offloads third-party scripts to a web worker.

Motivation

Our goal was to leverage Partytown 🎉 to unblock the main thread on superside.com, while maintaining the ability to debug GTM using Tag Assistant. Some suggest disabling Partytown when a specific query string parameter is detected. This can create a false sense of functionality and may lead to issues for actual users.

By integrating Partytown with GTM Tag Assistant, we successfully identified and resolved several issues in the Partytown source code.

Installation

Install this package using your package manager of choice:

npm:

npm install --save @superside-oss/partytown-gtm

yarn:

yarn add @superside-oss/partytown-gtm

Integrating with React Application

To integrate this module with a React application, import it alongside Partytown.

import { Partytown } from '@builder.io/partytown/react';
import {
  GTMScript,
  GTM_TAG_ASSISTANT_ACCESSOR,
  GTM_TAG_ASSISTANT_FORWARDER,
  partytownResolveUrl
} from '@superside-oss/partytown-gtm';

function ThirdPartyScripts() {
  return (
    <>
      <Partytown
        forward={[
          'dataLayer.push',
          GTM_TAG_ASSISTANT_FORWARDER
        ]}
        mainWindowAccessors={[
          GTM_TAG_ASSISTANT_ACCESSOR
        ]}
        resolveUrl={partytownResolveUrl}
      />
      <GTMScript gtmId={process.env.NEXT_PUBLIC_GTM_ID as string} />
    </>
  );
}

export default ThirdPartyScripts;

Steps:

  1. Add GTM_TAG_ASSISTANT_FORWARDER to Partytown's forward array.

  2. Add GTM_TAG_ASSISTANT_ACCESSOR to Partytown's mainWindowAccessors.

  3. Set Partytown's resolveUrl to partytownResolveUrl.

    This resolver takes care of third-party JS scripts missing CORS headers. These files should be proxied through a server endpoint.

  4. Add <GTMScript /> after <Partytown/> and set your gtmId.

  5. Implement a server-side proxy for assets lacking CORS headers. You can find a sample NextJS endpoint implementation in integration/nextjs.

If you've reached this point, congratulations, you're almost done! 🚀

The final step for GTM debugging is to install the Tag Assistant Companion browser extension. Navigate to https://tagassistant.google.com and click the Install extension button in the top-right corner.

Take a look at the sample NextJS integration in integration/nextjs.