User Consent Cookie

lightning/userConsentCookie

Manages cookie consent preferences on a component.

For Use In

Experience Builder Sites

The lightning/userConsentCookie module provides utility functions that enable you to incorporate the Cookie Consent mechanism in your components. This module abstracts all the cookie functions, such as fetching, reading, writing, and updating cookies. This component requires API version 53.0 or later.

Understand How the userConsentCookie Module Works

To implement user-authorized cookie consent:

Enable cookie consent in Security & Privacy Settings. You can then provide users the option to allow Marketing, Preference, and Statistics cookies as well. If you don’t enable cookie consent, only Required cookies are allowed.
Import the userConsentCookie module in your cookie consent component JavaScript.
Add the ability for a user to consent to one or more specific cookie types (Required, Marketing, Preference, and Statistics) using HTML and JavaScript in your consent component.

Two Salesforce cookies (CookieConsentPolicy and CookieConsent) are used to put this scheme into place across your org. Client-side APIs enable you to check and set the cookie consent preferences that are persisted in the two Salesforce cookies.

Understand How the userConsentCookie Cookies Interact

As mentioned above, Salesforce ePrivacy consent is managed through the interaction of two cookies, CookieConsentPolicy and CookieConsent.

The CookieConsentPolicy cookie records whether consent is enabled. Consent is enabled by an admin in the Security & Privacy settings. See Enable Cookie Consent in Security & Privacy.
The CookieConsent cookie records the user’s consent choices, and is used only when consent is enabled and reflected in the CookieConsentPolicy cookie. The CookieConsent cookie is set by way of ePrivacyCookie client-side functions through user choices. See Manage Consent Options with ePrivacyCookieConsent Functions.

An org administrator enables Cookie Consent from Settings in the Security & Privacy tab. Under Site Cookie Usage, turn on the Allow only required cookies for this site toggle to restrict the consent to Required cookies only.

Turn on the toggle to enable consent for Required, Marketing, Preference, or Statistics cookies. Your code can then provide users with the ability to fine-tune consent for the cookie types they do and do not want to permit.

The ePrivacyCookieConsent component provides two JavaScript functions that enable you to manage user consent options:

isCategoryAllowedForCurrentConsent() retrieves the user’s decision about a cookie category. See Check Consent With isCategoryAllowedForCurrentConsent() below.
setCookieConsent() records the user’s consent. See Set Preferences With setCookieConsent().

Import the userConsentCookie Component Methods

To call the component’s methods, you must import the lightning/userConsentCookie component inside your custom component. For example:

1import { setCookieConsent, isCategoryAllowedForCurrentConsent } from "lightning/userConsentCookie";

The isCategoryAllowedForCurrentConsent function enables you to check consent for a single cookie category. Specify the category you want to check consent for. Valid values are Required, Preference, Marketing, and Statistics.

1isCategoryAllowedForCurrentConsent(Name);

Parameter	Type	Description
Name	String	Cookie category to check consent for.

To see this function called in context, see the Example section.

Set Preferences With setCookieConsent()

This client-side method relies on the ConsentPreference JavaScript object, which contains the list of one or more cookie categories you want to grant or deny consent for.

1setCookieConsent(ConsentPreference);

Parameter	Type	Description
ConsentPreference	object	Cookie categories to set preferences for.

The ConsentPreference object structure is as follows:

1{
2<<categoryName>> : boolean,
3...
4}

For example, if you wanted to grant consent for the Marketing category, but deny consent for the Preferences category, you would do something similar to the following:

1var consent = {
2  Preferences: false,
3  Marketing: true,
4};
5
6setCookieConsent(consent);

In this example, the “Statistics” category is not listed, so cookies of that type are denied consent by default.

To see this function called in context, see the Example section below.

Example

This example shows a component that sets or clears the consent for four categories of cookie: Essential, Preferences, Marketing, and Statistics. Feel free to modify the UI, but don’t change the defined categories, as these are standard categories used throughout the Salesforce application.

