@thg-agentic/hyper-personalisation-web 3.25.0 → 3.26.0

package/src/onsite/api.js

@@ -1,8 +1,9 @@
 /**
- * The five calls a form makes, each authenticated with the page's publishable key and never with a
+ * The calls a form makes, each authenticated with the page's publishable key and never with a
  * cookie: `POST /v1/decisions` and `POST /v1/offers/claim` on the public API (with `hp-consent`, as
- * every serving request), `GET /v1/capture/challenge`, `POST /v1/capture` and
- * `POST /v1/capture/answers` on the ingest gateway.
+ * every serving request), `GET /v1/audiences/datafile` there for a form limited to audiences,
+ * `GET /v1/capture/challenge`, `POST /v1/capture` and `POST /v1/capture/answers` on the ingest
+ * gateway.
  * Every call resolves, to `{ status, body }` (status 0 when the network failed).
  */
 
@@ -16,6 +17,8 @@ const challengePath = (path) =>
 
 /** How long one claim request may take before it counts as failed. */
 const CLAIM_TIMEOUT_MS = 8000;
+/** How long a limited form waits for the audience datafile before it is decided without a claim. */
+const DATAFILE_TIMEOUT_MS = 1500;
 
 /**
  * @param {object} access What the client exposes to ./onsite (index.js, ONSITE_ACCESS).
@@ -57,8 +60,13 @@ export function createApi(access, options = {}) {
 	}
 
 	return {
-		/** The decision for one slot, as the page's other serving calls ask for it, with its pin. */
-		decide: (slot, pin) =>
+		/**
+		 * The decision for one slot, as the page's other serving calls ask for it, with its pin and
+		 * what the browser knows of the visit: for a form limited to audiences, `visitAudiences`, the
+		 * session audiences it meets; for a form that names a campaign, `visitCampaign`, the campaign
+		 * the visit arrived from. The server holds either form back unless its rules hold.
+		 */
+		decide: (slot, pin, { visitAudiences, visitCampaign } = {}) =>
 			call(`${serving}/v1/decisions`, {
 				method: 'POST',
 				consent: true,
@@ -73,9 +81,18 @@ export function createApi(access, options = {}) {
 					],
 					identifier_value: access.anonymousId() ?? undefined,
 					session_id: access.sessionId() ?? undefined,
+					// What a promo reminder's code is answered for under a publishable key (ADR 0067).
+					identity_token: access.identityToken?.() ?? undefined,
 					...(access.preview ? { preview: access.preview } : {}),
+					...(visitAudiences ? { visit_audiences: visitAudiences } : {}),
+					...(visitCampaign ? { visit_campaign: visitCampaign } : {}),
 				},
 			}),
+		/** The property's audience definitions: the same for everybody, so no consent header. */
+		datafile: () =>
+			call(`${serving}/v1/audiences/datafile`, {
+				timeoutMs: DATAFILE_TIMEOUT_MS,
+			}),
 		challenge: () => call(`${gateway}${challengePath(options.challenge)}`),
 		capture: (body) => call(`${gateway}/v1/capture`, { method: 'POST', body }),
 		// Answers given after the email step, with its address and receipt.

package/src/onsite/audiences-loader.js

@@ -0,0 +1,6 @@
+/**
+ * The session-rule evaluator, only for a form limited to audiences: a bundler splits this import
+ * out of ./onsite, and the CDN build swaps this module for cdn/audiences-loader.js, which loads
+ * dist/onsite-audiences.min.js.
+ */
+export const loadAudiences = () => import('./visit-audiences.js');

package/src/onsite/counters.js

@@ -2,8 +2,8 @@
  * What the caps count, per slot, as opaque numbers: shows this session (sessionStorage), and shows
  * ever, when it was last closed and whether it was submitted (localStorage), plus one subscribed
  * flag, whether a teaser's tab is out, when a covering form last showed and the version an A/B test
- * pinned for the visit (sessionStorage), and the
- * last code this browser claimed, for a promo reminder. Never an address, a number or an answer.
+ * pinned for the visit (sessionStorage), and the last code this browser claimed, for a promo
+ * reminder. Never an address, a number or an answer.
  * Every access is wrapped: without storage the caps hold for the page view only.
  *
  * The counts follow what the shopper did (saw, closed, signed up) and serve only the caps: UI

