@financial-times/cmp-client 2.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +87 -0
  2. package/package.json +50 -0
package/README.md ADDED
@@ -0,0 +1,87 @@
1
+ # CMP Client
2
+
3
+ A package to help you add a CMP (currently provided by Sourcepoint) to your application.
4
+
5
+ ## Installation
6
+
7
+ Install the package from npm:
8
+
9
+ ```copy
10
+ npm install @financial-times/cmp-client
11
+ ```
12
+
13
+ There are reference implementations that you can look at in `src/examples/cmp-client`.
14
+
15
+ To see a demo in action in your browser, run:
16
+
17
+ ```copy
18
+ npm run dev -w src/examples/cmp-client
19
+ ```
20
+
21
+ Visit https://localhost:5173 (see setup details in `src/examples/cmp-client`) to interact with the banner and see how cookies are set accordingly
22
+
23
+ ## Usage
24
+
25
+ ```js
26
+ import { initSourcepointCmp } from "@financial-times/cmp-client/client";
27
+ import { FT_DOTCOM_LOCAL } from "@financial-times/cmp-client/properties";
28
+
29
+ // we suggest using a feature flag to disable the existing cookie banner and enable the new one
30
+ if (flagsClient.get("adsDisableInternalCMP")) {
31
+ initSourcepointCmp({
32
+ propertyConfig: FT_DOTCOM_LOCAL,
33
+ // useConsentStore: false (set to false e.g for non-FT.com properties or websites)
34
+ });
35
+ }
36
+ ```
37
+
38
+ We will be adding new properties 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 e.g it is on a different domain from the `ft.com` domain
39
+
40
+ ### CMP configuration options:
41
+
42
+ | Option | Description |
43
+ | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
44
+ | `propertyConfig` (SourcepointConfig) | 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 FT_DOTCOM_PROD preset |
45
+ | `userId` (string) | 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 `useFTSession` to true instead. Defaults to `undefined` for anonymous users |
46
+ | `useFTSession` (boolean) | Set this flag if you want the user's Id to be automatically derived from their FT Secure Session . Defaults to `true` |
47
+ | `consentProxyHost` (string) | The fully qualified domain name for your consent proxy instance e.g `https://consent.thebanker.com`. Defaults to `https://consent.ft.com` |
48
+ | `cookieDomain` (string) | The domain (and subdomains) that the FTConsent cookie will apply to e.g `.thebanker.com`. Defaults to `.ft.com` |
49
+ | `formOfWordsId` (string) | 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 `sourcepointCmp` form-of-words and its ID is default value |
50
+ | `useConsentStore` (boolean) | 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 `false` as `true` is the default behavior |
51
+
52
+ ### Available Properties (constantly being updated)
53
+
54
+ | Property Key | Details |
55
+ | ----------------- | ------------------------------------------------------------------------------------------------------------------- |
56
+ | `FT_DOTCOM_LOCAL` | Configuration preset for all properties on FT.com domain operating in a local environment - `https://local.ft.com` |
57
+ | `FT_DOTCOM_PROD` | Configuration preset for all properties on FT.com domain operating in a production environment - `https://*.ft.com` |
58
+
59
+ ## Consent Banner scripts only
60
+
61
+ If you only want the scripts to setup the consent banner for your page with interacting without interacting with the FT's consent APIs, the package also exposes a `getCmpScripts` method, which returns a `DocumentFragment` containing block of scripts that you can to your page's `<head>` element.
62
+
63
+ ```js
64
+ import { getCmpScripts } from "@financial-times/cmp-client/client";
65
+ import { FT_DOTCOM_LOCAL } from "@financial-times/cmp-client/properties";
66
+
67
+ const cmpScripts = getCmpScripts(FT_DOTCOM_LOCAL);
68
+ document.head.appendChild(cmpScripts);
69
+ ```
70
+
71
+ ## Debugging
72
+
73
+ You can verify that the CMP is correctly configured by adding an `events` map to your configuration: the `debug` module used in the examples provides a sample implementation:
74
+
75
+ ```js
76
+ import { getCmpScripts } from "@financial-times/cmp-client/client";
77
+ import { ft } from "@financial-times/cmp-client/properties";
78
+ import { events } from "@financial-times/cmp-client/debug";
79
+
80
+ // Merge the events map into the domain configuration
81
+ const config = { ...ft, events };
82
+ document.head.appendChild(getCmpScripts(config));
83
+ ```
84
+
85
+ If everything's working then when running the demo app you'll see the CMP log its lifecycle events to the console, _even if its UI isn't displayed_.
86
+
87
+ This can easily happen when you've made a previous consent choice and the CMP is now picking it up from local storage. We recommend running in an incognito window during development.
package/package.json ADDED
@@ -0,0 +1,50 @@
1
+ {
2
+ "name": "@financial-times/cmp-client",
3
+ "version": "2.0.2",
4
+ "private": false,
5
+ "type": "module",
6
+ "types": "./dist/types.d.ts",
7
+ "files": [
8
+ "dist"
9
+ ],
10
+ "exports": {
11
+ "./client": {
12
+ "import": "./dist/client.js",
13
+ "require": "./dist/client.cjs"
14
+ },
15
+ "./ssr": {
16
+ "import": "./dist/ssr.js",
17
+ "require": "./dist/ssr.cjs"
18
+ },
19
+ "./properties": {
20
+ "import": "./dist/properties.js",
21
+ "require": "./dist/properties.cjs"
22
+ },
23
+ "./debug": {
24
+ "import": "./dist/debug.js",
25
+ "require": "./dist/debug.cjs"
26
+ }
27
+ },
28
+ "dependencies": {
29
+ "@financial-times/privacy-utils": "file:../privacy-utils",
30
+ "next-session-client": "^5.0.0",
31
+ "react": "^18.2.0",
32
+ "react-dom": "^18.2.0"
33
+ },
34
+ "devDependencies": {
35
+ "@types/react": "^18.2.29",
36
+ "@types/react-dom": "^18.2.13",
37
+ "@vitejs/plugin-react": "^4.1.0",
38
+ "eslint": "^8.51.0",
39
+ "express": "^4.18.2",
40
+ "typescript": "^5.2.2",
41
+ "vite": "^4.5.0",
42
+ "vite-plugin-dts": "^3.6.0",
43
+ "vitest": "^0.34.6"
44
+ },
45
+ "scripts": {
46
+ "lint": "eslint . --ext js,jsx",
47
+ "build": "vite build",
48
+ "test": "echo 'noop'"
49
+ }
50
+ }