Integraties

CMS plugin – design recommendations

262 views 24 april 2018 9 mei 2018 Christian Vriens 2

What is ConsentCookie?

ConsentCookie is a cookie consent mechanism, which enables website visitors to have control over data being stored by trackers, pixels, cookies en similar technologies. 

ConsentCookie can be used on a website by injecting a script, which enables the ConsentCookie widget.

WordPress example of the ConsentCookie widget

 

Who should read this document?

The most basic way to implement ConsentCookie on your website is adding the script to your website. This requires some technical expertise and you have to have access to templates or files which host your website.

Most Content Management Systems (like WordPress) or webshops (like Magento), can be extended with plugins. This document describes how to develop a ConsentCookie plugin for such platforms. A ConsentCookie plugin should make it easier to integrate ConsentCookie on a website platform. The plugin must inject the ConsentCookie script and offer the possibility to configure ConsentCookie in an easy way.

So, to come back to the question, who should read this document? This document is targeted for developers who are going to develop a plugin for a platform to integrate ConsentCookie and need some extra information about how to do this.

Functionalities

Basically the plugin should offer two functionalities:

  1. a configuration page for ConsentCookie
  2. publish the ConsentCookie widget on public pages

ConsentCookie configuration page

The ConsentCookie configuration page enables the website owner to configure ConsentCookie to their needs. Once configured, the plugin must store the configuration, most likely in the database of the used platform. This configuration should be loaded together with the static ConsentCookie script when publishing the widget.

The ConsentCookie configuration is split up in two parts:

  1. JSON configuration which defines consents are active and how the widget is displayed
  2. custom Java script which handles the (de)activation of a consent

WordPress example of a configuration page

JSON configuration

The JSON configuration defines which consents are offered in the widget. For example, if your website uses Google Analytics and Facebook your widget should be configured in a way that consents for these tracking applications. Per application it is possible to configure if opt-in, opt-out, or always-on applies to the consent.

HumanSwitch maintains a predefined list of applications. This list can be used on the configuration page as a list from which the user can choose which applications are active on the website.

The style and some texts can be modified with the configuration as well. Currently you can configure:

  • if a consent wall is active and its delay time
  • position of the widget (bottom left or bottom right (default))
  • primary and secondary color
  • help title
  • help contents

 

The configuration should be passed along to the ConsentCookie javascript component as JSON.

 

window.ConsentCookie.init({
    "general": {
       "consentwall": {
          "enabled": false,
          "timeout": 1000
       }
    },
    "apps": {
       "endpoint": "https://www.consentcookie.nl/consentcookie/latest/consentcookie.json",
       "consent": {
          "ga": {
             "initstate": "optin"
          },
          "gtm": {
             "initstate": "optin"
          }
       }
    },
    "design": {
       "layout": {
          "position": "right"
       },
       "colorscheme": {
          "primary": "#FC6D6D",
          "secondary": "#FFFFFF"
       }
    },
    "resources": {
       "nl": {
          "info": {
             "title": "Over ConsentCookie",
             "text": "<p>Baas ... entcookie.nl</a></p>"
          },
          "consent": {
             "title": "ConsentCookie!",
             "text": "<p>Deze...eren.</p>",
             "button": "Ok!",
             "infolink": "https://www.consentcookie.nl"
          }
       }
    }
 });

Example of configuring the ConsentCookie JavaScript component

You can create a configuration screen that offers all kind of configuration fields and which eventually mappes those fields to a configuration JSON object, like the previous example. However, you can also integrate a JavaScript component, called ConsentCookie Configurator, which will do all the hard work for you!

ConsentCookie configurator

The ConsentCookie configurator (CCC) is a JavaScript component which can be included on a configuration page. Contact us for the latest version. Look at it like it is a form component, like a textarea. Instead, it displays a lot of controls for you and in the end it will create the configuration JSON for you.

Example ConsentCookie configurator (CCC)

 

To integrate CCC on your configuration page you will first have to:

  1. add the following JavaScripts and stylesheet to the <head> section of the page:
    • manifest.js
    • vendor.js
    • app.js
    • app.css
  2. insert a <div> tag with an id. This will be the placeholder for the CCC.
  3. initialize and mount the CCC component:
new CCC("#<id>").mount();

 

At this point, the <div> tag will be replaced with the CCC component.

The CCC object has a few functions, which are described here.

 

The following example is a very plain configuration page that will put the CCC configuration in an textarea field when the CCC configuration changes.

 

