@financial-times/ads-personalised-consent

ads-personalised-consent
=================

A client side package to provide consent settings of personalised advertisement.

Functionality Overview

This package collects all the information related to privacy and generates an answer on whether different types of personalised advertisement is allowed. It takes into account of:
- The privacy policy of the location which the user is in (e.g. California Consumer Privacy Act (CCPA) for California, US), which is collected from Privacy Legislation Client
- The browser settings - e.g. Global Privacy Control (GPC).
- The consents settings for _behavioral_, _demographic_ and _programmatic_ ads retrieved via the FTConsent cookie. Users can configure these settings via the Manage Cookies page in FT.com, the Manage Cookies page on the FT App and the Manage Cookies pages on the specialist titles websites. These values can also be configured via the Cookie Banner displayed on FT.com, FT App or specialist titles. Yet another way to configure ads consent is via the Privacy page on FT.com

Use

Typical usage would be to add the module to your app, call the imported method
and then check whether the personalised advertisement is allowed:

``js
import { getPersonalisedConsent } from "@financial-times/ads-personalised-consent";

async function onPageLoad() {
// create a fresh, updated instance of PersonalisedConsent, and get the privacy properties via getters
const pc = await getPersonalisedConsent();
const personalisedConsent = pc.isAllowed();
// check whether a certain type of personalised ads is allowed or not
if (personalisedConsent.behavioral) {
setupBehavioralAds();
} else {
blockBehavioralAds();
}

// alternatively, only update the privacy legislation properties and retrieve the new values
await pc.updatePrivacyLegislation();
const legislation = pc.getLegislation();
const region = pc.getRegion();
// similar for GPC value and consent cookie
pc.updateGpcValue();
const gpc = pc.getGpcValue();
pc.updateConsentCookie();
const consentCookie = pc.getConsentCookie();
...
}
`

API

$3

Initialise the instance of PersaonalisedConsent and update all the privacy related properties. Returns a Promise which always resolves with the said instance.

$3

Returns an Object identifying whether different types of personalised ads (behavioural, demographic and programmatic) are allowed or not, based on
- The privacy policy obtained from Privacy Legislation Client (If Privacy Legislation Client returns error, it will consider the user is subject to all the policies available.)
- The browser settings for Global Privacy Control (GPC)
- The consents settings for _behavioral_, _demographic_ and _programmatic_ ads retrieved via the FTConsent cookie.

| Name | Data-structure | Notes |
|-------------------|----------------------------|-------|
| behavioral | boolean | whether behavioral ads is allowed |
| demographic | boolean | whether demographic ads is allowed |
| programmatic | boolean | whether programmatic ads is allowed |

$3

Returns the legislation stored in the instance since last update, which is either
- a Set of legislation which the user is subject to if Privacy Legislation Client succeeds, or;
- undefined if Privacy Legislation Client throws error.

$3

Returns the region stored in the instance since last update, which is either
- a string identifying the region which the user is in if Privacy Legislation Client succeeds, or;
- undefined if Privacy Legislation Client throws error.

$3

Returns a boolean showing the GPC settings on the browser (which is Navigator.globalPrivacyControl) stored in the instance since last update.

$3

Returns an Object identifying user's settings in FTConsent cookie for different types of personalised ads (behavioural, demographic and programmatic) stored in the instance since last update.

| Name | Data-structure | Notes |
|-------------------|----------------------------|-------|
| behavioral | boolean | FTConsent cookie exists and behaviouraladsOnsite:on is set |
| demographic | boolean | FTConsent cookie exists and demographicadsOnsite:on is set |
| programmatic | boolean | FTConsent cookie exists and programmaticadsOnsite:on is set |

$3

Update all the privacy related properties. Returns a Promise which always resolves.

$3

Updates only legislation and region, and returns a Promise containing

| Name | Data-structure | Notes |
|-------------------|----------------------------|-------|
| legislation | Set of string OR undefined | a Set of legislation which the user is subject to if Privacy Legislation Client succeeds, otherwise undefined |
| region | string OR undefined | a string identifying the region which the user is in if Privacy Legislation Client succeeds, otherwise undefined |

$3

Updates only the GPC settings, and return a boolean showing the latest GPC settings on the browser.

$3

Updates only the user's settings in FTConsent cookie for different types of personalised ads, and return an Object identifying the settings.

| Name | Data-structure | Notes |
|-------------------|----------------------------|-------|
| behavioral | boolean | FTConsent cookie exists and behaviouraladsOnsite:on is set |
| demographic | boolean | FTConsent cookie exists and demographicadsOnsite:on is set |
| programmatic | boolean | FTConsent cookie exists and programmaticadsOnsite:on` is set |