search

facebook / docusaurus

Easy to maintain open source documentation websites.
https://docusaurus.io
MIT License
56.87k stars 8.56k forks source link

Make gtag compliant with GDPR #2407

Open Alcatros opened 4 years ago

Alcatros commented 4 years ago

🐛 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:support@companyname.com',
            },
          ],
        },
      ],
      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 commented 4 years ago

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

Alcatros commented 4 years ago

@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 commented 4 years ago

@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 commented 4 years ago

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

Alcatros commented 4 years ago

@yangshun Thanks, i've corrected the header accordingly

amimas commented 4 years ago

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

shinebayar-g commented 4 years ago

@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 commented 4 years ago

@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.

Alcatros commented 4 years ago

@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 commented 4 years ago

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 commented 3 years ago

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 commented 3 years ago

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:

Screen Shot 2021-10-29 at 2 02 14 PM

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 commented 3 years ago

@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 commented 3 years ago

@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 commented 3 years ago

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 commented 3 years ago

@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 commented 1 year ago

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.)

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:

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) image image

Additional Notes: