@eo/next-ccm
v1.0.0
Published
Cookie Consent Module for Next.js & Tailwind websites
Downloads
952
Maintainers
daankruis
thaisi
nathanvangoor
robinfeo
sander.vm
jesseflikweerteo
jonahockey
ronald_elzen
wouternoordhof
evangelischeomroep
lklein
hermankremer
mhuijserKeywords
Readme
@eo/next-ccm
Easy use of the NPO Cookie Consent Module v1.1 within Next.js projects.
Originally a clone of @bnnvara/ccm version 1.1.0.
We removed all non-react/next npm dependencies, changed the module to TypeScript, added a README, and added Tailwind.
Usage
Installation and configuration
Execute the following:
pnpm install @eo/next-ccmAdd @eo/next-ccm to your project's tailwind content configuration, like so:
import { config as defaultConfig } from '@eo/next-ui'
export default {
...defaultConfig,
content: [
'./node_modules/@eo/next-ccm/src/**/*.{js,ts,jsx,tsx}',
...
],
...
}This package is not transpiled, so you need to add the following to your next.config.js module.exports:
module.exports = {
transpilePackages: [
'@eo/next-ccm',
...
],
...
}Initialization
Implement the CookieConsentModule in your root layout.
import { CookieConsentModule } from '@eo/next-ccm';
...
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="nl">
<body>
<UserProvider>
<Suspense>
// Using e.g. cookies.eo.nl instead of (the default) ccm.npo.nl,
// because we want to use 1st party cookies instead of 3rd party
<CookieConsentModule
organisation="EO"
site="eo.nl"
ccmDomain="https://cookies.eo.nl"
/>
</Suspense>
<ApolloWrapper>
<Header />
...
</ApolloWrapper>
</UserProvider>
</body>
</html>
)
}Consent Wrapper
import { CookieConsentWrapper, CcmCategories } from '@eo/next-ccm';
// The `ssr={true}` (default) will render the placeholder during Server Rendering.
// Consequently, `ssr={false}` will render the placeholder during Client Rendering.
export default const () => (
<CookieConsentWrapper
placeholder={<p>OOPS! No permission given!</p>}
categories={[
CcmCategories.SOCIAL,
CcmCategories.ANALYTICS,
]}
ssr={true}
>
Granted content
</CookieConsentWrapper>
)To make sure a user doesn't get cookies they have not given permission for, be sure to always place your external content within the <CookieConsentWrapper></CookieConsentWrapper> tags. Always classify for which categories we need permission from the user before displaying the wrapped content. See #categories.
If CookieConsentWrapper determines not all required permissions were given, the value of placeholder is rendered instead, until the required permissions have been given. If no placeholder is given, a default placeholder is rendered. A custom, component specific, placeholder is preferred.
Interacting with NPO CCM script and popup
If you want to interact with the NPO cookie management, you can place buttons within your placeholder (or anywhere else on your site for that matter) with specific properties to do so.
Opening the NPO cookie popup can be done by adding CcmClasses.openGenericNotification to an anchor tag's class names. Suppose your content cannot be showed and you want to highlight the specific cookie categories for which permission is required, you can bring up the NPO CCM popup and highlight those specific categories (or only show them, depending on the CCM selected at ccm.npo.nl) by using CcmClasses.openSpecificNotification and e.g. data-ccm-categories={[ CcmCategories.SOCIAL ]}.
Examples:
import { CcmClasses, CcmCategories } from '@eo/next-ccm';
// open cookie popup
<a
href="#"
className={CcmClasses.openGenericNotification}
data-ccm-categories={CcmCategories.requestable} // always specify data-ccm-categories!
>
Aanpassen
</a>
// open cookie popup with highlight on data-ccm-categories' categories
// or simply open a popup consiting of only the related categories
<a
href="#"
className={CcmClasses.openSpecificNotification}
data-ccm-categories={[ // always specify data-ccm-categories!
CcmCategories.SOCIAL,
CcmCategories.ANALYTICS
]}
>
Aanpassen
</a>
// go to cookies.eo.nl's settings page, instead of opening a popup
<a
href="#"
className={CcmClasses.openSettings}
data-ccm-categories={CcmCategories.requestable} // always specify data-ccm-categories!
>
Aanpassen
</a>Migrating from 'NPO Lower Bar' to 'NPO Lower Bar Split Request Multi Accept'
This package also allows for easily migrating to the NPO Lower Bar Split Request Multi Accept (from now on abbreviated LBSRMA).
Normally, having LBSRMA as the selected Cookie Bar Template allows for only requesting primary categories.
Permission for secondary categories can be given by clicking an anchor tag with class ccm_message_split_request_link with data-ccm-categories being set to any secondary categories we want permission to be given for.
However, when we're migrating from one template to the other, we cannot simply update every CCM-button on every website.
So, per our request NPO implemented a new feature.
As of LBSRMA version 3.3.0 we can pass along a splitRequestCategoryRequire property to NPO's CCM initialization script.
Any secondary categories specified here will be internally be handled as if they're primary categories.
In this @eo/next-ccm package, by default we set this splitRequestCategoryRequire property to ALL optional categories, i.e. CcmCategories.requestable.
This guarantees that when we're switching to LBSRMA through the https://ccm.npo.nl portal, all of our Next.js websites will still function correctly, because any secondary categories will still be handled as primary categories.
After we've switched to the LBSRMA template, we can update this package with the following changes:
- Update the CCM API's (
src/api/index.ts) Classes Enum:openGenericNotification = 'ccm_message_split_request_link'openSpecificNotification = 'ccm_message_split_request_link'
- Update CookieConsentModule component's
splitRequestCategoryRequireproperty to by default be[]instead ofCcmCategories.requestable. - Publish a new version on this package and update all packages and websites that use it.
Permissions
Cookies can be classified in multiple categories. To use a cookie within a category X, the user must have given the permission belonging to X.
| Category | Permission key | Permission value | Required/optional
|-|-|-|-|
| po_cc_necessary | CcmCategories.NECESSARY | necessary | Required |
| po_cc_analytics | CcmCategories.ANALYTICS | analytics | Required |
| po_cc_social | CcmCategories.SOCIAL | social | Optional |
| po_cc_advertising | CcmCategories.ADVERTISING | advertising | Optional |
| po_cc_recommendations | CcmCategories.RECOMMENDATIONS | recommendations | Optional |
| po_cc_miscellaneous | CcmCategories.MISCELLANEOUS | miscellaneous | Optional |
!!! Updating package
Package versions follow SemVer 2.0.0.
Publishing pre-release versions (-rc.1, -beta.1, etc) may be done from your own feature/bugfix/whatever branch, but actual release versions must be done from the main branch.
Check you're currently on the main branch, unless you're publishing a pre-release version.
Then run pnpm release.