feat: add useAreAllConsentsAccepted() hook (#22)

Author: Mingyu Cui

README.md

@@ -194,6 +194,25 @@ Returns `true` or `false` based on consent status, or `null` when unknown (not y
 }
 ```
 
+#### `useAreAllConsentsAccepted`
+
+Whether all Usercentrics services have been given consent.
+Returns `true` or `false` based on consent status, or `null` when unknown (not yet loaded).
+
+**Warning:** it's best to assume no consent until this hook returns `true`
+
+```tsx
+;() => {
+    const hasAllConsents = useAreAllConsentsAccepted()
+
+    useEffect(() => {
+        if (hasAllConsents) {
+            loadMyService()
+        }
+    }, [hasAllConsents])
+}
+```
+
 #### `useIsFailed`
 
 Returns `true` if Usercentrics failed to load inside the
@@ -386,6 +405,18 @@ if (hasConsent) {
 }
 ```
 
+#### `areAllConsentsAccepted`
+
+Returns true if all Usercentrics services have been given consent
+
+```tsx
+const hasAllConsents = areAllConsentsAccepted()
+
+if (hasAllConsents) {
+    loadMyService()
+}
+```
+
 #### `acceptService`
 
 A method for accepting a single service.

src/hooks/use-are-all-consents-accepted.ts

@@ -0,0 +1,29 @@
+import { useContext } from 'react'
+
+import { UsercentricsContext } from '../context.js'
+import { areAllConsentsAccepted } from '../utils.js'
+
+/**
+ * Whether all Usercentrics services have been given consent.
+ * Returns `true` or `false` based on consent status, or `null` when unknown (not yet loaded).
+ *
+ * @warn it's best to assume no consent until this hook returns `true`
+ */
+export const useAreAllConsentsAccepted = (): boolean | null => {
+    const { isClientSide, isInitialized, localStorageState } = useContext(UsercentricsContext)
+
+    /** Consent status is unknown during SSR because CMP is only available client-side */
+    if (!isClientSide) {
+        return null
+    }
+
+    /**
+     * Until Usercentrics CMP has loaded, try to get consent status from localStorage.
+     * If it's not loaded, and there's nothing in localStorage, this will return `null`
+     */
+    if (!isInitialized) {
+        return localStorageState.length > 0 ? localStorageState.every((service) => service.status === true) : null
+    }
+
+    return areAllConsentsAccepted()
+}

src/types.ts

@@ -83,6 +83,12 @@ type UC_UI = {
      * @see https://docs.usercentrics.com/#/cmp-v2-ui-api?id=acceptservice
      */
     acceptService?: (serviceId: ServiceId, consentType?: ConsentType) => Promise<void>
+
+    /**
+     * A method to check if all consents were accepted
+     * @see https://docs.usercentrics.com/#/cmp-v2-ui-api?id=areallconsentsaccepted
+     */
+    areAllConsentsAccepted?: () => boolean
 }
 
 /**

src/utils.ts

@@ -129,3 +129,9 @@ export const acceptService = async (serviceId: ServiceId, consentType?: ConsentT
         await (window as UCWindow).UC_UI?.acceptService?.(serviceId, consentType)
     }
 }
+
+/**
+ * A method to check if all consents were accepted
+ * @see https://docs.usercentrics.com/#/cmp-v2-ui-api?id=areallconsentsaccepted
+ */
+export const areAllConsentsAccepted = () => !!(IS_BROWSER && (window as UCWindow).UC_UI?.areAllConsentsAccepted?.())

tests/hooks/use-are-all-consents-accepted.test.tsx

@@ -0,0 +1,99 @@
+import { renderHook } from '@testing-library/react'
+import type { ContextType, FC, ReactNode } from 'react'
+import React from 'react'
+
+import { UsercentricsContext } from '../../src/context.js'
+import { useAreAllConsentsAccepted } from '../../src/hooks/use-are-all-consents-accepted.js'
+import * as utils from '../../src/utils.js'
+
+const mockAreAllConsentsAccepted = jest.spyOn(utils, 'areAllConsentsAccepted')
+
+describe('Usercentrics', () => {
+    describe('hooks', () => {
+        describe('useAreAllConsentsAccepted', () => {
+            const CONTEXT: ContextType<typeof UsercentricsContext> = {
+                hasInteracted: false,
+                isClientSide: true,
+                isFailed: false,
+                isInitialized: true,
+                isOpen: false,
+                localStorageState: [],
+                ping: Symbol(),
+                strictMode: false,
+            }
+
+            const getWrapper =
+                (context?: Partial<ContextType<typeof UsercentricsContext>>): FC<{ children: ReactNode }> =>
+                // eslint-disable-next-line react/display-name
+                ({ children }) => (
+                    <UsercentricsContext.Provider value={{ ...CONTEXT, ...context }}>
+                        {children}
+                    </UsercentricsContext.Provider>
+                )
+
+            it('should return null during SSR', () => {
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper({ isClientSide: false }),
+                })
+
+                expect(result.current).toEqual(null)
+            })
+
+            it('should return null when not initialized and localStorage is empty', () => {
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper({ isInitialized: false }),
+                })
+
+                expect(result.current).toEqual(null)
+            })
+
+            it('should return false when not initialized and some services in localStorage do not have consent', () => {
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper({
+                        isInitialized: false,
+                        localStorageState: [
+                            { id: 'test-id', status: true },
+                            { id: 'test-id2', status: false },
+                        ],
+                    }),
+                })
+
+                expect(result.current).toEqual(false)
+            })
+
+            it('should return true when not initialized and all services in localStorage have consent', () => {
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper({
+                        isInitialized: false,
+                        localStorageState: [
+                            { id: 'test-id', status: true },
+                            { id: 'test-id2', status: true },
+                        ],
+                    }),
+                })
+
+                expect(result.current).toEqual(true)
+            })
+
+            it('should return false when not all consents are given', () => {
+                mockAreAllConsentsAccepted.mockReturnValue(false)
+
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper(),
+                })
+
+                expect(result.current).toEqual(false)
+            })
+
+            it('should return true when all consents are given', () => {
+                mockAreAllConsentsAccepted.mockReturnValue(true)
+
+                const { result } = renderHook(() => useAreAllConsentsAccepted(), {
+                    wrapper: getWrapper(),
+                })
+
+                expect(result.current).toEqual(true)
+            })
+        })
+    })
+})