feat: add google analytics gtag.js plugin

[ekoz]

Summary

Google Universal Analytics (gtag.js) plugin, usage is the same as src/plugins/ga.js

What kind of change does this PR introduce?

Feature

For any code change,

• Related documentation has been updated if needed
• Related tests have been updated or tests have been added

Does this PR introduce a breaking change? (check one)

• Yes
• No

If yes, please describe the impact and migration path for existing applications:

Related issue, if any:

#1695

Tested in the following browsers:

• Chrome
• Firefox
• Safari
• Edge
• IE

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/docsify-core/docsify-preview/42cj1nPMt4MNgraowyET4t8gHDEe
✅ Preview: https://docsify-preview-git-fork-ekoz-develop-docsify-core.vercel.app

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 6a3bd84:

Sandbox	Source
docsify-template	Configuration

[trusktr]

Nice, thanks! Can you add a similar doc section as GA? Also it needs lint fix.

[ekoz]

@trusktr Hi, I update this merge request again, pls check it when you are free, thanks ~

[ekoz]

@trusktr Hi, there is an error, ci/codesandbox — Building packages failed., Is there anything I can do?

[trusktr]

Hey @ekoz. Updated and re-running the checks.

[ekoz]

@jhildenbiddle thanks, I read the docs https://playwright.dev/docs and have a try, run with npm run test:e2e ga.test.js.

How to test data-ga with playwright?

[ekoz]

@jhildenbiddle Ping! 😄

[jhildenbiddle]

Hey @ekoz.

Apologies for the delayed response. Let's see if we can wrap this up and get it shipped. 😄

• Now that I better understand the purpose of the gtag snippet, I think we are better off creating a new gtag plugin (as you originally proposed). I initially thought the snippet GA4-specific, but my understanding is that it is more of a universal snippet for Google services. Knowing this, it would be inappropriate to imply that this is a "Google Analytics" plugin ("ga.js") and instead make it clear that this is for Google's universal gtag plugin ("gtag.js").
• If we create a new "gtag" plugin, we'll need to update the $docsify property names as well (e.g., gtag instead of ga).
• I don't think we need to worry about the more complex scenarios handled by gaCollector as proposed in previous comments. Advanced users that require these configurations can simply call gtag() in a <script> on their own (see below). We should call this out in the docs as well.

What this all boils down to:

1. Rename plugin to gtag.js and make necessary updates to accommodate name change
2. Fix issues outlined below

Thanks for your patience with all of this back and forth, @ekoz. As I said early on, I'm not a Google Analytics expert so much of the churn has been caused by me learning more about GA and the gtag snippet as we go.

[jhildenbiddle]

Please disable eslint's "camelcase" rules for under_score properties to prevent lint warnings:

window.gtag('event', 'page_view', {
  /* eslint-disable camelcase */
  page_title: document.title,
  page_location: location.href,
  page_path: location.pathname,
  /* eslint-enable camelcase */
});

You can verify the fix by running npm run lint.

[ekoz]

Hi, there is some questions:

1. Do we still need to keep ga.js ?
2. docs/plugins.md is necessary to keep the instructions for ga and add the instructions for gtag ?

[jhildenbiddle]

I believe we need to keep ga.js (unmodified) because people are actively using this plugin. Your work would then be a new plugin, gtag.js.

We should update the documentation and specify that the

We should update the documentation to specify that the ga.js plugin is for "Google Universal Analytics". We can also provide a slightly modified warning that align with the one Google shows when you log into https://analytics.google.com/ and view a UA property:

Perhaps our message under the ga.js heading can read:

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.

How does that sound?

[ekoz]

Great~

[ekoz]

I just pushed the code, there is an exception in ci/codesandbox. I'm not sure what the reason is, please check it for me.

[jhildenbiddle]

I took a look and tried a few things in #1851 but I was unable to find the issue. This happened once before with Codesandbox it is it kinda of a PITA to troublehoot because the failures don't happen locally or in CI tests.

As much as I'd love to wrap this up, I don't have the spare cycles to devote to it right now. I will circle back as soon as I can devote some time to it.

In the meantime, thanks for being patient with this, @ekoz. Very much appreciated. 😄

[jhildenbiddle]

Let's move the window.dataLayer and window.gtag setup outside of the initGlobalSiteTag function. This will allow users to call gtag() so long as it is done after the plugin's <script> tag:

Plugin:

window.dataLayer = window.dataLayer || [];
window.gtag =
  window.gtag ||
  function () {
    window.dataLayer.push(arguments);
  };

$docsify.plugins = [].concat(install, $docsify.plugins);

HTML:

<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify@4/lib/plugins/gtag.min.js"></script>
<script>
// Advanced users can call `gtag()` on their own
window.gtag('event', 'conversion', {
  allow_custom_scripts: true,
  send_to: 'DC-ZZZZZZ/actions/locat304+standard',
});
</script>

[ekoz]

This is not work, I think we can ignore this function for the time being, and then pass the custom collector in through parameters when we need it later.

[jhildenbiddle]

Let's remove or comment out the console.log tests so we don't see them in every test run.

[JobaDiniz]

can we merge this one?