npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@guardian/consent-management-platform

v13.12.0

Published

Consent management for *.theguardian.com.

Downloads

6,449

Readme

Consent Management Platform

npm (scoped) ES version Types Coverage Status

Consent management for *.theguardian.com.

The Guardian CMP handles applying the CCPA to users in the USA, and TCFv2 to everyone else.

Table of Contents

Installation

Generic badge

yarn add @guardian/consent-management-platform

or

npm install @guardian/consent-management-platform

Bundling

This package uses ES2020.

If your target environment does not support that, make sure you transpile this package when bundling your application.

Managing Consent

import { cmp } from '@guardian/consent-management-platform';

cmp.init(options)

returns: void

Adds the relevent privacy framework to the page. It must be called to enable privacy management. If necessary, it will also display the initial privacy message.

options.country

type: string values: any 2-letter, ISO_3166-1 country code, e.g. GB, US, AU, …

Declare which country your user is in. Required – throws an error if it's missing.

options.pubData

type: Object

Optional additional parameters for reporting.

pubData.pageViewId

type: string

Optional value identifying the unique pageview associated with this instance of the CMP.

Will be used to link back to a browserId for further reporting; if possible this should be available via the pageview table.

Example

cmp.init({
	country: 'GB',
	pubData: {
		pageViewId: 'jkao3u2kcbaqk',
	},
});

cmp.hasInitialised()

returns: boolean

Returns true if the CMP has initialised.

cmp.willShowPrivacyMessage()

returns: Promise<Boolean>

Returns a promise that resolves to true if the CMP will show the initial privacy message once it has initialised, or false if not.

Example

cmp.willShowPrivacyMessage()
    .then(willShow =>
        if (willShow) {
            console.log("a privacy message will show as soon as it's ready");
            // e.g. don't show any other banners
        } else {
            console.log('a privacy message will not be shown');
            // e.g. show another banner if you like
        }
    );

cmp.willShowPrivacyMessageSync()

returns: Boolean

You almost always want to use the async version above.

Returns true if the CMP has shown, is showing or will show the initial privacy message. Returns false otherwise.

Throws an error if the CMP has not been initialised.

Example

if (cmp.hasInitialised()) {
	if (cmp.willShowPrivacyMessageSync()) {
		// do something
	}
}

cmp.showPrivacyManager()

Displays an interface that allows users to manage their privacy settings at any time.

Example

cmp.showPrivacyManager();

Using Consent

import {
	onConsent,
	onConsentChange,
	getConsentFor,
} from '@guardian/consent-management-platform';

onConsentChange(callback, final?)

returns: void

An event listener that invokes callbacks whenever the consent state:

  • is acquired (e.g. after initialising)
  • changes (eg. if a user changes their privacy preferences)

If the consent state has already been acquired when onConsentChange is called, the callback will be invoked immediately.

Passing true for the optional final parameter guarantees that the callback will be executed after all other callbacks that haven't been registered with the flag when consent state changes. If more than one callback registered with final = true, they will be executed in the order in which they were registered when consent changes.

callback(consentState)

type: function

Reports the user's privacy preferences.

consentState.tcfv2

type: Object or undefined

Reports the user's preferences for each of the TCFv2 purposes, the last CMP event status, custom vendor consents, flag if GDPR applies, the TC string and addtlConsent string.

If the user is either in the USA or Australia, it will be undefined.

Unlike the __tcfapi, all ten consents will have a set boolean value, defaulting to false where no explicit consent was given.

{
    gdprApplies: Boolean | undefined, // true - GDPR Applies, false - GDPR Does not apply, undefined - unknown whether GDPR Applies
    tcString: String, // 'base64url-encoded TC string with segments'
    addtlConsent: String, // Google AC string
    eventStatus: String, // 'tcloaded' | 'cmpuishown' | 'useractioncomplete'
    consents: {
        1: Boolean,
        2: Boolean,
        /* … */
        9: Boolean,
        10: Boolean,
    },

    vendorConsents: {
        'abcdefghijklmnopqrstuvwx': Boolean,
        'yz1234567890abcdefghijkl': Boolean,
        'mnopqrstuvwxyz1234567890': Boolean,
        // Sourcepoint IDs, etc.
    }
}
consentState.ccpa

