@financial-times/consent-resolution

This package exposes named consent decisions to client-side consumers through window.FTConsent. The interface is the same whether Sourcepoint supplies TCF or GPP consent data.

Purpose

Sourcepoint provides consent through different APIs and data models depending on which privacy framework applies. Consumers should not need to interpret those APIs, know Sourcepoint vendor and purpose IDs, or derive decisions from the FTConsent cookie.

A resolution is a named consent decision, such as youtube, derived from the applicable TCF or GPP data.

How it works

1. The package subscribes to Sourcepoint's TCF and GPP event APIs.
2. It compares data from the applicable API with the requirements defined for each resolution.
3. It updates window.FTConsent and runs the registered callbacks.

Each entry in the resolutions map defines the requirements for that decision: TCF vendor grants, TCF purpose grants, and GPP opt-out signals. Later consent events are evaluated against the same map.

Integrations

@financial-times/cmp-client

Consent resolution is bundled with @financial-times/cmp-client and initialised when the CMP client starts. This applies whether an application loads the hosted cmp.js script or calls initSourcepointCmp from the npm package.

See the CMP client documentation for integration instructions.

FT.com Google Tag Manager

The FT.com GTM container is configured to consume resolutions through the FTConsent (granted resolutions) variable. This variable is part of the FT.com GTM integration rather than an export from this package.

To require the youtube resolution, use a GTM Window Loaded trigger with a contains condition:

resolutions.youtube.granted

Use a resolution

The examples use youtube; replace it with another key from the resolutions map as needed.

Using window.FTConsent

Consent is resolved asynchronously. Register a callback before reading a resolution:

if (!window.FTConsent?.readyCallbacks) {
  window.FTConsent = { readyCallbacks: [] };
}

window.FTConsent.readyCallbacks.push({
  callbackFunction: () => {
    const hasConsent = window.FTConsent.resolutions?.get("youtube")?.consented === true;

    if (hasConsent) {
      loadYouTube();
    }
  },
});

Callbacks registered before consent is ready are queued. Callbacks registered after consent is ready run immediately, so consumers can always use the same registration pattern.

Only consented: true should enable a feature. Treat a missing resolution, or a callback that has not run, as no consent.

Respond to consent updates

By default, a callback runs once for the initial consent decision. Consumers that need to respond to later changes can set respondToUpdates:

window.FTConsent.readyCallbacks.push({
  callbackFunction: () => {
    const hasConsent = window.FTConsent.resolutions?.get("youtube")?.consented === true;

    if (hasConsent) {
      loadYouTube();
    }
  },
  respondToUpdates: true,
});

The callback should read the resolution each time it runs. Because it can run more than once, its side effects should be safe to repeat. It receives false as isAnUpdate on its first invocation and true on later invocations.

TypeScript

When the CMP client supplies the runtime, install this package as a development dependency to use its types:

npm install --save-dev @financial-times/consent-resolution

The package augments window.FTConsent and exports its interface types:

import type {
  FTConsentCmpState,
  FTConsentReadyCallbackFunction,
  FTConsentReadyCallbackOptions,
  FTConsentState,
} from "@financial-times/consent-resolution";

API reference

| Property | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | ready | Whether the initial consent resolutions are available. This does not represent CMP or privacy-manager readiness. | | consentedAll | Whether all resolutions are consented. Use a named resolution to gate a feature. | | resolutions | A Map of { consented: boolean } values keyed by resolution name. | | readyCallbacks | Callbacks for the initial decision and, when requested, later changes. | | cmp | CMP state populated by @financial-times/cmp-client and preserved when Consent Resolution initialises. | | cmp.activeLegislation | The applicable "gdpr" or "usnat" legislation. It is undefined until Sourcepoint reports which legislation applies to the user. | | cmp.openPrivacyManager | Opens the privacy manager configured by CMP client. |