Merge pull request #34 from s-group-dev/web-cmp-v3

Migrate to Usercentrics Web CMP v3

Author: iiroj

MIGRATION.md

@@ -1,3 +1,20 @@
+## 3.0.0
+
+- The Usercentrics Web CMP has been updated to v3 and includes a lot of changes.
+    - Read more about the CMP v3 here: https://usercentrics.com/docs/web/v3/
+    - Read the Usercentrics Migration guide here for more context, although it shouldn't be relevant when using this package: https://usercentrics.com/docs/web/migration/migration-from-v2/
+- The `windowEvent` prop for `<UsercentricsProvider />` is no longer supported and should be removed. The CMP v3 handles this automatically with a new event internally.
+- The `uiVersion` prop for `<UsercentricsScript />` is no longer supported and should be removed. The CMP v3 loader script currently supports only the "latest" version.
+    - This also means that hard-coding a version number and its [Subresource Integrity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hash is no longer supported. Instead, use a random `nonce` value when implementing a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP).
+- The `showSecondLayer()` util no longer supports passing a service id argument to directly open to the service info. Instead, use the new `showServiceDetails(serviceId: ServiceId)` util.
+- The `getServicesFromLocalStorage()` util has been replaced with `getConsentsFromLocalStorage()` with a different format.
+- The following utils and hooks have been removed because CMP v3 no longer supports them:
+    - `getServicesBaseInfo()`
+    - `useServiceInfo()`
+    - `getServicesFullInfo()`
+    - `useServiceFullInfo()`
+- All the utils are now `async` to match the CMP v3 implementations
+
 ## 2.0.0
 
 - No functional changes. This version is only released to sync the package version with the supported Usercentrics Web CMP v2 version.

README.md

