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

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/onsite/wheel.js

@@ -16,6 +16,8 @@ const LABEL_TO = 0.95;
 /** Its type: as large as fits up to the first, never under the second (about 11px on a 320px wheel). */
 const FONT_MAX = 0.105;
 const FONT_MIN = 0.082;
+/** The least a label is shrunk to before it is shortened: a smaller label beats a cut one. */
+const FONT_FLOOR = 0.062;
 /** A bold sans character's width, a little over the average, so a label is never cut. */
 const EM_PER_CHAR = 0.62;
 const LINE_HEIGHT = 1.15;
@@ -49,8 +51,9 @@ const point = (deg, r = 1) => {
 
 /**
  * How a prize label fits its slice: on one line at the largest size that fits; else on two, broken
- * at the space nearest its middle; else shortened with an ellipsis at the smallest size. A slice's
- * width near the hub bounds the size too, so many slices draw smaller type.
+ * at the space nearest its middle; else the same again down to a smaller floor; else shortened with
+ * an ellipsis at the floor. A slice's width near the hub bounds the size too, so many slices draw
+ * smaller type.
  *
  * @returns {{ lines: string[], size: number }}
  */
@@ -61,20 +64,60 @@ export function fitLabel(label, slices) {
 	const top = (lines) =>
 		Math.max(FONT_MIN, Math.min(FONT_MAX, across / (lines * LINE_HEIGHT)));
 	const sizeFor = (text) => room / (Math.max(1, text.length) * EM_PER_CHAR);
-	const one = sizeFor(label);
-	if (one >= FONT_MIN) return { lines: [label], size: Math.min(top(1), one) };
 	const spaces = [...label.matchAll(/ /g)].map((m) => m.index);
-	if (spaces.length) {
-		const middle = label.length / 2;
-		const at = spaces.reduce((a, b) =>
-			Math.abs(b - middle) < Math.abs(a - middle) ? b : a,
+	const middle = label.length / 2;
+	const at = spaces.length
+		? spaces.reduce((a, b) =>
+				Math.abs(b - middle) < Math.abs(a - middle) ? b : a,
+			)
+		: -1;
+	const two = at < 0 ? null : [label.slice(0, at), label.slice(at + 1)];
+	for (const least of [FONT_MIN, FONT_FLOOR]) {
+		const one = sizeFor(label);
+		if (one >= least) return { lines: [label], size: Math.min(top(1), one) };
+		if (two) {
+			const size = Math.min(top(2), ...two.map(sizeFor));
+			if (size >= least) return { lines: two, size };
+		}
+	}
+	const fits = Math.floor(room / (FONT_FLOOR * EM_PER_CHAR));
+	return {
+		lines: [`${label.slice(0, fits - 1).trimEnd()}…`],
+		size: FONT_FLOOR,
+	};
+}
+
+/**
+ * Hold drawn labels to their room by their real width, once the page lays them out: the estimate
+ * in `fitLabel` cannot know the site's font, and a wide one ran "15% off" past its slice's edge.
+ * A line too wide is shrunk to fit, down to the floor, and squeezed to the room past it. Labels not
+ * laid out yet (a detached wheel) measure nothing and are left as estimated.
+ *
+ * @param {SVGTextElement[]} texts
+ */
+export function fitDrawnLabels(texts) {
+	const room = LABEL_TO - LABEL_FROM;
+	const width = (span) => span.getComputedTextLength?.() ?? 0;
+	for (const text of texts) {
+		const spans = [...text.querySelectorAll('tspan')];
+		const widest = Math.max(0, ...spans.map(width));
+		if (!(widest > room)) continue;
+		const size = Math.max(
+			FONT_FLOOR,
+			(Number(text.getAttribute('font-size')) * room) / widest,
 		);
-		const lines = [label.slice(0, at), label.slice(at + 1)];
-		const size = Math.min(top(2), ...lines.map(sizeFor));
-		if (size >= FONT_MIN) return { lines, size };
+		text.setAttribute('font-size', size.toFixed(4));
+		spans.forEach((span, k) => {
+			span.setAttribute(
+				'y',
+				((k - (spans.length - 1) / 2) * size * LINE_HEIGHT).toFixed(4),
+			);
+			if (width(span) > room) {
+				span.setAttribute('textLength', room.toFixed(4));
+				span.setAttribute('lengthAdjust', 'spacingAndGlyphs');
+			}
+		});
 	}
-	const fits = Math.floor(room / (FONT_MIN * EM_PER_CHAR));
-	return { lines: [`${label.slice(0, fits - 1).trimEnd()}…`], size: FONT_MIN };
 }
 
 /**
@@ -108,6 +151,7 @@ export function mountWheel(container, prizes) {
 	];
 	wheel.append(paint(make('circle', { r: 1 }), BG));
 	const lights = [];
+	const texts = [];
 	labels.forEach((label, i) => {
 		const [tone, ink] = tones[n % 2 === 1 && i === n - 1 ? 2 : i % 2];
 		wheel.append(
@@ -148,6 +192,7 @@ export function mountWheel(container, prizes) {
 			text.append(span);
 		});
 		wheel.append(text);
+		texts.push(text);
 		for (const at of [i * size, (i + 0.5) * size]) {
 			const [cx, cy] = point(at, 1.075).split(' ');
 			lights.push(paint(make('circle', { cx, cy, r: 0.024 }), BG));
@@ -170,6 +215,9 @@ export function mountWheel(container, prizes) {
 		),
 	);
 	container.append(svg);
+	fitDrawnLabels(texts);
+	// A wheel drawn before its step is shown has no layout yet: measured again on the next frame.
+	globalThis.requestAnimationFrame?.(() => fitDrawnLabels(texts));
 
 	return {
 		spinTo(index) {

package/src/settings.js

@@ -21,6 +21,18 @@ const isStringArray = (v) =>
 
 export const DISABLED = Object.freeze({ enabled: false });
 
+/**
+ * What a page with no cached settings starts on when the API cannot be asked: collection only, every
+ * other setting read as absent. Settings switch features on; their absence never switches capture
+ * off (Snowplow's tracker needs no remote config to collect). Consent is still the page's CMP,
+ * strictly. The property is the page's, else the one the ingest stamps for a single-property key.
+ * URLs keep campaign parameters only. Never cached: the next page asks the API again.
+ */
+export const BUILT_IN = Object.freeze({
+	enabled: true,
+	queryParamAllowlist: Object.freeze([]),
+});
+
 /**
  * Whether a tracking plan lets the track event `name` through. Segment's `plan.track` semantics: an
  * event marked `enabled: false` is dropped at the source, and `__default` covers events the plan
@@ -218,19 +230,35 @@ export function readSettings(body) {
 }
 
 /**
- * The settings for `writeKey`: DISABLED when the API says so, null when it could not be asked (an
- * outage keeps whatever the cache last held rather than switching a working site off).
+ * How long a page without cached settings waits for them. The answer is cached at the edge, so one
+ * this slow is an outage, and a host that awaits `bootstrap` must never wait on HP for longer.
+ */
+export const SETTINGS_TIMEOUT_MS = 3000;
+
+/**
+ * The settings for `writeKey`: DISABLED when the API says so, null when it could not be asked in
+ * time (an outage keeps whatever the cache last held rather than switching a working site off).
  */
 export async function fetchSettings(
 	apiHost,
 	writeKey,
 	fetchImpl = globalThis.fetch,
+	timeoutMs = SETTINGS_TIMEOUT_MS,
 ) {
 	try {
 		const res = await fetchImpl(settingsUrl(apiHost, writeKey), {
 			credentials: 'omit',
 			headers: { accept: 'application/json' },
+			signal: AbortSignal.timeout?.(timeoutMs),
 		});
+		// An answered refusal is the key's; only an error, a throttle or a timeout is an outage.
+		if (
+			res.status >= 400 &&
+			res.status < 500 &&
+			res.status !== 408 &&
+			res.status !== 429
+		)
+			return DISABLED;
 		if (!res.ok) return null;
 		const body = await res.json();
 		return isSettingsAnswer(body) ? readSettings(body) : null;

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/social-proof.js

@@ -7,7 +7,7 @@
 
 import { parseConsentCookie, servingHeaders } from './consent.js';
 import { getCookie } from './context.js';
-import { resolveApiHost } from './settings.js';
+import { resolveApiHost, SETTINGS_TIMEOUT_MS } from './settings.js';
 import { storageName } from './storage-scope.js';
 
 const DEFAULT_TTL_MS = 60_000;
@@ -37,6 +37,7 @@ const chunk = (items, size) => {
  * @param {number} [options.ttlMs]   How long to reuse an answer. The numbers move on a pipeline
  *                                   schedule of tens of minutes.
  * @param {typeof fetch} [options.fetchImpl]
+ * @param {number} [options.timeoutMs] How long to wait for an answer, as for the settings (3 s).
  * @param {() => object|null} [options.getConsent] The visitor's consent state, sent as `hp-consent`
  *   like every serving request. Default: read back from the consent cookie the SDK writes; pass
  *   `() => analytics.consent` to use the live state instead.
@@ -48,6 +49,7 @@ export function createSocialProof({
 	ttlMs = DEFAULT_TTL_MS,
 	fetchImpl,
 	getConsent,
+	timeoutMs = SETTINGS_TIMEOUT_MS,
 }) {
 	const base = resolveApiHost(apiHost);
 	if (!base)
@@ -74,6 +76,8 @@ export function createSocialProof({
 				// No credentials: the answer is the same for every visitor, and a cookie would make it
 				// uncacheable.
 				credentials: 'omit',
+				// A badge is never worth a wait: an API that does not answer in time is no answer.
+				signal: AbortSignal.timeout?.(timeoutMs),
 				headers: {
 					accept: 'application/json',
 					authorization: `Bearer ${writeKey}`,

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

@@ -11,7 +11,7 @@
 export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	/** Cookie: the visitor's consent decision, for the site's own servers to forward. */
 	consent: 'thg_hp_consent',
-	/** localStorage, per property: batches waiting for the ingest to answer. */
+	/** localStorage, per write key (property before 3.25): batches waiting for the ingest to answer. */
 	retry: 'thg_hp_retry',
 	/** localStorage per property and session (sessionStorage until a session is bound). */
 	sessionSignals: 'thg_hp_session_signals',
@@ -24,7 +24,7 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	/** localStorage, per write key: the last good remote settings. */
 	settings: 'thg_hp_settings',
 	/**
-	 * sessionStorage, per property: events held for an unanswered CMP, carried to the next page.
+	 * sessionStorage, per write key: events held for an unanswered CMP, carried to the next page.
 	 * Only with `holdAcrossPages` (3.5).
 	 */
 	held: 'thg_hp_held',
@@ -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/transport.js

@@ -5,7 +5,8 @@
  *
  *  1. Persisted retry: every batch is written to localStorage before its first attempt and
  *     removed only once the ingest has answered for it.
- *  2. Unload delivery: on pagehide the queue goes by sendBeacon, which outlives the document.
+ *  2. Unload delivery: on pagehide the queue goes by sendBeacon, which outlives the document. A
+ *     beacon's answer is never seen, so while the ingest is failing a copy is also persisted.
  *  3. Bounded: queue size, retry age and payload size are capped, so a broken ingest degrades
  *     instead of filling the user's disk.
  */
@@ -103,6 +104,10 @@ export class Transport {
 		this.wakers = new Set();
 		this.replayAllowed = !this.o.deferReplay;
 		this.draining = null;
+		/** The last attempt failed, or the host was found unreachable: unload persists what it beacons. */
+		this.failing = false;
+		/** The ingest has accepted a batch on this page: only a send that fails says otherwise. */
+		this.answered = false;
 
 		if (isBrowser()) {
 			// pagehide is the unload, and the beacon the only send sure to outlive it. A hidden tab may
@@ -115,6 +120,11 @@ export class Transport {
 		}
 	}
 
+	/** The ingest is taken as down until a send succeeds, unless one already has: see #flushBeacon. */
+	markFailing() {
+		if (!this.answered) this.failing = true;
+	}
+
 	/** Allow, and start, the replay of persisted batches. Idempotent. */
 	replayPersisted() {
 		this.replayAllowed = true;
@@ -292,6 +302,8 @@ export class Transport {
 	 * Unload: every chunk that fits goes by beacon. A chunk the browser refuses (its keepalive
 	 * quota is shared across the page) is persisted for the next page load AND tried by fetch;
 	 * a fetch that lands removes it again, and a duplicate is deduplicated on messageId downstream.
+	 * While the ingest is failing a beaconed chunk is persisted too, since the browser accepting a
+	 * beacon says nothing of the ingest: the next page replays it, a duplicate if it did land.
 	 *
 	 * The fetch builds its own body rather than reusing the beacon's, for the same reason every retry
 	 * does: see #send.
@@ -318,7 +330,12 @@ export class Transport {
 				} catch {
 					ok = false;
 				}
-				if (ok) continue;
+				if (ok) {
+					// Claimed, so a page restored from the back/forward cache does not replay it itself.
+					const id = this.failing ? this.#persist(batch) : null;
+					if (id) this.sending.add(id);
+					continue;
+				}
 			}
 			this.#send(batch, 0, this.#persist(batch));
 		}
@@ -346,6 +363,8 @@ export class Transport {
 			});
 
 			if (res.ok) {
+				this.failing = false;
+				this.answered = true;
 				this.#settle(persisted);
 				// The ingest is answering again: whatever an earlier outage left behind can go now.
 				this.#drainPersisted();
@@ -365,6 +384,7 @@ export class Transport {
 			}
 			throw new Error(`retryable ${res.status}`);
 		} catch (err) {
+			this.failing = true;
 			if (attempt >= this.o.maxRetries) {
 				if (persisted) this.sending.delete(persisted);
 				const fate = persisted ? 'kept for the next page' : 'dropped';

package/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '3.24.1';
+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 */
+	}
+}