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

package/src/consent-gate.js

@@ -98,7 +98,8 @@ function previousFromCookie(name) {
  * @param {boolean} [options.debug]
  * @param {{ read: () => any[], write: (items: any[]) => void }} [options.store]
  *   Carry held items across pages (`holdAcrossPages`). Read on start, so a grant on the next page
- *   releases what the previous one held; cleared on a grant or a refusal, never at unload.
+ *   releases what the previous one held; written when the page is hidden, cleared on a grant or a
+ *   refusal.
  */
 export function createConsentGate(options) {
 	const {
@@ -240,9 +241,12 @@ export function createConsentGate(options) {
 	 */
 	function onHidden(event) {
 		if (!awaitingAnswer()) return;
-		// With a store, the stored copy is what the next page answers for: the end of this one
-		// discards nothing.
-		if (store) return;
+		// With a store, the stored copy is what the next page answers for: written here, once, rather
+		// than on every held event, and the end of this page discards nothing.
+		if (store) {
+			store.write(held);
+			return;
+		}
 		if (event?.type !== 'visibilitychange' && !event?.persisted) discardHeld();
 	}
 
@@ -297,7 +301,6 @@ export function createConsentGate(options) {
 				return false;
 			}
 			held.push(item);
-			store?.write(held);
 			return true;
 		},
 		/** Items unload would lose; the caller's own unload path flushes after this. */

package/src/context.js

@@ -344,7 +344,8 @@ export const CONTEXT_KEYS = [
 
 export function sourceContext(cfg) {
 	return {
-		property_id: String(cfg.propertyId),
+		// None known (BUILT_IN settings): the ingest stamps the key's.
+		...(cfg.propertyId == null ? {} : { property_id: String(cfg.propertyId) }),
 		channel: cfg.channel ?? null,
 		market: cfg.market ?? null,
 		environment: cfg.environment ?? null,

package/src/device-storage.js

@@ -2,9 +2,9 @@
  * Two device writes beyond the SDK's own buffers.
  *
  *   held store     events the consent gate holds for an unanswered CMP, in sessionStorage per
- *                  property, so a navigation before the answer (a sign-in redirect) does not lose
- *                  them (`holdAcrossPages`, 3.5). They leave only on a grant, on whichever page it
- *                  comes; a refusal deletes them.
+ *                  write key, so a navigation before the answer (a sign-in redirect) does not lose
+ *                  them (`holdAcrossPages`, 3.5). They leave only on a
+ *                  grant, on whichever page it comes; a refusal deletes them.
  *   device cookie  Hyper-Personalisation's device id, for a source whose settings say `hp_cookie`
  *                  (3.6). Under strict consent it is written only once analytics is granted.
  */
@@ -33,7 +33,7 @@ const local = () => {
 };
 
 /**
- * @param {string} key  A property-scoped key (storageKey(storageName('held'), propertyId)).
+ * @param {string} key  A write-key-scoped key (storageKey(storageName('held'), writeKey)).
  * @param {() => number} [now]
  */
 export function createHeldStore(key, now = () => Date.now()) {

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([
@@ -115,6 +123,10 @@ export { emailSha256, getCookie };
 
 /** How a call made before the SDK started is replayed with the messageId and time it was made at. */
 const REPLAY = Symbol.for('@thg-agentic/hyper-personalisation-web.replay');
+/** How bootstrap tells the client its API could not be reached. Not public API. */
+const UNREACHABLE = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.unreachable',
+);
 /** How ./onsite reads what it needs from a client it was handed. Not public API. */
 const ONSITE_ACCESS = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite-access',
@@ -309,14 +321,65 @@ function contextOverrides(options) {
 	return options;
 }
 
+/**
+ * Before 3.25 the retry buffer and the held store were per property. What a 3.24 page kept there
+ * moves to this write key's, oldest first, and the old key goes: the batches keep their messageIds
+ * and are replayed as any other, under the same consent rules.
+ */
+function adoptPropertyScopedBuffers(propertyId, writeKey) {
+	if (propertyId == null || String(propertyId) === writeKey) return;
+	const moves = [
+		[
+			'localStorage',
+			'retry',
+			(old, current) => [
+				...(Array.isArray(old) ? old : []),
+				...(Array.isArray(current) ? current : []),
+			],
+		],
+		[
+			'sessionStorage',
+			'held',
+			(old, current) =>
+				current
+					? {
+							...current,
+							items: [...(old.items ?? []), ...(current.items ?? [])],
+						}
+					: old,
+		],
+	];
+	for (const [store, name, merge] of moves) {
+		try {
+			const storage = globalThis[store];
+			const from = storageKey(storageName(name), propertyId);
+			const raw = storage?.getItem(from);
+			if (!raw) continue;
+			const to = storageKey(storageName(name), writeKey);
+			const current = storage.getItem(to);
+			storage.setItem(
+				to,
+				JSON.stringify(
+					merge(JSON.parse(raw), current ? JSON.parse(current) : null),
+				),
+			);
+			storage.removeItem(from);
+		} catch {
+			/* unreadable or full: left where it was */
+		}
+	}
+}
+
 export function createAnalytics(options) {
 	const apiHost = resolveApiHost(options?.apiHost);
 	if (!apiHost)
 		throw new Error(
 			'createAnalytics: apiHost, when given, must be a host or an http(s) origin',
 		);
-	if (!options?.propertyId)
-		throw new Error('createAnalytics: propertyId is required');
+	if (options?.propertyId !== null && !options?.propertyId)
+		throw new Error(
+			'createAnalytics: propertyId is required (null: the ingest stamps the key’s)',
+		);
 
 	const cfg = {
 		libraryName: LIB,
@@ -341,10 +404,12 @@ export function createAnalytics(options) {
 	cfg.getConsent = () => (gate ? gate.stamp() : hostConsent());
 	const granted = () => !strict || gate?.status === 'granted';
 
-	// Opt-in (3.5): events held for an unanswered CMP survive a navigation, in sessionStorage.
+	adoptPropertyScopedBuffers(cfg.propertyId, cfg.writeKey);
+	// Opt-in (3.5): events held for an unanswered CMP survive a navigation, in sessionStorage. Per
+	// write key, as the retry buffer: what they are sent with.
 	const heldStore =
 		strict && cfg.holdAcrossPages
-			? createHeldStore(storageKey(storageName('held'), cfg.propertyId))
+			? createHeldStore(storageKey(storageName('held'), cfg.writeKey))
 			: null;
 	const carried = heldStore?.read() ?? { items: [], anonymousId: null };
 
@@ -369,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) =>
@@ -379,9 +466,9 @@ export function createAnalytics(options) {
 		new Transport({
 			apiHost: cfg.apiHost,
 			writeKey: cfg.writeKey,
-			// Per tenant: a persisted batch is replayed through whichever instance starts next, with its
-			// writeKey, and one origin can serve several tenants.
-			storageKey: storageKey(storageName('retry'), cfg.propertyId),
+			// Per write key, which a replay is sent with: one origin can serve several tenants, and a page
+			// started without its property (BUILT_IN settings) is replayed by the next one, which has it.
+			storageKey: storageKey(storageName('retry'), cfg.writeKey),
 			// Under strict consent, persisting is a device write and replaying is a send: both wait for a
 			// grant (see onStatus below, which replays on a grant and clears on a refusal).
 			mayPersist: strict ? () => gate?.status === 'granted' : undefined,
@@ -432,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;
@@ -464,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) {
@@ -608,6 +702,7 @@ export function createAnalytics(options) {
 		exposedTokens.clear();
 		device?.forget();
 		forgetKeptVisit(true);
+		clearVisitCampaign();
 	}
 
 	function deliver(event, force) {
@@ -644,6 +739,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,
@@ -701,7 +798,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',
@@ -715,6 +815,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. */
@@ -802,6 +904,7 @@ export function createAnalytics(options) {
 		userId = null;
 		identifiedUserId = null;
 		optionsUserId = null;
+		identityToken = null;
 		return event;
 	}
 
@@ -846,8 +949,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) {
@@ -867,10 +979,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,
 			);
 		},
 
@@ -884,6 +998,7 @@ export function createAnalytics(options) {
 			userId = null;
 			identifiedUserId = null;
 			optionsUserId = null;
+			identityToken = null;
 			writeLastPageMessageId('');
 		},
 
@@ -1063,6 +1178,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(),
@@ -1072,6 +1189,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.
@@ -1080,6 +1202,12 @@ 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. */
+				sessionSignals: () => {
+					if (!personalisationGranted()) return null;
+					scopeVisit();
+					return getSessionSignals();
+				},
 				/** Calls `listener` whenever the page reports its basket; answers how to stop. */
 				onBasket: (listener) => {
 					basketListeners.add(listener);
@@ -1098,6 +1226,10 @@ export function createAnalytics(options) {
 				},
 			};
 		},
+		/** bootstrap: the settings could not be fetched, so the ingest on the same host is taken as down. */
+		[UNREACHABLE]() {
+			transport.markFailing?.();
+		},
 		/** `hp` and bootstrap replay a call made before the start through this. Not public API. */
 		[REPLAY](method, args, made) {
 			if (typeof this[method] !== 'function') return;

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