type: Object or undefined

Reports whether user has withdrawn consent to sell their data in the USA.

If the user is not in the USA, it will be undefined.

{
	doNotSell: Boolean;
}
consentState.aus

type: Object or undefined

Reports whether user has withdrawn consent to personalised advertising in Australia.

If the user is not in Australia, it will be undefined.

{
    personalisedAdvertising: Boolean, // True by default
}
consentState.canTarget

type: boolean

If the user can be targeted for personalisation according to the active consent framework.

For example canTarget would be true in the following scenarios:

  • for CCPA if the user has not clicked "do not sell",
  • for AUS if the user has not opted out of personalised advertising
  • for TCFv2 if the user has given consent for all purposes
consentState.framework

type: string | null

The active consent framework e.g. "ccpa", "aus", "tcfv2" or null.

Example

import { onConsentChange } from '@guardian/consent-management-platform';

onConsentChange(({ tcfv2, ccpa, aus }) => {
	if (tcfv2) {
		console.log(tcfv2); // { 1: true || false, 1: true || false, ... }
	}

	if (ccpa) {
		console.log(ccpa); // { doNotSell: true || false }
	}

	if (aus) {
		console.log(aus); // { personalisedAdvertising: true || false }
	}
});

onConsent()

A promise wrapper around onConsentChange that resolves the initial consent state.

This will only resolve once whereas callbacks passed to onConsentChange are executed each time consent state changes. Avoid using this function in contexts where subsequent consent states must be listened for.

returns: Promise<ConsentState>

getConsentFor(vendor, consentState)

returns: boolean

Gets the consent for a given vendor.

vendor

type: string

TCFV2 vendors

  • "a9"
  • "acast"
  • "braze"
  • "comscore"
  • "criteo"
  • "google-analytics"
  • "google-mobile-ads"
  • "google-tag-manager"
  • "googletag"
  • "ias"
  • "inizio"
  • "ipsos"
  • "magnite" (do not use until contract signed)
  • "nielsen"
  • "ophan"
  • "permutive"
  • "prebid"
  • "qm" (Quantum Metric)
  • "redplanet" (Australia only)
  • "remarketing"
  • "sentry"
  • "teads"
  • "twitter"
  • "youtube-player"

Aus only Vendors

  • "redplanet"

consentState

type: Object

The consent object passed to the onConsentChange callback.

Example

import {
	onConsentChange,
	getConsentFor,
} from '@guardian/consent-management-platform';

onConsentChange((consentState) => {
	const ga = getConsentFor('google-analytics', consentState); // true
	const comscore = getConsentFor('comscore', consentState); // false

	// throws error
	const eowifnwoeifjoweinf = getConsentFor(
		'eowifnwoeifjoweinf',
		consentState,
	);

	// you can still use the consent state for a more complicated task
	const complexConsentCondition = myComplexConsentTask(consentState);
});

Disabling Consent

It is possible to disable the CMP entirely in the current browser, which can be useful for testing host applications.

cmp.__disable()

returns: void

Example

cmp.__disable(); // CMP won't run even if you try

cmp.__enable()

returns: void

Example

cmp.__enable(); // CMP will work as normal

cmp.__isDisabled()

returns: boolean

Example

cmp.__isDisabled(); // => true/false

Manually

Set a gu-cmp-disabled=true cookie. This is the same as running cmp.__disable().

Example

document.cookie = 'gu-cmp-disabled=true;';

Removing it is the same as running cmp.__enable().

Example

document.cookie = 'gu-cmp-disabled=; Max-Age=0;';

Using Cypress

To disable consent in Cypress tests, see their setCookie documentation.

Development

See the developer docs