Make gtag compliant with GDPR

[Alcatros]

🐛 Improvement (European E-Privacy directive and GDPR) - GTAG Manager not recognized

We add the google tag manager configuration like described in Docusaurus 1 but Docusaurus 2 seems not to recognize it. Responds with : Error: The field(s) 'gaTrackingId', 'gaGtag' are not recognized in docusaurus.config.js

I've realised that GTAG Manager can't be loaded with the current implementation, this is not according to the european data regulations eg. GDPR and E-Privacy. Therefore the errors below are not correct as stated as the feature is missing and we have changed it from a bug report to an improvement.

To Reproduce

Use the following config:

module.exports = {
  title: 'ProductMS Docs',
  tagline: 'Here we show you how you can use our software.',
  url: 'https://docs.companyname.com',
  baseUrl: '/',
  favicon: 'img/favicon.ico',
  organizationName: 'Company Compliance GmbH', // Usually your GitHub org/user name.
  projectName: 'Documentation', // Usually your repo name.
  gaTrackingId: 'GTM-ABCDEF', // Google Analytics GA TAG
  gaGtag: true,
  themeConfig: {
    navbar: {
      title: 'ProductMS Docs',
      logo: {
        alt: 'Product-Detail Logo',
        src: 'img/logo.svg',
      },
      links: [
        {to: 'docs/welcome', label: 'Docs', position: 'left'},
        {
          href: 'https://portal.companyname.com',
          label: 'Get Product-Detail',
          position: 'left',
        },
        {
          href: 'https://companyname.atlassian.net/servicedesk/customer/portals',
          label: 'Support',
          position: 'left',
        },
        {
          href: 'https://www.companyname.com/print_page.php',
          label: 'Imprint',
          position: 'right',
        },
        {
          href: 'https://www.companyname.com/privacy_policy_en.php',
          label: 'Privacy Policy',
          position: 'right',
        },
      ],
    },
    footer: {
      style: 'dark',
      links: [
        {
          title: 'Docs',
          items: [
            {
              label: 'Welcome',
              to: 'docs/welcome',
            },
          ],
        },
        {
          title: 'Support',
          items: [
            {
              label: 'EMail',
              href: 'mailto:[email protected]',
            },
          ],
        },
      ],
      logo: {
        alt: 'Company Compliance Logo',
        src: 'https://www.companyname.com/assets/img/Company.png',
      },
      copyright: `Copyright © ${new Date().getFullYear()} Company Compliance Limited`,
    },
  },
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],
};

Reproduction Steps:

yarn run v1.19.2
$ docusaurus build
Creating an optimized production build...
Error: The field(s) 'gaTrackingId', 'gaGtag' are not recognized in docusaurus.config.js

Expected behavior

I would have expected this to incorporate Google Tag Manager properly

Actual Behavior

It responded with the error message Error: The field(s) 'gaTrackingId', 'gaGtag' are not recognized in docusaurus.config.js

Your Environment

{
  "name": "g-3-dpms-documentation",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "docusaurus": "docusaurus",
    "start": "docusaurus start",
    "build": "docusaurus build",
    "swizzle": "docusaurus swizzle",
    "deploy": "docusaurus deploy"
  },
  "dependencies": {
    "@docusaurus/core": "^2.0.0-alpha.23",
    "@docusaurus/preset-classic": "^2.0.0-alpha.23",
    "classnames": "^2.2.6",
    "react": "^16.9.0",
    "react-dom": "^16.9.0"
  },
  "browserslist": {
    "production": [
      ">0.2%",
      "not dead",
      "not op_mini all"
    ],
    "development": [
      "last 1 chrome version",
      "last 1 firefox version",
      "last 1 safari version"
    ]
  }
}

Reproducible Demo

I dont have a runnable demo, as my build server is in a vpc, but i assume that you would be able to tell me if im doing something which is not possible or if its a bug / if im the first one to try, thank you

[yangshun]

Please read the docs - https://v2.docusaurus.io/docs/migrating-from-v1-to-v2/#gatrackingid

[Alcatros]

