1.0.0-alpha.0 • Published 5 months ago
@usercentrics/cmp-web-sdk v1.0.0-alpha.0
Usercentrics CMP Web SDK (alpha)
Please visit our official https://usercentrics.com/docs/web/implementation/sdk/ (alpha version, not to be used in production).
Installation
# npm
npm install @usercentrics/cmp-web-sdk
# yarn
yarn install @usercentrics/cmp-web-sdk
Usage
Initialisation
import CmpWebSdk from '@usercentrics/cmp-web-sdk';
(async () => {
const cmpWebSdk = new CmpWebSdk(); // init the sdk
const cmpController = await cmpWebSdk.initBySetting('YOUR_SETTINGS_ID'); // get the cmp controller
// your custom cmp ui logic
})();
Applying Consent
Generic Consent Methods
// accept all
await cmpWebSdk.acceptAllConsents();
// deny all
await cmpWebSdk.denyAllConsents();
// update services consent
await cmpWebSdk.updateServicesConsent({
id: 'SERVICE_ID', // the service id
consent: true, // the consent state true | false
});
// update categories consent
await cmpWebSdk.updateCategoryConsent([{
id: 'CATEGORY_ID', // the category id
consent: true, // the consent state true | false
}]);
/* IMPORTANT:
all above methods just change the consent state internally,
to persist the user decision (e.g. after a save consent button click by the user)
you need to persist/save the consents */
await cmpWebSdk.saveConsents();
Getting Data
Generic Data
// gets services
await cmpWebSdk.getServices();
// gets categories
await cmpWebSdk.getCategories();
// gets languages
await cmpWebSdk.getLanguages();
Useful methods
// changes the language
await cmpWebSdk.changeLanguage('en');
// returns true if all consents are accepted
await cmpWebSdk.areAllConsentsAccepted();
// returns true if all consents are denied
await cmpWebSdk.areAllConsentsDenied();
// returns true if a decision consent is required
await cmpWebSdk.getIsConsentRequired();
Skeleton Examples
GDPR
// import GDPR optimized GdprWebSdk
import { GdprWebSdk, GdprCmpController, UiView } from '@usercentrics/cmp-web-sdk';
// simple vanilla js view
class CmpView {
private cmpController: GdprCmpController;
private cmpElement: HTMLDivElement;
constructor(cmpController: GdprCmpController) {
this.cmpController = cmpController;
}
public async init() {
// create and attach the ui view
const cmpElement = document.createElement('div');
cmpElement.id = 'cmp';
if (typeof cmpElement.attachShadow === 'function') {
// optional -> attach shadow
cmpElement.attachShadow({ mode: 'open' });
}
this.cmpElement = (cmpElement.shadowRoot as HTMLDivElement) || cmpElement;
this.setView(this.cmpController.ui.initialView || 'none');
return new Promise((resolve) => {
if (document.body) {
document.body.appendChild(cmpElement);
resolve();
}
document.addEventListener('DOMContentLoaded', () => {
document.body.append(cmpElement);
resolve();
});
});
}
public setView(view: UiView) {
const consents = JSON.stringify(this.cmpController.dps.getServicesConsents()); // data example
switch (view) {
case 'none':
// do not show the cmp, do not show a cmp button/trigger
this.cmpElement.innerHTML = '';
break;
case 'button':
// do not show the cmp, show a cmp button/trigger
this.cmpElement.innerHTML = 'custom button view';
break;
case 'first':
// the cmp needs to be shown
this.cmpElement.innerHTML = `custom first layer view: ${consents}`;
break;
case 'second':
// the optional custom secondary layer (never an initial view)
this.cmpElement.innerHTML = `custom second layer view ${consents}`;
break;
}
}
}
(async () => {
const gdprWebSdk = new GdprWebSdk();
const gdprCmpController = await gdprWebSdk.initBySetting('YOUR_GDPR_SETTINGS_ID');
const cmpView = new CmpView(gdprCmpController);
await cmpView.init();
})();
US (CCPA)
Same as GDPR but use UsWebSdk;
TCF
Same as GDPR but use TcfWebSdk;
1.0.0-alpha.0
5 months ago