@thg-agentic/hyper-personalisation-web 3.28.1 → 3.30.0

package/src/onsite/index.js

@@ -65,6 +65,28 @@ const INERT = {
 	code: () => null,
 };
 
+/**
+ * The codes a fired form says `nothing` with: HP has nothing to show for it, rather than its rules
+ * (caps, the gap, the site's suppression, another form showing) keeping it away.
+ */
+const NOTHING = new Set([
+	'decision-failed',
+	'no-creative',
+	'no-code',
+	'renderer-failed',
+	'products-failed',
+	'error',
+]);
+
+/**
+ * The longest from the end of the fire window to a form's decision, renderer and products: past it
+ * the form shows nothing, and an answer that comes later is never used. Forms that fire together
+ * share one, so `nothing` comes at most FIRE_WINDOW_MS + DEADLINE_MS after the trigger.
+ */
+const DEADLINE_MS = 3000;
+/** A decision that did not come in time, as one the network failed. */
+const LATE = { status: 0, body: 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. */
@@ -148,6 +170,7 @@ export function startOnsite(client, options = {}) {
 			trace.set(String(raw?.slot ?? `form ${trace.size + 1}`), {
 				slot: String(raw?.slot ?? ''),
 				state: 'invalid',
+				code: 'invalid',
 				reasons: ['not a form this SDK can show'],
 			});
 	}
@@ -170,6 +193,7 @@ export function startOnsite(client, options = {}) {
 	const covering = new Map();
 	const opening = new Map();
 	let spent = null;
+	let stopped = false;
 	/** The pictures warmed on this page view, by every form, so none is fetched twice. */
 	const warmed = new Set();
 	/**
@@ -185,7 +209,10 @@ export function startOnsite(client, options = {}) {
 		}
 		return null;
 	};
-	let fired = [];
+	/** The covering forms whose triggers fired in this window, and the deadline they share. */
+	let batch = null;
+	/** Every window still collecting or being decided: a form the site opens is taken from each. */
+	const windows = new Set();
 	const gap = Number.isInteger(settings.overlay_gap_minutes)
 		? settings.overlay_gap_minutes
 		: 0;
@@ -203,20 +230,51 @@ export function startOnsite(client, options = {}) {
 	/** Covering forms whose trigger fired before the consent banner was answered. */
 	const awaitingConsent = new Map();
 
-	const note = (form, state, reasons = []) => {
+	const note = (form, state, code, reasons = []) => {
 		trace.set(form.slot, {
 			slot: form.slot,
 			format: form.format,
 			trigger: form.trigger.type,
 			priority: form.priority,
 			state,
+			code,
 			reasons,
 		});
 		if (logging)
 			console.info(
 				`[hp] onsite ${form.slot}: ${state}${reasons.length ? ` (${reasons.join('; ')})` : ''}`,
 			);
-		return state;
+		return { state, code };
+	};
+	/** A form that was being opened gives up: it covers nothing any more. */
+	const drop = (form, state, code, reasons) => {
+		covering.delete(form.slot);
+		return note(form, state, code, reasons);
+	};
+	/**
+	 * `promise`, or `late` once `deadline` has passed: an answer read after it (a busy main thread
+	 * runs the timer late) is dropped too.
+	 */
+	const within = (promise, deadline, late) => {
+		let id;
+		return Promise.race([
+			promise,
+			new Promise((resolve) => {
+				id = setTimeout(resolve, deadline - Date.now(), late);
+			}),
+		])
+			.then((value) => (Date.now() > deadline ? late : value))
+			.finally(() => clearTimeout(id));
+	};
+	/**
+	 * Tell the page HP shows nothing for `form`: the site shows its own popup in its place, so the
+	 * page view's allowance is spent, as a held-out visitor's is, and no other HP form follows it.
+	 */
+	const say = (form, code) => {
+		// A page suppressed while the form was decided keeps its own screen clear: nothing to fill.
+		if (stopped || suppressed()) return;
+		spent ??= form.slot;
+		emit('nothing', { slot: form.slot, format: form.format, code });
 	};
 
 	const sessionAudiences = () => {
@@ -246,29 +304,51 @@ export function startOnsite(client, options = {}) {
 	};
 
 	/**
-	 * Show `form` if its rules allow it; resolves to the state its trace records. A form on screen is
-	 * not mounted again, and a second call while it is being opened (a double click during the
-	 * decision) shares the first one's answer.
+	 * Show `form` if its rules allow it; resolves to the `{ state, code }` its trace records, and
+	 * whether the site asked for or opened it (`asked`). A form on screen is not mounted again, and a second
+	 * call while it is being opened (a double click during the decision, or the site opening a form
+	 * whose trigger just fired) shares the first one's answer. A throw anywhere in it is the code
+	 * `error`.
 	 */
-	function show(form, reason, kept = false, asked = ASKED(form)) {
-		if (mounted.has(form.slot)) return Promise.resolve('shown');
-		if (!opening.has(form.slot))
-			opening.set(
-				form.slot,
-				attempt(form, reason, kept, asked).finally(() =>
-					opening.delete(form.slot),
-				),
-			);
-		return opening.get(form.slot);
+	function show(
+		form,
+		reason,
+		kept = false,
+		asked = ASKED(form),
+		deadline = Date.now() + DEADLINE_MS,
+	) {
+		if (mounted.has(form.slot))
+			return Promise.resolve({ state: 'shown', code: 'shown', asked });
+		let entry = opening.get(form.slot);
+		if (entry) {
+			entry.asked ||= asked;
+			return entry.done;
+		}
+		entry = { asked };
+		entry.done = attempt(form, reason, kept, asked, deadline)
+			.catch((err) => {
+				if (mounted.has(form.slot)) return { state: 'shown', code: 'shown' };
+				console.warn('[hp] onsite form failed:', err?.message ?? err);
+				return drop(form, 'not shown', 'error', [
+					`failed: ${err?.message ?? err}`,
+				]);
+			})
+			.then((result) => {
+				opening.delete(form.slot);
+				return { ...result, asked: entry.asked || entry.opened };
+			});
+		opening.set(form.slot, entry);
+		return entry.done;
 	}
 
 	/**
 	 * `kept`: a teaser's tab carried from an earlier page, shown again whatever its caps. `asked`: the
 	 * shopper asked for it (a `manual` form, or one opened by an alias), so its counters do not apply.
+	 * `deadline`: when its decision, renderer and products must have come (DEADLINE_MS).
 	 */
-	async function attempt(form, reason, kept, asked) {
+	async function attempt(form, reason, kept, asked, deadline) {
 		if (suppressed()) {
-			return note(form, 'not shown', [
+			return note(form, 'not shown', 'suppressed', [
 				`suppressed: ${[...window[SUPPRESSED]].join(', ')}`,
 			]);
 		}
@@ -278,24 +358,29 @@ export function startOnsite(client, options = {}) {
 			asked,
 		});
 		if (reasons.length) {
-			return note(form, 'not eligible', reasons);
+			return note(form, 'not eligible', 'not-eligible', reasons);
 		}
 		// The gap first: it holds for the whole session, so it is the reason worth reading.
 		const interrupts = INTERRUPTS(form.format) && !kept;
 		const wait = interrupts && !asked && gapHolds();
 		if (wait) {
-			return note(form, 'not shown', [wait]);
+			return note(form, 'not shown', 'overlay-gap', [wait]);
 		}
 		// Never over an unanswered consent banner: the shopper answers it first, whatever the answer.
 		if (interrupts && !access.preview && access.consentAnswered?.() === false) {
 			awaitingConsent.set(form, asked);
-			return note(form, 'not shown', ['waiting for the consent banner']);
+			return note(form, 'not shown', 'awaiting-consent', [
+				'waiting for the consent banner',
+			]);
 		}
 		const covers = OVERLAY(form.format);
 		const shown = covers && blocker(asked);
-		if (shown) return note(form, 'not shown', [`${shown} is showing`]);
+		if (shown)
+			return note(form, 'not shown', 'another-showing', [
+				`${shown} is showing`,
+			]);
 		if (covers && spent && !asked) {
-			return note(form, 'not shown', [
+			return note(form, 'not shown', 'allowance-spent', [
 				`${spent} already showed on this page view`,
 			]);
 		}
@@ -307,12 +392,14 @@ export function startOnsite(client, options = {}) {
 				container = null;
 			}
 			if (!container) {
-				return note(form, 'not shown', ['no element matches its selector']);
+				return note(form, 'not shown', 'no-element', [
+					'no element matches its selector',
+				]);
 			}
 		}
 		if (covers) covering.set(form.slot, form);
 		unwatch(form);
-		note(form, 'asking for a decision', [reason]);
+		note(form, 'asking for a decision', 'deciding', [reason]);
 		// The renderer is fetched while the decision is asked, so neither waits on the other.
 		const renderer = loadRender().catch((err) => {
 			console.warn('[hp] onsite renderer not loaded:', err?.message ?? err);
@@ -332,7 +419,7 @@ export function startOnsite(client, options = {}) {
 			.slice(0, 100);
 		const claimed =
 			form.audiences.length > 0 && !access.preview && access.personalisation()
-				? await Promise.race([
+				? await within(
 						audiencesChunk().then((chunk) =>
 							chunk
 								? chunk.visitAudiences(
@@ -343,20 +430,33 @@ export function startOnsite(client, options = {}) {
 									)
 								: 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,
-			// Only for a form whose products are filled from it; never kept or logged by the server.
-			visitContext:
-				form.visit_context === true ? (access.visitContext?.() ?? null) : null,
-		});
-		const decision =
-			res.status === 200
-				? res.body?.decisions?.find((d) => d?.slot === form.slot)
+						Math.min(deadline, Date.now() + CLAIMS_MS),
+						given,
+					)
 				: null;
+		// Nothing is asked once the deadline has passed: a decision never shown is never made.
+		const res =
+			Date.now() < deadline
+				? await within(
+						api.decide(form.slot, counters.pin(form.slot), {
+							visitAudiences: claimed,
+							visitCampaign: form.arrived_from.length ? campaign() : null,
+							// Only for a form whose products are filled from it; never kept or logged by the server.
+							visitContext:
+								form.visit_context === true
+									? (access.visitContext?.() ?? null)
+									: null,
+							timeoutMs: deadline - Date.now(),
+						}),
+						deadline,
+						LATE,
+					)
+				: LATE;
+		// An answer without a list of decisions is a failed one; a list without the slot, no creative.
+		const decisions = res.status === 200 ? res.body?.decisions : null;
+		const decision = Array.isArray(decisions)
+			? decisions.find((d) => d?.slot === form.slot)
+			: null;
 		// The version this visit was shown in the form's A/B test, kept for the rest of it (ADR 0065).
 		if (decision?.experiment && decision.arm && decision.split)
 			counters.pin(form.slot, [
@@ -381,62 +481,59 @@ export function startOnsite(client, options = {}) {
 				!(basket > 0) &&
 				'the basket is empty');
 		if (missing) {
-			covering.delete(form.slot);
-			if (missing === 'the basket is empty') awaitingBasket.add(form);
-			return note(form, 'not shown', [missing]);
+			const empty = missing === 'the basket is empty';
+			if (empty) awaitingBasket.add(form);
+			return drop(form, 'not shown', empty ? 'empty-basket' : 'no-code', [
+				missing,
+			]);
 		}
 		awaitingBasket.delete(form);
 		if (!creative) {
+			const held = decision?.holdout === true;
 			// A held-out visitor whose trigger fired is exposed to the default, as a treated one is,
 			// and its page stays one with no popup: the allowance is spent as a shown one spends it.
-			if (decision?.holdout === true && access.analytics())
-				client.recordExposure(res.body);
-			covering.delete(form.slot);
-			if (covers && decision?.holdout === true) spent ??= form.slot;
+			if (held && access.analytics()) client.recordExposure(res.body);
+			if (covers && held) spent ??= form.slot;
 			// The site shows a held-out visitor what it shows without HP, at the same moment; a form
 			// the site opened hears so from `open`, which resolves false.
-			if (decision?.holdout === true && !asked)
+			if (held && !asked)
 				emit('held', {
 					slot: form.slot,
 					arm: decision.arm ?? null,
 					format: form.format,
 				});
-			return note(
-				form,
-				decision?.holdout === true ? 'held out' : 'no decision',
-				[
-					res.status === 200
-						? 'no creative for this visitor'
-						: `decisions answered ${res.status}`,
-				],
-			);
-		}
-		const render = await renderer;
-		if (!render) {
-			covering.delete(form.slot);
-			return note(form, 'not shown', ['the renderer did not load']);
+			if (held || Array.isArray(decisions))
+				return drop(
+					form,
+					held ? 'held out' : 'no decision',
+					held ? 'held-out' : 'no-creative',
+					['no creative for this visitor'],
+				);
+			return drop(form, 'no decision', 'decision-failed', [
+				`decisions answered ${res.status}`,
+			]);
 		}
+		const render = await within(renderer, deadline, null);
+		if (!render)
+			return drop(form, 'not shown', 'renderer-failed', [
+				'the renderer did not load',
+			]);
 		// Its products are drawn by their own chunk: without it the form would open on an empty block.
 		if (showsProducts(creative)) {
 			cards ??= loadProducts().catch(() => null);
-			if (!(await cards)) {
-				covering.delete(form.slot);
-				return note(form, 'not shown', ['its products did not load']);
-			}
+			if (!(await within(cards, deadline, null)))
+				return drop(form, 'not shown', 'products-failed', [
+					'its products did not load',
+				]);
 		}
 		// Its first step's pictures fetched and decoded first, so it never opens on an empty one, and
-		// never waits for them longer than WARM_MS.
-		await Promise.race([
+		// never waits for them longer than WARM_MS or past its deadline.
+		await within(
 			render.warm?.(form, creative, creative.steps[0].id, warmed),
-			new Promise((resolve) => setTimeout(resolve, WARM_MS)),
-		]);
-		if (suppressed()) {
-			covering.delete(form.slot);
-			return note(form, 'not shown', ['suppressed']);
-		}
-		if (!kept) counters.shown(form.slot);
-		if (interrupts) counters.covered();
-		if (covers) spent ??= form.slot;
+			Math.min(deadline, Date.now() + WARM_MS),
+		);
+		if (suppressed())
+			return drop(form, 'not shown', 'suppressed', ['suppressed']);
 		const tell = (name, detail = {}) =>
 			emit(name, {
 				slot: form.slot,
@@ -463,37 +560,71 @@ export function startOnsite(client, options = {}) {
 			onClose(why) {
 				mounted.delete(form.slot);
 				covering.delete(form.slot);
-				note(form, 'closed', [why]);
+				note(form, 'closed', 'closed', [why]);
 				tell('closed', { reason: why });
 			},
 		});
 		mounted.set(form.slot, handle);
+		// Counted once it is on screen, so a form that failed to open spends none of its caps.
+		if (!kept) counters.shown(form.slot);
+		if (interrupts) counters.covered();
+		if (covers) spent ??= form.slot;
 		if (access.analytics()) client.recordExposure(res.body);
-		note(form, 'shown', [reason]);
+		const result = note(form, 'shown', 'shown', [reason]);
 		tell('shown');
-		return 'shown';
+		return result;
 	}
 
 	/**
 	 * Triggers that fire within FIRE_WINDOW_MS of each other compete: only the highest priority shows.
 	 * One that cannot show passes to the next; a held-out visitor sees none, so the holdout stays clean.
+	 * They share one deadline. When none shows or is held out, the highest that HP had nothing for
+	 * (NOTHING), unless the site asked for it, says `nothing`: a site whose own popup HP's form
+	 * replaces shows its own there, and that spends the page view's allowance.
 	 */
 	function fire(form, reason, asked = ASKED(form)) {
 		if (!OVERLAY(form.format)) return show(form, reason, false, asked);
-		fired.push([form, reason, asked]);
-		if (fired.length > 1) return;
-		setTimeout(async () => {
-			const queue = fired.sort(([a], [b]) => byPriority(a, b));
-			fired = [];
-			for (const [i, [next, why, ask]] of queue.entries()) {
-				const state = await show(next, why, false, ask);
-				if (state === 'shown' || state === 'held out') {
-					for (const [f] of queue.slice(i + 1))
-						note(f, 'not shown', [`${next.slot} has a higher priority`]);
-					return;
-				}
+		if (!batch) {
+			// Set when the first trigger enters, so a timer the browser runs late takes none of it.
+			const fired = {
+				forms: [],
+				taken: new Set(),
+				deadline: Date.now() + FIRE_WINDOW_MS + DEADLINE_MS,
+			};
+			batch = fired;
+			windows.add(fired);
+			setTimeout(() => {
+				batch = null;
+				decideFired(fired);
+			}, FIRE_WINDOW_MS);
+		}
+		batch.forms.push([form, reason, asked]);
+	}
+
+	/**
+	 * The forms of one window, highest first, until one shows or is held out. A form the site opened
+	 * meanwhile (`taken`) is the site's: it gets no attempt here, and no `nothing`.
+	 */
+	async function decideFired(fired) {
+		const queue = fired.forms.sort(([a], [b]) => byPriority(a, b));
+		// The site takes the place of the highest that HP had nothing for, and only that one.
+		let missed = null;
+		for (const [i, [next, why, ask]] of queue.entries()) {
+			if (fired.taken.has(next)) continue;
+			const result = await show(next, why, false, ask, fired.deadline);
+			if (!missed && NOTHING.has(result.code) && !result.asked)
+				missed = [next, result.code];
+			if (result.state === 'shown' || result.state === 'held out') {
+				for (const [f] of queue.slice(i + 1))
+					note(f, 'not shown', 'lower-priority', [
+						`${next.slot} has a higher priority`,
+					]);
+				missed = null;
+				break;
 			}
-		}, FIRE_WINDOW_MS);
+		}
+		windows.delete(fired);
+		if (missed) say(...missed);
 	}
 
 	for (const form of forms) {
@@ -504,11 +635,12 @@ export function startOnsite(client, options = {}) {
 		}
 		const reasons = blockers(form, env(form));
 		if (reasons.length) {
-			note(form, 'not eligible', reasons);
+			note(form, 'not eligible', 'not-eligible', reasons);
 			continue;
 		}
 		const type = form.trigger.type;
-		if (type === 'manual') note(form, 'waiting for hp.onsite.open');
+		if (type === 'manual')
+			note(form, 'waiting for hp.onsite.open', 'waiting-for-open');
 		else if (type === 'inline' || form.format === 'inline')
 			show(form, 'inline');
 		else arm(form);
@@ -529,7 +661,7 @@ export function startOnsite(client, options = {}) {
 				{ device },
 			),
 		);
-		note(form, 'armed', [`${form.trigger.type} on ${device}`]);
+		note(form, 'armed', 'armed', [`${form.trigger.type} on ${device}`]);
 	}
 
 	// Once the banner is answered, a form that waited is armed again, so it opens at its trigger's
@@ -563,11 +695,14 @@ export function startOnsite(client, options = {}) {
 			if (!form) return Promise.resolve(false);
 			// One already on screen (an inline form) is shown, not mounted twice. A form opened by an
 			// alias is the shopper asking, as a `manual` one is.
-			return mounted.has(form.slot)
-				? Promise.resolve(true)
-				: show(form, 'manual', false, ASKED(form) || !keyed).then(
-						(state) => state === 'shown',
-					);
+			if (mounted.has(form.slot)) return Promise.resolve(true);
+			// The site's open takes the place of a trigger of the same form still in a window.
+			for (const fired of windows) fired.taken.add(form);
+			const opened = show(form, 'manual', false, ASKED(form) || !keyed);
+			// The site hears from this `open`, so the attempt it may have joined says no `nothing`.
+			const entry = opening.get(form.slot);
+			if (entry) entry.opened = true;
+			return opened.then(({ state }) => state === 'shown');
 		},
 		/** `hp.onsite.suppress`: take every form off the screen, quietly; none shows until unsuppressed. */
 		suppress() {
@@ -576,14 +711,15 @@ export function startOnsite(client, options = {}) {
 				mounted.delete(slot);
 				covering.delete(slot);
 				const form = forms.find((f) => f.slot === slot);
-				if (form) note(form, 'closed', ['suppressed']);
+				if (form) note(form, 'closed', 'suppressed', ['suppressed']);
 			}
 		},
 		/** Each form's state on this page and why, in settings order. */
 		debug: () =>
 			[...trace.values()].map((t) => ({ ...t, reasons: [...t.reasons] })),
-		/** Stop watching every trigger. A form on screen stays until it is closed. */
+		/** Stop watching every trigger, and say no `nothing` after. A form on screen stays until it is closed. */
 		stop() {
+			stopped = true;
 			for (const stop of stops.values()) stop();
 			stops.clear();
 			stopBasket?.();

package/src/onsite/preview.js

@@ -6,7 +6,7 @@
  * `device` picks the small-screen layout whatever the console's own width.
  */
 
-import { answerFields, answerOf } from './answers.js';
+import { answerCards, answerFields, answerOf, countdown } from './answers.js';
 import { mountProducts } from './products.js';
 import { mountForm } from './render.js';
 import { readCreative } from './rules.js';
@@ -67,7 +67,8 @@ export function mountPreview(host, creative, options = {}) {
 			api: null,
 			counters: inert,
 			loadWheel: () => Promise.resolve({ mountWheel }),
-			loadAnswers: () => Promise.resolve({ answerFields, answerOf }),
+			loadAnswers: () =>
+				Promise.resolve({ answerCards, answerFields, answerOf, countdown }),
 			loadProducts: () => Promise.resolve({ mountProducts }),
 			basket: () =>
 				Number.isFinite(opts.basketValue) ? opts.basketValue : SAMPLE_BASKET,