@commercetools-frontend/cookie-consent

@commercetools-frontend/cookie-consent

This is a package used internally for Merchant Center applications. We do not provide any guarantees or support for the functionality.

This package provides an easy to use integration with OneTrust cookie consent.

Installation

$ npm install --save @commercetools-frontend/cookie-consent

Background

Cookie consent is given from a user towards a company as the legal entity for all of its products not for every single product. Consent via OneTrust is can be given on a marketing website for instance commercetools.com. The OneTrust cookie banner supports opting out of certain categories of cookies or revoking consent entirely.

The resulting cookie stored in a user's browser is called OptanonConsent. The contents of those cookie can be of the following:

isGpcEnabled=0&datestamp=Wed+Feb+01+2023+12%3A35%3A32+GMT%2B0100+(Central+European+Standard+Time)&version=202209.1.0&isIABGlobal=false&hosts=&consentId=7f3cf16d-b3e1-4781-8db1-61482d0a9dff&interactionCount=1&landingPath=NotLandingPage&groups=C0001%3A1%2CC0002%3A0%2CC0003%3A1%2CC0004%3A1%2CC0005%3A1&geolocation=AT%3B9&AwaitingReconsent=false

The cookie will be removed after 365 days yielding repeated consent to be requested by the user on our marketing website. The cookie itself is URL encoded and can be parsed using URLSearchParams. The field of interest is groups. These are the groups for which consent was granted or not:

1. EssentialCookies: 'C0001'
2. PerformanceCookies: 'C0002'
3. FunctionalCookies: 'C0003'
4. TargetingCookies: 'C0004'
5. SocialMediaCookies: 'C0005'

This package parses the cookie if present and returns consent for groups given or revoked.

Usage

Retrieving consent values

This package does not make assumptions what framework you use. To integrate without any assumptions about the framework use the /core entry point:

import { getParsedConsentCookieGroups } from '@commercetools-frontend/cookie-consent/core';

const consentGroups = getParsedConsentCookieGroups();
// { essentialCookies: true, performanceCookies: false }

If there is ever a need to use the raw consent cookie's value itself you can retrieve it too:

import { getRawConsentCookie } from '@commercetools-frontend/cookie-consent/core';

const rawConsentCookie = getRawConsentCookie();
// The value of the `OptanonConsent` cookie

Knowing the consent groups you can use a constant to easily map them onto something easier to understand:

import { getParsedConsentCookieGroups } from '@commercetools-frontend/cookie-consent/core';

const consentGroups = getParsedConsentCookieGroups();
const hasGivenPerformanceCookieConsent = Boolean(
  consentGroups.performanceCookies
);

You can also use the useCookieConsent from the /react entry point of the package.

import { useCookieConsent } from '@commercetools-frontend/cookie-consent/react';

const { givenConsent } = useCookieConsent('performanceCookies');

Note also that in certain cases (e.g. a staging environment) you may want to skip cookie consent entirely. To do so you can use the skipConsent option:

const { givenConsent } = useCookieConsent('performanceCookies', {
  skipConsent: true,
});

The preferred value of skipConsent can be determined for instance by an environment variable and read using the useSkipCookieConsent hook.

The resulting givenConsent value is a boolean which can be passed to any software needing consent for instance FullStory or Intercom. A combination of @commercetools-frontend/cookie-consent and @commercetools-frontend/fullstory could look like this:

const { givenConsent } = useCookieConsent('performanceCookies');

useFullStoryTrackingEffect({ disable: !givenConsent });

Setting consent values

To integrate without any assumptions about the framework again, use the /core entry point:

import { setConsentCookie } from '@commercetools-frontend/cookie-consent/core';

setConsentCookie({ performanceCookieConsent: true });

Setting a cookie also accepts a domain as a second argument. This value defaults to .commercetools.com but can also be influenced using the additionalEnv when building a Custom Application:

additionalEnv: {
    cookieConsentDomain: '${env:COOKIE_CONSENT_DOMAIN}',
},

Whenever you are not building a Custom Application you can define the window.app.cookieConsentDomain instead.

When needing to set a cookie you can use the useCookieConsent from the /react entry point of the package.

import { useCookieConsent } from '@commercetools-frontend/cookie-consent/react';

const { setConsent } = useCookieConsent('performanceCookies');

// For instance in an `onClick` hander you can
<button onClick={() => setConsent({ performanceCookieConsent: true })}>
  Update cookie consent
</button>;

Showing a consent banner

You can render the CookieConsentBanner to show a consent banner.

import { CookieConsentBanner } from '@commercetools-frontend/cookie-consent/react';

<CookieConsentBanner />;

Showing a consent modal

You can render the CookieConsentModal to open a consent modal. Upon interaction with the modal a cookie will be written in accordance with the consent groups selected.

import { CookieConsentModal } from '@commercetools-frontend/cookie-consent/react';

<CookieConsentModal />;