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

package/src/session/signals.js

@@ -69,7 +69,8 @@ function readUnscoped() {
 				parsed.listViews > 0 ||
 				parsed.basketValue != null ||
 				parsed.recentProducts?.length ||
-				parsed.recentBrowse?.length);
+				parsed.recentBrowse?.length ||
+				parsed.campaign);
 		return busy ? parsed : null;
 	} catch {
 		return null;
@@ -101,6 +102,9 @@ function emptySignals() {
 		recentBrowseCategories: [],
 		browsingListing: null,
 		listViewsByCategory: {},
+		// The campaign the visit arrived from (`readVisitCampaign`, the first page with utm_* tags).
+		// Null for a visit that arrived untagged, so every rule on a campaign tag fails closed.
+		campaign: null,
 		startedAt: 0,
 	};
 }

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.27.0';
 export const LIB = '@thg-agentic/hyper-personalisation-web';

package/src/visit-campaign.js

@@ -0,0 +1,177 @@
+/**
+ * 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 a campaign tag meets one wanted value, trimmed and in any case: `is` the whole tag,
+ * `contains` a part of it that is not empty. The one matcher behind a form's `arrived_from` and a
+ * session audience's campaign rules, so the two cannot disagree.
+ */
+export function tagMatches(tag, match, want) {
+	const have = norm(tag);
+	const wanted = norm(want);
+	return match === 'is'
+		? have === wanted
+		: match === 'contains' && wanted !== '' && have.includes(wanted);
+}
+
+/**
+ * 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;
+		return []
+			.concat(rule.values ?? [])
+			.some((v) => tagMatches(tag, rule.match, v));
+	});
+}
+
+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;