package/src/onsite/index.js

@@ -19,6 +19,7 @@
 
 import { loadAnswers } from './answers-loader.js';
 import { createApi } from './api.js';
+import { loadAudiences } from './audiences-loader.js';
 import { createCounters } from './counters.js';
 import { loadRender } from './render-loader.js';
 import {
@@ -63,6 +64,8 @@ const INERT = {
 	code: () => null,
 };
 
+/** The longest a limited form waits for the evaluator and the datafile before it is decided without. */
+const CLAIMS_MS = 1500;
 /** How long a fired trigger waits for others, so two forms entering together show the higher priority. */
 const FIRE_WINDOW_MS = 50;
 /** The longest a form waits for its first step's pictures before it opens without them. */
@@ -103,6 +106,13 @@ export function startOnsite(client, options = {}) {
 	const counters = access.preview
 		? INERT
 		: createCounters(access.storageKey, access.personalisation);
+	/**
+	 * The campaign this visit arrived from, the landing page's tags (GA4's session source, and the
+	 * warehouse's): kept for the visit from the first page that has them. A preview reads this page's
+	 * own, so a trader's test link shows the form its tags would.
+	 */
+	const campaign = () => access.campaign?.() ?? null;
+
 	const mounted = new Map();
 	const suppressed = () => window[SUPPRESSED]?.size > 0;
 
@@ -131,6 +141,18 @@ export function startOnsite(client, options = {}) {
 				reasons: ['not a form this SDK can show'],
 			});
 	}
+	/** The session-rule evaluator, for a limited form; null when its chunk cannot be loaded. */
+	const audiencesChunk = () =>
+		loadAudiences().catch((err) => {
+			console.warn('[hp] onsite audiences not loaded:', err?.message ?? err);
+			return null;
+		});
+	// Warmed with the datafile now, so a limited form that fires waits for neither.
+	if (
+		access.personalisation() &&
+		forms.some((form) => form.audiences.length > 0)
+	)
+		audiencesChunk().then((chunk) => chunk?.prefetch(api));
 	/**
 	 * The covering forms on screen or being opened, by slot (a bar and a popup the shopper asked for
 	 * can both be up), the slots being opened now, and the form that spent this page view's allowance.
@@ -199,6 +221,7 @@ export function startOnsite(client, options = {}) {
 	const env = (form) => ({
 		path: location.pathname,
 		device,
+		campaign: campaign(),
 		now: Date.now(),
 		seen: counters.seen(form.slot),
 		subscribed: counters.subscribed() || options.subscribed?.() === true,
@@ -285,7 +308,35 @@ export function startOnsite(client, options = {}) {
 			console.warn('[hp] onsite renderer not loaded:', err?.message ?? err);
 			return null;
 		});
-		const res = await api.decide(form.slot, counters.pin(form.slot));
+		// The server decides a limited form's audiences; the browser tells it which session rules hold,
+		// and which the page gave. Within CLAIMS_MS, else only the page's: the server decides from what
+		// it holds.
+		// The evaluator orders the page's own with the visit's (targets and what they require first);
+		// a fallback sends the page's alone, the form's targets first and capped at the server's 100.
+		const page = sessionAudiences() ?? [];
+		const given = [...new Set([...form.audiences, ...page])]
+			.filter((slug) => page.includes(slug))
+			.slice(0, 100);
+		const claimed =
+			form.audiences.length > 0 && !access.preview && access.personalisation()
+				? await Promise.race([
+						audiencesChunk().then((chunk) =>
+							chunk
+								? chunk.visitAudiences(
+										api,
+										access.sessionSignals,
+										form.audiences,
+										page,
+									)
+								: given,
+						),
+						new Promise((resolve) => setTimeout(resolve, CLAIMS_MS, given)),
+					])
+				: null;
+		const res = await api.decide(form.slot, counters.pin(form.slot), {
+			visitAudiences: claimed,
+			visitCampaign: form.arrived_from.length ? campaign() : null,
+		});
 		const decision =
 			res.status === 200
 				? res.body?.decisions?.find((d) => d?.slot === form.slot)

package/src/onsite/rules.js

@@ -3,6 +3,8 @@
  * counters, so the eligibility trace (`hp.onsite.debug()`) says exactly what decided.
  */
 
