@thg-agentic/hyper-personalisation-web 3.19.0 → 3.22.2

package/README.md

@@ -1,7 +1,7 @@
 # @thg-agentic/hyper-personalisation-web
 
 The browser SDK for THG Hyper-Personalisation, a customer data platform. It implements the event
-specification (spec 1.10, stamped on every event as `context.spec.version`) for any storefront: it
+specification (spec 1.16, stamped on every event as `context.spec.version`) for any storefront: it
 sends events in the Segment wire format, applies consent strictly whichever CMP the site uses, reads
 the GA4 `dataLayer` the site already pushes to, and has no runtime dependencies.
 
@@ -45,12 +45,12 @@ collects, is a settings change and never a deploy:
 | From the settings (`hp`) | |
 |---|---|
 | `enabled` | Anything but `true` leaves the SDK off: no events, no cookie, nothing stored. |
-| `propertyId` | `context.source.property_id`. Null for a key scoped to several properties; the page then passes `propertyId`. |
+| `propertyId` | `context.source.property_id`: the source's default property. A `propertyId` the page passes wins over it (since 3.20); a key scoped to several properties with no default needs one. |
 | `environment` | `context.source.environment`. |
 | `consent.purposes` | The purposes the property asks for. Only those are reported; the rest read as unanswered. Strict is the only mode. |
 | `queryParamAllowlist` | Query parameters kept on page URLs (plus campaign parameters). |
 | `anonymousId` | Where device ids come from, chosen per source in the console (since 3.6): `{ source: 'site_cookie', cookie }` or `{ source: 'hp_cookie' }`. See [Device ids](#device-ids). |
-| `apiHost` | Where events go, when not the host the settings came from. |
+| `apiHost` | Where events go when the page set no `apiHost` (an `https://` host only). A page's own `apiHost` is a proxy and carries events too (since 3.20). |
 | `plan.track` | Segment's tracking plan: an event with `enabled: false` is dropped at the source. The console's blocked events arrive here. |
 | `sampleRate` | The share of visitors events are sent for, by a hash of the anonymous id (since 3.18). Absent: 1. |
 | `debug` | `{ enabled, tokenSha256 }`: console logging for everyone, or for a session opened with `?hp_debug=<token>` whose SHA-256 is `tokenSha256` (since 3.18). `?hp_debug=` ends it. |
@@ -85,7 +85,10 @@ What `bootstrap` does:
   and an `ETag`, so the browser revalidates for a `304`). A key the API switches off clears the cache, so the next page is
   off too.
 - **Consent**, identity, one page view, the dataLayer bridge and a once-per-session `identify`, as
-  configured.
+  configured. A page restored from the back/forward cache runs no script again, so `bootstrap`
+  reads consent again, then sends its `back_forward` page view on `pageshow` and reports its lists
+  afresh (3.22.2). A host on `createAnalytics` sends that view itself: `page({ navigation_trigger:
+  'back_forward' })` on a `pageshow` whose `persisted` is true.
 - **Never waited for.** Call `hp` (`@thg-agentic/hyper-personalisation-web/hp`) from anywhere, at
   any time, and never await or flush it: calls made before the client starts wait, each with the
   messageId and time it was made at, and are sent in order once it has. The page view is stamped
@@ -189,7 +192,7 @@ Since 3.19 (spec 1.12), a search box's suggestions are their own event:
 
 | Option | Default | |
 |---|---|---|
-| `apiHost` | the HP API | Only for a first-party proxy. Events are POSTed to `${apiHost}/v1/batch`. |
+| `apiHost` | the HP API | Only for a first-party proxy. The settings and the events both go to it: events are POSTed to `${apiHost}/v1/batch` (since 3.20 a host in the settings never overrides it). |
 | `writeKey` | `'web'` | The source's publishable key, `hp_pk_…`. Sent in the batch body. |
 | `propertyId` | required | `context.source.property_id`. |
 | `channel`, `market`, `environment` | `null` | The rest of `context.source`. |
