Q4Widgets API Documentation

q4.cookieMonster

Cookie Monster - Q4 Cookie Management Tool
This tool was created for Q4 Sites to be more compliant with GDPR and ePR
This tool enables more control on how third-party plugins are added to the site and gives users the ability to opt-in or out from plugins
that sets cookies to track possibly personally indentifiable information.

Latest Version Update: 1.0.0
- updated optional cookie toggle to be accessible


Version Update: 0.1.8
- added disclaimer tpl and preferences tpl as options
- more control with how the template is added using container and insert function options


Version Update: 0.1.7
- widget content is appended instead of prepended
- fix button classes that were not working from options
Script link
q4.cookiemonster.1.0.0.min.js
Source file
q4.cookiemonster.js, line 49
Requires

Examples

<script type="text/javascript">
$(window).cookieMonster({
  logo: '', //default
  initState: 'disclaimer', // disclaimer/open/closed
  acceptOnClose: false, // when users click on the close button or outside the sidebar this will set the cookie and the recommended settings.
  googleUACode: 'UA-xxxxxxx-xx',
  disclaimer: {
    layout: 'banner', //popup/banner
    style: 'slide-up', //slide-up/fade-in
    header: 'Cookies on this website.',
    description: 'We use cookies on q4inc.com to provide you with the best possible experience. If you wish to review the cookies we store, please select the Cookie Preferences option on this banner. After your preferences are saved, you can use the cookie icon at the left to modify your selections at any time. For more information, you can review our <a href="/privacy-policy/default.aspx">Privacy Policy</a> and <a href="/cookie-policy/default.aspx">Cookie Policy</a>.',
    accept: 'Accept',
    control: 'Cookie Preferences',
    deny: 'No, thanks',
    closeButton: true,
    onDeny: function() {},
    onAccept: function() {},
    onClose: function() {}
  },
  preferences: {
    position: 'left', //left/right
    header: 'Q4INC.COM Cookie Preferences',
    description: 'Please use the following sections to learn more about the types of cookies we use, and how you can opt out of those you do not wish to be stored. At q4inc.com, we respect your privacy and are committed to protecting your information. For more information, you can review our <a href="/privacy-policy/default.aspx">Privacy Policy</a> and <a href="/cookie-policy/default.aspx">Cookie Policy</a>.',
    statement: null,
    recommendedText: 'Accept Recommended Settings',
    necessaryHeader: 'Necessary Cookies',
    necessaryDescription: 'These cookies are necessary for the services and viewing experience of this site, and cannot be opted out of via this tool. If you still wish to remove these, you may do using your browser settings. A description of these technologies is provided in our <a href="/privacy-policy/default.aspx">Privacy Policy</a> and <a href="/cookie-policy/default.aspx">Cookie Policy</a>.',
    thirdPartyHeader: 'Warning: Some cookies require your attention',
    thirdPartyDescription: 'Consent for some third party cookies can not be automatically revoked. Please follow the link below if you want to opt out of them.',
  },
  style: {
    disclaimer: {
      headerColor: '#0f5ca3',
      textColor: '#939ba0',
      buttonTextColor: '#2a3035',
      acceptButtonColor: '#f1af0f',
      acceptButtonBorder: '2px solid #f1af0f'
    },
    preference: {
      bgcolor: '',
      headerColor: '#0f5ca3',
      textColor: '#939ba0',
      acceptButtonColor: '#f1af0f',
      buttonTextColor: '#2a3035',
      warningHeaderColor: '#333',
    }
  },
  optionalCookies: [{
      name: 'pardot',
      label: 'Pardot by Salesforce',
      description: 'We use these cookies to deliver a seamless user experience for those customers and users that have created an account with us for receiving email communications.',
      cookies: ['lpv*', 'pardot', 'visitor_id*'],
      onAccept: function() {
        piAId = 'xxxx';
        piCId = 'xxxx';

        function async_load() {
          var s = document.createElement('script');
          s.type = 'text/javascript';
          s.src = ('https:' == document.location.protocol ? 'https://pi' : 'http://cdn') +
            '.pardot.com/pd.js';
          var c = document.getElementsByTagName('script')[0];
          c.parentNode.insertBefore(s, c);
        }
        async_load();
      },
      onRevoke: function() {},
      onDeny: function() {},
      thirdPartyCookies: {
        name: 'Pardot by Salesforce',
        optOutLink: 'https://help.salesforce.com/articleView?id=pardot_basics_cookies.htm&type=5'
      }
    },
    {
      name: 'linkedin',
      label: 'LinkedIn Ads',
      description: 'We use the LinkedIn Ads cookie to track the success of LinkedIn advertising. This cookie is an analytics tool that allows us to measure the effectiveness of advertising by understanding the actions people take on our website.',
      cookies: ['bcookie', 'liap', 'li_oatml'],
      onAccept: function() {
        _linkedin_data_partner_id = "xxxxx";
        var s = document.getElementsByTagName("script")[0];
        var b = document.createElement("script");
        b.type = "text/javascript";
        b.async = true;
        b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
        s.parentNode.insertBefore(b, s);
      },
      onDeny: function() {},
      onRevoke: function() {},
      thirdPartyCookies: {
        name: 'LinkedIn Ads',
        optOutLink: 'https://www.linkedin.com/help/linkedin/answer/62931/manage-advertising-preferences?lang=en'
      }
    }
  ],
  complete: function(e) {}
});
</script>

Options

