feat: add google analytics gtag.js plugin (#1702)

Co-authored-by: Joe Pea <joe@trusktr.io>
Co-authored-by: 沈唁 <52o@qq52o.cn>
Co-authored-by: John Hildenbiddle <jhildenbiddle@users.noreply.github.com>
Co-authored-by: zhanzhao <zhanzhao@megvii.com>

build/build.js

@@ -80,6 +80,7 @@ async function buildAllPlugin() {
   var plugins = [
     {name: 'search', input: 'search/index.js'},
     {name: 'ga', input: 'ga.js'},
+    {name: 'gtag', input: 'gtag.js'},
     {name: 'matomo', input: 'matomo.js'},
     {name: 'emoji', input: 'emoji.js'},
     {name: 'external-script', input: 'external-script.js'},

docs/plugins.md

@@ -71,6 +71,8 @@ This plugin ignores diacritical marks when performing a full text search (e.g.,
 
 ## Google Analytics
 
+> Google's Universal Analytics service will no longer process new data in standard properties beginning July 1, 2023. Prepare now by setting up and switching over to a Google Analytics 4 property and docsify's gtag.js plugin.
+
 Install the plugin and configure the track id.
 
 ```html
@@ -91,6 +93,31 @@ Configure by `data-ga`.
 <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
 ```
 
+## Google Analytics 4 (GA4)
+
+Install the plugin and configure the track id.
+
+```html
+<script>
+  // Single ID
+  window.$docsify = {
+    gtag: 'UA-XXXXX-Y',
+  };
+
+  // Multiple IDs
+  window.$docsify = {
+    gtag: [
+      'G-XXXXXXXX', // Google Analytics 4 (GA4)
+      'UA-XXXXXXXX', // Google Universal Analytics (GA3)
+      'AW-XXXXXXXX', // Google Ads
+      'DC-XXXXXXXX', // Floodlight
+    ],
+  };
+</script>
+<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
+<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/gtag.min.js"></script>
+```
+
 ## Emoji
 
 Renders a larger collection of emoji shorthand codes. Without this plugin, Docsify is able to render only a limited number of emoji shorthand codes.

src/plugins/gtag.js

@@ -0,0 +1,72 @@
+/* eslint-disable no-console */
+// From ./ga.js
+
+function appendScript(id) {
+  const script = document.createElement('script');
+  script.async = true;
+  script.src = 'https://www.googletagmanager.com/gtag/js?id=' + id;
+  document.body.appendChild(script);
+}
+
+// global site tag instance initialized
+function initGlobalSiteTag(id) {
+  appendScript(id);
+
+  window.dataLayer = window.dataLayer || [];
+  window.gtag =
+    window.gtag ||
+    function () {
+      window.dataLayer.push(arguments);
+    };
+
+  window.gtag('js', new Date());
+  window.gtag('config', id);
+}
+
+// add additional products to your tag
+// https://developers.google.com/tag-platform/gtagjs/install
+function initAdditionalTag(id) {
+  window.gtag('config', id);
+}
+
+function init(ids) {
+  if (Array.isArray(ids)) {
+    // set the first id to be a global site tag
+    initGlobalSiteTag(ids[0]);
+
+    // the rest ids
+    ids.forEach((id, index) => {
+      if (index > 0) {
+        initAdditionalTag(id);
+      }
+    });
+  } else {
+    initGlobalSiteTag(ids);
+  }
+}
+
+function collect() {
+  if (!window.gtag) {
+    init($docsify.gtag);
+  }
+
+  // usage: https://developers.google.com/analytics/devguides/collection/gtagjs/pages
+  window.gtag('event', 'page_view', {
+    /* eslint-disable camelcase */
+    page_title: document.title,
+    page_location: location.href,
+    page_path: location.pathname,
+    /* eslint-disable camelcase */
+  });
+}
+
+const install = function (hook) {
+  if (!$docsify.gtag) {
+    console.error('[Docsify] gtag is required.');
+    return;
+  }
+
+  hook.beforeEach(collect);
+};
+
+$docsify.plugins = [].concat(install, $docsify.plugins);

test/e2e/gtag.test.js

@@ -0,0 +1,97 @@
+// Modules, constants, and variables
+// npm run test:e2e gtag.test.js
+// -----------------------------------------------------------------------------
+const docsifyInit = require('../helpers/docsify-init');
+const { test, expect } = require('./fixtures/docsify-init-fixture');
+
+const gtagList = [
+  'AW-YYYYYY', // Google Ads
+  'DC-ZZZZZZ', // Floodlight
+  'G-XXXXXX', // Google Analytics 4 (GA4)
+  'UA-XXXXXX', // Google Universal Analytics (GA3)
+];
+
+// Suite
+// -----------------------------------------------------------------------------
+test.describe('Gtag Plugin Tests', () => {
+  // page request listened, print collect url
+  function pageRequestListened(page) {
+    page.on('request', request => {
+      if (request.url().indexOf('www.google-analytics.com') !== -1) {
+        // console.log(request.url());
+      }
+    });
+
+    page.on('response', response => {
+      const request = response.request();
+      // googleads.g.doubleclick.net
+      // www.google-analytics.com
+      // www.googletagmanager.com
+      const reg =
+        /googleads\.g\.doubleclick\.net|www\.google-analytics\.com|www\.googletagmanager\.com/g;
+      if (request.url().match(reg)) {
+        // console.log(request.url(), response.status());
+      }
+    });
+  }
+
+  // Tests
+  // ---------------------------------------------------------------------------
+  test('single gtag', async ({ page }) => {
+    pageRequestListened(page);
+
+    const docsifyInitConfig = {
+      config: {
+        gtag: gtagList[0],
+      },
+      scriptURLs: ['/lib/plugins/gtag.min.js'],
+      styleURLs: ['/lib/themes/vue.css'],
+    };
+
+    await docsifyInit({
+      ...docsifyInitConfig,
+    });
+
+    const $docsify = await page.evaluate(() => window.$docsify);
+
+    // Verify config options
+    expect(typeof $docsify).toEqual('object');
+
+    // console.log($docsify.gtag, $docsify.gtag === '');
+
+    // Tests
+    expect($docsify.gtag).not.toEqual('');
+  });
+
+  test('multi gtag', async ({ page }) => {
+    pageRequestListened(page);
+
+    const docsifyInitConfig = {
+      config: {
+        gtag: gtagList,
+      },
+      scriptURLs: ['/lib/plugins/gtag.min.js'],
+      styleURLs: ['/lib/themes/vue.css'],
+    };
+
+    await docsifyInit({
+      ...docsifyInitConfig,
+    });
+
+    const $docsify = await page.evaluate(() => window.$docsify);
+
+    // Verify config options
+    expect(typeof $docsify).toEqual('object');
+
+    // console.log($docsify.gtag, $docsify.gtag === '');
+
+    // Tests
+    expect($docsify.gtag).not.toEqual('');
+  });
+
+  test('data-ga attribute', async ({ page }) => {
+    pageRequestListened(page);
+
+    // TODO
+  });
+});