feat(gatsby-plugin-google-analytics): add custom event helper (#17612)

Author: robmarshall

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

@@ -150,6 +150,58 @@ This plugin also supports several optional General fields documented in [Google
 
 These fields can be specified in the plugin's `options` as shown in the [How to use](#how-to-use) section.
 
+## TrackCustomEvent Function
+
+To allow custom events to be tracked, the plugin exposes a function to include in your project.
+
+To use it, import the package and call the event within your components and business logic.
+
+```jsx
+import React
+import { trackCustomEvent } from 'gatsby-plugin-google-analytics'
+
+export default () => {
+  <div>
+    <button
+      onClick={e => {
+        // To stop the page reloading
+        e.preventDefault()
+        // Lets track that custom click
+        trackCustomEvent({
+          // string - required - The object that was interacted with (e.g.video)
+          category: "Special Button",
+          // string - required - Type of interaction (e.g. 'play')
+          action: "Click",
+          // string - optional - Useful for categorizing events (e.g. 'Spring Campaign')
+          label: "Gatsby Plugin Example Campaign",
+          // number - optional - Numeric value associated with the event. (e.g. A product ID)
+          value: 43
+        })
+        //... Other logic here
+      }}
+    >
+      Tap that!
+    </button>
+  </div>
+}
+```
+
+### All Fields Options
+
+- `category`: string - required
+- `action`: string - required
+- `label`: string
+- `value`: integer
+- `nonInteraction`: bool
+- `transport`: string
+- `hitCallback`: function
+
+For more information see the [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#events) documentation.
+
+#### hitCallback
+
+A timeout is included by default incase the Analytics library fails to load. For more information see [Google Analytics - Handling Timeouts](https://developers.google.com/analytics/devguides/collection/analyticsjs/sending-hits#handling_timeouts)
+
 ## Troubleshooting
 
 ### No actions are tracked

packages/gatsby-plugin-google-analytics/index.d.ts

@@ -8,3 +8,16 @@ export class OutboundLink extends React.Component<
   OutboundLinkProps & React.HTMLProps<HTMLAnchorElement>,
   any
 > {}
+
+export interface CustomEventArgs {
+  category: string
+  action: string
+  label?: string
+  value?: string
+  nonInteraction: boolean
+  transport: "beacon" | "xhr" | "image"
+  hitCallback: Function
+  callbackTimeout: Number
+}
+
+export function trackCustomEvent(args: CustomEventArgs): void

packages/gatsby-plugin-google-analytics/package.json

@@ -41,5 +41,6 @@
   },
   "engines": {
     "node": ">=8.0.0"
-  }
+  },
+  "types": "./index.d.ts"
 }

packages/gatsby-plugin-google-analytics/src/__tests__/index.js

@@ -1,6 +1,6 @@
 import React from "react"
 import { cleanup, fireEvent, render } from "@testing-library/react"
-import { OutboundLink } from "../"
+import { trackCustomEvent, OutboundLink } from "../"
 
 describe(`index.js`, () => {
   describe(`<OutboundLink />`, () => {
@@ -65,4 +65,40 @@ describe(`index.js`, () => {
       expect(props.onClick).toHaveBeenCalled()
     })
   })
+
+  describe(`trackCustomEvent()`, () => {
+    afterEach(cleanup)
+
+    const setup = props => {
+      const utils = render(
+        <button
+          onClick={e => {
+            e.preventDefault()
+            trackCustomEvent({
+              category: `event`,
+              action: `action`,
+              label: `label`,
+              value: `value`,
+            })
+          }}
+        >
+          tapthis
+        </button>
+      )
+
+      return Object.assign({}, utils, {
+        button: utils.getByText(`tapthis`),
+      })
+    }
+
+    it(`sends tracking event when clicked`, () => {
+      window.ga = jest.fn()
+
+      const { button } = setup()
+
+      fireEvent.click(button)
+
+      expect(window.ga).toHaveBeenCalled()
+    })
+  })
 })

packages/gatsby-plugin-google-analytics/src/index.js

@@ -1,6 +1,18 @@
 import React from "react"
 import PropTypes from "prop-types"
 
+const createFunctionWithTimeout = (callback, opt_timeout = 1000) => {
+  let called = false
+  const raceCallback = () => {
+    if (!called) {
+      called = true
+      callback()
+    }
+  }
+  setTimeout(raceCallback, opt_timeout)
+  return raceCallback
+}
+
 function OutboundLink(props) {
   return (
     <a
@@ -53,4 +65,41 @@ OutboundLink.propTypes = {
   onClick: PropTypes.func,
 }
 
-export { OutboundLink }
+/**
+ * This allows the user to create custom events within their Gatsby projects.
+ *
+ * @param {import('gatsby-plugin-google-analytics').CustomEventArgs} args
+ * @see https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#events
+ */
+function trackCustomEvent({
+  category,
+  action,
+  label,
+  value,
+  nonInteraction = true,
+  transport,
+  hitCallback,
+  callbackTimeout = 1000,
+}) {
+  if (typeof window !== `undefined` && window.ga) {
+    const trackingEventOptions = {
+      eventCategory: category,
+      eventAction: action,
+      eventLabel: label,
+      eventValue: value,
+      nonInteraction: nonInteraction,
+      transport,
+    }
+
+    if (hitCallback && typeof hitCallback === `function`) {
+      trackingEventOptions.hitCallback = createFunctionWithTimeout(
+        hitCallback,
+        callbackTimeout
+      )
+    }
+
+    window.ga(`send`, `event`, trackingEventOptions)
+  }
+}
+
+export { OutboundLink, trackCustomEvent }