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

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

@@ -147,3 +147,39 @@ This plugin also supports several optional General fields documented in [Google
 - `transport`: string
 
 These fields can be specified in the plugin's `options` as shown in the [How to use](#how-to-use) section.
+
+## CustomTrackingEvent Function
+
+To allow custom events to be tracked, the plugin exposes a function to include in your project.
+
+To use it, simply import it and use it within your scripts, both within components and logic functions.
+
+```jsx
+import React
+import { CustomTrackingEvent } from 'gatsby-plugin-google-analytics'
+
+export default () => {
+  <div>
+    <button
+      onClick={e => {
+        // To stop the page reloading
+        e.preventDefault()
+        // Lets track that custom click
+        CustomTrackingEvent({
+          // 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>
+}
+```

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 { CustomTrackingEvent, OutboundLink } from "../"
 
 describe(`index.js`, () => {
   describe(`<OutboundLink />`, () => {
@@ -65,4 +65,40 @@ describe(`index.js`, () => {
       expect(props.onClick).toHaveBeenCalled()
     })
   })
+
+  describe(`CustomTrackingEvent()`, () => {
+    afterEach(cleanup)
+
+    const setup = props => {
+      const utils = render(
+        <button
+          onClick={e => {
+            e.preventDefault()
+            CustomTrackingEvent({
+              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

@@ -53,4 +53,31 @@ OutboundLink.propTypes = {
   onClick: PropTypes.func,
 }
 
-export { OutboundLink }
+/**
+ * This allows the user to create custom events within their Gatsby projects.
+ * @param {string} category Required - The object that was interacted with (e.g.video)
+ * @param {string} action Required - Type of interaction (e.g. 'play')
+ * @param {string} label Optional - Useful for categorizing events (e.g. 'Spring Campaign')
+ * @param {string} value Optional - Numeric value associated with the event. (e.g. A product ID)
+ *
+ * @link https://developers.google.com/analytics/devguides/collection/analyticsjs/field-reference#events
+ */
+function CustomTrackingEvent({ category, action, label, value }) {
+  if (window.ga) {
+    window.ga(`send`, `event`, {
+      eventCategory: category,
+      eventAction: action,
+      eventLabel: label,
+      eventValue: value,
+    })
+  }
+}
+
+CustomTrackingEvent.propTypes = {
+  category: PropTypes.string.isRequired,
+  action: PropTypes.string.isRequired,
+  label: PropTypes.string,
+  value: PropTypes.number,
+}
+
+export { OutboundLink, CustomTrackingEvent }