@thg-agentic/hyper-personalisation-web 3.22.0 → 3.23.0

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.15, stamped on every event as `context.spec.version`) for any storefront: it
+specification (spec 1.18, 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.
 
@@ -53,6 +53,7 @@ collects, is a settings change and never a deploy:
 | `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. |
+| `onsite` | The live onsite forms (`{ forms, capture }`): triggers, pages, caps, consent texts (an SMS one for a form that collects texts), prize labels. Never creatives or odds. Used only by a page that passes `onsite`; see [Onsite forms](#onsite-forms). |
 | `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. |
 
 **The page configures only what the page knows** (the second argument):
@@ -73,6 +74,7 @@ collects, is a settings change and never a deploy:
 | `debug` | Log every event and delivery problem. Also on when the settings' `debug` says so. |
 | `settings` | Development and tests only: use this settings response, never fetch or cache one. |
 | `extend` | `createAnalytics` options that are functions, such as `getRecommendations` or `getExtensions`. |
+| `onsite` | `true`, or the onsite options: start [onsite forms](#onsite-forms) when the settings have a live one. Absent: the runtime is never loaded. |
 
 What `bootstrap` does:
 
@@ -85,7 +87,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
@@ -204,7 +209,7 @@ 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` | 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)). |
@@ -329,6 +334,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
@@ -338,13 +348,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
@@ -353,20 +357,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.
@@ -473,6 +485,145 @@ const badges = await proof.forProducts(['123', '456']); // GET /v1/social-proof,
 It sends the key and `hp-consent` itself; `propertyId` is needed only for a key scoped to several
 properties.
 
+## Onsite forms
+
+Sign-up popups, sheets, bars, teasers, inline forms and spin-to-win
+([ADR 0064](../../docs/architecture/decisions/0064-onsite-capture.md)). Built dark: nothing shows
+until a form is set live in the console. One line on the host:
+
+```js
+const hp = await bootstrap({ writeKey: 'hp_pk_live_…' }, { consent: { provider: 'onetrust' }, onsite: true });
+```
+
+With `onsite` set and a live form in the settings' `hp.onsite`, bootstrap loads `./onsite` as a
+separate chunk and starts it; otherwise it is never fetched. A page on `createAnalytics` starts it
+itself: `import { startOnsite } from '@thg-agentic/hyper-personalisation-web/onsite'` then
+`startOnsite(client, options)`. On the CDN, `hp.min.js` loads `onsite.min.js` (and that loads
+`onsite-render.min.js` once a trigger fires, `onsite-wheel.min.js` for a wheel,
+`onsite-answers.min.js` for a date or number question) from beside itself; a self-hosted copy keeps
+all four beside `hp.min.js`. The runtime watches triggers, caps and consent and asks for the
+decision; the renderer and its stylesheet are fetched only when a trigger fires, alongside the
+decision request, so a page whose forms never fire never downloads them. If the renderer cannot
+load, the form is not shown (`hp.onsite.debug()` says `the renderer did not load`) and the page goes
+on. A bundler splits `./onsite`, the renderer, the wheel and the answers the same way.
+
+**Layout stability.** A form moving to a shorter step (the thanks after a slow sign-up) keeps the
+card's size, its content centred, so nothing on screen moves under the shopper; a taller step still
+grows. An image with `widths` (the smaller copies the console's upload made, at `-<w>w.webp`) is a
+`srcset` with the original at its `width`, and `sizes` for where it shows: the whole screen under
+640px, else the card's width (46% of it beside a split).
+
+
+**Questions.** A choice (`one`, `many`) shows as buttons, a list of radio buttons or checkboxes, or
+a dropdown, as its question block's `display` says (a multiple choice is never a dropdown). A
+`date` question is a birthday's day and month selects and, when asked, a year field, in the order
+and month names of the form's `locale` (the page's `lang` when the form has none); or the browser's
+own date field for any other date. A `number` question is a text field with a numeric keyboard and
+its unit. A half-filled date, or a number out of the question's bounds or the gateway's limits (ten
+digits, at most a billion either way), is the shopper's to correct before the step moves on; the
+gateway checks every answer again. Answers are stored as option values, `YYYY-MM-DD` or `--MM-DD`,
+and digits. A form that asks a date or a number loads their fields once, as it mounts; if they
+cannot load, the question says it is not available and the form goes on without that answer (every
+question is optional). A phone field's country code starts on the block's `country`, else the
+region of the form's `locale`.
+
+**How a form shows.** The browser judges the trigger; the server decides the rest. Each live form's
+trigger is watched: `entry` (`delay_ms`), `exit`, `scroll` (`depth`), `time` and `idle`
+(`seconds`), `inline` (rendered into `selector`) and `manual` (`hp.onsite.open(slot)`). Exit intent
+on desktop arms after `delay_ms` (5 s) and once the pointer has been below the top tenth of the
+viewport, and fires when it leaves through the top edge, moving up. On mobile it is a fast upward
+flick (120px at 0.5 px/ms) after 30% of the page, or a return to the tab after 10 s away. Pages
+(include/exclude globs on the path, `*` matching anything, in any case), devices (`mobile` is a coarse pointer
+or under 768px), dates and caps are checked first; then `POST /v1/decisions` is asked for that one
+slot. A held-out visitor, or no decision, sees nothing. One overlay per page view: of the forms that
+fire within 50 ms, the highest `priority`. With the property's `overlay_gap_minutes`, no popup, sheet or full-screen form
+shows until that long after the last one this session (1440 is once per session); bars, teasers and
+inline forms are never held back. A form with `audiences` needs personalisation consent.
+
+| Option | |
+|---|---|
+| `audiences()` | The visitor's session audiences, when the page evaluates them: a form targeting none of them is skipped. Without it the server decides. |
+| `subscribed()` | True for a visitor the page knows is subscribed, for forms with `exclude_subscribed`. |
+| `servingHost`, `gatewayHost` | Where decisions and claims go (default: the host the SDK was pointed at) and capture goes (default: where events go). |
+| `debug` | Log why each form did or did not show. Also on with `?hp_debug=onsite`. |
+| `settings` | Development and tests: these forms instead of the settings'. |
+
+`hp.onsite.debug()` returns each form's state and reasons (`armed`, `not eligible: per_session cap`,
+`held out`, `shown`, …).
+
+| `hp.onsite` | |
+|---|---|
+| `open(slot)`, `show(slot)` | Show a form now, past its trigger; resolves with whether it showed. |
+| `on(name, fn)` | `shown`, `submitted`, `apply` or `closed`, with `{ slot, arm, format }`; `submitted` and `apply` add `coupon` (`{ code, prize }` or `null`), `closed` adds `reason`. A form with prizes says `submitted` once, when its claim settles: with the code, or `null` if the claim failed. Returns a function that stops listening. A throwing listener is logged, never breaks the form. |
+| `suppress(reason)`, `unsuppress(reason?)` | Take any form off the screen quietly (not a dismissal) and keep forms away while any reason holds; `unsuppress()` lifts all. |
+
+**Formats.** A `teaser` is a tab (its first step) that opens the rest as a popup; the tab is kept on
+the session's later pages until opened or dismissed, and never traps focus. A `bar` with a
+`progress` block is a basket bar: free-delivery progress from the basket value the SDK keeps from
+`cartUpdated`, not shown for an empty basket. A `code` block on a first step is a promo reminder,
+shown only with a code to remind of (the decision's `offer.code`, or the code this browser claimed,
+kept 14 days); its `apply` button emits `apply`. `inline` renders into the trigger's `selector`, a
+tile among products. Steps take a `layout` template (`stack`, `split`, `overlay`, `image-only`) with
+image or muted, looping video media; see ADR 0064.
+
+**Preview.** `?hp_preview=<token>` asks `POST /v1/decisions` for the previewed version and counts
+nothing. For an editor, `import { mountPreview } from
+'@thg-agentic/hyper-personalisation-web/onsite/preview'`; `mountPreview(host, creative, { step,
+device: 'desktop' | 'mobile', consentText, smsConsentText, questions, prizes, basketValue })` draws the creative
+inside `host` with no request, event or counter, and returns `{ update(creative, options), destroy(),
+step() }`. It is not part of the runtime chunk.
+
+**Rendering.** A shadow root on an `<hp-onsite>` element. Popup and fullscreen are a native
+`<dialog>` opened with `showModal()` (focus trap, inert page, Esc, focus restore); sheet, bar and
+teaser are non-modal (focus stays on the page); inline renders into the page's element and never
+takes focus or scrolls the page. The close button is always there, and every control is at least 44px
+to touch. Button text is dark or white, whichever contrasts more with the accent.
+Text is the creative's RichText, built with DOM APIs only (text, bold, italic, https links), never
+`innerHTML`. Under 640px a popup is a bottom sheet with a drag handle (drag down to close) and a split stacks;
+`prefers-reduced-motion` stops the animation, video autoplay and the wheel's spin; a video pauses
+while the page is hidden.
+
+**Capture.** On submit the form fetches `GET /v1/capture/challenge` (started on the field's first
+focus), solves the ALTCHA proof of work in a Worker made from a Blob (the main thread, yielding,
+where a CSP refuses one), and posts `POST /v1/capture` to the ingest gateway with the address, the
+consent text's id and version (`sms_consent_text` for a phone number, `consent_text` otherwise; a
+consent block shows the same one), any answers and the decision. The field is emptied; only the receipt
+is kept, in memory, for a spin's `POST /v1/offers/claim` (with the decision id when there is one;
+a 503 is retried twice, after 0.5 s and 1.5 s). A question answered on a later step is posted to
+`POST /v1/capture/answers` with the email step's address and receipt, for the destinations and
+`Preferences Stated`; the address and receipt are kept only while the form is open. When every prize's codes are gone the form shows the
+creative's `fallback` step, else a plain thanks, with no countdown and nothing to copy. Allow `blob:` in `worker-src` for the
+Worker.
+
+**Events**, each only with analytics consent, and none while previewing:
+
+| When | Event |
+|---|---|
+| The form renders, or a held-out visitor's trigger fires | `Personalisation Exposed` (surface `decisions`, from the decisions response) |
+| A sign-up succeeds | `Slot Engaged` `{ engagement: 'submit', step }`. The gateway sends `Newsletter Subscribed`, and `Preferences Stated` for answers sent with it |
+| A question is answered after the sign-up | Sent by the gateway with `POST /v1/capture/answers` after an email step; otherwise `Preferences Stated` `{ source: 'onsite' }` from the page |
+| Closed, Esc or declined before a sign-up | `Slot Engaged` `{ engagement: 'dismiss', step }` |
+| A link button is clicked | `Slot Engaged` `{ engagement: 'click' }` |
+
+The sign-up itself is sent whatever the analytics answer: it is the visitor's marketing consent.
+
+**Privacy.** No contact data is kept in the browser. The caps are opaque counters per slot under
+`storageNames.onsite` (`thg_hp_onsite`): shows this session (sessionStorage), and shows ever, last
+close and submitted, plus one subscribed flag and the last claimed code (localStorage), and a
+kept teaser tab (sessionStorage).
+
+**Budgets**, enforced by `tests/onsite-chunks.test.mjs`, each about 5% over its chunk:
+`onsite.min.js` under 5.875 KiB gzipped (about 5.6 KiB), `onsite-render.min.js` under 14 KiB (about
+13.7 KiB), so a page that shows a form loads about 19 KiB of onsite code and one whose forms never
+fire about 5.6 KiB; `onsite-wheel.min.js` under 8 KiB (about 1.3 KiB), `onsite-answers.min.js` under
+2 KiB (about 1.5 KiB). The core carries only the loader.
+
+Try it locally: `node tools/local/serve.mjs`, then
+`http://localhost:8099/onsite.html?hp_debug=onsite` (offline mocks by default, `?mode=live` for
+the local gateway and public API). `?example=<name>` shows one example creative from
+`tools/local/testpage/onsite-examples.js` (hero, split, gif, spin, teaser, bar, sheet, gate, sms,
+exit, inline, basket, promo, fullscreen), with local images under `testpage/media/`.
+
 ## Consent
 
 With a `consent` adapter the SDK is strict:
@@ -503,6 +654,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
@@ -527,7 +682,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 |
 
@@ -838,6 +993,7 @@ SDK per page.
 | `session` | `thg_hp_session` | cookie, one per browser | the session id the SDK keeps when you name none, 30 minutes from the last event; only under a grant (3.15, see [Session ids](#session-ids)) |
 | `preview` | `thg_hp_preview` | session cookie | a trader's preview token from `?hp_preview=` (3.15, see [Preview](#preview)) |
 | `debug` | `thg_hp_debug` | sessionStorage | a developer's debug token from `?hp_debug=` (3.18), checked against the settings on every page |
+| `onsite` | `thg_hp_onsite:<property>` | localStorage, sessionStorage | onsite forms' opaque counters per slot and a subscribed flag; never contact data (see [Onsite forms](#onsite-forms)) |
 | — | `thg_hp_conformance_page_type` | sessionStorage | the previous page's type, only while the development-only conformance checker runs |
 
 Keys are scoped by property because one origin can serve several tenants. The names the SDK used