ConsentCookie

Open source AVG solution for websites. More info: www.consentcookie.nl

ConsentCookie on your website

Download the script here or build your own (custom) ConsentCookie

Include the script on your website:

<script src="https://github.com/humanswitch/consentcookie/raw/master/path/to/consentcookie.min.js"></script>

Initialize ConsentCookie:

<script>
// An example of ConsentCookie initialized with a custom config
ConsentCookie.init({
    'connections': {
      'cc': {
        'initstate': 'disabled'
      },
      'iq': {
        'initstate': 'optout'
      },
      'ga': {
        'initstate': 'disabled'
      },
      'gtm': {
        'initstate': 'disabled'
      }
    },
    'moreinfolink': 'https://www.humanswitch.io/over/privacy/'
  });
</script>

To load a tracker based on the ConsentCookie preference of the user you can do the following:

<script>
// Check if the user accepted the consent for the given connection by its id
if(ConsentCookie.get("id").flag === 1){
  // Do stuff
}
</script>

Google Analytics example

<script>
// 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>

Basic Usage

API

ConsentCookie.init

To enabled ConsentCookie you need to initialize it with a config object. The config object should have the following properties:

ConsentCookie.init({
    'connections': {
      // connection 1
      'id 2':{
        //connection config
      }
      // connection 2
      'id 1':{
        //connection config
      }
    },
    'moreinfolink': 'https://www.link-to-your-info.com'
  });
</script>

A connection represents a consent integration with your website. Each connection has a specific id that should correspond with an id of a connection listed in ConsentCookie tracker list. The connection config should have the following properties

ConsentCookie.on

You can listen for an event with a given callback:

ConsentCookie.on("consent",function($payload){
  // Do stuff
});

The following events are emitted:

The callback function will receive a single payload object as argument with the following default properties:

Depending on the event type additional properties can be available in the payload object.

ConsentCookie.off

You can remove all event listeners of an event by giving the name of the specific event:

ConsentCookie.off("consent");

You can also remove a single listener:

var specificListener = function($payload){
  // Do stuff
};

// Register the specific listener
ConsentCookie.on("consent",specificListener);

// Unregister the specific listener
ConsentCookie.off("consent",specificListener);

ConsentCookie.get

You can get the current state of a consent by giving the id of the consent:

ConsentCookie.get("id");

The return is a consent object with the following properties:

ConsentCookie.registerPlugin

To add addition functionality to ConsentCookie, you can register a plugin for each unique connection.

Plugins

ConsentCookie plugins provide the option to extend ConsentCookie functionality for specific connections. Each connection can load a (custom) plugin. Default plugins are provided by the default ConsentCookie tracker list.

Plugins are Javascript files following a spefic convention and should be publicly availbled by a url. They are initially loaded when opening the Connections view, for each connection if configured for that specific connection.

Example

(function ($global) {

function Plugin() {}

Plugin.prototype.register = function ($context) {
this.context = $context;
};

Plugin.prototype.getId = function () {};

Plugin.prototype.getProfileId = function () {};

Plugin.prototype.getProfileIds = function () {};

Plugin.prototype.getProfile = function () {};

Plugin.prototype.getProfileInfo = function () {};

Plugin.prototype.deleteProfile = function () {};

if (!$global || !$global.ConsentCookie || typeof $global.ConsentCookie.registerPlugin !== 'function') {
throw new Error('ConsentCookie not available. Unable to register plugin: ' + DEFAULT_ID);
}

$global.ConsentCookie.registerPlugin(new Plugin());

})(window);

Registering a plugin in the ConsentCookie client

To make the plugin available in ConsentCookie it needs to register itself by calling ConsentCookie.registerPlugin. Calling this function, will load the plugin and call Plugin.register providing a context object that can be used within the plugin.

$global.ConsentCookie.registerPlugin(new Plugin());

Called by ConsentCookie when registerPlugin is executed:

Plugin.prototype.register = function ($context) {
  this.context = $context;
};

Plugin Context

The plugin context is a Javascript object with the following API:

The following libraries are available:

Plugin default interface

ConsentCookie will call the following functions of the plugin when implemented.

Plugin.getProfileInfo

This function is used by ConsentCookie to show a summary of the profile the connection is managing. ConsentCookie uses a default template for showing this info. The template consists of a header and content panel.

When ConsentCookie calls getProfileInfo it expects a promise that resolves in an object with the following properties:

{
    "header": "<div>I am a header</div>",
    "content": "<div>I am content</div>"
}

Plugin listening for events

A plugin can also listen for changes by using the ConsentCookie event framework.

// Plugin code that runs when loading the plugin
(function ($global) {

    // Register event listener when plugin is loaded
    $global.ConsentCookie.on('connection', function ($payload) {

        // Listen for connection changes

        // Do stuff
    });

})(window);

Custom plugin

By default all used plugins are defined in the ConsentCookie tracker list. When you want to use a custom plugin for a specific connection your can override the default url with a custom one.

To override the default url, add the property plugin to the connection config of which you want to load the custom plugin.

ConsentCookie.init({
    'connections': {
      // Google Analytics with custom plugin
      'ga': {
        'initstate': 'disabled',
        'plugin':'https://yourdomain.com/the/location/of/the/plugin.js'
      }
    },
    'moreinfolink': 'https://www.link-to-your-info.com'
  });

Build your own ConsentCookie

Prerequisites

1. Node.js => 4.0.0
2. NPM => 3.0.0

Installing

Clone a copy of the main ConsentCookie git repo by running:

git clone git://github.com/humanswitch/consentcookie.git

Install the project dependencies:

cd consentcookie && npm install

Developing

To run the development server with the demo page:

npm run dev

A browser window will automatically open with the demo page visible.

Building

To build ConsentCookie for deployment:

npm run build -- -r

Using the -r option will create a singlefile minified version of ConsentCookie that is optimized for use on websites.

Building single file

To build ConsentCookie in 1 file consentcookie.min.js for release.

npm run release

Built With

• VueJS - The application framework used
• Webpack - Module bundler for building the application

Authors

• Christian Vriens - Initial work - HumanSwitch
• Ramon Rockx - Initial work - HumanSwitch
• Steven Choo - Initial work - HumanSwitch

See also the list of contributors

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details

Acknowledgments

• OOGT - for creating the intial design of ConsentCookie
• Eveline Druncks - for helping with improving the initial design of ConsentCookie