From 428af8af5ebb8dbcd619a12f5da524143130331c Mon Sep 17 00:00:00 2001 From: Lane Goolsby Date: Thu, 29 Dec 2022 07:53:54 -0800 Subject: [PATCH] feat(plugin-google-tag-manager): add new google-tag-manager plugin + deprecate google-analytics plugin (#8470) Co-authored-by: Goolsby, Lane Co-authored-by: sebastienlorber fix https://github.com/facebook/docusaurus/issues/7221 --- .../.npmignore | 3 + .../README.md | 7 ++ .../package.json | 33 ++++++++ .../src/index.ts | 78 +++++++++++++++++++ .../src/options.ts | 12 +++ .../src/types.d.ts | 8 ++ .../tsconfig.client.json | 15 ++++ .../tsconfig.json | 13 ++++ .../docusaurus-preset-classic/package.json | 1 + .../docusaurus-preset-classic/src/index.ts | 6 ++ .../docusaurus-preset-classic/src/options.ts | 2 + .../api/plugins/plugin-google-analytics.md | 10 +++ .../api/plugins/plugin-google-tag-manager.md | 71 +++++++++++++++++ website/docs/using-plugins.md | 7 +- 14 files changed, 264 insertions(+), 2 deletions(-) create mode 100644 packages/docusaurus-plugin-google-tag-manager/.npmignore create mode 100644 packages/docusaurus-plugin-google-tag-manager/README.md create mode 100644 packages/docusaurus-plugin-google-tag-manager/package.json create mode 100644 packages/docusaurus-plugin-google-tag-manager/src/index.ts create mode 100644 packages/docusaurus-plugin-google-tag-manager/src/options.ts create mode 100644 packages/docusaurus-plugin-google-tag-manager/src/types.d.ts create mode 100644 packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json create mode 100644 packages/docusaurus-plugin-google-tag-manager/tsconfig.json create mode 100644 website/docs/api/plugins/plugin-google-tag-manager.md diff --git a/packages/docusaurus-plugin-google-tag-manager/.npmignore b/packages/docusaurus-plugin-google-tag-manager/.npmignore new file mode 100644 index 000000000000..03c9ae1e1b54 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/.npmignore @@ -0,0 +1,3 @@ +.tsbuildinfo* +tsconfig* +__tests__ diff --git a/packages/docusaurus-plugin-google-tag-manager/README.md b/packages/docusaurus-plugin-google-tag-manager/README.md new file mode 100644 index 000000000000..01e213fe34fc --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/README.md @@ -0,0 +1,7 @@ +# `@docusaurus/plugin-google-tag-manager` + +Google Tag Manager plugin for Docusaurus. + +## Usage + +See [plugin-google-tag-manager documentation](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-google-tag-manager). diff --git a/packages/docusaurus-plugin-google-tag-manager/package.json b/packages/docusaurus-plugin-google-tag-manager/package.json new file mode 100644 index 000000000000..8b9b8789b7bb --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/package.json @@ -0,0 +1,33 @@ +{ + "name": "@docusaurus/plugin-google-tag-manager", + "version": "3.0.0-alpha.0", + "description": "Google Tag Manager (gtm.js) plugin for Docusaurus.", + "main": "lib/index.js", + "types": "lib/index.d.ts", + "publishConfig": { + "access": "public" + }, + "scripts": { + "build": "tsc --build", + "watch": "tsc --build --watch" + }, + "repository": { + "type": "git", + "url": "https://github.com/facebook/docusaurus.git", + "directory": "packages/docusaurus-plugin-google-tag-manager" + }, + "license": "MIT", + "dependencies": { + "@docusaurus/core": "^3.0.0-alpha.0", + "@docusaurus/types": "^3.0.0-alpha.0", + "@docusaurus/utils-validation": "^3.0.0-alpha.0", + "tslib": "^2.4.0" + }, + "peerDependencies": { + "react": "^16.8.4 || ^17.0.0", + "react-dom": "^16.8.4 || ^17.0.0" + }, + "engines": { + "node": ">=16.14" + } +} diff --git a/packages/docusaurus-plugin-google-tag-manager/src/index.ts b/packages/docusaurus-plugin-google-tag-manager/src/index.ts new file mode 100644 index 000000000000..10e0c3868ea7 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/src/index.ts @@ -0,0 +1,78 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +import {Joi} from '@docusaurus/utils-validation'; +import type { + LoadContext, + Plugin, + OptionValidationContext, +} from '@docusaurus/types'; +import type {PluginOptions, Options} from './options'; + +export default function pluginGoogleAnalytics( + context: LoadContext, + options: PluginOptions, +): Plugin { + const {containerId} = options; + const isProd = process.env.NODE_ENV === 'production'; + + return { + name: 'docusaurus-plugin-google-tag-manager', + + contentLoaded({actions}) { + actions.setGlobalData(options); + }, + + injectHtmlTags() { + if (!isProd) { + return {}; + } + return { + preBodyTags: [ + { + tagName: 'noscript', + innerHTML: ``, + }, + ], + headTags: [ + { + tagName: 'link', + attributes: { + rel: 'preconnect', + href: 'https://www.googletagmanager.com', + }, + }, + { + tagName: 'script', + innerHTML: `window.dataLayer = window.dataLayer || [];`, + }, + { + tagName: 'script', + innerHTML: `(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start': +new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0], +j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src= +'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f); +})(window,document,'script','dataLayer','${containerId}');`, + }, + ], + }; + }, + }; +} + +const pluginOptionsSchema = Joi.object({ + containerId: Joi.string().required(), +}); + +export function validateOptions({ + validate, + options, +}: OptionValidationContext): PluginOptions { + return validate(pluginOptionsSchema, options); +} + +export type {PluginOptions, Options}; diff --git a/packages/docusaurus-plugin-google-tag-manager/src/options.ts b/packages/docusaurus-plugin-google-tag-manager/src/options.ts new file mode 100644 index 000000000000..6ffe05812a64 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/src/options.ts @@ -0,0 +1,12 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +export type PluginOptions = { + containerId: string; +}; + +export type Options = Partial; diff --git a/packages/docusaurus-plugin-google-tag-manager/src/types.d.ts b/packages/docusaurus-plugin-google-tag-manager/src/types.d.ts new file mode 100644 index 000000000000..6f6f99f12793 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/src/types.d.ts @@ -0,0 +1,8 @@ +/** + * Copyright (c) Facebook, Inc. and its affiliates. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +/// diff --git a/packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json b/packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json new file mode 100644 index 000000000000..14bbcd3b6a55 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/tsconfig.client.json @@ -0,0 +1,15 @@ +{ + "extends": "../../tsconfig.json", + "compilerOptions": { + "noEmit": false, + "composite": true, + "incremental": true, + "tsBuildInfoFile": "./lib/.tsbuildinfo-client", + "module": "esnext", + "target": "esnext", + "rootDir": "src", + "outDir": "lib" + }, + "include": ["src/*.d.ts"], + "exclude": ["**/__tests__/**"] +} diff --git a/packages/docusaurus-plugin-google-tag-manager/tsconfig.json b/packages/docusaurus-plugin-google-tag-manager/tsconfig.json new file mode 100644 index 000000000000..1e49538f9ea2 --- /dev/null +++ b/packages/docusaurus-plugin-google-tag-manager/tsconfig.json @@ -0,0 +1,13 @@ +{ + "extends": "../../tsconfig.json", + "references": [{"path": "./tsconfig.client.json"}], + "compilerOptions": { + "noEmit": false, + "incremental": true, + "tsBuildInfoFile": "./lib/.tsbuildinfo", + "rootDir": "src", + "outDir": "lib" + }, + "include": ["src"], + "exclude": ["**/__tests__/**"] +} diff --git a/packages/docusaurus-preset-classic/package.json b/packages/docusaurus-preset-classic/package.json index aa1d22269951..a26cd69a62b4 100644 --- a/packages/docusaurus-preset-classic/package.json +++ b/packages/docusaurus-preset-classic/package.json @@ -25,6 +25,7 @@ "@docusaurus/plugin-debug": "^3.0.0-alpha.0", "@docusaurus/plugin-google-analytics": "^3.0.0-alpha.0", "@docusaurus/plugin-google-gtag": "^3.0.0-alpha.0", + "@docusaurus/plugin-google-tag-manager": "^3.0.0-alpha.0", "@docusaurus/plugin-sitemap": "^3.0.0-alpha.0", "@docusaurus/theme-classic": "^3.0.0-alpha.0", "@docusaurus/theme-common": "^3.0.0-alpha.0", diff --git a/packages/docusaurus-preset-classic/src/index.ts b/packages/docusaurus-preset-classic/src/index.ts index c7fe1c825a3e..c1cc099c39bd 100644 --- a/packages/docusaurus-preset-classic/src/index.ts +++ b/packages/docusaurus-preset-classic/src/index.ts @@ -40,6 +40,7 @@ export default function preset( theme, googleAnalytics, gtag, + googleTagManager, ...rest } = opts; @@ -80,6 +81,11 @@ export default function preset( if (gtag) { plugins.push(makePluginConfig('@docusaurus/plugin-google-gtag', gtag)); } + if (googleTagManager) { + plugins.push( + makePluginConfig('@docusaurus/plugin-google-gtag', googleTagManager), + ); + } if (isProd && sitemap !== false) { plugins.push(makePluginConfig('@docusaurus/plugin-sitemap', sitemap)); } diff --git a/packages/docusaurus-preset-classic/src/options.ts b/packages/docusaurus-preset-classic/src/options.ts index 1e65f826fa31..a8fdb68125f2 100644 --- a/packages/docusaurus-preset-classic/src/options.ts +++ b/packages/docusaurus-preset-classic/src/options.ts @@ -11,6 +11,7 @@ import type {Options as PagesPluginOptions} from '@docusaurus/plugin-content-pag import type {Options as SitemapPluginOptions} from '@docusaurus/plugin-sitemap'; import type {Options as GAPluginOptions} from '@docusaurus/plugin-google-analytics'; import type {Options as GtagPluginOptions} from '@docusaurus/plugin-google-gtag'; +import type {Options as GTMPluginOptions} from '@docusaurus/plugin-google-tag-manager'; import type {Options as ThemeOptions} from '@docusaurus/theme-classic'; import type {ThemeConfig as BaseThemeConfig} from '@docusaurus/types'; import type {UserThemeConfig as ClassicThemeConfig} from '@docusaurus/theme-common'; @@ -42,6 +43,7 @@ export type Options = { * is present. */ gtag?: GtagPluginOptions; + googleTagManager?: GTMPluginOptions; }; export type ThemeConfig = BaseThemeConfig & diff --git a/website/docs/api/plugins/plugin-google-analytics.md b/website/docs/api/plugins/plugin-google-analytics.md index 1426e6265a1c..98dfc41b924e 100644 --- a/website/docs/api/plugins/plugin-google-analytics.md +++ b/website/docs/api/plugins/plugin-google-analytics.md @@ -9,6 +9,16 @@ import APITable from '@site/src/components/APITable'; The default [Google Analytics](https://developers.google.com/analytics/devguides/collection/analyticsjs/) plugin. It is a JavaScript library for measuring how users interact with your website **in the production build**. If you are using Google Analytics 4 you might need to consider using [plugin-google-gtag](./plugin-google-gtag.md) instead. +:::danger Deprecated + +This plugin is **deprecated**, and will become useless on July 1, 2023. + +Google is [moving away from Universal Analytics](https://blog.google/products/marketingplatform/analytics/prepare-for-future-with-google-analytics-4/). + +If you are still using this plugin with a `UA-*` tracking id, you should create a Google Analytics 4 account as soon as possible, and use [`@docusaurus/plugin-google-gtag`](./plugin-google-gtag.md) instead of this plugin. More details [here](https://github.com/facebook/docusaurus/issues/7221). + +::: + :::caution production only This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics. diff --git a/website/docs/api/plugins/plugin-google-tag-manager.md b/website/docs/api/plugins/plugin-google-tag-manager.md new file mode 100644 index 000000000000..1b9776cc5394 --- /dev/null +++ b/website/docs/api/plugins/plugin-google-tag-manager.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 8 +slug: /api/plugins/@docusaurus/plugin-google-tag-manager +--- + +# 📦 plugin-google-tag-manager + +import APITable from '@site/src/components/APITable'; + +A plugin for adding [Google Tag Manager (gtm.js)](https://developers.google.com/tag-platform/tag-manager) to a Docusaurus site. Use this plugin in conjunction with the standard [gtag plugin](./plugin-google-gtag.md) for in-depth analysis of how users are using your site. + +:::tip + +You can use [Google's Tag Assistant](https://tagassistant.google.com/) tool to check if tag manager is set up correctly! + +::: + +:::caution production only + +This plugin is always inactive in development and **only active in production** to avoid polluting the analytics statistics. + +::: + +## Installation {#installation} + +```bash npm2yarn +npm install --save @docusaurus/plugin-google-tag-manager +``` + +:::tip + +If you use the preset `@docusaurus/preset-classic`, you don't need to install this plugin as a dependency. + +You can configure this plugin through the preset options. + +::: + +## Configuration {#configuration} + +Accepted fields: + +```mdx-code-block + +``` + +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `containerId` | `string` | **Required** | Your Tag Manager container Id (usually starts with `GTM-`). | + +```mdx-code-block + +``` + +### Example configuration {#ex-config} + +You can configure this plugin through preset options or plugin options. + +:::tip + +Most Docusaurus users configure this plugin through the preset options. + +::: + +```js config-tabs +// Preset Options: googleTagManager +// Plugin Options: @docusaurus/plugin-google-tag-manager + +const config = { + containerId: 'GTM-12345', +}; +``` diff --git a/website/docs/using-plugins.md b/website/docs/using-plugins.md index 891f2e88172f..81d95d831c4b 100644 --- a/website/docs/using-plugins.md +++ b/website/docs/using-plugins.md @@ -144,8 +144,9 @@ The classic preset is shipped by default to new Docusaurus websites created with - [`@docusaurus/plugin-content-blog`](./api/plugins/plugin-content-blog.md) - [`@docusaurus/plugin-content-pages`](./api/plugins/plugin-content-pages.md) - [`@docusaurus/plugin-debug`](./api/plugins/plugin-debug.md) -- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) - [`@docusaurus/plugin-google-gtag`](./api/plugins/plugin-google-gtag.md) +- [`@docusaurus/plugin-google-tag-manager`](./api/plugins/plugin-google-tag-manager.md) +- [`@docusaurus/plugin-google-analytics`](./api/plugins/plugin-google-analytics.md) (**deprecated**) - [`@docusaurus/plugin-sitemap`](./api/plugins/plugin-sitemap.md) The classic preset will relay each option entry to the respective plugin/theme. @@ -172,7 +173,9 @@ module.exports = { sitemap: {}, // Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified) gtag: {}, - // Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified) + // Will be passed to @docusaurus/plugin-google-tag-manager (only enabled when explicitly specified) + googleTagManager: {}, + // DEPRECATED: Will be passed to @docusaurus/plugin-google-analytics (only enabled when explicitly specified) googleAnalytics: {}, }, ],