Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →

@eo/next-ccm

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@eo/next-ccm

Cookie Consent Module for Next.js & Tailwind websites

1.0.0
latest
npm

Version published: 3 months ago

Maintainers: 0

Created: 12 months ago

Source

@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-ccm

Add @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>
  )
}

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.

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 splitRequestCategoryRequire property to by default be [] instead of CcmCategories.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.

FAQs

What is @eo/next-ccm?

Is @eo/next-ccm well maintained?

Package last updated on 24 Oct 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install