Implement tracking disable support (#15)

* Upgrade to GA4

* Implement tracking disable support

* Change verison bump

README.md

@@ -8,7 +8,7 @@ A lightweight React library to implement custom Google Tag Manager events.
 
 ## Introduction
 
-Designed to use and extend [Google Analytics 4](https://support.google.com/analytics/answer/10089681?hl=en). **Note**: If upgrading from react-gtm `0.0.6` or older, or currently using an older version of Google Analytics, you'll need to [upgrade](https://support.google.com/analytics/answer/9744165?hl=en). This library is also SSR safe and does not break when used without window existing.
+Designed to use and extend [Google Analytics 4](https://support.google.com/analytics/answer/10089681?hl=en). **Note**: If upgrading from react-gtm `0.0.6` or older, or currently using an older version of Google Analytics, you'll need to [upgrade](https://support.google.com/analytics/answer/9744165?hl=en). This library is also SSR safe and does not break when used without window existing. This package is intended to be used with React / older Next.JS apps, for Next.JS 11 and above we recommend using [@phntms/next-gtm](https://www.npmjs.com/package/@phntms/next-gtm).
 
 ## Installation
 
@@ -22,9 +22,10 @@ npm i @phntms/react-gtm
 
 ### <TrackingHeadScript />
 
-| Property | Type     | Default   | Required | Notes                                                                           |
-| -------- | -------- | --------- | -------- | ------------------------------------------------------------------------------- |
-| **id**   | `string` | undefined | **Yes**  | ID that uniquely identifies GTM Container. Will be in the format; `GTM-xxxxxx`. |
+| Property    | Type      | Default   | Notes                                                                                                     |
+| ----------- | --------- | --------- | --------------------------------------------------------------------------------------------------------- |
+| **id**      | `string`  | undefined | ID that uniquely identifies GTM Container. Example format: `GTM-xxxxxx`.                                  |
+| **disable** | `boolean` | false     | Used to disable tracking events. Use if you want user to consent to being tracked before tracking events. |
 
 To initialize GTM, add `TrackingHeadScript` to the `head` of the page.
 
@@ -60,9 +61,9 @@ export default class MyDocument extends Document {
 
 ### trackEvent()
 
-| Parameter | Type                 | Default   | Required | Notes                                           |
-| --------- | -------------------- | --------- | -------- | ----------------------------------------------- |
-| props     | `EventTrackingProps` | undefined | No       | Custom tracking event to push to GTM container. |
+| Parameter | Type                 | Default   | Notes                                           |
+| --------- | -------------------- | --------- | ----------------------------------------------- |
+| props     | `EventTrackingProps` | undefined | Custom tracking event to push to GTM container. |
 
 Example of a basic tracking event:
 
@@ -79,6 +80,15 @@ trackEvent({
 });
 ```
 
+### enableTracking()
+
+| Parameter  | Type      | Default   | Notes                                                               |
+| ---------- | --------- | --------- | ------------------------------------------------------------------- |
+| **id**     | `string`  | undefined | Same ID used in `trackingHeadScript`. Example format: `GTM-xxxxxx`. |
+| **enable** | `boolean` | true      | Used to enable or disable tracking events.                          |
+
+**Note**: This _should_ only be used if needed, for example after user has consented to being tracked. You _shouldn't_ need to toggle this in normal usage.
+
 ### EventDataProps
 
 | Parameter | Type             | Default       | Required | Notes                                                                                                                                     |

src/components/TrackingHeadScript.tsx

@@ -2,7 +2,7 @@ import React from "react";
 
 import { EmbedTrackingProps } from "../types";
 
-const TrackingHeadScript = ({ id }: EmbedTrackingProps) => (
+const TrackingHeadScript = ({ id, disable = false }: EmbedTrackingProps) => (
   <>
     {id && (
       <>
@@ -13,6 +13,8 @@ const TrackingHeadScript = ({ id }: EmbedTrackingProps) => (
         <script>
           {`
             window.dataLayer = window.dataLayer || [];
+            window['ga-disable-${id}'] = ${disable.toString()};
+
             function gtag() { dataLayer.push(arguments); }
             gtag('js', new Date());
             gtag('config', '${id}', { page_path: window.location.pathname });

src/index.ts

@@ -1,5 +1,6 @@
 export { default as TrackingHeadScript } from "./components/TrackingHeadScript";
 export { default as trackEvent } from "./utils/trackEvent";
+export { default as enableTracking } from "./utils/enableTracking";
 export {
   EmbedTrackingProps,
   EventTrackingProps,

src/types.tsx

@@ -1,5 +1,6 @@
 export interface EmbedTrackingProps {
   id?: string;
+  disable?: boolean;
 }
 
 export interface EventTrackingProps {

src/utils/enableTracking.ts

@@ -0,0 +1,8 @@
+import { IS_BROWSER } from "./platform";
+
+const enableTracking = (id: string, enable = true) => {
+  if (!IS_BROWSER) return;
+  window[`ga-disable-${id}`] = (!enable).toString();
+};
+
+export default enableTracking;

test/index.test.tsx

@@ -2,7 +2,7 @@ import React from "react";
 
 import TestRenderer from "react-test-renderer";
 
-import { trackEvent, TrackingHeadScript } from "../src";
+import { enableTracking, trackEvent, TrackingHeadScript } from "../src";
 import { IS_BROWSER } from "../src/utils/platform";
 
 const ID = "GTM-xxxxxx";
@@ -17,6 +17,26 @@ describe("<TrackingHeadScript />", () => {
     const renderer = TestRenderer.create(<TrackingHeadScript />);
     expect(renderer.toJSON()).toEqual(null);
   });
+
+  it("disables tracking if disable prop is used", async () => {
+    const renderer = TestRenderer.create(
+      <TrackingHeadScript id={ID} disable />
+    );
+    expect(
+      JSON.stringify(renderer.toJSON()).includes(
+        `window['ga-disable-${ID}'] = true`
+      )
+    ).toBe(true);
+  });
+
+  it("doesn't disable tracking if disable prop isn't used", async () => {
+    const renderer = TestRenderer.create(<TrackingHeadScript id={ID} />);
+    expect(
+      JSON.stringify(renderer.toJSON()).includes(
+        `window['ga-disable-${ID}'] = false`
+      )
+    ).toEqual(true);
+  });
 });
 
 describe("trackEvent()", () => {
@@ -61,3 +81,15 @@ describe("trackEvent()", () => {
     expect(window.dataLayer).toHaveLength(1);
   });
 });
+
+describe("enableTracking()", () => {
+  it("enables tracking events if used", async () => {
+    enableTracking(ID);
+    expect(window[`ga-disable-${ID}`]).toEqual("false");
+  });
+
+  it("disables tracking events if enable is set to false", async () => {
+    enableTracking(ID, false);
+    expect(window[`ga-disable-${ID}`]).toEqual("true");
+  });
+});

tsconfig.json

@@ -17,7 +17,8 @@
     "alwaysStrict": true,
     "noImplicitReturns": true,
     "allowSyntheticDefaultImports": true,
-    "esModuleInterop": true
+    "esModuleInterop": true,
+    "suppressImplicitAnyIndexErrors": true
   },
   "include": ["src/**/*.ts"],
   "exclude": ["test/**/*"]