@schibsted/account-sdk-browser 5.2.7 → 5.3.0

package/README.md

@@ -124,6 +124,84 @@ function userClicksLogIn() {
 }
 ```
 
+#### Forward consents to Account
+
+The SDK forwards the user's current consents to Schibsted account in every login URL. The consents are
+read by a `getConsents` reader, which returns them serialized as `URLSearchParams`; the SDK appends them
+to the login URL as they are. The reader is called synchronously every time a login URL is created, so it
+must return the current state immediately instead of waiting for the consent dialog.
+`login()` and `loginUrl()` stay synchronous; a login started before the user answers the dialog
+(e.g. from the dialog itself) continues without consents.
+
+Login links rendered before the user answered the consent dialog are refreshed when they are clicked:
+the SDK listens to clicks on the document and updates the consents of `<a>` elements that point to its
+own login URL. Links inside iframes and URLs opened with `window.open()` are not refreshed;
+create the URL at the time of the user's action if that matters.
+
+##### Schibsted sites
+
+By default, consents are read from the Schibsted Sourcepoint integration (`window._tcf_` or
+`window._scc_`), so Schibsted sites forward consents out of the box, without any configuration:
+
+```javascript
+const identity = new Identity({
+    clientId: '56e9a5d1eee0000000000000',
+    redirectUri: 'https://awesomenews.site',
+    sessionDomain: 'https://id.awesomenews.site',
+    // Optional: opt out of refreshing rendered login links
+    refreshLoginLinks: false,
+});
+```
+
+##### Other CMPs
+
+Sites without the Schibsted Sourcepoint integration pass their own reader:
+
+```javascript
+const identity = new Identity({
+    clientId: '56e9a5d1eee0000000000000',
+    redirectUri: 'https://awesomenews.site',
+    sessionDomain: 'https://id.awesomenews.site',
+    // Reads the decision of your CMP, see the interface below
+    getConsents: readConsentsFromMyCmp,
+});
+```
+
+Use `getConsents: () => null` to forward no consents.
+
+##### The `getConsents` interface
+
+```typescript
+type ConsentReader = () => URLSearchParams | null;
+```
+
+A reader must:
+
+- **Be synchronous.** Return the decision the CMP already has, e.g. from its in-memory state or its
+  stored consent cookie. Do not return a `Promise` or wait for the consent dialog.
+- **Return `URLSearchParams` or `null`.** `null` or empty params mean the decision is unknown, and no consent
+  parameters are added. The SDK logs any other return value and any thrown error, and the login continues
+  without consents.
+- **Return only consent parameters.** Every key it returns is added to the login URL. When a rendered
+  link is refreshed, those keys replace the values already on it, so do not return OAuth parameters such
+  as `state` or `redirect_uri`. Repeated keys (e.g. `purpose=a&purpose=b`) are kept.
+
+Return these parameters (format `v1`, the only supported version):
+
+| Parameter         | Value                                                                                  |
+|-------------------|----------------------------------------------------------------------------------------|
+| `consents`        | Alphabetically sorted, comma-separated purposes the user granted, or `rejected` if the user rejected all of them. Purposes: `advertising`, `analytics`, `marketing`, `personalisation` |
+| `consent_version` | Version of this parameter format; always `v1`                                          |
+
+Examples of serialized params returned by a reader:
+
+| User's decision                       | Returned `URLSearchParams` (serialized)             |
+|---------------------------------------|-----------------------------------------------------|
+| Granted advertising and analytics     | `consents=advertising%2Canalytics&consent_version=v1` |
+| Granted analytics only                | `consents=analytics&consent_version=v1`             |
+| Rejected all purposes                 | `consents=rejected&consent_version=v1`              |
+| Not answered yet                      | `null` (or empty `URLSearchParams`)                 |
+
 #### Regarding `state`
 
 This parameter is an OpenID Connect parameter (described in [this paragraph in the
@@ -310,6 +388,12 @@ browser side. Nevertheless, here is a short description of them.
     * `referer` (yep, missing the double "rr"..): If this is missing, a call to hassession will
       return a `401` with a `UserException` that says `No session found`.
 
+## Development
+
+Dependencies are installed from [Schibsted Artifactory](https://artifactory.schibsted.io) (see [`.npmrc`](./.npmrc)),
+so npm must be authenticated to it before `npm install`. The private `@schibsted/consent-url-utils` package is
+bundled into `src/vendor/` on install (`npm run vendor`), so the published SDK does not depend on it.
+
 ## Publishing
 
 Versioning and changelog are handled by [Release Please (GitHub Action)](https://github.com/googleapis/release-please). Publishing to [npmjs.org](https://www.npmjs.com/package/@schibsted/account-sdk-browser) is handled by the [npm-publish workflow](./.github/workflows/npm-publish.yml). See the [Release Please workflow](./.github/workflows/release-please.yml) and [`release-please-config.json`](./release-please-config.json).