react-gdpr-guard

react-gdpr-guard - v1.3.0

Official React binding for gdpr-guard

react-gdpr-guard acts like a meta-hook library: it exposes a single hook that you can use outside of your React app to create hooks that you will later use in that react app.

Here's a demo

Before using the library

You must know about the gdpr-guard library and how it works.

Here are a few links to get up to speed:

Setup the library

In a separate file, let's say a hooks/gdpr.js for instance, you can create your hooks alongside your GdprSavior and manager factory:

// src/hooks/gdpr.js

const managerFactory = () => {
    return GdprManagerBuilder.make()
        /* [...] */
        .build();
};
const savior = new MyGdprSavior();

export const {
    useSetupGdprEffect,
    useAttachGdprListenersEffect,
    useGdprManager,
    useGdprSavior,
    useGdpr,
    useGdprComputed,
    useGdprGuard,
    useGdprGuardEnabledState,
} = createGdprGuardHooks(savior, managerFactory);

Then, in your main component, you can attach the setup hook and the listeners hook:

// src/App.jsx

import {
    useSetupGdprEffect,
    useAttachGdprListenersEffect,
    useGdpr,
} from "./hooks/gdpr.js";

import MyGdprBanner from "./components/MyGdprBanner";
import MyGdprSettingsOpener from "./components/MyGdprSettingsOpener";

export default function App() {
    const {
        bannerWasShown,
        closeGdprBanner,
        resetAndShowBanner,
    } = useGdpr();

    // Bootstrap the library
    useSetupGdprEffect();

    // Attach events
    useAttachGdprListenersEffect(eventHub => {
        eventHub.onEnable("_ga", () => {
            // Load all Analytics scripts here
        });

        eventHub.onDisable("myIntrusive3rdPartyStuff", () => {
            // Disable everything from the intrusive 3rd-party lib
        });
    });

    // The rest of your component logic
    return (
        <>
            <MyGdprSettingsOpener onClick={resetAndShowBanner}/>
            {!bannerWasShown && <MyGdprBanner onClose={closeGdprBanner} />}
            {/* The rest of your component's UI */}
        </>
    );
}

UI/UX component recommendations

Default values must be chosen carefully and with the user's experience in mind. For instance: if geolocation is optional, disable it by default.

After the user changes their settings, saving them using the Savior API is recommended.

A tiny button or link that, when clicked, calls the resetAndShowBanner so that the GDPR settings UI may be opened again.

A banner, a modal or whatever prevents users from using your website without first interacting with it.

It should display at the very least 4 buttons:

"Accept all" which calls enableManager and then closeBanner
"Deny all" which calls disableManager and then closeBanner
"Accept current settings" which just calls closeBanner
"Modify settings" which opens your GDPR settings UI

Generally a modal (but can be whatever) in which the user has access to the following:

A switch/checkbox to toggle the whole manager using toggleManager
A link/button to accept all and thus call enableManager and then closeBanner
A link/button to deny all and thus call disableManager and then closeBanner
A list/tree of groups and guards with ways to toggle them individually
A button to cancel the modification of settings (which just closes the settings' UI and goes back to the banner)
A button to save the modifications and thus call closeBanner

The hooks

createGdprGuardHooks(gdprSavior, gdprManagerFactory)

The meta-hook that creates hooks, based on your manager and savior, that you can use throughout your app.

useSetupGdprEffect is a simple hook that just bootstrap the whole library's core logic. As such, you must use it (preferably only in one place) within your app. To keep things simple and organized, you might want to call it within your App component.

useGdprComputed(factory, deps = [])

It behaves exactly like useMemo but recomputes its value upon changes within the GDPR manager.

useGdprSavior()

Gives you direct access to the wrapper around the GdprSavior instance you provided. This may not be needed, but is useful if you need to tap into the lifecycle of your GDPR manager.

useGdprManager()

Gives you direct access to the wrapper around the GdprManager instance that is restored using the provided GdprSavior. It allows you to query and mutate your manager's state directly even though there are different hooks for that exact purpose.

useAttachGdprListenersEffect(callback)

It allows you to attach events listeners to your manager's GdprManagerEventHub. This is where you'll listen for enable/disable events on particular guards.

useGdprGuardEnabledState(guardName, useBannerStatus = false)

It allows you to query the enabled state of the guard that has the given guardName. If useBannerStatus, and for the enable state to be true, the banner would have to have been shown to the user.

useGdprGuard(guardName)

It allows you to control a single guard and access its data:

const {
    guard, // instance of GdprGuardRaw
    enableGuard, // callback to enable that guard
    disableGuard, // callback to disable that guard
    toggleGuard, // callback to toggle that guard
} = useGdprGuard("My guard's name");

Note that this also applies to GdprGroups since they are also GdprGuards.

useGdpr()

It allows you to do and access a lot of things at once, so let's detail those:

const {
    bannerWasShown,
    manager,
    closeGdprBanner,
    resetAndShowBanner,
    enableManager,
    disableManager,
    toggleManager,
    enableGuard,
    disableGuard,
    toggleGuard,
    guardIsEnabled,
    enableForStorage,
    disableForStorage,
    toggleForStorage,
} = useGdpr();