@usercentrics/cmp-web-sdk/README.md

Please visit our official [https://usercentrics.com/docs/web/implementation/sdk/][docs] (alpha version, not to be used in production).

# Usercentrics CMP Web SDK (alpha)

Please visit our official [https://usercentrics.com/docs/web/implementation/sdk/][docs] (alpha version, not to be used in production).

## Installation

```sh
# npm
npm install @usercentrics/cmp-web-sdk

# yarn
yarn install @usercentrics/cmp-web-sdk
```

## Usage

### Initialisation

```ts
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
```ts
// 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

```ts
// gets services
await cmpWebSdk.getServices();

// gets categories
await cmpWebSdk.getCategories();

// gets languages
await cmpWebSdk.getLanguages();
```

## Useful methods
```ts
// 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

```ts
// 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;