From 8fcaf80215758b3b7a5dcbc17a82997b42809d05 Mon Sep 17 00:00:00 2001 From: Sunny Freshheads Date: Tue, 10 Oct 2023 10:27:04 +0200 Subject: [PATCH 1/2] Update docs --- README.md | 68 ++++++++++++++++------------- doc/gtag_setup.md | 95 +++++++++++++++++++++++++++++++++++++++++ doc/tagmanager_setup.md | 52 ++++++++++++++++++++++ 3 files changed, 185 insertions(+), 30 deletions(-) create mode 100644 doc/gtag_setup.md create mode 100644 doc/tagmanager_setup.md diff --git a/README.md b/README.md index fab2346..0eba318 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,11 @@ The cookie settings are stored as follows: `'["functional","analytics","marketing"]'` +## Setup with @freshheads/analytics-essentials + +- [Gtag & analytics-essentials setup](doc/gtag_setup.md) +- [Tag Manager & analytics-essentials setup](doc/tagmanager_setup.md) + ## Usage You can use the build in cookieguard to get up and running quickly or use the provided hooks to make your own. @@ -14,13 +19,13 @@ The cookiebanner makes use of Context to share the cookie state throughout the a - Wrap your app with the Provider: - ```jsx - import { CookieGuardContextProvider } from '@freshheads/cookie-guard'; +```jsx +import { CookieGuardContextProvider } from '@freshheads/cookie-guard'; - - - ; - ``` + + +; +``` - The provider optionally accepts: @@ -32,30 +37,33 @@ The cookiebanner makes use of Context to share the cookie state throughout the a - Add the premade Cookie Banner to your app - ```jsx - import { - CookieGuard, - CookieGuardContextProvider, - CookieGuardProps - } from '@freshheads/cookie-guard'; - import '@freshheads/cookie-guard/dist/style.css'; - - const CookieGuardProps = { - title: 'Onze site maakt gebruik van cookies.', - description: - 'Wij gebruiken cookies voor de werking van de website, analyse en verbetering en marketingdoeleinden.', - acceptAllLabel: 'Alle cookies accepteren', - saveLabel: 'Opslaan', - functionalLabel: 'Noodzakelijke cookies', - analyticsLabel: 'Analytische cookies', - marketingLabel: 'Marketing cookies', - } - - - - - - ``` +```jsx +import { + CookieBanner, + CookieCategorySettings, + CookieGuardProvider +} from '@freshheads/cookie-guard'; +import '@freshheads/cookie-guard/dist/style.css'; + +const CookieGuardProps = { + title: 'Onze site maakt gebruik van cookies.', + description: + 'Wij gebruiken cookies voor de werking van de website, analyse en verbetering en marketingdoeleinden.', + acceptAllLabel: 'Alle cookies accepteren', + saveLabel: 'Opslaan', + requiredLabel: 'Noodzakelijke cookies'. + functionalLabel: 'Noodzakelijke cookies', + analyticsLabel: 'Analytische cookies', + marketingLabel: 'Marketing cookies', +} + +return ( + + {/** your app components **/} + + +); +``` - To style look at the source code `/src/popupstyles.css` and import your own css. diff --git a/doc/gtag_setup.md b/doc/gtag_setup.md new file mode 100644 index 0000000..b587f98 --- /dev/null +++ b/doc/gtag_setup.md @@ -0,0 +1,95 @@ +# Gtag setup + +Setup with use of Gtag & [@freshheads/analytics-essentials](https://github.com/freshheads/analytics-essentials) + +#### **`components/GA4Loader.tsx`** + +Add a component to load GA4 within the `` so we have access to the analytics cookies. + +```jsx +import { + CookieConsentOptions, + CookieConsentValues, + LoadGA4, +} from '@freshheads/analytics-essentials'; +import { CookieCategorySettings, useCookies } from '@freshheads/cookie-guard'; + +export const formatCookiesForGA = ( + cookieSettings: CookieCategorySettings +): CookieConsentOptions | undefined => { + // formats cookies from Cookie Guard + if (!cookieSettings) return undefined; + + return { + ad_storage: + cookieSettings.marketing === true + ? CookieConsentValues.GRANTED + : CookieConsentValues.DENIED, + analytics_storage: + cookieSettings.analytics === true + ? CookieConsentValues.GRANTED + : CookieConsentValues.DENIED, + functionality_storage: + cookieSettings.functional === true + ? CookieConsentValues.GRANTED + : CookieConsentValues.DENIED, + personalization_storage: + cookieSettings.marketing === true + ? CookieConsentValues.GRANTED + : CookieConsentValues.DENIED, + }; +}; + +const GA4Loader = () => { + const { cookieSettings } = useCookies(); + + return ( + <> + {process.env.NEXT_PUBLIC_GA_MEASUREMENT_ID && ( + + )} + + ); +}; +``` + +#### **`app.tsx`** + +```jsx +import { pushGaConsent } from '@freshheads/analytics-essentials'; +import { + CookieBanner, + CookieCategorySettings, + CookieGuardProvider, +} from '@freshheads/cookie-guard'; +import GA4Loader, { formatCookiesForGA } from '@/components/GA4Loader'; + +const App = () => { + const onCookiesChanged = (cookieSettings: CookieCategorySettings) => { + if (!cookieSettings) return; + const formattedCookies = formatCookiesForGA(cookieSettings); + if (!formattedCookies) return; + pushGaConsent(formattedCookies); + }; + + return ( + + + {/** your app components **/} + + + ); +}; +``` diff --git a/doc/tagmanager_setup.md b/doc/tagmanager_setup.md new file mode 100644 index 0000000..b1801d6 --- /dev/null +++ b/doc/tagmanager_setup.md @@ -0,0 +1,52 @@ +# Tag Manager setup + +Setup with use of Tag Manager & [@freshheads/analytics-essentials](https://github.com/freshheads/analytics-essentials) + +#### **`app.tsx`** + +```jsx +import { + CookieBanner, + CookieCategorySettings, + CookieGuardProvider, +} from '@freshheads/cookie-guard'; +import { + EventTypes, + LoadTagManager, + pushDataLayerEvent, +} from '@freshheads/analytics-essentials'; + +const App = () => { + const onCookiesChanged = (cookieSettings: CookieCategorySettings) => { + if (!cookieSettings) return; + + pushDataLayerEvent({ + type: EventTypes.CUSTOM, + name: 'cookie_settings_changed', + }); + }; + + return ( + <> + {process.env.NEXT_PUBLIC_GTM_ID && ( + + )} + + {/** your app components **/} + + + + ); +}; +``` From 7a5ec7027ba2018015d67499a91ac5bd26d24d4e Mon Sep 17 00:00:00 2001 From: Sunny Freshheads Date: Tue, 10 Oct 2023 11:43:23 +0200 Subject: [PATCH 2/2] v4 | add Chakra-UI example --- README.md | 6 +- examples/ChakraUI/.gitignore | 3 + examples/ChakraUI/CookieBanner.tsx | 142 +++++++++++++++++++++++++++++ examples/ChakraUI/package.json | 16 ++++ 4 files changed, 163 insertions(+), 4 deletions(-) create mode 100644 examples/ChakraUI/.gitignore create mode 100644 examples/ChakraUI/CookieBanner.tsx create mode 100644 examples/ChakraUI/package.json diff --git a/README.md b/README.md index 0eba318..7d6945a 100644 --- a/README.md +++ b/README.md @@ -69,8 +69,6 @@ return ( - You can also use the hooks to make your own custom cookiebanner -TODO: explain hooks with chakraui example +## Examples -```jsx - -``` +- [Chakra-UI](examples/ChakraUI) custom cookie banner diff --git a/examples/ChakraUI/.gitignore b/examples/ChakraUI/.gitignore new file mode 100644 index 0000000..51e7ab2 --- /dev/null +++ b/examples/ChakraUI/.gitignore @@ -0,0 +1,3 @@ +/node_modules + +package-lock.json \ No newline at end of file diff --git a/examples/ChakraUI/CookieBanner.tsx b/examples/ChakraUI/CookieBanner.tsx new file mode 100644 index 0000000..ebf0c35 --- /dev/null +++ b/examples/ChakraUI/CookieBanner.tsx @@ -0,0 +1,142 @@ +import { + Button, + Checkbox, + HStack, + Modal, + ModalBody, + ModalContent, + ModalHeader, + ModalOverlay, + Text, + VStack, +} from '@chakra-ui/react'; +import { useCookies } from '@freshheads/cookie-guard'; +import React from 'react'; +import { FC, useEffect, useState } from 'react'; + +const CookieBannerPrimitive: FC = () => { + const { + cookieSettings, + setCookieSettings, + cookieBannerIsOpen, + setCookieBannerIsOpen, + } = useCookies(); + /* + To prevent the cookie banner changing the settings without pressing save, + we need to keep track of the options in the banner itself. + */ + const [cookieOptions, setCookieOptions] = useState<{ + required: boolean; + functional: boolean; + analytics: boolean; + marketing: boolean; + }>({ + required: cookieSettings?.required ?? true, + functional: cookieSettings?.functional ?? false, + analytics: cookieSettings?.analytics ?? false, + marketing: cookieSettings?.marketing ?? false, + }); + + useEffect(() => { + setCookieOptions({ + required: cookieSettings?.required ?? true, + functional: cookieSettings?.functional ?? false, + analytics: cookieSettings?.analytics ?? false, + marketing: cookieSettings?.marketing ?? false, + }); + }, [cookieSettings]); + + const onAcceptAll = () => { + setCookieSettings({ + functional: true, + analytics: true, + marketing: true, + }); + setCookieBannerIsOpen(false); + }; + + return ( + {}} + isCentered + size={'2xl'} + closeOnEsc={false} + closeOnOverlayClick={false} + > + + + Onze site maakt gebruik van cookies + + + Wij gebruiken cookies voor de werking van de website, + analyse en verbetering en marketingdoeleinden. + + + + + Noodzakelijke cookies + + + setCookieOptions({ + ...cookieOptions, + functional: !cookieOptions.functional, + }) + } + > + Functionele cookies + + + setCookieOptions({ + ...cookieOptions, + analytics: !cookieOptions.analytics, + }) + } + > + Analytische cookies + + + setCookieOptions({ + ...cookieOptions, + marketing: !cookieOptions.marketing, + }) + } + > + Marketing cookies + + + + + + + + + + + ); +}; + +export default CookieBannerPrimitive; diff --git a/examples/ChakraUI/package.json b/examples/ChakraUI/package.json new file mode 100644 index 0000000..ca5e94c --- /dev/null +++ b/examples/ChakraUI/package.json @@ -0,0 +1,16 @@ +{ + "name": "@freshheads/cookie-guard-example-chakra-ui", + "private": true, + "version": "1.0.0", + "author": "Freshheads", + "license": "MIT", + "dependencies": { + "@chakra-ui/react": "^2.8.1", + "@emotion/react": "^11.11.1", + "@emotion/styled": "^11.11.0", + "@freshheads/cookie-guard": "^4.0.0-alpha.4", + "framer-motion": "^10.16.4", + "react": "^18.2.0", + "react-dom": "^18.2.0" + } +}