container string
Element container to append the tool
Default value
body
insertFunction string
jQuery function used to add the template to container
Default value
prepend
acceptOnClose boolean
Determines if the close buttons and overlay should accept recommended settings (turns all plugins on) when clicked.
Default value
false
initState string
Initial state of the tool when no cookie is set. 'disclaimer' will show a popup banner or box. 'open' will show the sidebar tool.
Default value
disclaimer
Example
initState: 'disclaimer'/'open',
googleUACode string
Google Analytics code can be added here, which the tool will automatically build the optional cookie object.
disclaimer object
Disclaimer object, comprises of text options and style options. As well as callback functions
Example
disclaimer: {
    layout: 'popup', // 'popup' - will show the disclaimer as a box on the right corner. 'banner' - will show it as a banner on bottom of screen
    style: 'slide-up', //slide-up - slide's up on load. fade-in - fades on load
    header: 'Cookies on this website', // header text
    description: 'We use cookies to optimise site functionality and give you the best possible experience.', // description text
    accept: 'Accept', // accept button text
    acceptCls: 'button', // accept button extra classes
    control: 'Cookie Preferences', // sidebar trigger text
    controlCls: 'button', // control button extra classes
    deny: 'No, thanks', // sidebar trigger text
    denyCls: 'button button--inverted', // deny button extra classes
    closeCls: 'button', // close button extra classes
    closeButton: true, // true - shows the close button, false - no close button
    onAccept: function() {}, // runs when accept button is clicked.
    onDeny: function() {}, //runs when deny button is clicked
    onClose: function() {} // runs when close button is clicked.
},
preferences object
Sidebar tool object, comprises of text options, position and style options.
Example
preferences: {
    position: 'left', // 'left' - shows tool on the left screen. 'right' - shows tool on the right screen.
    header: 'This site uses cookies.',  // Main header text.
    description: 'Some of these cookies are essential while others improve your experience', // Tool description text.
    statement: { // statement object.
        description: 'For more information visit our', // description text.
        link: 'Privacy Statement', // link text.
        url: '/', // link url.
    },
    recommendedText: 'Accept Recommended Settings', // Recommended button text.
    necessaryHeader: 'Necessary Cookies', // Necessary header text.
    necessaryDescription: 'We use this so you see the site', // Necessary description text.
    thirdPartyHeader: 'Warning: Some cookies require your attention', // Third party warning header text.
    thirdPartyDescription: 'Consent for some third party cookies can not be automatically revoked. Please follow the link below if you want to opt out of them.', // Third party warning description text.
},
style object
Color options for branding
Example
style: {
    disclaimer: {
        bgcolor: '',
        headerColor: '',
        textColor: '',
        acceptButtonColor: '',
        preferenceButtonColor: '',
        buttonTextColor: '',
        acceptButtonBorder: ''
        preferenceButtonBorder: ''
    },
    preference: {
        bgcolor: '',
        headerColor: '',
        textColor: '',
        acceptButtonColor:'',
        buttonTextColor: '',
        switchOnColor: '',
        switchOffColor: '',
        switchToggleColor: '',
        warningBG: '',
        warningBorderColor: '',
        warningHeaderColor: '',
        warningTextColor: ''
    }
},
optionalCookies object
Array of objects (third-party plugins). This is where to add the third-party plugins that the tool controls
Example
name - name of plugin
label - category of plugin that is shown on the sidebar tool
description - description of the plugin
cookies - an array of cookies that the plugin sets. Required! This list will be deleted/try to be deleted when user revoke's the plugin
onByDefault - boolean whether the tool is automatically set by default (Most likely will only be applied to Google Analytics)
onAccept - callback function, this is where the script of the plugin should be added. See example
onRevoke - callback function, runs when plugin is turned off.
thirdPartyCookies - Object (name: third party cookie name, optOutLink: link to direct users to the opt out page of the plugin).
optionalCookies: [{
    name: 'googleAnalytics',
    label: 'Analytical Cookies',
    description: 'Analytical cookies help us to improve our website by collecting and reporting information on its usage.',
    cookies: ['_ga', '_gid', '_gat', '__utma', '__utmt', '__utmb', '__utmc', '__utmz', '__utmv', '_gat_Client'],
    onByDefault: true,
    onAccept: function() {
        window['ga-disable-UA-XXXXX-Y'] = false;
        (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');
    },
    onRevoke: function() {
        // Disable Google Analytics
        window['ga-disable-UA-XXXXX-Y'] = true;
    },
    onDeny: function() {}
},
{
    name: 'addToAny',
    label: 'Social Sharing Cookies (AddToAny)',
    description: 'We use some social sharing plugins, to allow you to share certain pages of our website on social media',
    cookies: ['__stid', '__unam', '__utma', '__utmz', '__uset', '__utmc', '_utmb', 'uvc', 'uuid', '_cfduid', 'page_services', '__atuvc', '__atuvs', 'di2', 'ouid', 'uid', 'vc'],
    onAccept: function() {
        var script = document.createElement("script");
        script.src = "//s7.addthis.com/js/300/addthis_widget.js#pubid=ra-581b3669203a9a52";
        document.body.appendChild(script);
    },
    onRevoke: function() {
        console.log('addToAny onRevoke');
    },
    thirdPartyCookies: {
        name: "AddToAny",
        optOutLink: "https://www.addtoany.com/privacy"
    }
}],
cookieRetention number
How many days before the cookie expires when initially set.
Default value
30
complete function
A callback that fires after the entire widget is rendered.
Parameters
event Event
The event object.