<!DOCTYPE html>
 <html>
 <head>
  <meta charset="UTF-8">
  <script type='text/javascript' src='https://www.consentcookie.nl/configurator/static/js/manifest.js'></script>
  <script type='text/javascript' src='https://www.consentcookie.nl/configurator/static/js/vendor.js'></script>
  <script type='text/javascript' src='https://www.consentcookie.nl/configurator/static/js/app.js'></script>
  <link rel='stylesheet' href='https://www.consentcookie.nl/configurator/static/css/app.css' type='text/css' media='all' />
 </head>
 <body>
  <div id="ccc-holder">
  </div>
  <textarea id="ccc-result"></textarea>
  <script>
  var ccc = new CCC("#ccc-holder").onChange(
  function(configurator, config) {
  document.getElementById("ccc-result").value = JSON
  .stringify(config, null, 2);
  }).mount();
  </script>
 </body>
 </html>

Example CCC configurator

This example can be found here.

Custom Java script

For now, for many applications some extra script is needed to anticipate on the users consent choice. Take Google Analytics for example. The following script is needed to enable Google Analytics when the users agrees with the GA consent:

 

// Check if the user accepted the Google Analytics consent
 if(ConsentCookie.get("ga").flag === 1){
   // If so, load the Google Analytics integration script, https://developers.google.com/analytics/devguides/collection/analyticsjs/
 
   // The script provided by Google Anayltics
   (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
   (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
   m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
   })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');
 
   ga('create', 'UA-XXXXX-Y', 'auto');
   ga('send', 'pageview');
 
 }

 

This piece of script is required in this case. So the user must be able to integrate this piece of script into the public page that uses ConsentCookie.

It is up to the plugin to offer a field in which the user can configure this script. If configured, the script should be added to the public pages that contains the ConsentCookie widget.

Publish ConsentCookie widget

The public CookieConsent script, the configuration (script) and the custom script are required on all of the pages on which CookieConsent are displayed.

For this, you will first have to add the CookieConsent script to the <head> section of the public page:

 

<head>

    <script type='text/javascript' src='https://www.consentcookie.nl/consentcookie/latest/consentcookie.min.js'></script>

 

This script will load the ConsentCookie library. After being loaded you can access the global ConsentCookie object and its functions.

It is preferred to load this script as early as possible. This way, other scripts get the most current state of a consent.

After this script is loaded it is best practice to immediately initialize ConsentCookie. This can be done with the function window.ConsentCookie.init(). This function expects the configuration in JSON format as an argument. See also JSON configuration.

Last, but not least, the configured script custom script needs to be dynamically added to the published page. You can insert this immediately after the initialization.

An example of all these pieces together:

<!DOCTYPE html>

<html>

<head>

    <meta charset="UTF-8">

    <script type='text/javascript' src='https://www.consentcookie.nl/consentcookie/latest/consentcookie.min.js'></script>

    <script type='text/javascript'>

        window.ConsentCookie.init({

            "general": {

                "consentwall": {

                    "enabled": false,

                    "timeout": 1000

                }

            },

            "apps": {

                "endpoint": "https://www.consentcookie.nl/consentcookie/latest/consentcookie.json",

                "consent": {

                    "ga": {

                        "initstate": "optin"

                    },

                    "gtm": {

                        "initstate": "optin"

                    }

                }

            },

            "design": {

                "layout": {

                    "position": "right"

                },

                "colorscheme": {

                    "primary": "#FC6D6D",

                    "secondary": "#FFFFFF"

                }

            },

            "resources": {

                "nl": {

                    "info": {

                        "title": "Over ConsentCookie",

                        "text": "<p>Baas over eigen data, dat vinden wij heel normaal. Niet alleen vanwege de AVG, maar omdat wij geloven in transparantie en fatsoen. Daarom gebruiken wij ConsentCookie.</p>\n<p>ConsentCookie laat jou zien welke data we van jou verzamelen en waarom we dat doen. Ga naar Jouw instellingen om jouw persoonlijke voorkeuren vast te leggen. Ze zijn daarna direct van kracht en kunnen op elk moment worden aangepast.</p>\n<p>ConsentCookie op jouw eigen website gebruiken?<br />Voor meer informatie:<a href=\"\\&quot;https:/www.consentcookie.nl\\&quot;\">www.consentcookie.nl</a></p>"

                    },

                    "consent": {

                        "title": "ConsentCookie!",

                        "text": "<p>Deze website maakt gebruik van <a href=\"\\&quot;https:/www.consentcookie.nl.nl\\&quot;\"><u>ConsentCookie</u></a> om je cookies en privacy toestemmingen op deze website te beheren.</p>",

                        "button": "Ok!",

                        "infolink": "https://www.consentcookie.nl"

                    }

                }

            }

        });



        // Check if the user accepted the Google Analytics consent

        if(ConsentCookie.get("ga").flag === 1){

            // If so, load the Google Analytics integration script, https://developers.google.com/analytics/devguides/collection/analyticsjs/



            // The script provided by Google Anayltics

            (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){

                    (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),

                m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)

            })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');



            ga('create', 'UA-XXXXX-Y', 'auto');

            ga('send', 'pageview');



        }

    </script>

</head>

<body>

</body>

</html>

Example public page with ConsentCookie widget

 

Heeft dit geholpen?