@@ -20,9 +20,7 @@ The next major version `@s-group/react-usercentrics@3` will only support [Userce
 
 ## Setup
 
-You will need to set up a Usercentrics service and note down its `settingsId`. You will also need to enable the [Window Event](https://docs.usercentrics.com/#/v2-events?id=usage-as-window-event) in the admin interface, and note down its name (for example, `ucEvent`).
-
-After this you need to render the `UsercentricsScript` component to load the Browser API, and then finally wrap your application in the `UsercentricsProvider`.
+You will need to set up a Usercentrics service and note down its `settingsId`. After this you need to render the `UsercentricsScript` component to load the Browser API, and then finally wrap your application in the `UsercentricsProvider`.
 
 ```tsx
 import { UsercentricsScript, UsercentricsProvider } from '@s-group/react-usercentrics'
@@ -80,14 +78,14 @@ consent can be either explicit (e.g. when clicking some custom button) or implic
 
 #### `UCWindow`
 
-Augmented window type, possibly including the `UC_UI` API.
+Augmented window type, possibly including the `__ucCmp` API.
 Do not declare this globally, but prefer to use the included utility functions instead.
 
 ### Components
 
 #### `UsercentricsScript`
 
-The script tag that loads the Usercentrics Browser UI and API.
+The script tag that loads the Usercentrics Browser CMP.
 
 ```tsx
 interface UsercentricsScriptProps
@@ -102,15 +100,6 @@ interface UsercentricsScriptProps
 
     settingsId: string
 
-    /**
-     * The specific version of Usercentrics UI to load instead of "latest", as a string value
-     *
-     * @default "latest"
-     * @example "3.24.0"
-     * @see https://releases.usercentrics.com/en?category=browser+ui&role=cmpv1%3Bcmpv2%3B
-     */
-    uiVersion?: string
-
     /**
      * Whether to run Usercentrics in "production" or "preview" mode
      * @default "production"
@@ -126,9 +115,6 @@ interface UsercentricsScriptProps
 /** Preview mode for development */
 ;() => <UsercentricsScript settingsId="1234" version="preview" />
 
-/* Fixed UI version instead of latest */
-;() => <UsercentricsScript settingsId="1234" uiVersion="3.24.0" />
-
 /* Fixed language code */
 ;() => <UsercentricsScript settingsId="1234" language="fi" />
 ```
@@ -152,23 +138,18 @@ interface UsercentricsProviderProps {
      * @default 5000
      */
     timeout?: number
-    /**
-     * The configured window event name from Usercentrics admin interface.
-     * @see https://docs.usercentrics.com/#/v2-events?id=usage-as-window-event
-     */
-    windowEventName: string
 }
 
 /** Basic usage */
 () => (
-  <UsercentricsProvider windowEventName="ucEvent">
+  <UsercentricsProvider>
     <App />
   </UsercentricsProvider>
 )
 
 /** Custom timeout in milliseconds */
 () => (
-  <UsercentricsProvider timeout={100} windowEventName="ucEvent">
+  <UsercentricsProvider timeout={100}>
     <App />
   </UsercentricsProvider>
 )
@@ -302,183 +283,87 @@ Returns `true` if the user has interacted with the Usercentrics dialog and given
 }
 ```
 
-#### `useServiceInfo`
-
-Returns basic info for specific Usercentrics service, or null if not found.
+### Utils
 
-The typing is _not complete_ and contains only the info used internally:
+#### `hasUserInteracted`
 
-- `id` of the service, autogenerated by Usercentrics
-- `name` of the service, configured in the admin interface
-- `consent.status` of the service
+A method to check if user has interacted with the consent prompt and given consent information.
 
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=getservicesbaseinfo
+See also `setUserHasInteracted`.
 
 ```tsx
-;() => {
-    const serviceInfo = useServiceInfo('my-service-id')
+const userInteracted = hasUserInteracted()
 
-    useEffect(() => {
-        if (!serviceInfo) {
-            console.error('Service not found for "my-service-id"')
-        } else {
-            console.info(`Consent for ${serviceInfo.name}: ${serviceInfo.consent.status}`)
-        }
-    }, [serviceInfo])
+if (userInteracted) {
+    actionRequiredConsentInfoGiven()
 }
 ```
 
-#### `useServiceFullInfo`
-
-Returns full info for specific Usercentrics service, or null if not found.
-This triggers an extra API call and also returns `null` while loading.
-
-The typing is _not complete_ and contains only the info used internally:
+#### `setUserHasInteracted`
 
-- `id` of the service, autogenerated by Usercentrics
-- `name` of the service, configured in the admin interface
-- `consent.status` of the service
-- `description` text of the service
+A method to set that user has interacted with the consent prompt and given consent information.
 
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=getservicesfullinfo
+See also `hasUserInteracted`.
 
 ```tsx
-;() => {
-    const serviceInfo = useServiceFullInfo('my-service-id')
-
-    useEffect(() => {
-        if (serviceInfo) {
-            console.info(`The ${serviceInfo.name} service is used to ${serviceInfo.description}`)
-        }
-    }, [serviceInfo])
-}
+setUserHasInteracted()
 ```
 
-### Utils
-
 #### `showFirstLayer`
 
 Programmatic way to show First Layer.
 
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=showfirstlayer
+See also https://usercentrics.com/docs/web/features/api/control-ui/#showfirstlayer
 
 ```tsx
-showFirstLayer()
+await showFirstLayer()
 ```
 
 #### `showSecondLayer`
 
-Programmatic way to show Second Layer. If a service/vendor Id value is passed,
-Second Layer will open the right tab, scroll to the given service/vendor entry and expand it.
-If no Id is passed, Second Layer will be shown without srcolling to any specific service/vendor.
-
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=showsecondlayer
-
-```tsx
-showSecondLayer()
-```
-
-```tsx
-showSecondLayer('my-service-id')
-```
-
-#### `getServicesBaseInfo`
-
-A method to get array of all services with their basic information
+Programmatic way to show Second Layer.
 
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=getservicesbaseinfo
+See also https://usercentrics.com/docs/web/features/api/control-ui/#showsecondlayer
 
 ```tsx
-const services = getServicesBaseInfo()
-
-const myService = services.find((service) => service.id === 'my-service-id')
+await showSecondLayer()
 ```
 
-#### `getServicesFullInfo`
-
-A method to get array of all services with their full information.
-An extra api request will be made, therefore the return represents
-the eventual completion (or failure) of an asynchronous operation
-and its returning value.
-
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=getservicesfullinfo
-
-```tsx
-const services = await getServicesFullInfo()
-
-const myService = services.find((service) => service.id === 'my-service-id')
-```
+#### `showServiceDetails`
 
-#### `hasServiceConsent`
+Programmatic way to show the details of a service.
 
-Returns true if Usercentrics service has been given consent
+See also https://usercentrics.com/docs/web/features/api/control-ui/#showservicedetails
 
 ```tsx
-const services = getServicesBaseInfo()
-const myService = services.find((service) => service.id === 'my-service-id')
-const hasConsent = hasServiceConsent(myService)
-
-if (hasConsent) {
-    loadMyService()
-}
+await showServiceDetails('my-service-id')
 ```
 
-#### `areAllConsentsAccepted`
+#### `getConsentsFromLocalStorage`
 
-Returns true if all Usercentrics services have been given consent
+A method to get consent status saved to localStorage.
 
 ```tsx
-const hasAllConsents = areAllConsentsAccepted()
-
-if (hasAllConsents) {
-    loadMyService()
-}
+const consents = getConsentsFromLocalStorage()
+const hasConsent = consents['my-service-id']?.consent === true
 ```
 
-#### `acceptService`
-
-A method for accepting a single service.
-
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=acceptservice
-
-```tsx
-await acceptService('my-service-id')
-```
-
-```tsx
-await acceptService('my-service-id', ConsentType.Explicit)
-```
-
-```tsx
-await acceptService('my-service-id', ConsentType.Implicit)
-```
-
-#### `hasUserInteracted`
-
-A method to check if user has interacted with the consent prompt and given consent information.
-
-```tsx
-const userInteracted = hasUserInteracted()
-if (userInteracted) {
-    actionRequiredConsentInfoGiven()
-}
-```
+#### `updateServicesConsents`
 
-#### `getServicesFromLocalStorage`
+Updates consents for individual or multiple services.
 
-A method to get array of all services from local storage
+See also https://usercentrics.com/docs/web/features/api/control-functionality/#updateservicesconsents
 
 ```tsx
-const services = getServicesFromLocalStorage()
-const myService = services.find((service) => service.id === 'my-service-id')
+updateServicesConsents([{ id: 'my-service-id', consent: true }])
 ```
 
 #### `updateLanguage`
 
 Programmatic way to set language for the CMP.
 The param `countryCode` is a two character country code, e.g. "en" = set language to English
 
-See also https://docs.usercentrics.com/#/cmp-v2-ui-api?id=updatelanguage
+See also https://usercentrics.com/docs/web/features/api/control-functionality/#changelanguage
 
 ```tsx
 updateLanguage('fi')

src/components/UsercentricsDialogToggle.tsx

@@ -25,7 +25,7 @@ export const UsercentricsDialogToggle: FC<UsercentricsDialogToggleProps> = ({ on
 
             event.preventDefault()
             if (isUsercentricsInitialized) {
-                showFirstLayer()
+                void showFirstLayer()
             }
         },
         [isUsercentricsInitialized, onClick],