Newfangled Package Modernizer

    gatsby-plugin-gdpr-tracking

    1.2.2 • Public • Published

    gatsby-plugin-gdpr-tracking

    Gatsby plugin to add analytics services like Google Analytics, Hotjar or Google Ads GDPR compliant.

    Install

    npm install --save gatsby-plugin-gdpr-tracking

    How to use

    // In your gatsby-config.js
    module.exports = {
      plugins: [
        {
          resolve: 'gatsby-plugin-gdpr-tracking',
          options: {
            // logging to the console, if debug is true
            debug: false, 
            googleAnalytics: { 
                // The property ID; the tracking code won't be generated without it.
                trackingId: 'YOUR_GOOGLE_ANALYTICS_TRACKING_ID',
                // Defines it google analytics should be started with out the cookie consent
                autoStart: true, // <--- default
                // Setting this parameter is optional
                anonymize: true, // <--- default
                // Name of the cookie, that enables the tracking if it is true
                controlCookieName: 'gdpr-analytics-enabled', // <--- default
                cookieFlags: 'secure;samesite=none' // <--- default
            },
            googleAds: {
              // The property ID; the tracking code won't be generated without it.
              trackingId: 'YOUR_GOOGLE_ADS_TRACKING_ID',
              // Setting this parameter is optional
              anonymize: true, // <--- default
              // Name of the cookie, that enables the tracking if it is true
              controlCookieName: 'gdpr-marketing-enabled', // <--- default
              cookieFlags: 'secure;samesite=none' // <--- default
            },
            facebookPixel: {
              // The property ID; the tracking code won't be generated without it.
              pixelId: 'YOUR_FACEBOOK_PIXEL_TRACKING_ID',
              // Name of the cookie, that enables the tracking if it is true
              controlCookieName: 'gdpr-marketing-enabled', // <--- default
            },
            hotjar: {
              // The Hotjar ID; the tracking code won't be generated without it.
              trackingId: 'YOUR_HOTJAR_ID',
              // Your Hotjar snippet version
              snippetVersion: '6', // <--- default
              // Name of the cookie, that enables the tracking if it is true
              controlCookieName: 'gdpr-analytics-enabled' // <--- default
            },
            // Defines the environments where the tracking should be available  - default is ["production"]
            environments: ['production', 'development']
          },
        },
      ],
    }

    How it works

    First of all the plugin checks in which environment your site is running. If it's currently running in one of your defined environments it will add the Google Analytics, Google Ads and Hotjar Pixel tracking code (script tags) by default to the <head> of your site. It will not be activated or initialized by this.

    PLEASE NOTICE!

    If the googleAnalytics.autoStart option is true, then it will start tracking to Google Analytics without user consent! In order to be perfectly compliant to GDPR you have to set it to false!

    Google Analytics

    If the googleAnalytics.autoStart option is false, this plugin will not send any data to Google Analytics to make it GDPR compliant. The user first needs to accept your cookie policy. By accepting that, you need to set the cookie, that you can configure in the option: googleAnalytics.controlCookieName. Depending on the user input the value of the cookies should be true or false. Usually you have to reload the page after changing the control cookie value. But with this plugin you can simple call the function window.trackGoogleAnalytics() to start the tracking. You page view will be tracked without reloading the page. This function still check the value of the control cookie. So you have to set it to true first and then call the function after the user has confirmed the consent.

    JavaScrip API of Google Analytics

    This plugin uses the new Google Analytics API that is working with Google Tag manager (gtas.js) Here you can find the Google Docs: https://developers.google.com/analytics/devguides/collection/gtagjs

    This plugin loads the gtag.js library, establishes googleAnalytics.trackingId as the default Google Analytics property ID, and sends a pageview hit to Google Analytics.

    This is the code of onRouteUpdate method created by this plugin

    gtag(
      'config', googleAnalyticsOpt.trackingId, {
      'anonymize_ip': googleAnalyticsOpt.anonymize.toString(),
      'page_path': location.pathname
    });

    Helper functions, that you can use in your code:

    window.trackGoogleAnalytics() - sends a pageview hit to Google Analytics, depending on the current value of the control cookie

    window.trackGoogleAnalyticsEvent(category, params) - sends an event to Google Analytics, depending on the current value of the control cookie

    window.gaOptout() - If your visitors should be able to set an Opt-Out-Cookie (No future tracking) you can set a link e.g. in your imprint as follows:

    <a href="javascript:gaOptout();">Deactivate Google Analytics</a>

    Google Ads and Hotjar

    By default, this plugin will not send any data to Google Ads or to Hotjar to make it GDPR compliant. The user first needs to accept your cookie policy. By accepting that you need to set cookies that you can configure in the options: googleAds.controlCookieName and hotjar.controlCookieName. Depending on the user input the value of each of the cookies should be true or false.

    Hotjar

    If the value of hotjar.controlCookieName cookie is true, Hotjar will be initialized onClientEntry. After the page reload it will track the page by the Hotjar library. You can also use trigger the tracking by using the helper function:

    window.trackHotjar() - trigger the tracking of the website by Hotjar, only if the value of the control cookie is true.

    Google Ads

    Sometimes you want to track the Google Ads Analytics in separate Google Ads account. Then you can activate it by setting the trackingId of googleAds configuration object.

    The tracking of Google Ads is very similar to Google Analytics. Basically they differ only by the tracking ID and the name of the helper functions to use.

    Helper functions, that you can use in your code:

    window.trackGoogleAds() - sends a pageview hit to Google Ads Analytics, depending on the current value of the control cookie

    window.trackGoogleAdsEvent(category, params) - sends an event to Google Ads Analytics, depending on the current value of the control cookie

    Facebook Pixel

    The user first needs to accept your cookie policy. By accepting that, you need to set the cookie, that you can configure in the option: facebookPixel.controlCookieName. Depending on the user input the value of the cookies should be true or false. Usually you have to reload the page after changing the control cookie value. But with this plugin you can simple call the function window.trackFbPixel() to start the tracking. You page view will be tracked without reloading the page. This function still check the value of the control cookie. So you have to set it to true first and then call the function after the user has confirmed the consent.

    JavaScrip API of Facebook Pixel

    This plugin loads the https://connect.facebook.net/en_US/fbevents.js library and sends a PageView hit to Facebook.

    This is the code of onRouteUpdate method created by this plugin

      fbq('track', 'PageView');

    Helper functions, that you can use in your code:

    window.trackFbPixel() - sends a pageview hit to Facebook, depending on the current value of the control cookie

    Important:

    Please keep in mind setting the cookies. Otherwise, the tracking won't work! Tracking won't happen at all if there are no cookies or they are set so false.

    Options

    Global:

    debug

    Logging to the console, if this option is true. Default is false.

    environments

    Defines the environments where the tracking should be available. Default is ["production"].

    Google Analytics googleAnalytics configuration object:

    trackingId

    Here you place your Google Analytics tracking id.

    autoStart

    Should the tracking starts immediately without consent or not. Default is true. You can set it to false to let it be controlled via cookie with the name defined in controlCookieName option

    controlCookieName

    Name of the control cookie. Needed if autoStart sets to false. If the value of this cookie it set to true, then tracking is activated

    anonymize

    Some countries (such as Germany) require you to use the _anonymizeIP function for Google Analytics. Otherwise you are not allowed to use it.

    Google Ads Pixel googleAds configuration object:

    trackingId

    Here you place your Google Analytics tracking id.

    anonymize

    Some countries (such as Germany) require you to use the _anonymizeIP function for Google Analytics. Otherwise you are not allowed to use it.

    controlCookieName

    Name of the control cookie. If the value of this cookie it set to true, then tracking is activated

    cookieFlags

    The new cookieFlags field allows you to set any cookie directive when the Google Analytics cookie is created.

    The value of this setting is a semi-colon separated list of lowercase cookie directives and their respective values. For example, this is a possible value of cookieFlags:

    max-age=7200;domain=simoahava.com;path=/;secure;samesite=none

    The default value is: secure;samesite=none

    See more details here: https://www.simoahava.com/analytics/cookieflags-field-google-analytics/

    Hotjar hotjar configuration object:

    trackingId

    Your Hotjar ID

    snippetVersion

    Your Hotjar snippet version or 6 by default

    controlCookieName

    Name of the control cookie. If the value of this cookie it set to true, then tracking is activated

    Facebook Pixel facebookPixel configuration object:

    pixelId

    Your Facebook Pixel ID

    controlCookieName

    Name of the control cookie. If the value of this cookie it set to true, then tracking is activated

    Install

    npm i gatsby-plugin-gdpr-tracking

    DownloadsWeekly Downloads

    303

    Version

    1.2.2

    License

    MIT

    Unpacked Size

    35.4 kB

    Total Files

    9

    Last publish

    Collaborators

    • dev-as