Consent management for
*.theguardian.com
.
The Guardian CMP handles applying the CCPA to users in the USA, and TCFv2 to everyone else.
yarn add @guardian/consent-management-platform
or
npm install @guardian/consent-management-platform
This package uses ES2020
.
If your target environment does not support that, make sure you transpile this package when bundling your application.
import { cmp } from '@guardian/consent-management-platform';
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.
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.
type: Object
Optional additional parameters for reporting.
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.
cmp.init({
country: 'GB',
pubData: {
pageViewId: 'jkao3u2kcbaqk',
},
});
returns: boolean
Returns true
if the CMP has initialised.
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.
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
}
);
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.
if (cmp.hasInitialised()) {
if (cmp.willShowPrivacyMessageSync()) {
// do something
}
}
Displays an interface that allows users to manage their privacy settings at any time.
cmp.showPrivacyManager();
import {
onConsent,
onConsentChange,
getConsentFor,
} from '@guardian/consent-management-platform';
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.
type: function
Reports the user's privacy preferences.
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.
}
}
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;
}
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
}
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
type: string
| null
The active consent framework e.g. "ccpa"
, "aus"
, "tcfv2"
or null
.
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 }
}
});
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>
returns: boolean
Gets the consent for a given vendor.
type: string
Supported 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"
"redplanet"
type: Object
The consent object passed to the onConsentChange
callback.
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);
});
It is possible to disable the CMP entirely in the current browser, which can be useful for testing host applications.
returns: void
cmp.__disable(); // CMP won't run even if you try
returns: void
cmp.__enable(); // CMP will work as normal
returns: boolean
cmp.__isDisabled(); // => true/false
Set a gu-cmp-disabled=true
cookie. This is the same as running cmp.__disable()
.
document.cookie = 'gu-cmp-disabled=true;';
Removing it is the same as running cmp.__enable()
.
document.cookie = 'gu-cmp-disabled=; Max-Age=0;';
To disable consent in Cypress tests, see their setCookie
documentation.
See the developer docs