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

package/src/index.js

@@ -50,6 +50,7 @@ import {
 	getCookie,
 	localeTag,
 	perRequest,
+	readCampaign,
 	scrubHref,
 } from './context.js';
 import { createDecisionMemory, servedDecisions } from './decisions.js';
@@ -82,6 +83,7 @@ import {
 	PAGE_TYPES,
 	pruneProperties,
 	realId,
+	tokenOf,
 	uuid,
 } from './shape.js';
 import {
@@ -96,6 +98,12 @@ import {
 	byteLength as utf8Bytes,
 } from './transport.js';
 import { LIB, VERSION } from './version.js';
+import {
+	clearVisitCampaign,
+	keepVisitCampaign,
+	readVisitCampaign,
+	visitCampaign,
+} from './visit-campaign.js';
 
 /** The surfaces a `Personalisation Exposed` names, as the public API's exposures do. */
 const EXPOSURE_SURFACES = new Set([
@@ -426,6 +434,28 @@ export function createAnalytics(options) {
 		storageName('preview'),
 		cfg.consentCookieDomain ?? null,
 	);
+	/** The session kept on the device (the host's, or the SDK's cookie); null while in memory only. */
+	const keptSession = () =>
+		realId(perRequest(hostSession, null)) ?? getCookie(storageName('session'));
+	/**
+	 * The tags the page loaded with, read now so a later `replaceState` cannot take them away, and
+	 * the visit's campaign kept from them when the visit has none (visit-campaign.js).
+	 */
+	const landingCampaign = visitCampaign(
+		typeof location === 'undefined' ? null : readCampaign(location.search),
+	);
+	/**
+	 * A page or an event of the visit, as it is collected whatever consent will say of sending it: the
+	 * visit's campaign lasts as its session does. A trader's preview is not a shopper's visit: it
+	 * reads its own URL's tags and keeps none.
+	 */
+	const keepCampaign = (landing = null) => {
+		if (!previewing)
+			keepVisitCampaign(cfg.propertyId, landing, {
+				sessionId: keptSession(),
+				keepSession: granted(),
+			});
+	};
 
 	/** Delivery problems, logged with `debug`. */
 	const reportError = (message, err) =>
@@ -489,6 +519,12 @@ export function createAnalytics(options) {
 	let identifiedUserId = null;
 	/** The user bootstrap's `identity` option named, only to warn when the host names another form. */
 	let optionsUserId = null;
+	/**
+	 * The signed-in user's identity token (ADR 0067), the one copy of it: from the `identityToken`
+	 * option for the user `getUserId` named, then whatever `identify` passes for its user. Another
+	 * user, `reset()` or a sign-out clears it, so nobody else's token outlives their sign-in.
+	 */
+	let identityToken = userId ? tokenOf(cfg.identityToken) : null;
 
 	/** The call being replayed: its first event keeps the messageId and time it was made with. */
 	let replaying = null;
@@ -521,6 +557,7 @@ export function createAnalytics(options) {
 	/** Tracking never throws into the host: an event that fails to build or deliver is dropped. */
 	function emit(partial, ctxOverrides, force = false) {
 		noteBasket(partial);
+		keepCampaign();
 		try {
 			return compose(partial, ctxOverrides, force);
 		} catch (err) {
@@ -604,7 +641,9 @@ export function createAnalytics(options) {
 	}
 
 	function observe(event) {
-		if (event.type === 'track') recordVisit(event);
+		// A page view folds in no counter, but brings the visit's campaign into the session signals,
+		// so a landing page that sends nothing else can resolve an audience on it.
+		if (event.type === 'track' || event.type === 'page') recordVisit(event);
 		// Lets a caller fold the event the warehouse will receive into session state. An observer
 		// that throws must not cost the event.
 		if (cfg.onEvent) {
@@ -629,11 +668,15 @@ export function createAnalytics(options) {
 		try {
 			if (personalisationGranted()) {
 				scopeVisit();
-				keepVisit(
-					recommendationContextFrom(
-						recordSessionEvent(event.event, event.properties),
-					),
+				const signals = recordSessionEvent(
+					event.event,
+					event.properties,
+					// The one visit-campaign store, kept since the landing page whatever the consent then.
+					readVisitCampaign(cfg.propertyId, { sessionId: keptSession() }),
 				);
+				// A page view changes nothing a rail reads, so it does not extend what is kept for one.
+				if (event.type === 'track')
+					keepVisit(recommendationContextFrom(signals));
 				visitKept = true;
 			} else {
 				// Not allowed, or withdrawn: what was kept under the permission goes with it.
@@ -665,6 +708,7 @@ export function createAnalytics(options) {
 		exposedTokens.clear();
 		device?.forget();
 		forgetKeptVisit(true);
+		clearVisitCampaign();
 	}
 
 	function deliver(event, force) {
@@ -701,6 +745,8 @@ export function createAnalytics(options) {
 		};
 	};
 
+	// Before the gate starts, so a withdrawal it finds on this page clears the landing tags too.
+	keepCampaign(landingCampaign);
 	if (strict) {
 		gate = createConsentGate({
 			adapter: cfg.consent,
@@ -758,7 +804,10 @@ export function createAnalytics(options) {
 				if (state?.personalisation !== true)
 					forgetKeptVisit(previous?.personalisation === true);
 				// Events collected under the grant are not sent after it is withdrawn: only the withdrawal.
-				if (withdrawal) transport.discardQueued?.();
+				if (withdrawal) {
+					transport.discardQueued?.();
+					clearVisitCampaign();
+				}
 				emit(
 					{
 						type: 'track',
@@ -772,6 +821,8 @@ export function createAnalytics(options) {
 			},
 		});
 		gate.start();
+		// Only what survived the gate: a visitor already granted keeps the session id with it.
+		keepCampaign();
 	}
 
 	/** The property's holdout split from the settings, as a serving response would state it. */
@@ -859,6 +910,7 @@ export function createAnalytics(options) {
 		userId = null;
 		identifiedUserId = null;
 		optionsUserId = null;
+		identityToken = null;
 		return event;
 	}
 
@@ -903,8 +955,17 @@ export function createAnalytics(options) {
 		identify(traits, ctx, source) {
 			const { userId: id, ...rest } =
 				traits && typeof traits === 'object' ? traits : {};
+			// The token the site's server signed for this user (ADR 0067): without it the identity graph
+			// records the sign-in and never joins this device to the user's others.
+			const passed = tokenOf(contextOverrides(ctx)?.identity_token);
 			if (id !== undefined) {
 				const next = realId(id);
+				// Another user's sign-in brings its own token or none; the same user's keeps the last.
+				identityToken = !next
+					? null
+					: next === userId
+						? (passed ?? identityToken)
+						: passed;
 				if (source === IDENTITY_OPTION) {
 					optionsUserId = next;
 				} else if (identifiedUserId && next && next !== identifiedUserId) {
@@ -924,10 +985,12 @@ export function createAnalytics(options) {
 				}
 				userId = next;
 				if (next && source !== IDENTITY_OPTION) identifiedUserId = next;
-			}
+			} else if (passed && userId) identityToken = passed;
+			// Only the current user's token is sent: one passed with nobody to keep it for goes nowhere.
+			const { identity_token: _, ...context } = contextOverrides(ctx) ?? {};
 			return emit(
 				{ type: 'identify', traits: identifyTraits(rest, cfg.debug) },
-				ctx,
+				identityToken ? { ...context, identity_token: identityToken } : context,
 			);
 		},
 
@@ -941,6 +1004,7 @@ export function createAnalytics(options) {
 			userId = null;
 			identifiedUserId = null;
 			optionsUserId = null;
+			identityToken = null;
 			writeLastPageMessageId('');
 		},
 
@@ -1120,6 +1184,8 @@ export function createAnalytics(options) {
 				preview: previewing,
 				anonymousId: () => realId(perRequest(cfg.getAnonymousId, null)),
 				sessionId: () => realId(perRequest(cfg.getSessionId, null)),
+				// Only where it is used: a reminder's code is answered with personalisation granted.
+				identityToken: () => (personalisationGranted() ? identityToken : null),
 				analytics: granted,
 				personalisation: personalisationGranted,
 				consent: () => cfg.getConsent(),
@@ -1129,6 +1195,11 @@ export function createAnalytics(options) {
 						? null
 						: scrubHref(location.href, cfg),
 				locale: () => localeTag(perRequest(cfg.getLocale, cfg.locale)),
+				/** The visit's campaign for "arrived from"; a preview's is its own URL's. */
+				campaign: () =>
+					previewing
+						? landingCampaign
+						: readVisitCampaign(cfg.propertyId, { sessionId: keptSession() }),
 				/**
 				 * A basket bar's progress: the basket this page reported, else the last one this visit
 				 * kept (under personalisation consent), else null.
@@ -1137,6 +1208,20 @@ export function createAnalytics(options) {
 					const value = getSessionSignals().basketValue;
 					return pageBasket ?? (Number.isFinite(value) ? value : null);
 				},
+				/**
+				 * This visit's session signals, kept only under personalisation consent; else null. The
+				 * campaign is the store's as it stands, so one that has lapsed since the last event is gone.
+				 */
+				sessionSignals: () => {
+					if (!personalisationGranted()) return null;
+					scopeVisit();
+					return {
+						...getSessionSignals(),
+						campaign: readVisitCampaign(cfg.propertyId, {
+							sessionId: keptSession(),
+						}),
+					};
+				},
 				/** Calls `listener` whenever the page reports its basket; answers how to stop. */
 				onBasket: (listener) => {
 					basketListeners.add(listener);

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/session/record.js

@@ -58,11 +58,16 @@ function countListView(s, category) {
  * Fold one CDP event into the session signals.
  *
  * Driven by the events the SDK already sends, so a session rule is only ever about something the
- * warehouse will also see.
+ * warehouse will also see. `campaign`, when given, is the visit's campaign (`readVisitCampaign`),
+ * mirrored as it stands so the two never disagree; left out, the kept one stays.
  */
-export function recordSessionEvent(eventName, properties) {
+export function recordSessionEvent(eventName, properties, campaign) {
 	const s = readSignals();
 	if (!s.startedAt) s.startedAt = Date.now();
+	const arrived =
+		campaign !== undefined &&
+		JSON.stringify(campaign ?? null) !== JSON.stringify(s.campaign ?? null);
+	if (arrived) s.campaign = campaign ?? null;
 
 	const products = Array.isArray(properties?.products)
 		? properties.products
@@ -178,6 +183,7 @@ export function recordSessionEvent(eventName, properties) {
 			return s;
 		}
 		default:
+			if (arrived) writeSignals(s);
 			return s;
 	}
 

package/src/session/rules.js

@@ -1,3 +1,4 @@
+import { CAMPAIGN_FIELDS, tagMatches } from '../visit-campaign.js';
 import { categoryKey } from './category.js';
 import { readSignals } from './signals.js';
 
@@ -17,12 +18,28 @@ const OPERATORS = {
 	'=': (a, b) => a === b,
 };
 
+/**
+ * Operators on a text field (the visit's campaign tags): `tagMatches`, the matcher a form's
+ * "arrived from" rule uses, so the two agree. A value of the wrong shape matches nothing.
+ */
+const text = (v) => typeof v === 'string';
+const is = (a, b) => text(b) && tagMatches(a, 'is', b);
+const STRING_OPERATORS = {
+	eq: is,
+	equals: is,
+	'=': is,
+	neq: (a, b) => text(b) && !is(a, b),
+	in: (a, b) => Array.isArray(b) && b.some((v) => is(a, v)),
+	contains: (a, b) => text(b) && tagMatches(a, 'contains', b),
+};
+
 /**
  * Every operator this evaluator can apply, including `between`. A contract test keeps the session
  * trait catalogue inside this set, since an unsupported operator fails closed silently.
  */
 export const SESSION_OPERATORS = new Set([
 	...Object.keys(OPERATORS),
+	...Object.keys(STRING_OPERATORS),
 	'between',
 ]);
 
@@ -54,14 +71,23 @@ const MEASURES = {
 /**
  * What a rule's field is worth right now, or null if this build does not know the field.
  *
- * A field is a counter name or `measure.dimension` (`browseShare.damen/schuhe`). Exported so a
- * storefront can explain a personalisation. Unknown fields fail the rule closed.
+ * A field is a counter name, `measure.dimension` (`browseShare.damen/schuhe`), or one of the
+ * visit's campaign tags (`campaign.source`), which is text and null for a visit that arrived
+ * untagged. Exported so a storefront can explain a personalisation. Unknown fields fail the rule
+ * closed.
  */
 export function measureField(field, signals) {
 	const separator = field.indexOf('.');
 	if (separator > 0) {
-		const fn = MEASURES[field.slice(0, separator)];
+		const name = field.slice(0, separator);
 		const arg = field.slice(separator + 1);
+		if (name === 'campaign') {
+			const tag = CAMPAIGN_FIELDS.includes(arg)
+				? signals.campaign?.[arg]
+				: null;
+			return typeof tag === 'string' ? tag : null;
+		}
+		const fn = MEASURES[name];
 		return fn && arg ? fn(signals, arg) : null;
 	}
 	const value = signals[field];
@@ -71,6 +97,10 @@ export function measureField(field, signals) {
 export function evaluateSessionRule(rule, signals) {
 	const actual = measureField(rule.field, signals);
 	if (actual === null) return false;
+	if (typeof actual === 'string') {
+		const compare = STRING_OPERATORS[rule.operator];
+		return compare ? compare(actual, rule.value) : false;
+	}
 	if (rule.operator === 'between') {
 		// A `between` missing either bound fails closed.
 		return (