react-cookiehub
v1.0.4
Published
React implementation for CookieHub
Downloads
1,441
Readme
react-cookiehub
A simple CookieHub implementation method for react and nextjs apps.
Table of Contents
- What is CookieHub
- Getting started
- React implementation
- Next.js App Router implementation
- Next.js Pages Router implementation
- CookieHub Scripts
- Configuration
What is CookieHub?
CookieHub is a cookie consent management platform designed to help website owners comply with data protection regulations, particularly the General Data Protection Regulation (GDPR) in the European Union. CookieHub provides tools and solutions that allow website administrators to easily obtain and manage user consent for the use of cookies and similar tracking technologies.
Key features of CookieHub include customizable cookie banners, preference centers, and mechanisms for obtaining granular consent from website visitors. The platform aims to simplify the process of implementing and maintaining compliance with privacy laws related to online tracking and data collection.
Get started by signing up if you don't already have an account.
Getting started
The CookieHub object should be initialized at the root of your project.
CookieHub.initialize('YOUR-DOMAIN-CODE', options)See Configuration for details about the options parameter
React Implementation
Initialize CookieHub at the root of your project
./src/App.js
import React from 'react';
import CookieHub from 'react-cookiehub';
function App() {
CookieHub.initialize('YOUR-DOMAIN-CODE');
return (
<div>
...
</div>
)
}
export default App;Next.js App Router implementation
CookieHub utilizes the global window object, which is only available on the client side, so we need to create a client component to initialize CookieHub.
./components/CookieHubInit.tsx
"use client";
import { CookieHub } from 'react-cookiehub';
import { useEffect } from 'react';
export function CookieHubInit() {
useEffect(() => {
CookieHub.initialize('YOUR-DOMAIN-CODE');
}, [])
return null;
}./app/layout.tsx
import { CookieHubInit } from '@/components/CookieHubInit'
export default function RootLayout({
children,
}: {
children: React.ReactNode
}) {
return (
<html>
<head>
<CookieHubInit />
</head>
<body>{children}</body>
</html>
)
}Next.js is known to cause problems with the load order of scripts, so we recommend using the CookieHub Scripts to prevent this problem.
Next.js Pages Router implementation
Initialize CookieHub in the _app file at the root of your project inside a useEffect to prevent CookieHub from running on the server side.
./_app.tsx
import type { AppProps } from 'next/app'
import { useEffect } from 'react'
import CookieHub from 'react-cookiehub';
export default function App({ Component, pageProps }: AppProps) {
useEffect(() => {
CookieHub.initialize('YOUR-DOMAIN-CODE');
}, [])
return <Component {...pageProps} />
}Next.js is known to cause problems with the load order of scripts, so we recommend using the CookieHub Scripts to prevent this problem.
CookieHub Scripts
The CookieHub package provides several components to implement tracking scripts without having to worry about them running before consent is given.
CookieHubScript
The CookieHubScript component can be used to load scripts the same way as any other scripts. You must set the category that the tracking script belongs to using the category parameter.
External scripts:
<CookieHubScript
src="my-tracking-script.com/1.js"
category="analytics"
/>Inline scripts:
<CookieHubScript
innerHTML={`
function myTrackingFunction(){
// Do some tracking
}
`}
category="marketing"
/>CookieHubGA
The CookieHubGA component can be used to load Google Analytics into your project. Set the trackingID parameter as your Google Analytics tracking ID.
<CookieHubGA trackingID='G-A5B4C3D2E1' />CookieHubPixel
The CookieHubPixel component can be used to load Facebook Pixel into your project. Set the pixelID parameter as your Facebook Pixel tracking ID.
<CookieHubPixel pixelID='123456789012345' />CookieHubYoutube
The CookieHubYoutube component can be used to load Youtube videos into your project. This component replaces the youtube url with a youtube-nocookie url which does not set any tracking cookies.
Using Video Url:
<CookieHubYoutube url="https://www.youtube.com/watch?v=_OKGUAbpj5k" />Using Video ID:
<CookieHubYoutube videoID={"_OKGUAbpj5k"} />Configuration
Alternative ways to block scripts until consent is given
If you're using other react packages to implement tracking services to your app you can utilize the onInitialise and onAllow CookieHub events to prevent them from running before CookieHub loads and is able to block them.
Tracking packages are different and might require different handling when loading them through CookieHub.
If the package requires initialization, similar to how CookieHub is initalized, you can use the onInitialize event that comes with the CookieHub package.
CookieHub.initialize('YOUR-DOMAIN-CODE', {
onInitialise: () => {
ReactGa.initialize('G-0000000000'); // Example for implementing Google Analytics
}
});You can also use the onAllow event to initialize packages when certain categories are allowed:
CookieHub.initialize('YOUR-DOMAIN-CODE', {
onAllow: (category) => {
if (category === 'analytics') {
ReactGa.initialize('G-0000000000'); // Example for implementing Google Analytics
}
}
});Events
Example of available events and how they can be utilized:
CookieHub.initialize('YOUR-DOMAIN-CODE', {
onInitialise: (status) => {
// CookieHub has been initalized
},
onAllow: (category) => {
if (category === 'analytics') {
// Consent has been given for the analytics category
}
},
onRevoke: (category) => {
if (category === 'marketing') {
// Consent has been denied for the marketing category
}
},
onStatusChange: (status, previousState) => {
if (status.answered === true) {
// User has updated their consent state
}
}
});Methods
load()
This method initializes CookieHub. It should be part of the default provided code and should only be called once on each page load. Any attempt to initialize CookieHub again will be ignored.
- options (object): An object containing a list of options and events.
CookieHub.load(options)hasAnswered()
Checks if the user has already made cookie choices by allowing all cookies or saving settings. This method doesn't accept any parameters.
CookieHub.hasAnswered()hasConsented(category)
Checks if the user has allowed the specified cookie category.
- category (string): The name or ID of the cookie category to check.
CookieHub.hasConsented(category)openDialog()
Opens the CookieHub dialog, typically displayed on the first load.
CookieHub.openDialog()closeDialog()
Closes the CookieHub dialog if it's still open.
CookieHub.closeDialog()openSettings()
Opens the CookieHub settings dialog. Useful if you've hidden the settings icon and want to create a custom link or button for opening the settings dialog.
CookieHub.openSettings()closeSettings()
Closes the CookieHub settings dialog.
CookieHub.closeSettings()allowAll()
Allows all cookie categories. This method offers an alternative way for users to consent to all categories.
CookieHub.allowAll()denyAll()
Denies all cookie categories. Similar to allowAll(), this method offers an alternative way for users to revoke consent for all categories.
CookieHub.denyAll()Linker
The Linker feature provided by CookieHub is a powerful tool that enables website owners to forward user consents to a different top-level domain with ease. This feature helps website owners eliminate repeated CookieHub consent dialogs when switching between top-level domains, as well as avoid requesting user consent again when changing a website's domain name.
CookieHub.initialize('YOUR-DOMAIN-CODE', {
linker: ['domain1.com', 'domain2.com']
});Debug
You can enable the debug flag to get more information from your CookieHub implementation which might help to solve some problems with the setup.
CookieHub.initialize('YOUR-DOMAIN-CODE', {
debug: true
});