+import { arrivedFrom } from '../visit-campaign.js';
+
 export const FORMATS = [
 	'popup',
 	'sheet',
@@ -39,6 +41,11 @@ const strings = (v) =>
 	Array.isArray(v) ? v.filter((s) => typeof s === 'string') : [];
 const count = (v) => (Number.isInteger(v) && v >= 0 ? v : null);
 
+/** A rule no visit meets: what an `arrived_from` this SDK cannot read becomes, so it fails closed. */
+const NEVER = { field: null, match: null, values: [] };
+const arrivedRules = (raw) =>
+	raw == null ? [] : Array.isArray(raw) && raw.every(isObject) ? raw : [NEVER];
+
 /** A form from the settings as the runtime uses it, or null when it cannot be used. */
 export function readForm(raw) {
 	if (!isObject(raw) || typeof raw.slot !== 'string' || raw.slot === '')
@@ -55,6 +62,7 @@ export function readForm(raw) {
 		devices: strings(raw.devices),
 		aliases: strings(raw.aliases),
 		audiences: strings(raw.audiences),
+		arrived_from: arrivedRules(raw.arrived_from),
 		caps: {
 			per_session: count(caps.per_session),
 			lifetime: count(caps.lifetime),
@@ -123,25 +131,32 @@ const at = (iso) => (typeof iso === 'string' ? Date.parse(iso) : Number.NaN);
 /**
  * A form the site opens itself (`manual`: its own sign-up button) is the shopper asking for it, so
  * how often it has shown does not hold it back: no caps, gap or page view allowance, as Klaviyo's
- * custom-triggered forms ignore their frequency settings. Its pages, devices, dates and audiences
- * still do.
+ * custom-triggered forms ignore their frequency settings. Its pages, devices, campaign, dates and
+ * audiences still do.
  */
 export const ASKED = (form) => form.trigger.type === 'manual';
 
 /**
  * Every reason `form` may not show now, empty when it may. `env` is the page:
- * `{ path, device, now, seen, subscribed, personalisation, preview, audiences }`, where `seen` is
- * the slot's counters and `audiences` the session audiences the host gave, or null.
+ * `{ path, device, campaign, now, seen, subscribed, personalisation, preview, audiences }`, where
+ * `campaign` is the visit's (`visitCampaign`), `seen` the slot's counters and `audiences` the
+ * session audiences the host gave, or null. The campaign is context about this visit, as the page
+ * is, so it needs no personalisation consent. A form limited to audiences needs personalisation
+ * consent; whether the visitor is in one is the server's to decide (`POST /v1/decisions`), unless
+ * the host gave its own list.
  */
 export function blockers(form, env) {
 	const reasons = [];
 	if (!pageAllowed(form.pages, env.path)) reasons.push('page not included');
 	if (form.devices.length && !form.devices.includes(env.device))
 		reasons.push(`not on ${env.device}`);
+	if (!arrivedFrom(form.arrived_from, env.campaign))
+		reasons.push('not from its campaign');
 	const starts = at(form.window.starts_at);
 	const ends = at(form.window.ends_at);
 	if (env.now < starts || env.now >= ends) reasons.push('outside its dates');
-	if (form.audiences.length) {
+	// A trader previewing a limited form sees it, as the server answers a preview.
+	if (form.audiences.length && !env.preview) {
 		if (!env.personalisation)
 			reasons.push('audiences need personalisation consent');
 		else if (

package/src/onsite/visit-audiences.js

@@ -0,0 +1,94 @@
+/**
+ * The session audiences whose rules hold in this visit, for a form limited to audiences (ADR 0064):
+ * the server decides membership, but the live tier counts only product views and cart adds, so the
+ * browser evaluates the datafile's session rules and sends the slugs as `visit_audiences`. Rules
+ * only: `requires`, MIXED and targetability are the server's to apply. A chunk of its own
+ * (./audiences-loader.js), loaded with the datafile as the runtime starts, only when a live form is
+ * limited and the visitor allowed personalisation.
+ */
+
+import { catalogueBrowse, sessionRulesHold } from '../session/rules.js';
+
+/** What the decide request accepts: more, or a longer slug, and it ignores the lot. */
+const MAX_AUDIENCES = 100;
+/** Past any slug the console makes: a name of at most 100 characters, and a `-2` to tell twins apart. */
+const MAX_SLUG = 128;
+
+const isSlug = (slug) =>
+	typeof slug === 'string' && slug !== '' && slug.length <= MAX_SLUG;
+
+/** The datafile for each onsite runtime's api: a 200 kept for the page, anything else asked again. */
+const datafiles = new WeakMap();
+
+/** Start fetching the datafile, so a form that fires later does not wait for it. */
+export function prefetch(api) {
+	if (!datafiles.has(api)) {
+		const fetching = api
+			.datafile()
+			.then((res) => (res.status === 200 ? res.body : null))
+			.catch(() => null);
+		datafiles.set(api, fetching);
+		fetching.then((body) => {
+			if (!body && datafiles.get(api) === fetching) datafiles.delete(api);
+		});
+	}
+	return datafiles.get(api);
+}
+
+/**
+ * The slugs to send: those whose rules hold in this visit (the datafile fetched once, the visit read
+ * each time) and those the page gave, once each, at most MAX_AUDIENCES of them. Past that, the form's
+ * own audiences and what they require go first, so the cap never drops the ones it asks about.
+ *
+ * @param {{ datafile: () => Promise<{ status: number, body: any }> }} api ./api.js
+ * @param {() => object | null | undefined} [signals] This visit's session signals, kept only under
+ *   personalisation consent.
+ * @param {string[]} [targets] The audiences the form is limited to.
+ * @param {string[]} [given] The session audiences the page gave (`startOnsite`'s `audiences()`).
+ * @returns {Promise<string[]>}
+ */
+export async function visitAudiences(api, signals, targets = [], given = []) {
+	const datafile = await prefetch(api);
+	const visit = signals?.();
+	const session = Array.isArray(datafile?.session_audiences)
+		? datafile.session_audiences
+		: [];
+	const held = datafile && visit ? holdingAudiences(datafile, visit) : [];
+	return firstWanted([...held, ...given], targets, session);
+}
+
+/** `slugs`, once each, `targets` and their transitive `requires` first, capped. */
+export function firstWanted(slugs, targets, session) {
+	const requires = new Map(
+		session.map((a) => [a?.slug, Array.isArray(a?.requires) ? a.requires : []]),
+	);
+	const wanted = new Set();
+	const visit = (slug) => {
+		if (wanted.has(slug)) return;
+		wanted.add(slug);
+		for (const required of requires.get(slug) ?? []) visit(required);
+	};
+	for (const slug of targets) visit(slug);
+	const unique = [...new Set(slugs.filter(isSlug))];
+	return [
+		...unique.filter((slug) => wanted.has(slug)),
+		...unique.filter((slug) => !wanted.has(slug)),
+	].slice(0, MAX_AUDIENCES);
+}
+
+/**
+ * @param {{ session_audiences?: unknown, browse_categories?: unknown }} datafile `GET /v1/audiences/datafile`.
+ * @param {object} signals This visit's session signals.
+ * @returns {string[]}
+ */
+export function holdingAudiences(datafile, signals) {
+	const audiences = Array.isArray(datafile?.session_audiences)
+		? datafile.session_audiences
+		: [];
+	const visit = catalogueBrowse(signals, datafile.browse_categories ?? null);
+	return audiences
+		.filter(
+			(audience) => isSlug(audience?.slug) && sessionRulesHold(audience, visit),
+		)
+		.map((audience) => audience.slug);
+}

package/src/shape.js

@@ -107,6 +107,10 @@ export function realId(value) {
 	return PLACEHOLDER_IDS.has(text.toLowerCase()) ? null : text;
 }
 
+/** An identity token (ADR 0067), or null for anything but a non-empty string. */
+export const tokenOf = (value) =>
+	typeof value === 'string' && value !== '' ? value : null;
+
 /** A random UUID: event messageIds and the SDK's own device id. */
 export function uuid() {
 	if (typeof crypto !== 'undefined' && crypto.randomUUID)

package/src/spec-version.js

@@ -1,4 +1,4 @@
 // Generated from the spec by scripts/build-types.mjs. DO NOT EDIT: run `pnpm run build:types`.
 
 /** The event specification this SDK emits, stamped on every event as context.spec.version. */
-export const SPEC_VERSION = '1.18';
+export const SPEC_VERSION = '1.20';

package/src/storage-scope.js

@@ -64,6 +64,12 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	 * last closed, submitted) and a subscribed flag. Never contact data (onsite).
 	 */
 	onsite: 'thg_hp_onsite',
+	/**
+	 * localStorage, per property: the campaign tags the visit landed with, when it was last active
+	 * and its session id once kept, ended by 30 minutes without a page or event. Never a device or
+	 * person id (3.26).
+	 */
+	visitCampaign: 'thg_hp_visit_campaign',
 });
 
 /**

package/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '3.25.0';
+export const VERSION = '3.26.0';
 export const LIB = '@thg-agentic/hyper-personalisation-web';

package/src/visit-campaign.js

@@ -0,0 +1,168 @@
+/**
+ * The campaign a visit arrived from: the landing page's `utm_*` tags, as GA4's session source and
+ * the warehouse's `profiles.sessions` attribute a session to its landing page view. Judged in the
+ * browser, and sent only with the decision request for a form with rules, never logged.
+ *
+ * One store per property, owned here and written by the client as it starts: localStorage, so every
+ * tab of the visit reads the same campaign. The first tagged page of a visit wins; the visit ends,
+ * as the SDK's session does, after SESSION_TIMEOUT_MS without a page or an event, or when the session
+ * it was kept under is replaced. It holds the tags, when the visit was last active and the session
+ * id once one is kept on the device: never a device or person id. Kept before consent as the onsite
+ * counters are (ICO, the strictly necessary exception): it is context about this visit, which the
+ * site's own forms need on the next page.
+ */
+
+import { SESSION_TIMEOUT_MS } from './session-id.js';
+import { storageKey, storageName } from './storage-scope.js';
+
+/** The longest a tag is read: the control plane's CAMPAIGN_VALUE_MAX, which the server cuts to. */
+const TAG_MAX = 100;
+
+export const CAMPAIGN_FIELDS = [
+	'source',
+	'medium',
+	'campaign',
+	'content',
+	'term',
+];
+
+/**
+ * `{ source, medium, campaign, content, term }` from `context.campaign` (`readCampaign`, which names
+ * `utm_campaign` `name`), only the tags present, each cut to TAG_MAX characters; null without a single `utm_*` (a click id alone is
+ * not a campaign).
+ *
+ * @param {Record<string, string> | null | undefined} campaign
+ */
+export function visitCampaign(campaign) {
+	if (!campaign || typeof campaign !== 'object') return null;
+	const out = {};
+	for (const field of CAMPAIGN_FIELDS) {
+		const value = campaign[field === 'campaign' ? 'name' : field];
+		if (typeof value === 'string' && value)
+			out[field] = value.slice(0, TAG_MAX);
+	}
+	return Object.keys(out).length ? out : null;
+}
+
+const norm = (v) => String(v).trim().toLowerCase();
+
+/**
+ * Whether `campaign` (a `visitCampaign`) meets every rule `{ field, match: 'is' | 'contains',
+ * values }`, any value meeting a rule, in any case. No rules: true. No campaign, or a rule this SDK
+ * cannot read: false.
+ */
+export function arrivedFrom(rules, campaign) {
+	return (Array.isArray(rules) ? rules : []).every((rule) => {
+		const tag = campaign?.[rule?.field];
+		if (!CAMPAIGN_FIELDS.includes(rule?.field) || typeof tag !== 'string')
+			return false;
+		const have = norm(tag);
+		return [].concat(rule.values ?? []).some((v) => {
+			const want = norm(v);
+			return rule.match === 'is'
+				? have === want
+				: rule.match === 'contains' && want !== '' && have.includes(want);
+		});
+	});
+}
+
+const keyOf = (propertyId) =>
+	storageKey(
+		storageName('visitCampaign'),
+		propertyId == null ? null : String(propertyId),
+	);
+
+/**
+ * What this page kept, by key, for a browser whose localStorage is missing or refused the last
+ * write: the campaign then holds for the page, read and expired as the stored one is.
+ */
+const memory = new Map();
+
+function stored(key) {
+	if (memory.has(key)) return memory.get(key);
+	try {
+		const kept = JSON.parse(localStorage.getItem(key));
+		return kept && typeof kept === 'object' ? kept : null;
+	} catch {
+		return null;
+	}
+}
+
+function put(key, value) {
+	try {
+		if (value) localStorage.setItem(key, JSON.stringify(value));
+		else localStorage.removeItem(key);
+		memory.delete(key);
+	} catch {
+		if (value) memory.set(key, value);
+		else memory.delete(key);
+	}
+}
+
+/** The kept visit when it is still this one: active within the timeout, and under this session. */
+function live(kept, sessionId, now) {
+	return typeof kept?.tags === 'object' &&
+		kept.tags !== null &&
+		Number.isFinite(kept.at) &&
+		now - kept.at < SESSION_TIMEOUT_MS &&
+		!(sessionId && kept.sid && kept.sid !== sessionId)
+		? kept
+		: null;
+}
+
+/**
+ * The campaign this visit arrived from (a `visitCampaign`), or null; reads only. `sessionId` is the
+ * session kept on the device (the host's, or the SDK's cookie), null while it lives in memory.
+ *
+ * @param {string|null|undefined} propertyId
+ * @param {{ sessionId?: string|null, now?: number }} [options]
+ */
+export function readVisitCampaign(
+	propertyId,
+	{ sessionId = null, now = Date.now() } = {},
+) {
+	return live(stored(keyOf(propertyId)), sessionId, now)?.tags ?? null;
+}
+
+/**
+ * A page or an event of the visit: the kept campaign stays, active from `now`; a visit with none
+ * takes `landing`, this page's tags, when it has any. Answers the visit's campaign. `sessionId` is
+ * compared with the kept one; it is stored only with `keepSession` (analytics granted).
+ *
+ * @param {string|null|undefined} propertyId
+ * @param {Record<string, string>|null} landing This page's `visitCampaign`, or null.
+ * @param {{ sessionId?: string|null, keepSession?: boolean, now?: number }} [options]
+ */
+export function keepVisitCampaign(
+	propertyId,
+	landing,
+	{ sessionId = null, keepSession = false, now = Date.now() } = {},
+) {
+	const key = keyOf(propertyId);
+	const raw = stored(key);
+	const kept = live(raw, sessionId, now);
+	const tags = kept?.tags ?? landing ?? null;
+	// A session id is added only while analytics is granted, as the session cookie is; one kept
+	// under an earlier grant stays while consent is pending, so a new session still ends the visit.
+	// Withdrawal clears the store (`clearVisitCampaign`).
+	if (tags)
+		put(key, {
+			tags,
+			at: now,
+			sid: (keepSession ? sessionId : null) ?? kept?.sid ?? null,
+		});
+	else if (raw) put(key, null);
+	return tags;
+}
+
+/** Forget every property's visit campaign on this origin: a sign-out, or consent withdrawn. */
+export function clearVisitCampaign() {
+	memory.clear();
+	try {
+		const prefix = `${storageName('visitCampaign')}:`;
+		for (const key of Object.keys(localStorage))
+			if (key.startsWith(prefix)) localStorage.removeItem(key);
+	} catch {
+		/* nothing was kept */
+	}
+}

package/types/bootstrap.d.ts

@@ -88,6 +88,13 @@ export interface Preset extends DataLayerPreset {
 export interface Identity {
 	userId?: string | number | null;
 	emailSha256?: string | null;
+	/**
+	 * The identity token your server signed for this user on this page view (ADR 0067): a JWT,
+	 * ES256 with `typ: "JWT"` over `{ sub: userId, aud: "hyper-personalisation", exp }`. Without
+	 * it the sign-in is recorded but never joins this device to the user's others, and a promo
+	 * reminder's code is not shown. Since 3.26.
+	 */
+	token?: string | null;
 }
 
 export interface AutocaptureOptions {

package/types/events.d.ts

@@ -1,7 +1,7 @@
 // Generated from spec/registry.json by scripts/generate-sdk-models.mjs.
 // DO NOT EDIT. Change the schema and regenerate — the schema is the contract,
 // and a hand-edit here is an SDK that disagrees with the ingest.
-// Spec version: 1.18
+// Spec version: 1.20
 
 /** context.source.environment. Environment the producer runs in. */
 export type CdpSourceEnvironment = 'production' | 'staging' | 'development';
@@ -91,6 +91,32 @@ export interface JourneyTriggered {
 	products?: CdpProduct[];
 }
 
+/** The serving log: one ranked rail as the recommender answered it, with the features it ranked on, recorded when it was served rather than recomputed later. */
+export interface RecommendationServed {
+	recommendation_request_id: string;
+	group: 'personalised' | 'holdout' | 'excluded';
+	personalised: boolean;
+	products: Record<string, unknown>[];
+	batch_request_id?: string | null;
+	placement?: string | null;
+	recipe_requested?: string | null;
+	recipe?: string | null;
+	strategy?: string | null;
+	algorithm_version?: string | null;
+	ranked_by?: 'ranker' | 'blend' | 'session' | 'manual' | 'other' | null;
+	fusion?: string | null;
+	fast_weight?: number | null;
+	found?: boolean | null;
+	degraded?: boolean | null;
+	person_id?: string | null;
+	decision_id?: string | null;
+	arm?: string | null;
+	propensity?: number;
+	limit?: number | null;
+	candidate_set_size?: number | null;
+	unserved?: Record<string, unknown>[] | null;
+}
+
 /** A visitor acted on a personalised surface: clicked it (for example opened a product from a rail), dismissed it, or submitted a step of an onsite form. */
 export interface SlotEngaged {
 	decision_id: string;
@@ -686,12 +712,13 @@ export interface SignUpRelayed {
 }
 
 /** The spec version these models implement. SDKs stamp it on context.spec.version. */
-export const SPEC_VERSION = '1.18';
+export const SPEC_VERSION = '1.20';
 
 /** Every event name the registry accepts. Anything else is rejected at the ingest. */
 export type CdpEventName =
 	| 'Decision Made'
 	| 'Journey Triggered'
+	| 'Recommendation Served'
 	| 'Slot Engaged'
 	| 'Recommendations Viewed'
 	| 'Promotion Viewed'
@@ -755,6 +782,7 @@ export type CdpEventName =
 export interface CdpEventProperties {
 	'Decision Made': DecisionMade;
 	'Journey Triggered': JourneyTriggered;
+	'Recommendation Served': RecommendationServed;
 	'Slot Engaged': SlotEngaged;
 	'Recommendations Viewed': RecommendationsViewed;
 	'Promotion Viewed': PromotionViewed;

package/types/index.d.ts

@@ -209,6 +209,12 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	 */
 	holdAcrossPages?: boolean;
 	getUserId?(): string | null | undefined;
+	/**
+	 * The identity token your server signed for the user `getUserId` names (a JWT, ADR 0067), read
+	 * once: sent on each identify and with each onsite decision until `reset()`, a sign-out or
+	 * another user's `identify`. A later sign-in passes its own on `identify`. Since 3.26.
+	 */
+	identityToken?: string | null;
 	/** Observer for every event that will be sent. Must not throw; failures are swallowed. */
 	onEvent?(event: CdpEvent): void;
 

package/types/onsite.d.ts

@@ -47,6 +47,15 @@ export interface OnsiteForm {
 	pages?: { include?: string[]; exclude?: string[] };
 	/** `mobile` is a coarse pointer or a viewport under 768px. Absent: both. */
 	devices?: Array<'desktop' | 'mobile'>;
+	/**
+	 * Shown only to a visit that arrived from a matching campaign: the landing page's `utm_*` tags,
+	 * kept for the visit. Every rule must hold; any of a rule's values meets it, in any case.
+	 */
+	arrived_from?: Array<{
+		field: 'source' | 'medium' | 'campaign' | 'content' | 'term';
+		match: 'is' | 'contains';
+		values: string[];
+	}>;
 	/** Shown only with personalisation consent, and only to members as the server decides. */
 	audiences?: string[];
 	exclude_subscribed?: boolean;