@yangshun thanks for the quick hint, how come the documentation doesnt show GTM-ABCDE , Google Tag Manager Identifications start with GTM and Universal Analytics from Google with UA

[Alcatros]

@yangshun Actually you should reopen the Issue. Docusaurus can't load GTAG Manager and is therefore uncompliant by default for European data regulations and privacy rights of the customer.

This makes docusaurus un-useable for european companies.

The modern GTAG (not to mistake by "GATAG or UA" which are the old versions), can understand if the customer wants his data to be taken or not for visiting the page. Otherwise docusaurus would need to implement an opt out banner itself to not load the Analytics.

[yangshun]

Ok then it's an improvement to make, and not a bug in the current implementation.

[Alcatros]

@yangshun Thanks, i've corrected the header accordingly

[amimas]

This would be a nice feature but just wanted to point out that google tag manager integration never existed in v1.

[shinebayar-g]

@Alcatros Is Google Tag Manager even supported in v1?

@amimas Do you know if it's there any workaround to get google tag manager working?

[amimas]

@shinebayar-g - I'm using V1 in several of my documentation website and have integrated with Google Tag Manager.

The way I've done it is this:

1. Add a script file in website/static/js/google-tag-manager.js that looks like this:

(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','<GTM-TAG-ID-GOES-HERE>');

2. Refer to the above script in site configuration (website/siteConfig.js):

  scripts: [
    siteUrl + "js/ep-google-tag-manager.js",
    'https://buttons.github.io/buttons.js'
  ]

The above steps will add the integration for you.

This would be a very simple feature for the V1 so that we could just add tag manager in website/siteConfig.js like this:

...
gtm_id: <GTM-TAG-ID-GOES-HERE>
...

But the V1 code base is apparently locked now; no small features or even bug fixes, even though V2 is not even past the alpha release yet.

[Alcatros]

@Alcatros Is Google Tag Manager even supported in v1?

@amimas Do you know if it's there any workaround to get google tag manager working?

No it isnt, the naming made me think it was but it was the prior version

@shinebayar-g - I'm using V1 in several of my documentation website and have integrated with Google Tag Manager.

The way I've done it is this:

1. Add a script file in `website/static/js/google-tag-manager.js` that looks like this:

(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','<GTM-TAG-ID-GOES-HERE>');

1. Refer to the above script in site configuration (`website/siteConfig.js`):

  scripts: [
    siteUrl + "js/ep-google-tag-manager.js",
    'https://buttons.github.io/buttons.js'
  ]

The above steps will add the integration for you.

This would be a very simple feature for the V1 so that we could just add tag manager in website/siteConfig.js like this:

...
gtm_id: <GTM-TAG-ID-GOES-HERE>
...

But the V1 code base is apparently locked now; no small features or even bug fixes, even though V2 is not even past the alpha release yet.

Would have been nice if you wrote it into the new codebase, the current Docusaurus cant be used without the consent notices for spying which documentation pages are visited. Makes it very unuseable, we like Docusaurus very much but compliance comes first

[amimas]

Would have been nice if you wrote it into the new codebase, the current Docusaurus cant be used without the consent notices for spying which documentation pages are visited. Makes it very unuseable, we like Docusaurus very much but compliance comes first

Not sure what you mean @Alcatros . It was just a workaround showing how gtm can be used with V1 as of this moment.

[slorber]

I believe we have happy users of GTM, like the React-Native website.

This issue is a bit messy and I have no idea what action to take on it. If there's still an issue on GTM support please open a new proper issue @Alcatros

[kravse]

I believe we have happy users of GTM, like the React-Native website.

This issue is a bit messy and I have no idea what action to take on it. If there's still an issue on GTM support please open a new proper issue @Alcatros

Ran into this problem, so just wanted to explain why I think it's still an issue.

https://reactnative.dev/ is using a universal analytics tag UA- rather than GTM- that @Alcatros requested above, meaning that they're not using the latest GDPR compliant version of google tag manager. Screenshot below illustrates this:

The solution would be to allow the docusaurus plugin-google-gtag to accept both tags like GTM-XXXXXXX or UA-XXXXXXXXX-X rather than the current implementation which only works with UA- prefixed tags. The difference between these two tags is fairly substantial (documented by google here) as the tags are tied to different versions of google tag manager.

Currently, if you shove a GTM- prefixed tag into plugin-google-gtag, the implementation fails and the tag appends the script but it doesn't fire properly.

Hope this is helpful in explaining the issue as I've experienced it.

[slorber]

@kravse

The solution would be to allow the docusaurus plugin-google-gtag to accept both tags like GTM-XXXXXXX or UA-XXXXXXXXX-X rather than the current implementation which only works with UA- prefixed tags.

Please explain how to do so. I'm not an expert at all on these topics and don't really understand why our current implementation is limited and can't work with GTM-xxx.

Also, what prevents you from implementing your own Docusaurus plugin in userland?

The goal of Docusaurus is not to provide an exhaustive list of fully-featured Analytics plugins. If gtag/ga plugins are in Docusaurus core, that's only because we use those plugins on the Docusaurus site itself, and should not be interpreted as a commitment for us to provide the ideal analytics for your use-case.

Considering I'm not an expert on this subject, it would be simpler for me if someone solved this first in userland so that I understand what it takes to support GTM tags, and then we could eventually find a way to merge this in Docusaurus core later if it makes sense.

[kravse]

@slorber very fair. My comment was only intended to clarify the ambiguities around the issue for anyone stumbling across the thread as I did. Whether its worth fixing is definitely up to you and the team or anyone who has time. I didn't request a fix, just provided some information in case it was useful.

I think the simplest work around is the one suggested earlier by @Alcatros.

All the best.

[slorber]

Thanks, going to re-open then.

I understand that Docusaurus is not compliant with GDPR. We are discussing internally to provide infrastructure to allow plugin authors (including ourselves) to hook into a global consent/cookie banner, so we'll make the GA/GTAG plugins compliant.

---

However, what I don't understand is why the lack of compliance with GDPR would actually make the plugin unusable with GTM?

I understand that you can't use it for legal reasons (only if you are in the EU BTW), not WHY it doesn't work.

@Alcatros can you clarify please?

The modern GTAG (not to mistake by "GATAG or UA" which are the old versions), can understand if the customer wants his data to be taken or not for visiting the page. Otherwise docusaurus would need to implement an opt out banner itself to not load the Analytics.

How does the "modern GTAG" know exactly?
Do you have any ref link to back this up?

[Alcatros]

@slorber since my initial comments a lot of things have changed.
You can achieve a GDPR compliant integration with GTAG which is Google Tag Manager
Nowadays you can also turn off data sharing with google analytics which is the GA-TAG im not 100% comfortable with my knowhow on UA but last time i reviewed this, that was uncompliant. (This is not legal advice here)

Here the reference for GTAG:
https://support.google.com/tagmanager/answer/7582054?hl=en
I wrote modern formerly as many people tend to host javascripts on their own pages :-)

[neoakris]

I don't believe GDPR compliance is solveable by Docusaurus (unless they bend over backwards to come up with some kind of free consent logging solution and make it easy to block cookie logic based on consent cookie), but it is easily solveable by the JAM stack architecture of using a Javascript based cookie consent API. So it might be worth closing this issue / declaring it as something the devs shouldn't try to solve, and instead directing people to use a solution like 1 of the 3 mentioned below, and if you google there's plenty more that exist than these.

I just finished implementing what I think is a compliant solution for my website:
Different Countries are adopting different privacy internet privacy laws
My strategy is to aim to comply with the most rigorous compliance requirements
as that way I'd likely be compliant with the laws of all countries.

When I was researching I read that the laws have evolved to a point where "consent logging" of cookie consent is recommended for maximum compliance. I'm unsure if it's actually required or just strongly encouraged.

Here are multiple sources that all recommend implementing consent logging: (Note no need to read through the following 3 links, I've summarized some key details further down, just trying to show sources of where I came up with the summarized information.)

• https://support.cookiebot.com/hc/en-us/articles/360003782654-Logging-and-demonstration-of-user-consents
• https://www.cookieyes.com/blog/cookieyes-logging-and-demonstration-of-cookie-consent
• https://www.iubenda.com/en/help/45718-cookie-preference-log

Consent logging = needs a database = costs money

The strictest compliance to internet privacy laws seem to require

1. Blocking / Preventing scripts/cookies associated with
   • Analytics (that could involve PII / collect IP Address)
   • Advertising
   • Marketing
     From running in a user's browser, until after users have explicitly consented to them.
2. Keeping "consent logs" / records of cookie preferences of users when they visit your site.
   In some cases it's not sufficient to merely refer to a correct configuration of the
   respective website. Documented Consent workflow with logs acts as strong evidence that a
   website obtained valid consent from the user.
3. The easyest way to copy with the above 2 options seems to be to use a $10/month or $100/year paid service
   like:
   • https://www.termsfeed.com/privacy-consent/
   • https://www.cookieyes.com/pricing/#pricing-comparison
   • https://www.cookiepro.com/products/cookie-consent/
   • Using a paid service makes sense, as it'd be difficult/costly to implement a
     logging database. The paid services are also affordable, offer a good
     developer UX/ease of implementation, and peace of mind in terms of maximum
     legal compliance.

Here's relevant config snippet from my docusaurus.config.js

const config = {
  presets: [ 
  ...
  ], //end presets
  scripts: [ //Note: All scripts are auto loaded regardless of whether or not users have consented to cookies.
  { async: true, src: 'https://cdn.termsfeedtag.com/plugins/pc/v1/dec09ef067_REDACTED_JIBBERISH_ad5a9/plugin.js', type: 'text/javascript' },
 ], //end scripts
 ...
 themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: { ... 
      },
     footer: {
       links: [
       ...
          { //footer column 5
            title: ' ',
            items: [
              {
                html: '<button href="#" id="open_privacy_preferences_element">Privacy Preferences</a>'
              },
              {
                html: '<button href="#" id="open_dnsmpi_element">Do Not Sell My Personal Information</a>'
              },
            ]
          }, //end footer column 5
        ]//end footer links                  
...

I login to termsfeed and add Google Analytics and Google Adsense to their solution. Their script makes it so Google AdSense and Google Analytics don't run until after the user has consented. And prevent them from running if the user removes their consent. Also in the footer I was able to create a button to let users adjust their consent at any time.

The button id's in the footer correspond to the termsfeed script / login portal website's docs.

guidescape.com if you want to see how the solution looks.
It's not free, but it's only $100/year so it's pretty affordable + great UX, functionality, seemingly legally correct, and I realize they need to use databases to host this solution, so for me that's more than enough to justify the price.

Note: I haven't used cookieyes.com but they have a reasonable / usable free tier that seems to meet GDPR requirements.

Another advantage of this approach is that it's a generic solution that works for all cookie use cases not just gtag.

Here are some snippets of the termsfeed.com login portal if anyone's curious:
(The Edit button in the picture is where I put the javascript logic associated with AdSense and different logic associated with Analytics)

Additional Notes:

• I'm not affiliated with them beyond being a satisfied customer
• I'm not 100% confident that termsfeed's blocking algorithm is 100% correct, but it's good enough for me.
  • here's what I mean by I'm not 100% confident it's correct
  • Firefox private window will default to reject all cookies and Google Adsense won't load unless user explicitly accepts.
  • Brave incognito window (when I use VPN from EU) results in Google Adsense not loading unless user explicitly accepts.
  • Brave incognito window (when I use VPN from USA) results in different behavior Google Adsense auto loads before explitly accepting, but if you reject and then reload the page, the Ads don't show up.
  • This might be normal behavior / them trying to use geolocation of client IP address to determine slightly different logic to apply, based on different laws of different country of origin determined by client IP.
  • Anyways I'm trying to say I've tested it and it seems to work / I'm personally happy enough with it to justify paying for it, but I'm not trying to make any guarantees.