Customer Privacy API

Feature name: consents-modal

Api name: customerPrivacyApi

---

API allows you to manage user consents, which are essential for respecting user privacy and adhering to legal requirements. It also allows to adjust how your code is executed based on consent status provided by the user as some features require such consent to run. This API is also used to manage the customer consent modal.

It's important to understand that you may only grant or withdrawn consents on user action. Doing it without user's permission might cause you legal problems.

classDiagram
direction LR
    CustomerPrivacyAPI --> getGrantedNames
    CustomerPrivacyAPI --> grantConsents
    CustomerPrivacyAPI --> onAnalyticsConsentGranted
    CustomerPrivacyAPI --> onMarketingConsentGranted
    CustomerPrivacyAPI --> onFunctionalConsentGranted
    CustomerPrivacyAPI --> onPlatformConsentGranted
    CustomerPrivacyAPI --> showConsentsModal
    CustomerPrivacyAPI --> withdrawConsents

    class CustomerPrivacyAPI {
        getGrantedNames() TConsentName[]
        grantConsents(consents: TConsentName[]) void
        onAnalyticsConsentGranted(callback: () => void) void
        onMarketingConsentGranted(callback: () => void) void
        onFunctionalConsentGranted(callback: () => void) void
        onPlatformConsentGranted(callback: () => void) void
        showConsentsModal() void
        withdrawConsents(consents: TConsentName[]) void
    }

    link getGrantedNames "../methods/get-granted-names/"
    link grantConsents "../methods/grant-consents/"
    link onAnalyticsConsentGranted "../methods/on-analytics-consent-granted/"
    link onFunctionalConsentGranted "../methods/on-functional-consent-granted/"
    link onMarketingConsentGranted "../methods/on-marketing-consent-granted/"
    link onPlatformConsentGranted "../methods/on-platform-consent-granted/"
    link showConsentsModal "../methods/show-consents-modal/"
    link showAdvancedConsentsModal "../methods/show-advanced-consents-modal/"
    link withdrawConsents "../methods/withdraw-consents/"
    link saveConsents "../methods/save-consents/"
    link isCookieInformationEnabled "../methods/is-cookie-information-enabled/"

Get API

To get the Customer Privacy API use its name customerPrivacyApi with the getApi method.

This API is initialized asynchronously which means that if you use the getApiSync method to get it, it might not exist yet and you will get an error as a result.

useStorefront(async (storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');
});

This API is initialized only after consents-modal webcomponent has been added to the page. Unless you add the webcomponent, you won't be able to fetch the API. If you wish to use the API alone without the webcomponent you can use the registerDynamic method from the Feature System API. Here is an example on how to do it:

useStorefront(async (storefront) => {
    const featureSystemApi = this.getApiSync('FeatureSystemApi');
    await featureSystemApi.registerDynamic('consents-modal');

    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');
});

Consent names

There are four types of consents you can work with also known as TConsentName:

• analyticsConsent - allows the collection of data for understanding user behavior and improving the service through usage statistics

• marketingConsent - allows the collection and use of data for marketing purposes, including personalized advertisements and promotional communications

• functionalConsent - necessary for enabling specific functionalities of the service, ensuring that core features work correctly and provide a better user experience

• platformAnalyticsConsent - covers the collection of data specifically for analyzing the platform's performance and usage patterns, helping to optimize and enhance the overall platform experience.

By managing these consents, you can ensure compliance with privacy regulations while providing a customized and efficient service to your users.

Methods

• getGrantedNames - retrieve an array of consents that have been granted by the user
• grantConsents - grant a given array of consents
• onAnalyticsConsentGranted - provide a callback which will be called when the user grants the analyticsConsent
• onMarketingConsentGranted - provide a callback which will be called when the user grants the marketingConsent
• onFunctionalConsentGranted - provide a callback which will be called when the user grants the functionalConsent
• onPlatformConsentGranted - provide a callback which will be called when the user grants the platformAnalyticsConsent
• showConsentsModal - show the consent modal
• showAdvancedConsentsModal - show the advanced consent modal allowing to grant or withdraw chosen only selected consents by the user
• withdrawConsents - withdraw a given array of consents
• saveConsents - ave the current granted consents status to the local storage
• isCookieInformationEnabled - check whether the cookies are enabled in the store or not

Event Bus events

Methods of this API method dispatch the following events with the Event Bus:

• consentsService.saved
• consentsService.showConsentsModal
• consentsService.showAdvancedConsentsModal

Example

In this example we make a customerPrivacyApi call to get names of the currently granted consents.

useStorefront((storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');

    const grantedConsents = customerPrivacyApi.getGrantedNames(); // ['marketingConsent', 'analyticsConsent']
});

Example

In this example we make a customerPrivacyApi call to grant a given array of consent names.

useStorefront((storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');

    customerPrivacyApi.grantConsents(['marketingConsent', 'analyticsConsent']);
});

Example

In this example we make a customerPrivacyApi call to fire a callback whenever analytics consents are granted by the user.

useStorefront((storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');

    customerPrivacyApi.onAnalyticsConsentGranted(() => {
        console.log('Analytics consent has been granted!');
    });
});

Example

In this example we make a customerPrivacyApi call to show the consent modal.

useStorefront((storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');

    customerPrivacyApi.showConsentsModal();
});

Example

In this example we make a customerPrivacyApi call to withdraw a given array of consents.

useStorefront((storefront) => {
    const customerPrivacyApi = await storefront.getApi('customerPrivacyApi');

    customerPrivacyApi.withdrawConsents(['analyticsConsent']);
});

Objects reference

• TConsentName

Webcomponents reference

• consents-modal

APIs reference

• Feature System API