Ba-js-cookie-banner NPM

ba-js-cookie-banner

ba-js-cookie-banner is an embeddable React-based cookie consent manager. In addition to cookie management, it installs and manages Bookassist and Google analytics tracking by leveraging ba-js-tracker.

Installation

# yarn
yarn add ba-js-cookie-banner

# unpkg
<script src="https://unpkg.com/ba-js-cookie-banner/dist/ba-js-cookie-banner.min.js"></script>

Documentation

The widget is auto-appended to the body as a div wrapper:

<body>
  <div id="cookie-bg-overlay">
    <div id="cookie-container">
      <!-- conditional banner content here -->
    </div>
  </div>
</body>

The banner content is displayed when the cookie-consent cookie is unset. The user can also display the banner manually by clicking on an element with a preset id value (#ba-edit-cookie) located anywhere on the page. This allows them to edit their cookie preferences.

The banner prompts the user to allow all cookies or select a subset of types they're willing to accept.

Cookie Type	Value	Optional
Necessary	1	No
Preferences	2	Yes
Statistics	4	Yes
Marketing	8	Yes

The allowed cookie type values are summed to provide the cookie-consent cookie value (e.g. a user permitting all cookie types would result in the value being set to 15).

Determining whether a given cookie type is permitted is done using a bitwise AND operation:

// are Statistics cookies permitted?
var cookieConsent = Cookies.get('cookie-consent')
if ((cookieConsent & 4) > 0) {
    // Statistics cookies are permitted
}

Script Loader

The cookie banner widget controls cookie setting indirectly by managing 3rd party script loading. On load the widget checks the current cookie-consent value, and if unset continues to listen for changes. Once the value is set the cookie banner:

Loads jQuery dynamically if not already present on the page. jQuery is a dependency of the preconditions/callback script in part 3. The BA.jQueryUrl global provides the relevant jQuery url.
Loads two JSON feeds:
1. a list of 3rd party scripts to load
2. script metadata: a classification by cookie type (according to the values from the above table), and any precondition (tests to pass prior to script load) and callback (run following script load) function metadata.
Loads the inventory of precondition and callback functions.

Once the user has selected their cookie preferences, the banner dynamically loads any compliant 3rd party scripts, respecting any associated preconditions and executing any associated callbacks

Analytics

Bookassist Analytics

The cookie banner comes bundled with ba-js-tracker. ba-js-tracker contains an always-on gdpr-compliant in-house tracker (baTracker).

Google Analytics

Google Analytics is loaded conditionally as per Script Loader 3rd party scripts, except in this case the consent value is obtained from the BA.gaConsent global. Google Analytics can also be unconditionally loaded by setting the BA.gaWaitForConsent global to false. The Google Analytics tracker is instantiated with the values provided by the BA.gaAnonymiseIp, BA.gaId, and BA.gaLinker globals. On load it sends a pageview event.

Events

// these events are structured as per ba-js-tracker requirements

// pageview event (baTracker, gaTracker)
event: {
  type: 'pageView'
}

// script loading errors (baTracker)
event: {
  type: 'error',
  key: err.name,
  value: {
    message: err.message,
    stack: err.stack,
  }
}

// set/change cookie-consent value (baTracker)
event: {
  type: 'technical',
  key: 'cookieConsent',
  value,
}

// show cookie consent widget (baTracker)
event: {
  type: 'technical',
  key: 'showCookieConsentWidget',
}

// custom set cookie preferences (baTracker)
event: {
  type: 'userInteraction',
  key: 'preferences',
}

Global Variables

These values must be set before loading ba-js-cookie-banner

BA.cookiePolicyUrl // cookie banner privay policy url (string)
BA.gaAnonymiseIp // google analytics anonymizeip field (boolean)
BA.gaConsent // google analytics cookie-consent value (integer)
BA.gaId // google analytics account id (string)
BA.gaLinker // google analytics linker parameters (array)
BA.gaWaitForConsent // require user consent before loading google analytics (boolean)
BA.gdpr // gdpr policy applicable (pseudo-boolean - "yes/no")
BA.i18n // jed i18n data (json)
BA.jQueryUrl // jquery version to load (if not present) (string)
BA.showBanner // show banner (when warranted) (pseudo-boolean - "yes/no")
BA.thirdPartyScriptsClasificationUrl // 3rd party script classification mapping url (string)
BA.thirdPartyScriptsFunctionsUrl // 3rd party script preconditions and functions url (string)
BA.thirdPartyScriptsURL // 3rd party scripts to load
BA.userLanguage // i18n user language