\n\n## Overview\n\nBrowser SDK V3 is a lightweight headless library which you can integrate with your own custom user interface for consent management\n\n> 💡 The SDK includes full TypeScript definitions for all exported classes and methods.\n\n## Table of Contents\n\n - [Installing](#installing)\n - [Package manager](#package-manager)\n - [Example](#example)\n - [Usercentrics API](#usercentrics-api)\n - [Applying Consent](#applying-consent)\n - [acceptAllConsents](#acceptallconsents)\n - [denyAllConsents](#denyallconsents)\n - [updateServiceConsent](#updateserviceconsent)\n - [updateServicesConsents](#updateservicesconsents)\n - [updateCategoryConsent](#updatecategoryconsent)\n - [updateCategoriesConsents](#updatecategoriesconsents)\n - [saveConsents](#saveconsents)\n - [Data](#data)\n - [getServices](#getservices)\n - [getServicesBaseInfo](#getservicesbaseinfo)\n - [getCategories](#getcategories)\n - [getLanguages](#getlanguages)\n - [Other methods](#other-methods)\n - [changeLanguage](#changelanguage)\n - [areAllConsentsAccepted](#areallconsentsaccepted)\n - [areAllConsentsDenied](#areallconsentsdenied)\n - [getIsConsentRequired](#getisconsentrequired)\n - [Implementation Examples](#implementation-examples)\n - [Building your custom TCF UI](#considerations-for-building-your-custom-tcf-ui)\n - [License](#license)\n\n## Installing\n\n### Package manager\n\nUsing npm:\n\n```bash\n$ npm install @usercentrics/cmp-web-sdk\n```\n\nUsing yarn:\n\n```bash\n$ yarn add @usercentrics/cmp-web-sdk\n```\n\nOnce the package is installed, you can import the library using `import` or `require` approach:\n\n```js\nimport WebSdk, {GdprWebSdk} from '@usercentrics/cmp-web-sdk'\n```\n\nYou can also use the default export, for a more generic approach:\n\n```js\nimport WebSdk from '@usercentrics/cmp-web-sdk';\n````\n\nIf you use `require` for importing, **only default export is available**:\n\n```js\nconst WebSdk = require('@usercentrics/cmp-web-sdk');\n```\n\nFor some bundlers and some ES6 linters you may need to do the following:\n\n```js\nimport { default as WebSdk } from '@usercentrics/cmp-web-sdk';\n```\n\n## Example\n\nInitializing the generic SDK\n```js\nimport WebSdk from '@usercentrics/cmp-web-sdk';\n\n(async () => {\n // Create the SDK instance\n const webSdk = new WebSdk();\n const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); // Initialize the SDK with your SettingsId\n})();\n```\n\nInitializing the GDPR-specific SDK\n```js\nimport { GdprWebSdk } from '@usercentrics/cmp-web-sdk';\n\n(async () => {\n // Create the SDK instance\n const webSdk = new GdprWebSdk();\n // Initialize the SDK with your SettingsId\n const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); \n})();\n```\n\nInitializing the TCF-specific SDK\n```js\nimport { TcfWebSdk } from '@usercentrics/cmp-web-sdk';\n\n(async () => {\n // Create the SDK instance\n const webSdk = new TcfWebSdk();\n // Initialize the SDK with your SettingsId\n const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID'); \n})();\n```\n\nInitializing the US-specific SDK\n```js\nimport { UsWebSdk } from '@usercentrics/cmp-web-sdk';\n\n(async () => {\n // Create the SDK instance\n const webSdk = new UsWebSdk();\n // Initialize the SDK with your SettingsId\n const cmpController = await webSdk.initBySetting('YOUR_SETTINGS_ID');\n})();\n```\n\n## Usercentrics API\n\n### Applying Consent\n\n##### acceptAllConsents\n\n```js\nawait webSdk.acceptAllConsents();\n```\n\n##### denyAllConsents\n\n```js\nawait webSdk.denyAllConsents();\n```\n\n##### updateServiceConsent\n\nUpdate a single service consent\n\n```js\nawait webSdk.updateServiceConsent({\n id: 'SERVICE_ID',\n consent: true, // or false\n});\n```\n\n##### updateServicesConsents\n\nUpdate multiple services consents\n\n```js\nawait webSdk.updateServicesConsents([\n {\n id: 'SERVICE_ID_1',\n consent: true, // or false\n },\n {\n id: 'SERVICE_ID_2',\n consent: false, // or true\n }\n]);\n```\n\n##### updateCategoryConsent\n\nUpdate a Category consent\n\n```js\nawait webSdk.updateCategoryConsent({\n id: 'CATEGORY_ID',\n consent: true, // or false\n});\n```\n\n##### updateCategoriesConsents\n\nUpdate multiple categories consents\n\n```js\nawait webSdk.updateCategoriesConsents([\n {\n id: 'CATEGORY_ID_1',\n consent: true, // or false\n },\n {\n id: 'CATEGORY_ID_2',\n consent: false, // or true\n },\n]);\n```\n\n#### saveConsents\n\n> **Note**: Consent usage\n> All of the above methods just change the consent state internally\n> to persist the user decision (e.g. after a save consent button click by the user) you need to persist/save the consents\n\n```js\nawait webSdk.saveConsents();\n```\n\n### Data\n\n#### getServices\n```js\nawait webSdk.getServices();\n```\n\n#### getServicesBaseInfo\n```js\nawait webSdk.getServicesBaseInfo();\n```\n\n#### getCategories\n```js\nawait webSdk.getCategories();\n```\n\n#### getLanguages\n```js\nawait webSdk.getLanguages();\n```\n\n### Other methods\n\n#### changeLanguage\nChange the language to a supported language\nFor the list of supported languages, please refer to [getLanguages](#getLanguages)\n```js\nawait webSdk.changeLanguage('en');\n```\n\n#### areAllConsentsAccepted\nReturns `true` if all the consents are accepted\n```js\nconst allConsentsAccepted = await webSdk.areAllConsentsAccepted();\n```\n\n#### areAllConsentsDenied\nReturns `true` if all the consents are denied\n```js\nconst allConsentsDenied = await webSdk.areAllConsentsDenied();\n```\n\n#### getIsConsentRequired\nReturns `true` if a user decision is needed\n```js\nconst isConsentRequired = await webSdk.getIsConsentRequired();\n```\n\n## Implementation Examples\n\n### GDPR\n\n```js\n// import GDPR optimized GdprWebSdk\nimport { GdprWebSdk, GdprCmpController, UiView } from '@usercentrics/cmp-web-sdk';\n\n// Vanilla JS view\nclass CmpView {\n private cmpController: GdprCmpController;\n private cmpElement: HTMLDivElement;\n\n constructor(cmpController: GdprCmpController) {\n this.cmpController = cmpController;\n }\n\n public async init() {\n // create and attach the ui view\n \n const cmpElement = document.createElement('div');\n cmpElement.id = 'cmp';\n\n if (typeof cmpElement.attachShadow === 'function') {\n // optional: attach shadow\n cmpElement.attachShadow({ mode: 'open' });\n }\n\n this.cmpElement = (cmpElement.shadowRoot as HTMLDivElement) || cmpElement;\n this.setView(this.cmpController.ui.initialView || 'none');\n\n return new Promise((resolve) => {\n if (document.body) {\n document.body.appendChild(cmpElement);\n resolve();\n }\n\n document.addEventListener('DOMContentLoaded', () => {\n document.body.append(cmpElement);\n resolve();\n });\n });\n }\n\n public setView(view: UiView) {\n const consents = JSON.stringify(this.cmpController.dps.getServicesConsents()); // data example\n\n switch (view) {\n case 'none':\n // do not show the cmp, do not show a cmp button/trigger\n this.cmpElement.innerHTML = '';\n break;\n case 'button':\n // do not show the cmp, show a cmp button/trigger\n this.cmpElement.innerHTML = 'custom button view';\n break;\n case 'first':\n // the cmp needs to be shown\n this.cmpElement.innerHTML = `custom first layer view: ${consents}`;\n break;\n case 'second':\n // the optional custom secondary layer (never an initial view)\n this.cmpElement.innerHTML = `custom second layer view ${consents}`;\n break;\n }\n }\n}\n\n(async () => {\n const gdprWebSdk = new GdprWebSdk();\n const gdprCmpController = await gdprWebSdk.initBySetting('YOUR_GDPR_SETTINGS_ID');\n\n const cmpView = new CmpView(gdprCmpController);\n await cmpView.init();\n})();\n```\n\n## Considerations for building your custom TCF UI\n\n> Note: This does NOT apply if you use the unaltered Usercentrics UI together with this SDK\n\nIf you plan to build your own custom UI for TCF, Usercentrics cannot be liable that your custom UI conforms to all the IAB rules and guidelines. In this case, you can still use this SDK, but you need to register your solution at the IAB yourself. You can then enter your cmp-id (provided by the IAB) and cmp-version through the Usercentrics Admin Interface.\n\nIn the case that you build your own TCF UI it is **NOT** allowed to use the default Usercentrics cmp-id and cmp-version.\n\n## License\n\n[](LICENSE)","readmeFilename":"README.md"}
![\"Usercentrics\"](\"https://usercentrics.com/wp-content/uploads/2024/09/UC_Web_Black.svg\")
\n