feat(tagmanager): add configurable event names (#21362) (#24076)

Co-authored-by: Rubén Below <[email protected]>
Co-authored-by: Ward Peeters <[email protected]>

Author: 3 people

packages/gatsby-plugin-google-tagmanager/README.md

@@ -17,18 +17,26 @@ plugins: [
       id: "YOUR_GOOGLE_TAGMANAGER_ID",
 
       // Include GTM in development.
+      //
       // Defaults to false meaning GTM will only be loaded in production.
       includeInDevelopment: false,
 
       // datalayer to be set before GTM is loaded
       // should be an object or a function that is executed in the browser
+      //
       // Defaults to null
       defaultDataLayer: { platform: "gatsby" },
 
       // Specify optional GTM environment details.
       gtmAuth: "YOUR_GOOGLE_TAGMANAGER_ENVIRONMENT_AUTH_STRING",
       gtmPreview: "YOUR_GOOGLE_TAGMANAGER_ENVIRONMENT_PREVIEW_NAME",
       dataLayerName: "YOUR_DATA_LAYER_NAME",
+
+      // Name of the event that is triggered
+      // on every Gatsby route change.
+      //
+      // Defaults to gatsby-route-change
+      routeChangeEventName: "YOUR_ROUTE_CHANGE_EVENT_NAME",
     },
   },
 ]
@@ -44,6 +52,7 @@ plugins: [
     options: {
       // datalayer to be set before GTM is loaded
       // should be a stringified object or object
+      //
       // Defaults to null
       defaultDataLayer: function () {
         return {
@@ -61,13 +70,13 @@ If you want to link analytics use with anything inside the container (for exampl
 
 #### Tracking routes
 
-This plugin will fire a new event called `gatsby-route-change` whenever a route is changed in your Gatsby application. To record this in Google Tag Manager, we will need to add a trigger to the desired tag to listen for the event:
+This plugin will fire a new event called `gatsby-route-change` (or as in the `gatsby-config.js` configured `routeChangeEventName`) whenever a route is changed in your Gatsby application. To record this in Google Tag Manager, we will need to add a trigger to the desired tag to listen for the event:
 
 1. Visit the [Google Tag Manager console](https://tagmanager.google.com/) and click on the workspace for your site.
 2. Navigate to the desired tag using the 'Tags' tab of the menu on the right hand side.
 3. Under "Triggering", click the pencil icon, then the "+" button to add a new trigger.
 4. In the "Choose a trigger" window, click on the "+" button again.
-5. Choose the trigger type by clicking the pencil button and clicking "Custom event". For event name, enter `gatsby-route-change`.
+5. Choose the trigger type by clicking the pencil button and clicking "Custom event". For event name, enter `gatsby-route-change` (or as in the `gatsby-config.js` configured `routeChangeEventName`).
 
 This tag will now catch every route change in Gatsby, and you can add Google tag services as you wish to it.
 

packages/gatsby-plugin-google-tagmanager/src/__tests__/gatsby-browser.js

@@ -70,6 +70,28 @@ describe(`onRouteUpdate`, () => {
     expect(window.dataLayer).toHaveLength(1)
   })
 
+  it(`registers a custom route change event name if given in routeChangeEventName`, () => {
+    const { onRouteUpdate } = getAPI(() => {
+      process.env.NODE_ENV = `production`
+    })
+    const customEventName = `custom-route-change-event-name`
+
+    onRouteUpdate(
+      {},
+      {
+        routeChangeEventName: customEventName,
+      }
+    )
+
+    jest.runAllTimers()
+
+    expect(window.dataLayer).toEqual([
+      {
+        event: customEventName,
+      },
+    ])
+  })
+
   it(`registers new data layer variable if dataLayerName is specified`, () => {
     const { onRouteUpdate } = getAPI(() => {
       process.env.NODE_ENV = `production`

packages/gatsby-plugin-google-tagmanager/src/gatsby-browser.js

@@ -8,8 +8,11 @@ exports.onRouteUpdate = (_, pluginOptions) => {
       let data = pluginOptions.dataLayerName
         ? window[pluginOptions.dataLayerName]
         : window.dataLayer
+      let eventName = pluginOptions.routeChangeEventName
+        ? pluginOptions.routeChangeEventName
+        : `gatsby-route-change`
 
-      data.push({ event: `gatsby-route-change` })
+      data.push({ event: eventName })
     }, 50)
   }
 }