Merge pull request #36 from s-group-dev/service-info

Service info

Author: iiroj

MIGRATION.md

@@ -5,15 +5,18 @@
     - 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).
+    - 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): https://usercentrics.com/docs/web/implementation/ui/optional-steps/#adding-a-nonce-to-the-script-tag
 - 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 `acceptService()` util has been replaced with `updateServicesConsents()` with a signature supporting multiple consents at a time.
+    - You will also need to call `saveConsents()` after updating them.
 - 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()`
+- Some utils and hooks have been removed because CMP v3 no longer supports them:
+    - Removed:
+        - `getServicesBaseInfo()`
+        - `useServiceInfo()`
+        - `getServicesFullInfo()`
+        - `useServiceFullInfo()`
+    - Added new `getServiceInfo()` util for getting service names and descriptions
 - All the utils are now `async` to match the CMP v3 implementations
 
 ## 2.0.0

README.md

@@ -69,18 +69,6 @@ declare module '@s-group/react-usercentrics/augmented' {
 
 ## API
 
-### Types
-
-#### `ConsentType`
-
-When giving consent using the API (instead of customer clicking the Dialog),
-consent can be either explicit (e.g. when clicking some custom button) or implicit.
-
-#### `UCWindow`
-
-Augmented window type, possibly including the `__ucCmp` API.
-Do not declare this globally, but prefer to use the included utility functions instead.
-
 ### Components
 
 #### `UsercentricsScript`
@@ -354,8 +342,20 @@ Updates consents for individual or multiple services.
 
 See also https://usercentrics.com/docs/web/features/api/control-functionality/#updateservicesconsents
 
+**Warning:** Updating consents doesn't save them! Remember to also call `saveConsents`.
+
 ```tsx
-updateServicesConsents([{ id: 'my-service-id', consent: true }])
+await updateServicesConsents([{ id: 'my-service-id', consent: true }])
+```
+
+#### `saveConsents`
+
+Saves the consents after being updated.
+
+See also https://usercentrics.com/docs/web/features/api/control-functionality/#saveconsents
+
+```tsx
+await saveConsents()
 ```
 
 #### `updateLanguage`
@@ -368,3 +368,13 @@ See also https://usercentrics.com/docs/web/features/api/control-functionality/#c
 ```tsx
 updateLanguage('fi')
 ```
+
+#### `getServiceInfo`
+
+Programmatic way to get the translated i18n content of the Web CMP modal.
+Useful for rendering custom UI with like listing services' names and descriptions.
+
+```tsx
+const services = await getServiceInfo()
+const { name, description } = services['my-service-id']
+```

src/hooks/use-has-service-consent.ts

@@ -25,7 +25,7 @@ export const useHasServiceConsent = (serviceId: ServiceId): boolean | null => {
         return consents[serviceId] ?? null
     }
 
-    if (strictMode) {
+    if (strictMode && !(serviceId in consents)) {
         throw new Error(`Usercentrics Service not found for id "${serviceId}"`)
     }
 

src/types.ts

@@ -5,12 +5,14 @@
 // eslint-disable-next-line @typescript-eslint/consistent-type-imports
 export type ServiceId = import('@s-group/react-usercentrics/augmented').ServiceId
 
+export type ConsentType = 'EXPLICIT' | 'IMPLICIT'
+
 /** Partial type for service info read from local storage, if available. Unused values are left out. */
 export type ServiceData = {
     name: string
     consent?: {
         given: boolean
-        type: 'IMPLICIT' | 'EXPLICIT'
+        type: ConsentType
     }
 }
 
@@ -21,6 +23,12 @@ export type ServiceData = {
 type ConsentData = {
     status: 'ALL_ACCEPTED' | 'ALL_DENIED' | 'SOME_ACCEPTED' | 'SOME_DENIED'
     required: boolean
+    language: string
+    setting: {
+        id: string
+        type: string
+        version: string
+    }
 }
 
 /**
@@ -72,9 +80,19 @@ type UC_CMP = {
      * @see https://usercentrics.com/docs/web/features/api/control-functionality/#updateservicesconsents
      *
      * @example updateServicesConsents([{ id: 'my-service-id', consent: true }])
+     *
+     * @warn Updating consents doesn't save them! Remember to also call `saveConsents`.
      */
     updateServicesConsents: (servicesConsents: { id: ServiceId; consent: boolean }[]) => Promise<void>
 
+    /**
+     * Saves the consents after being updated.
+     * @see https://usercentrics.com/docs/web/features/api/control-functionality/#saveconsents
+     *
+     * @example saveConsents()
+     */
+    saveConsents: () => Promise<void>
+
     /**
      * Retrieves all the consent details
      *
@@ -134,3 +152,17 @@ export type UCUIVIewChanged = CustomEvent<{
     view: UCUIView
     previousView: UCUIView
 }>
+
+/**
+ * The i18n localization content for the Web CMP. Unused values are left out.
+ */
+export type CMPi18nContent = {
+    services: Record<
+        ServiceId,
+        {
+            id: ServiceId
+            name: string
+            description: string
+        }
+    >
+}

src/utils.ts

@@ -1,4 +1,4 @@
-import type { ServiceId, UCDataFromLocalStorage, UCWindow } from './types.js'
+import type { CMPi18nContent, ServiceId, UCDataFromLocalStorage, UCWindow } from './types.js'
 
 /**
  * A method to check if user has interacted with the consent prompt and given consent information.
@@ -95,13 +95,25 @@ export const getConsentsFromLocalStorage = (): UCDataFromLocalStorage['consent']
  * @see https://usercentrics.com/docs/web/features/api/control-functionality/#updateservicesconsents
  *
  * @example updateServicesConsents([{ id: 'my-service-id', consent: true }])
+ *
+ * @warn Updating consents doesn't save them! Remember to also call `saveConsents`.
  */
 export const updateServicesConsents = async (
     servicesConsents: { id: ServiceId; consent: boolean }[],
 ): Promise<void> => {
     await (window as UCWindow).__ucCmp?.updateServicesConsents(servicesConsents)
 }
 
+/**
+ * Saves the consents after being updated.
+ * @see https://usercentrics.com/docs/web/features/api/control-functionality/#saveconsents
+ *
+ * @example saveConsents()
+ */
+export async function saveConsents(): Promise<void> {
+    await (window as UCWindow).__ucCmp?.saveConsents()
+}
+
 /**
  * Programmatic way to set language for the CMP.
  * @param countryCode Two character country code, e.g. "en" = set language to English
@@ -123,3 +135,35 @@ export const isOpen = (): boolean => {
 
     return false
 }
+
+/**
+ * Programmatic way to get the translated i18n content of the Web CMP modal.
+ * Useful for rendering custom UI with like listing services' names and descriptions.
+ * @param [countryCode] Two character country code, e.g. "en" = set language to English; defaults to configured language
+ *
+ * @example
+ * const services = await getServiceInfo()
+ * const { name, description } = services['my-service-id']
+ */
+export const getServiceInfo = async (countryCode?: string): Promise<CMPi18nContent['services']> => {
+    const consentDetails = await (window as UCWindow).__ucCmp!.getConsentDetails()
+    const language = countryCode ?? consentDetails.consent.language
+    const { id, type, version } = consentDetails.consent.setting
+
+    const response = await window.fetch(
+        `https://v1.api.service.cmp.usercentrics.eu/latest/i18n/${language}/${type}/${id}/${version}`,
+    )
+
+    const i18n = (await response.json()) as CMPi18nContent
+    return Object.values(i18n.services).reduce(
+        (acc, service) => ({
+            ...acc,
+            [service.id]: {
+                id: service.id,
+                name: service.name,
+                description: service.description,
+            },
+        }),
+        {} as CMPi18nContent['services'],
+    )
+}