In the consent component’s JavaScript, the cookie consent methods are imported and used in the change handlers for input toggle components.

1import { LightningElement, track } from "lwc";
2import { ShowToastEvent } from "lightning/platformShowToastEvent";
3import { isCategoryAllowedForCurrentConsent, setCookieConsent } from "lightning/userConsentCookie";
4
5export default class CookieConsentToggleButton extends LightningElement {
6  @track checkedEssential = true;
7  @track checkedPreferences = isCategoryAllowedForCurrentConsent("Preferences");
8  @track checkedMarketing = isCategoryAllowedForCurrentConsent("Marketing");
9  @track checkedStatistics = isCategoryAllowedForCurrentConsent("Statistics");
10
11  @track
12  consent = {
13    Preferences: this.checkedPreferences,
14    Marketing: this.checkedMarketing,
15    Statistics: this.checkedEssential,
16  };
17
18  changeToggleEssential(event) {
19    console.log("Change toggle Essential triggered. Cannot be changed");
20    this.checkedEssential = this.checkedEssential;
21    this.showErrorToast();
22  }
23
24  changeTogglePreferences(event) {
25    console.log("Change toggle Preference triggered");
26    this.checkedPreferences = !this.checkedPreferences;
27    console.log("Current setting for Preferences : " + this.checkedPreferences);
28    this.setPreferences(this.checkedPreferences);
29    console.log(JSON.parse(JSON.stringify(this.consent)));
30    setCookieConsent(this.consent);
31  }
32
33  changeToggleMarketing(event) {
34    console.log("Change toggle Marketing triggered");
35    this.checkedMarketing = !this.checkedMarketing;
36    console.log("Current setting for Marketing : " + this.checkedMarketing);
37    this.setMarketing(this.checkedMarketing);
38    console.log(JSON.parse(JSON.stringify(this.consent)));
39    setCookieConsent(this.consent);
40  }
41
42  changeToggleStatistics(event) {
43    console.log("Change toggle Statistics triggered");
44    this.checkedStatistics = !this.checkedStatistics;
45    console.log("Current setting for Statistics : " + this.checkedStatistics);
46    this.setStatistics(this.checkedStatistics);
47    console.log(JSON.parse(JSON.stringify(this.consent)));
48    setCookieConsent(this.consent);
49  }
50
51  showErrorToast() {
52    const evt = new ShowToastEvent({
53      title: "Essential Cookies cannot be blocked",
54      message: "These cookies are required for the app to function properly.",
55      variant: "error",
56      mode: "dismissable",
57    });
58    this.dispatchEvent(evt);
59  }
60
61  setPreferences(value) {
62    this.consent.Preferences = value;
63  }
64
65  setMarketing(value) {
66    this.consent.Marketing = value;
67  }
68
69  setStatistics(value) {
70    this.consent.Statistics = value;
71  }
72
73  handleClickSetConsent() {
74    console.log(JSON.parse(JSON.stringify(this.preferences)));
75    setCookieConsent(this.consent);
76  }
77}

The component HTML template presents toggle inputs for the user to choose the types of cookies to accept and a button to set the consent value.

