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

package/src/onsite/render.js

@@ -56,6 +56,8 @@ const COPY = {
 	claimed: 'This email address has already claimed its code.',
 	copied: 'Copied',
 	thanks: 'Thanks, you’re signed up',
+	retry: 'You’re signed up, but we couldn’t load your prize. Please try again.',
+	unclaimed: 'We couldn’t load your prize right now.',
 	unavailable: 'Not available right now.',
 	won: 'You won',
 };
@@ -404,6 +406,9 @@ export function mountForm(o) {
 		warmed: o.warmed ?? new Set(),
 		warming: false,
 		owed: false,
+		// Whether the last claim failed (said where the code would be), and how many spins it failed.
+		unclaimed: false,
+		misses: 0,
 		submitted: false,
 		pow: null,
 		wheel: null,
@@ -651,9 +656,19 @@ export function mountForm(o) {
 	function fillCodes() {
 		for (const box of state.codes) {
 			box.replaceChildren();
-			if (!state.claim) continue;
+			if (!state.claim) {
+				if (state.unclaimed) box.append(el('p', '', COPY.unclaimed));
+				continue;
+			}
 			if (!state.claim.code) {
-				box.append(el('p', '', state.claim.held ? COPY.claimed : COPY.code));
+				// A code still to come only when every pool was out (`fallback`); a prize with no pool
+				// ("Try again") gives none, so it says its own words and nothing about a code.
+				const said = state.claim.held
+					? COPY.claimed
+					: state.claim.fallback === true
+						? COPY.code
+						: state.claim.prize?.label;
+				if (said) box.append(el('p', '', said));
 				continue;
 			}
 			// The prize the code is for, beside it: "You won!" alone does not say what.
@@ -1206,6 +1221,7 @@ export function mountForm(o) {
 		if (channel === 'email')
 			state.signedUp = { email: value, email_receipt: state.receipt };
 		state.submitted = true;
+		// Subscribed and done with this form, whatever its claim does: a shopper is never asked twice.
 		counters.submitted(form.slot);
 		engaged('submit', step.id);
 		// A form with prizes claims its code now, whether or not the shopper goes on to spin, so the
@@ -1246,27 +1262,36 @@ export function mountForm(o) {
 	 * The creative's step `id`, else the SDK's own plain one: a thanks with no prize (`fallback`); a
 	 * code this browser claimed on another form, with that code (`held`); or, for an address another
 	 * sign-up claimed with (`held`, no code), a welcome back. That code is never shown here: the
-	 * sign-up hands it to the destinations again, so the inbox has it when one carries it.
+	 * sign-up hands it to the destinations again, so the inbox has it when one carries it. Or a claim
+	 * that kept failing (`unclaimed`): the sign-up stands and the prize could not be loaded, so it
+	 * thanks the shopper and says so, as Klaviyo's and Privy's wheels do, rather than an error.
 	 */
 	function ownStep(id) {
 		if (creative.steps.some((s) => s.id === id)) return id;
+		const shop = { t: 'button', label: COPY.shop, action: 'close' };
 		const blocks =
-			id === 'fallback' || state.claim?.code
+			id === 'unclaimed'
 				? [
-						{
-							t: 'heading',
-							text: id === 'fallback' ? COPY.thanks : COPY.yours,
-						},
-						{ t: 'code' },
+						{ t: 'heading', text: COPY.thanks },
+						{ t: 'text', text: COPY.unclaimed },
+						shop,
 					]
-				: [
-						{ t: 'heading', text: COPY.held },
-						{
-							t: 'text',
-							text: form.code_relayed === true ? COPY.resent : COPY.inbox,
-						},
-						{ t: 'button', label: COPY.shop, action: 'close' },
-					];
+				: id === 'fallback' || state.claim?.code
+					? [
+							{
+								t: 'heading',
+								text: id === 'fallback' ? COPY.thanks : COPY.yours,
+							},
+							{ t: 'code' },
+						]
+					: [
+							{ t: 'heading', text: COPY.held },
+							{
+								t: 'text',
+								text: form.code_relayed === true ? COPY.resent : COPY.inbox,
+							},
+							shop,
+						];
 		creative.steps.push({ id, blocks });
 		return id;
 	}
@@ -1284,6 +1309,7 @@ export function mountForm(o) {
 	function claim(retries = CLAIM_RETRY_MS) {
 		const receipt = state.receipt;
 		state.claiming ??= (async () => {
+			state.unclaimed = false;
 			let res;
 			for (const ms of [0, ...retries]) {
 				if (ms) await new Promise((r) => setTimeout(r, ms));
@@ -1302,6 +1328,8 @@ export function mountForm(o) {
 				// the page; any other failure is final until a spin asks again.
 				if (!retries.length && res.status === 503) return claim();
 				settled(null);
+				state.unclaimed = true;
+				if (!state.closed) fillCodes();
 				return null;
 			}
 			// The browser that claimed the code proved it is the shopper's when it won it: a held claim
@@ -1322,9 +1350,12 @@ export function mountForm(o) {
 		busy(true);
 		const won = await claim();
 		if (state.closed) return;
+		// The sign-up stands whatever the claim did: a failed one is offered once more, then the
+		// shopper is thanked and told the prize could not be loaded, never left on an error.
 		if (!won) {
 			busy(false);
-			return say(COPY.failed);
+			state.misses += 1;
+			return state.misses < 2 ? say(COPY.retry) : show(ownStep('unclaimed'));
 		}
 		const fallback = won.fallback === true && !won.code;
 		// A code the address claimed on another form is that form's prize: the wheel lands only on

package/src/onsite/styles.js

@@ -145,7 +145,7 @@ hr{width:100%;margin:4px 0;border:0;border-top:1px solid var(--ln)}
 .hd{display:none}
 .uc h2{text-transform:uppercase;font-weight:800;letter-spacing:-.01em;line-height:1.02}
 .uc .btn:not(.no),.uc .tb{text-transform:uppercase;letter-spacing:.06em}
-.sheet,.bar,.teaser{position:fixed;inset:auto;z-index:2147483646;display:flex;flex-direction:column}
+.sheet,.bar,.teaser{position:fixed;inset:auto;height:auto;z-index:2147483646;display:flex;flex-direction:column}
 .sheet{right:24px;bottom:24px;width:min(400px,calc(100% - 32px));max-height:calc(100% - 48px)}
 .sheet.p-bottom-left{right:auto;left:24px}
 .sheet.p-bottom{right:auto;left:50%;translate:-50% 0}

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/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/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',

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

package/types/bootstrap.d.ts

@@ -165,8 +165,9 @@ export interface BootstrappedClient extends AnalyticsClient {
 }
 
 /**
- * The client, or null when the key is not enabled, the settings cannot be fetched on a first
- * visit, or the options are invalid. Never rejects. Idempotent per page.
+ * The client, or null when the key is not enabled or the options are invalid. Settings that cannot
+ * be fetched on a first visit start it on built-in, collect-only defaults (3.25). Never rejects.
+ * Idempotent per page.
  */
 export declare function bootstrap(
 	config: HpConfig,

package/types/hp.d.ts

@@ -35,8 +35,9 @@ interface HpTrack {
 /**
  * The page's client, callable from anywhere: calls made before `bootstrap` has started it wait and
  * replay in order, keeping the messageId and time they were made with; on a page that turns out to
- * be off they are dropped. A page that navigates first, or never reaches the API, carries them to the
- * next page, which sends them under its own consent (3.9, 3.9.1). Nothing is returned (but by
+ * be off they are dropped. A page that navigates first carries them to the next page, which sends
+ * them under its own consent (3.9); one that cannot reach the API starts on built-in settings and
+ * sends them itself (3.25). Nothing is returned (but by
  * `assignmentDecisionId` and `recommendationContext`), nothing is awaited, and nothing ever throws
  * into the caller.
  */

package/types/index.d.ts

@@ -119,7 +119,8 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	apiHost?: string;
 	/** Default 'web'. */
 	writeKey?: string;
-	propertyId: string | number;
+	/** null: none on the wire, and the ingest stamps the key's (a key scoped to one property). */
+	propertyId: string | number | null;
 	channel?: string | null;
 	market?: string | null;
 	environment?: string | null;
@@ -200,7 +201,7 @@ export interface AnalyticsOptions extends AnalyticsContextSources {
 	mintAnonymousId?: boolean;
 	/**
 	 * Strict consent: carry events held for an unanswered CMP across a navigation, in sessionStorage
-	 * per property (`thg_hp_held`), so a redirect before the answer (a sign-in) does not lose them.
+	 * per write key (`thg_hp_held`), so a redirect before the answer (a sign-in) does not lose them.
 	 * They leave only on a grant, on whichever page it comes, and are deleted on a refusal or after
 	 * 30 minutes. This writes event data to the device before the visitor has answered: enable it
 	 * only where your consent policy allows that. With bootstrap it also lets `hp` carry calls made
@@ -466,7 +467,7 @@ export interface StorageNames {
 	decisions?: string;
 	/** localStorage. Default 'thg_hp_settings'. */
 	settings?: string;
-	/** sessionStorage, with holdAcrossPages. Default 'thg_hp_held'. */
+	/** sessionStorage, per write key, with holdAcrossPages. Default 'thg_hp_held'. */
 	held?: string;
 	/** sessionStorage: `hp` calls carried to the next page (3.9). Default 'thg_hp_carried'. */
 	carried?: string;