tests/utils.test.ts

@@ -1,16 +1,31 @@
 import type { UCWindow } from '../src/types.js'
 import * as utils from '../src/utils.js'
 
+const TEST_SERVICE_INFO = {
+    'test-id': {
+        name: 'Test Service',
+        id: 'test-id',
+        description: 'This is a mocked test service',
+    },
+}
+
 describe('Usercentrics', () => {
     beforeAll(() => {
         ;(window as UCWindow).__ucCmp = {
             changeLanguage: jest.fn(),
             getConsentDetails: jest.fn(),
+            saveConsents: jest.fn(),
             showFirstLayer: jest.fn(),
             showSecondLayer: jest.fn(),
             showServiceDetails: jest.fn(),
             updateServicesConsents: jest.fn(),
         }
+
+        global.fetch = jest.fn().mockReturnValue({
+            json: jest.fn().mockReturnValue({
+                services: TEST_SERVICE_INFO,
+            }),
+        })
     })
 
     afterEach(() => {
@@ -29,6 +44,11 @@ describe('Usercentrics', () => {
             ])
         })
 
+        test('saveConsents', async () => {
+            await utils.saveConsents()
+            expect((window as UCWindow).__ucCmp?.saveConsents).toHaveBeenCalledWith()
+        })
+
         test('showFirstLayer', async () => {
             await utils.showFirstLayer()
             expect((window as UCWindow).__ucCmp?.showFirstLayer).toHaveBeenCalledTimes(1)
@@ -72,5 +92,31 @@ describe('Usercentrics', () => {
                 expect(utils.getConsentsFromLocalStorage()).toEqual(ucData.consent.services)
             })
         })
+
+        describe('getServiceInfo', () => {
+            it('should call upstream API with configured values', async () => {
+                jest.mocked((window as UCWindow).__ucCmp?.getConsentDetails)?.mockResolvedValueOnce({
+                    consent: {
+                        language: 'fi',
+                        required: false,
+                        status: 'ALL_DENIED',
+                        setting: {
+                            id: 'mock-id',
+                            type: 'GDPR',
+                            version: '1.2.3',
+                        },
+                    },
+                    services: {},
+                })
+
+                const serviceInfo = await utils.getServiceInfo()
+
+                expect(fetch).toHaveBeenCalledWith(
+                    'https://v1.api.service.cmp.usercentrics.eu/latest/i18n/fi/GDPR/mock-id/1.2.3',
+                )
+
+                expect(serviceInfo).toEqual(TEST_SERVICE_INFO)
+            })
+        })
     })
 })