1<template>
2    <lightning-card title="Consent Information" icon-name="custom:custom14">
3    <div class="slds-m-around_medium">
4        <div>
5            <p>We use cookies to personalize contents and ads.
6            Please accept/reject the categories below to set your consent.</p>
7        </div>
8        <br>
9        <div>
10            <h2><b>Essential</b></h2>
11            <lightning-input
12                data-id="toggleEssential" type="toggle"
13                label="" checked={checkedEssential}
14                onchange={changeToggleEssential} disabled=""
15                message-toggle-active="" message-toggle-inactive=""
16                read-only>
17            </lightning-input> <br/>
18            <h2><b>Preferences</b></h2>
19            <lightning-input
20                data-id="togglePreferences" type="toggle"
21                label="" checked={checkedPreferences}
22                onchange={changeTogglePreferences} message-toggle-active=""
23                message-toggle-inactive="">
24            </lightning-input> <br/>
25            <h2><b>Marketing</b></h2>
26            <lightning-input
27                data-id="toggleMarketing" type="toggle"
28                label="" checked={checkedMarketing}
29                onchange={changeToggleMarketing} message-toggle-active=""
30                message-toggle-inactive="" >
31            </lightning-input> <br/>
32            <h2><b>Statistics</b></h2>
33            <lightning-input
34                data-id="toggleStatistics" type="toggle"
35                label="" checked={checkedStatistics}
36                onchange={changeToggleStatistics}
37                message-toggle-active="" message-toggle-inactive="" >
38            </lightning-input> <br/>
39        </div>
40    </div>
41    <div>
42        <lightning-button
43             class="slds-m-left_small nav-button"
44             label="Set Consent"
45             variant="brand"
46             onclick={handleClickSetConsent}>
47         </lightning-button>
48     </div>
49    </lightning-card>
50</template>

The structure of CookieConsentPolicy value is:

SiteOptionValue:CookieConsentPermValue

with possible values of either “0:1” or “1:1”.

The second bit (CookieConsentPermValue) in the cookie value is always enabled.

If the value is “0:1”, only essential cookies will be enabled. If the value is “1:1”. cookies will be enabled and disabled based on the consent preferences of the customer.

CookieConsent

The following table defines the fields of the CookieConsent cookie:

Field	Type	Encoding	Purpose
Cookie Version	String	n/a	Format Sensitivity
Metadata Version	String	n/a	Metadata Sensitivity
Timestamp	String	ISO_INSTANT: YYYY-mm-DDTHH:MM:ssZ	Consent Time Sensitivity
Consent	String	Hexadecimal or plaintext	Array or bit-vector of consent-per-classification
ReconsentRequired	boolean	integer	Notify the consent UI that re-consent is required, without dropping existing consent preferences.

An example of this cookie would be:

230.6.1:20.4.0:2021-08-03T06:21:44Z:1100:0

In this example, the Consent field of 1100 indicates that Required and Preference cookies are permitted, but Marketing and Statistics cookies are not.

Use the Client-Side APIs

Set Preferences With setCookieConsent()

This client-side method relies on the ConsentPreference JavaScript object which contains the list of one or more cookie categories you want to grant or deny consent for.

Parameter	Type	Description
ConsentPreference	object	Cookie categories to set preferences for.

The ConsentPreference object structure is as follows:

1{
2	<<categoryName>> : boolean,
3	...
4}

For example, if you plan to grant consent for the Marketing category, but deny consent for the Preferences category, you would prepare this object:

1{
2	Marketing : true,
3	Preferences : false
4}

A complete example is as follows:

1var consent = {
2    "Preferences" : true,
3    "Statistics" : true,
4    "Marketing" : false
5}
6
7Sfdc.Cookie.setCookieConsent(consent);

To check consent with this simple call, specify the category you want to check consent for.

Parameter	Type	Description
Name	String	Cookie category to check consent for.

1isCategoryAllowedForCurrentConsent("Marketing");

This check returns the consent value for the specified category. See Enable Cookie Consent in Security & Privacy.

Understand How the userConsentCookie Module Works

Understand How the userConsentCookie Cookies Interact

Import the userConsentCookie Component Methods

Set Preferences With setCookieConsent()

Example

CookieConsent

Use the Client-Side APIs

Set Preferences With setCookieConsent()

See Also

Lightning Component Reference

Contents

Understand How the userConsentCookie Module Works

Understand How the userConsentCookie Cookies Interact

Enable Cookie Consent in Security & Privacy

Manage Consent Options with ePrivacyCookieConsent Functions

Import the userConsentCookie Component Methods

Check Consent With isCategoryAllowedForCurrentConsent()

Set Preferences With setCookieConsent()

Example