@financial-times/cmp-client 0.0.0-backup.1

package/README.md

@@ -0,0 +1,273 @@
+# CMP Client
+
+A client-side library to help you add a CMP (currently provided by Sourcepoint) to your application.
+
+<details>
+  <summary>How it works</summary>
+
+[(Source on Confluence)](https://financialtimes.atlassian.net/wiki/spaces/ADS/pages/8151990292/New+Consent+Migration+Guide+for+teams#What-happens-when-a-user-visits-%5BinlineCard%5D--in-the-new-consent-framework%3F)
+
+![CMP Client Overview](docs/overview.jpg)
+
+</details>
+
+## Installation
+
+Install as a \<script> tag (**recommended**):
+
+```copy
+<script async src="https://consent-notice.ft.com/cmp.js"></script>
+```
+
+Install the library from NPM:
+
+```copy
+npm install @financial-times/cmp-client
+```
+
+## Using the script tag
+
+The `src` attribute of the `script` tag points to an immediately invoked function expression (IIFE) that sets up the CMP client on the host page. When the CMP client is installed this way, no additional work needs to be done.
+
+The primary benefit of using this integration method is that your users will automatically get new updates to the CMP client as soon as they are available, as opposed to requiring a version bump and application release. However, for this method to work successfully, the host page must be one of our [registered properties](#available-properties-constantly-being-updated). Please reach out to the Ads & Privacy team if you are not sure or you would like to register a property.
+
+By default the source link integrates the latest version of the CMP client. If you would like to pin a different version, you can append a `version` query parameter to the source link as follows:
+
+```copy
+<script async src="https://consent-notice.ft.com/cmp.js?version=4.0.0"></script>
+```
+
+## Using the NPM package
+
+> [!Note]
+> We will be adding new properties (i.e. websites under FT group) and their configs as we start rolling out.
+>
+> Please reach out to the Ads & Privacy team if you think your domain needs a new property config
+
+### Usage on non-FT.com properties
+
+```js
+import {
+  initSourcepointCmp,
+  properties,
+  interceptManageCookiesLinks,
+  debug,
+} from "@financial-times/cmp-client";
+
+/**
+ * Optionally enable debug mode to see CMP events in the console
+ */
+debug.logCmpEvents();
+
+/**
+ * Import your domain's CMP configuration from the `properties` module:
+ * e.g. properties.MM_IGNITES_ASIA, properties.SP_THE_BANKER, etc.
+ *
+ * We will add more domains as we create new properties in Sourcepoint
+ *
+ * See below for the full list of initialisation options
+ */
+initSourcepointCmp({
+  propertyConfig: properties["YOUR_PROPERTY_CONFIG_KEY"],
+  useConsentStore: false, // Specialist Titles _must_ opt out of Single Consent Store
+});
+/**
+ * Optionally enable "Manage Cookies" link util
+ */
+interceptManageCookiesLinks(properties["YOUR_PROPERTY_CONFIG_KEY"]);
+```
+
+### Usage on FT.com
+
+```js
+import {
+  initSourcepointCmp,
+  properties,
+  interceptManageCookiesLinks,
+  debug,
+} from "@financial-times/cmp-client";
+
+/**
+ * Optionally enable debug mode to see CMP events in the console
+ */
+debug.logCmpEvents();
+
+/**
+ * We suggest using a feature flag to disable the existing cookie banner
+ * and enable the new one
+ */
+if (flagsClient.get("adsDisableInternalCMP")) {
+  initSourcepointCmp({
+    propertyConfig: FT_DOTCOM_TEST,
+  });
+  interceptManageCookiesLinks();
+}
+```
+
+### CMP configuration options:
+
+<table>
+  <thead>
+    <tr>
+      <th>Option</th>
+      <th>Description</th>
+    </tr>
+  <thead/>
+  <tbody>
+    <tr>
+      <td><code>propertyConfig</code> (SourcepointConfig)</td>
+      <td>This config object is directly passed to Sourcepoint (our external CMP) and presets (imported like example usage) will be made available for different properties/titles under the FT group. This currently defaults to the <code>FT_DOTCOM_PROD</code> preset</td>
+    </tr>
+    <tr>
+      <td><code>userId</code> (string)</td>
+      <td>Please provide a userId if the user is a logged in user. If your app uses the FT Secure Session token, you can leave empty and set <code>useFTSession</code> to true instead. Defaults to <code>undefined</code> for anonymous users</td>
+    </tr>
+    <tr>
+      <td><code>useFTSession</code> (boolean)</td>
+      <td>Set this flag if you want the user's Id to be automatically derived from their FT Secure Session. Set to <code>false</code> if your app doesn't use FT Secure Session. Defaults to <code>true</code></td>
+    </tr>
+    <tr>
+      <td><code>consentProxyHost</code> (string)</td>
+      <td>The fully qualified domain name for your consent proxy instance e.g <code>https://consent.thebanker.com</code>. Defaults to <code>https://consent.ft.com</code></td>
+    </tr>
+    <tr>
+      <td><code>cookieDomain</code> (string)</td>
+      <td>The domain (and subdomains) that the FTConsent cookie will apply to e.g <code>.thebanker.com</code>. Defaults to <code>.ft.com</code></td>
+    </tr>
+    <tr>
+      <td><code>formOfWordsId</code> (string)</td>
+      <td>The IAB custom categories that you have adapted might be tracked under a different FOW ID. At the moment, all custom categories are tracked under the <code>sourcepointCmp</code> form-of-words and it defaults to <code>sourcepointCmp/VngD.XycZut.595cp9fWdp5XYP9vlFvk</code>. Properties using the consent banner as presented should use the default value</td>
+    </tr>
+    <tr>
+      <td><code>useConsentStore</code> (boolean)</td>
+      <td>Specifies whether the user's consent record should also be backed by the Single Consent Store. Properties like Specialist titles will need to explicitly set this to <code>false</code> as <code>true</code> is the default behavior</td>
+    </tr>
+    <tr>
+      <td><code>disableFTCookies</code> (boolean)</td>
+      <td>Specifies whether the user's consent record should be saved to FT Cookies. Properties like Specialist titles that don't utilize FT cookies will need to explicitly set this to <code>true</code> as <code>false</code> is the default behavior</td>
+    </tr>
+    <tr>
+      <td><code>events</code> (object)</td>
+      <td>Used internally to define handlers for events emitted by the Vendor-supplied CMP module. See notes on "Responding to CMP events" below for details on how to define custom event handlers</td>
+    </tr>
+  </tbody>
+<table/>
+
+### Available Properties (constantly being updated)
+
+<table>
+  <thead>
+    <tr>
+      <th>Property Key</th>
+      <th>Details</th>
+    </tr>
+  <thead/>
+  <tbody>
+    <tr>
+      <td><code>FT_DOTCOM_TEST</code></td>
+      <td>
+        <p>Use this configuration preset for testing the CMP on a property that has not yet been registered in the Sourcepoint portal.</p>
+        <p>All <code>*.ft.com</code> are currently registered and this config will spoof your request as coming from <code>https://local.ft.com</code>
+        </p>
+      </td>
+    </tr>
+    <tr>
+      <td><code>FT_DOTCOM_PROD</code></td>
+      <td>Configuration preset for all properties on FT.com domain operating in a production environment - <code>https://*.ft.com</code></td>
+    </tr>
+    <tr>
+      <td><code>SP_THE_BANKER</code></td>
+      <td>Configuration preset for properties on thebanker.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_PWMNET</code></td>
+      <td>Configuration preset for properties on pwmnet.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_FDI_INTELLIGENCE</code></td>
+      <td>Configuration preset for properties on fdiintelligence.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_BANKING_RR</code></td>
+      <td>Configuration preset for properties on bankingriskandregulation.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_SUSTAINABLE_VIEWS</code></td>
+      <td>Configuration preset for properties on sustainableviews.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_FT_ADVISER</code></td>
+      <td>Configuration preset for properties on ftadviser.com domain</td>
+    </tr>
+    <tr>
+      <td><code>SP_INVESTORS_CHRONICLE</code></td>
+      <td>Configuration preset for properties on investorschronicle.co.uk domain</td>
+    </tr>
+    <tr>
+      <td><code>MM_IGNITES_ASIA</code></td>
+      <td>Configuration preset for properties on ignitesasia.com domain</td>
+    </tr>
+    <tr>
+      <td><code>MM_IGNITES_EUROPE</code></td>
+      <td>Configuration preset for properties on igniteseurope.com domain</td>
+    </tr>
+  </tbody>
+<table/>
+
+## Responding to CMP events
+
+If you need to do additional work in response to events emitted by the CMP Vendor module – e.g. initialising vendor packages that match the purposes granted by the user – you can do so via the `window._sp_.addEventListener` method:
+
+```js
+window._sp_.addEventListener("onMessageReady", (messageType) => {... });
+window._sp_.addEventListener("onConsentReady", (legislation, consentUUID, consentString, consentMeta) => { ... });
+```
+
+> [!Note]
+> The `onConsentReady` event is fired
+>
+> 1. As soon as the CMP has finished loading and the user's consent choices are available
+> 1. Subsequently, whenever the user's consent choices change
+
+See the [Sourcepoint docs](https://docs.sourcepoint.com/hc/en-us/articles/4412176150035-Queue-event-callbacks) for a full listing of the events you can listen for and the arguments passed to the callbacks.
+
+## Debugging
+
+You can verify that the CMP is correctly configured using the `logCmpEvents` method exported from the `debug` module:
+
+```js
+import { debug } from "@financial-times/cmp-client";
+
+debug.logCmpEvents();
+```
+
+If everything's working then you'll see the CMP Module log its lifecycle events to the console, _even if its UI isn't displayed_.
+
+This can easily happen when you've made a previous consent choice and the CMP is now picking it up from local storage. For this reason we recommend running in an incognito window during development.
+
+> [!Note]
+> Please ensure that your app always uses the latest version of the CMP Client library.
+>
+> You can check the version your live app is using by running the following in the browser console:
+>
+> ```copy
+> window.FT_CMP_CLIENT_VERSION
+> ```
+
+## Development
+
+If you have access to the source on Github you can take a look at [the reference implementations in `src/examples/cmp-client`](https://github.com/Financial-Times/privacy/tree/main/src/examples).
+
+To see a demo in action in your browser, run:
+
+```copy
+npm run dev -w src/examples/cmp-client
+```
+
+Visit https://localhost:5173 (see setup details in `src/examples/cmp-client`) to interact with the banner and see how cookies are set accordingly
+
+> For resetting your consent cookies/record and other common troubleshooting issues, see the [Troubleshooting Guide](./docs/troubleshooting.md)
+
+#### Resources
+
+For a detailed deep-dive (internal only) of how the static deployment process works, the design is [documented here](https://financialtimes.atlassian.net/wiki/spaces/ADS/pages/8293711881/How+the+CMP+static+loader+works). If you need to be granted access, please reach out to the Ads & Privacy team.