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

package/README.md

@@ -0,0 +1,195 @@
+# CMP Client
+
+A client-side package 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 the package from npm:
+
+```copy
+npm install @financial-times/cmp-client
+```
+
+## Usage
+
+```js
+import { initSourcepointCmp } from "@financial-times/cmp-client/client";
+import { FT_DOTCOM_TEST } from "@financial-times/cmp-client/properties";
+
+// 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,
+    // useConsentStore: false (set to false for non-FT.com properties or websites)
+  });
+}
+```
+
+We will be adding new properties (websites under FT group) and their configs as we start rolling out. Please reach out to the Ads & Privacy team if you think you need to create a new property for your domain - for example, if it is on a different domain from the `ft.com` domain.
+
+### 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>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 package.
+>
+> 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