@@ -204,10 +207,10 @@ Since 3.19 (spec 1.12), a search box's suggestions are their own event:
 | `storageNames` | `thg_hp_*` | Rename what the SDK stores; see [Storage](#storage). |
 | `plan` | none | A Segment tracking plan, `{ track: { [event]: { enabled } } }`; `__default` covers unlisted events. |
 | `sampleRate` | `1` | The share of visitors to send for, by a hash of the anonymous id salted `hp_sample`; a visitor with no anonymous id is sent for. A consent withdrawal is always sent. Since 3.18. |
-| `queryParamAllowlist` | none | Keep only these query params (plus campaign params) in `context.page`. Patterns are anchored and case-insensitive. |
+| `queryParamAllowlist` | none | Keep only these query params (plus campaign params) in `context.page`, and in a clicked link's `href`, which leaves another site's link as origin and path only (3.22.2). Patterns are anchored and case-insensitive. |
 | `queryParamBlocklist` | `[]` | Strip these params. Ignored when an allowlist is given. |
 | `sensitiveParamAllowlist` | `[]` | Whatever else is configured, a param is always dropped from every reported URL when its name contains `email`, `token`, `password`, `secret`, `auth`, `session`, `phone`, `address`, `card`, `customerid` and the like (see `SENSITIVE_PARAM_FRAGMENTS` in `src/context.js`), or when its value is an email address or a card-length number — campaign params and the referrer included. This exempts names from the first rule, for a false positive such as an `author` filter; nothing exempts a value. |
-| `getAnonymousId`, `getUserId`, `getSessionId`, `getRenderId` | none | Identity accessors. Without `getSessionId` the SDK keeps its own session (see [Session ids](#session-ids)); a missing or empty device id gives way to the SDK's own (see [Device ids](#device-ids)). |
+| `getAnonymousId`, `getUserId`, `getSessionId` | none | Identity accessors. Without `getSessionId` the SDK keeps its own session (see [Session ids](#session-ids)); a missing or empty device id gives way to the SDK's own (see [Device ids](#device-ids)). |
 | `getExperiments`, `getAudiences`, `getDecisions`, `getRecommendations`, `getExtensions` | none | Read per event into the matching `context` field. Without `getDecisions`, `context.decisions` is what `recordExposure` last recorded per slot. |
 | `pageType` | `null` | `context.page.type` before the first `page()` call. |
 | `onEvent` | none | Observer for every event that will be sent. |
@@ -230,7 +233,7 @@ Declarations are in `types/`, and event properties are typed from the registry.
 - **One event is at most 55 KB** of JSON (3.19), so that it can always travel in a keepalive request
   at unload. A bigger one is not sent and its method returns null; with `debug` the SDK logs it.
   Segment's limit is 32 KB; this one is higher so that a long product list still fits.
-- **A sign-out forgets the visit** (3.19). `signedOut()`, or `reset()` while a user is signed in,
+- **A sign-out forgets the visit** (3.19). `signedOut()` (or `track('Signed Out')`, since 3.20), or `reset()` while a user is signed in,
   also forgets the SDK's session, the decisions in force and the recommendation context, so the
   next person on a shared device inherits none of them. `reset()` with nobody signed in changes
   nothing else, so a host that calls it on every page keeps its session. The SDK's own device id
@@ -245,9 +248,22 @@ Declarations are in `types/`, and event properties are typed from the registry.
   `Consent Updated` event. Before the client starts, `hp.recommendationContext()` reads the kept
   visit only when the consent cookie grants personalisation.
 - **Retries wait out `Retry-After`** on a 429 or 5xx (3.19), as well as backing off exponentially
-  with jitter, up to 30 seconds. The browser lets the SDK read the header only from a first-party
-  proxy for now: cross-origin it needs `Access-Control-Expose-Headers: Retry-After`, which the HP
-  ingest does not send yet. Without it the backoff alone applies.
+  with jitter, up to 30 seconds. Cross-origin, the HP ingest exposes the header to the page
+  (`Access-Control-Expose-Headers: Retry-After`, from the `ingest-gateway-v1.13.0` release);
+  a same-origin proxy needs nothing. Where the header cannot be read the backoff alone applies.
+- **A refusal sends only the withdrawal** (3.20): what was collected under the grant and not yet sent
+  is dropped, including batches already cut while one was on the wire.
+- **`identify` sends only the spec's traits** (3.20): `email_sha256` and `phone_sha256` (SHA-256 hex,
+  or base64 sent as hex), `accepts_marketing` (boolean), `gender` (string) and `created_at` (RFC 3339
+  date-time). Anything else, a raw `email` or `phone` included, is not sent; with `debug` the dropped
+  keys are logged.
+- **A listing must name its own `category`** (3.22): a Product List Viewed without one, and its
+  facets, no longer count as browsing (`listViews`, `browseViews`, `browseShare`), with or without
+  `browse_categories`, and product views after it credit no category page. Send `category` on every
+  category listing. See [Visit traits](#visit-traits).
+- **The tracking plan covers every call** (3.20): it is keyed as the gateway keys it, a track's
+  event name or otherwise the call's type (`page`, `identify`), so an allow-list that omits `page`
+  sends no page views. A consent withdrawal is sent whatever the plan says.
 
 ## Calling the serving API
 
@@ -316,6 +332,11 @@ render(body);
 hp.recordExposure(body);
 ```
 
+For a decisions response the exposure lists each slot's `decision_id`, which is what marks that
+decision shown (a click is a `Slot Engaged` with `engagement: 'click'` and the same `decision_id`).
+It is one event per response, so record it once the slots are rendered: a slot rendered below the
+fold counts as shown.
+
 Since 3.7, recording a decisions response also puts its decisions in force. Every later event in
 the browser session carries them as `context.decisions`, latest per slot, so a basket is credited
 to the slot shown before it. Send the session id your events carry as `session_id` on
@@ -325,13 +346,7 @@ to the slot shown before it. Send the session id your events carry as `session_i
 ### Server-side assignments
 
 A page your server rendered from `POST /v1/assignments` and cached per arm has no `decision_id` in
-it. Since 3.10, `hp.assignmentDecisionId({ slot, arm })` derives the one HP logged, synchronously,
-for that page's `Slot Engaged`:
-
-```js
-const decisionId = hp.assignmentDecisionId({ slot, arm });
-if (decisionId) hp.slotEngaged({ slot, arm, engagement: 'view', decision_id: decisionId });
-```
+it. Since 3.10, `hp.assignmentDecisionId({ slot, arm })` derives the one HP logged, synchronously.
 
 It reads the session cookie named in `identityCookies.sessionId`, else the visitor cookie
 (`identityCookies.anonymousId`), as your renderer forwards them to HP, so it answers once
@@ -340,20 +355,28 @@ with neither cookie. The id is `UUIDv5(ASSIGNMENT_DECISION_NAMESPACE, "<session>
 `assignmentDecisionId({ sessionId, slot, arm })` from the main entry computes it from values you
 pass, and the spec's `assignment/decision-id.json` has the vectors.
 
-Such a page also reports the property holdout's exposure itself, when the slot is on screen, for
-both groups. The answer's `hash` is `holdout` for a held-out visitor (cache that page apart from
-the `""` one); on any other page with a hash the visitor was treated. The exposure token is the
-assignment's derived id for the arm shown, control included. Since 3.13 the shares come from the
-property's settings when the exposure has none:
+Such a page reports the property holdout's exposure itself, when the slot is on screen, for both
+groups, and a `Slot Engaged` click when a link in the slot is clicked. The answer's `hash` is
+`holdout` for a held-out visitor (cache that page apart from the `""` one); on any other page with
+a hash the visitor was treated. The exposure token is the assignment's derived id for the arm
+shown, control included, and a held-out visitor's exposure names no decision. Since 3.13 the shares
+come from the property's settings when the exposure has none:
 
 ```js
 const token = hp.assignmentDecisionId({ slot, arm });
+const holdout = hash === 'holdout';
+// When the slot is on screen:
 hp.recordExposure({
   exposure: { token, surface: 'decisions', holdout },
   decisions: [holdout ? { slot, holdout: true } : { slot, arm, decision_id: token }],
 });
+// When a link in the slot is clicked:
+if (token && !holdout) hp.slotEngaged({ slot, arm, engagement: 'click', decision_id: token });
 ```
 
+The exposure is what marks the decision shown; the click is its reward. Slot Engaged's `view` is
+deprecated since spec 1.16: it repeated the exposure.
+
 A surface your server fetched from HP for the page, so the page never sees HP's answer, reports
 its exposure with `surfaceViewed` when it comes into view: a product rail your server asked HP for,
 which HP answers with its rail for a treated visitor and the site's own rail for a held-out one.
@@ -407,6 +430,25 @@ A session audience's rules name fields the SDK keeps for the visit, from the eve
 `categoryViews.<path>`, `categoryShare.<path>` and, since 3.18, `basketValue`. A field this build
 does not know fails its rule closed.
 
+`listViews`, `browseViews` and `browseShare` count category pages, as the warehouse does. A listing
+must send its own `category` (Product List Viewed); one without is not recorded. Since 3.22, pass
+the datafile's `browse_categories` as the fifth argument to `resolveAudiences` or
+`resolveAudienceMemberships`, and a listing counts only when the catalogue files products under its
+`category`, so a merchandising list (best sellers, new in, a sale) is never browsing interest:
+
+```js
+resolveAudienceMemberships(body.audiences, datafile.session_audiences, undefined, body.qualified_for, datafile.browse_categories);
+```
+
+Each trail entry is judged on the listing it came from, as the warehouse judges each event: two
+listings under one path, one a category and one a sale list, count once. Product views and adds
+credit the category page they were reached from, and a facet (Product List Filtered) counts only on
+the listing being browsed; the warehouse counts neither, so these two measures run a little ahead
+of it. Without `browse_categories` (a datafile that predates it, or a property whose catalogue is
+not served yet, when the field is absent), every listing that names a category counts. A visit
+recorded by an SDK before 3.22 has no listing categories, so with the list its earlier browsing
+drops out once.
+
 `basketValue` is the `value` of the last `cartUpdated` (Cart Updated), in that event's currency:
 the basket as your platform priced it. It is never summed from `productAdded` lines, whose prices
 can include tax where `value` does not. It is `null`, so every rule on it fails, until the visit
@@ -420,7 +462,7 @@ response's `audiences` and `qualified_for`, and the datafile's `session_audience
 `resolveAudienceMemberships` exactly as before:
 
 ```js
-const memberships = resolveAudienceMemberships(body.audiences, datafile.session_audiences, undefined, body.qualified_for);
+const memberships = resolveAudienceMemberships(body.audiences, datafile.session_audiences, undefined, body.qualified_for, datafile.browse_categories);
 ```
 
 A targetable visit audience may require an audience nobody may target. The server sends that base
@@ -471,6 +513,10 @@ With a `consent` adapter the SDK is strict:
 - **Changes nothing announces:** after the first answer, an adapter whose `subscribe` cannot see
   every change (a cookie adapter on a browser without the Cookie Store API, or your own adapter
   without `observesChanges: true`) is re-read every 2 seconds while the page is visible.
+- **Decisions made in another tab:** a CMP reports a change only in the tab where it was made
+  (OneTrust's `OnConsentChanged`, Didomi's `consent.changed`). Another tab already open applies
+  it at its next page load, as Segment's, RudderStack's and mParticle's OneTrust integrations and
+  Google Consent Mode do.
 
 - **Purposes the property does not ask for:** with the settings' `consent.purposes`, only the
   purposes listed as `true` are reported (analytics always is). The others read as unanswered in
@@ -495,7 +541,7 @@ All adapters are imported from `@thg-agentic/hyper-personalisation-web/consent`.
 | Adapter | Reads | Not answered while |
 |---|---|---|
 | `didomiConsent({ purposes })` | `Didomi.getCurrentUserStatus().purposes`, subscribed via `didomiEventListeners` / `consent.changed` | Didomi is not loaded, `shouldUserStatusBeCollected()` is true, or `isUserStatusPartial()` is true |
-| `oneTrustConsent({ groups, impliedConsent })` | `OnetrustActiveGroups`, else the `OptanonConsent` cookie's `groups=`; subscribed via `OneTrustGroupsUpdated`, `OptanonWrapper` and `OneTrust.OnConsentChanged` | The banner was never closed (`OptanonAlertBoxClosed`) and never interacted with (`interactionCount`) |
+| `oneTrustConsent({ groups, impliedConsent })` | The `OptanonConsent` cookie's `groups=`, else `OnetrustActiveGroups` before OneTrust has written it; subscribed via `OneTrustGroupsUpdated`, `OptanonWrapper` and `OneTrust.OnConsentChanged` | The banner was never closed (`OptanonAlertBoxClosed`) and never interacted with (`interactionCount`) |
 | `cookieConsent({ name, categories, parse, refusedValue, source, changeEvent })` | A first-party cookie your banner writes; subscribed via a `thg_hp_consent_change` window event (`changeEvent`) and Cookie Store `change` | The cookie is absent, or its value cannot be parsed |
 | `staticConsent(state)` | The state you pass, for sites with no CMP | Never |
 
@@ -855,8 +901,8 @@ memory), and a refusal deletes it. Before 3.15 such a site sent `session_id: nul
 
 ## CSP and proxying
 
-The SDK makes requests only to `apiHost` (the settings, and the events unless the settings name
-another host), so allow it in `connect-src`: `resolveApiHost(apiHost)` is that origin, the HP API
+The SDK makes requests only to `apiHost` (the settings and the events; without an `apiHost`, events
+go to the settings' host when they name one), so allow it in `connect-src`: `resolveApiHost(apiHost)` is that origin, the HP API
 (`DEFAULT_API_HOST`) when you set none. Since 3.18 that is `https://hp.thgingenuity.com`
 (`connect-src https://hp.thgingenuity.com`); 3.17 used HP's nonprod host and 3.16 and earlier a
 staging host that is being retired. Allow the CDN host in `script-src` too if you use the script. Call the API host directly rather than through a CDN proxy route: behind a proxy the ingest