npm package: @financial-times/ads-personalised-consent
Description: ads-personalised-consent =================
Latest version: 7.4.0

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](https://github.com/Financial-Times/privacy/tree/main/src/packages/legislation-client)
- The browser settings - e.g. [Global Privacy Control (GPC)](https://globalprivacycontrol.org/).
- 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](https://www.ft.com/preferences/manage-cookies), the [Manage Cookies page on the FT App](https://app.ft.com/manage_cookies) 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](https://www.ft.com/preferences/privacy)

## 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

### getPersonalisedConsent()

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

### personalisedConsent.isAllowed()

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](https://github.com/Financial-Times/privacy/tree/main/src/packages/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)](https://globalprivacycontrol.org/)
- 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 |

### personalisedConsent.getLegislation()

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.

### personalisedConsent.getRegion()

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.

### personalisedConsent.getGpcValue()

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

### personalisedConsent.getConsentCookie()

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 |

### personalisedConsent.update()

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

### personalisedConsent.updatePrivacyLegislation()

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` |

### personalisedConsent.updateGpcValue()

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

### personalisedConsent.updateConsentCookie()

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  |