@thg-agentic/hyper-personalisation-web 0.0.0-stage → 3.18.0

package/src/auto/promotions.js

@@ -0,0 +1,104 @@
+import { firstAttr } from './attributes.js';
+import {
+	DEFAULT_DWELL_MS,
+	DEFAULT_VISIBLE_RATIO,
+	watchViewability,
+} from './viewability.js';
+
+/** Read a promotion off its `data-hp-promotion*` attributes. */
+function defaultResolve(el, index) {
+	const promotionId = firstAttr(el, 'hpPromotion');
+	if (!promotionId) return null;
+
+	return {
+		promotion_id: promotionId,
+		name: firstAttr(el, 'hpPromotionName'),
+		creative: firstAttr(el, 'hpPromotionCreative'),
+		// Segment's `position` (GA4 calls it creative_slot): a named slot, or the 1-based rank down
+		// the page as a string.
+		position: firstAttr(el, 'hpPromotionSlot') ?? String(index + 1),
+	};
+}
+
+/**
+ * Watch promotional slots and report impressions and clicks.
+ *
+ * @param {object} analytics An SDK instance from createAnalytics.
+ * @param {object} [options]
+ * @param {string} [options.selector] Which elements are promotional slots.
+ * @param {(el: Element, index: number) => object|null} [options.resolve] Element -> spec fields.
+ *   Returning null skips the element, which is how a slot with no stable id opts out.
+ * @param {number} [options.visibleRatio] Fraction on screen that counts as visible.
+ * @param {number} [options.dwellMs] How long it must stay visible.
+ * @param {Document|Element} [options.root] Where to look. Defaults to the document.
+ * @returns {() => void} Teardown, for a SPA route change.
+ */
+export function trackPromotions(analytics, options = {}) {
+	if (typeof window === 'undefined' || typeof document === 'undefined')
+		return () => {};
+
+	const {
+		selector = '[data-hp-promotion]',
+		resolve = defaultResolve,
+		visibleRatio = DEFAULT_VISIBLE_RATIO,
+		dwellMs = DEFAULT_DWELL_MS,
+		root = document,
+	} = options;
+
+	// Keyed by promotion id, not element: a re-rendered carousel replaces the node, not the banner.
+	const seen = new Set();
+
+	const fieldsFor = (el) => {
+		// Ranked among the slots in the document now, in document order.
+		const all = Array.from(root.querySelectorAll(selector));
+		const index = all.indexOf(el);
+		try {
+			return resolve(el, index < 0 ? all.length : index);
+		} catch {
+			// A resolver that throws on one odd slot must not stop the rest of the page reporting.
+			return null;
+		}
+	};
+
+	const stopWatching = watchViewability({
+		selector,
+		root,
+		visibleRatio,
+		dwellMs,
+		onViewable(el) {
+			const fields = fieldsFor(el);
+			if (!fields || seen.has(fields.promotion_id)) return false;
+			seen.add(fields.promotion_id);
+			analytics.promotionViewed(fields);
+			return true;
+		},
+	});
+
+	// Capture phase: banner components often stopPropagation, which would hide them from a bubble
+	// listener. Only a link is a click-through: a slider's arrows, a tab or a video's play button
+	// inside the slot are not.
+	const onClick = (event) => {
+		const target = event.target;
+		if (!target || typeof target.closest !== 'function') return;
+		const el = target.closest(selector);
+		const anchor = target.closest('a[href]');
+		if (!el || !anchor) return;
+		// The link must belong to the slot: inside it, or wrapping it.
+		if (!el.contains(anchor) && !anchor.contains(el)) return;
+
+		const fields = fieldsFor(el);
+		if (!fields) return;
+
+		analytics.promotionClicked({
+			...fields,
+			href: anchor.getAttribute('href'),
+		});
+	};
+
+	document.addEventListener('click', onClick, true);
+
+	return () => {
+		document.removeEventListener('click', onClick, true);
+		stopWatching();
+	};
+}

package/src/auto/rails.js

@@ -0,0 +1,217 @@
+import { firstAttr, intAttr } from './attributes.js';
+import {
+	DEFAULT_DWELL_MS,
+	DEFAULT_VISIBLE_RATIO,
+	watchViewability,
+} from './viewability.js';
+
+/**
+ * Read a rail's serving metadata off its container. A rail missing its request id, placement or
+ * strategy is skipped: a placeholder would validate and silently corrupt the join.
+ */
+function defaultResolveRail(el) {
+	const requestId = firstAttr(el, 'hpRecoRequest');
+	const placement = firstAttr(el, 'hpRecoPlacement');
+	const strategy = firstAttr(el, 'hpRecoStrategy');
+	if (!requestId || !placement || !strategy) return null;
+
+	const holdout = firstAttr(el, 'hpRecoHoldout');
+
+	return {
+		recommendation_request_id: requestId,
+		placement,
+		strategy,
+		recipe: firstAttr(el, 'hpRecoRecipe'),
+		algorithm_version: firstAttr(el, 'hpRecoAlgorithmVersion'),
+		experiment: firstAttr(el, 'hpRecoExperiment'),
+		variant: firstAttr(el, 'hpRecoVariant'),
+		// Absent means no holdout is running, not the treated arm, so it is not defaulted to false.
+		holdout: holdout === null ? null : holdout === 'true',
+		assignment_bucket: intAttr(el, 'hpRecoBucket'),
+		assignment_unit_kind: firstAttr(el, 'hpRecoUnitKind'),
+		candidate_set_fingerprint: firstAttr(el, 'hpRecoFingerprint'),
+		candidate_set_size: intAttr(el, 'hpRecoCandidates'),
+		ranked_by: firstAttr(el, 'hpRecoRankedBy'),
+		served_at: firstAttr(el, 'hpRecoServedAt'),
+	};
+}
+
+/**
+ * Read one tile of a rail. `position` falls back to DOM order within the rail; stamp it where a
+ * carousel positions tiles with CSS.
+ */
+function defaultResolveTile(el, index) {
+	const productId = firstAttr(el, 'hpRecoProduct');
+	if (!productId) return null;
+
+	const price = firstAttr(el, 'hpRecoPrice');
+	return {
+		product_id: productId,
+		sku: firstAttr(el, 'hpRecoSku'),
+		name: firstAttr(el, 'hpRecoName'),
+		brand: firstAttr(el, 'hpRecoBrand'),
+		price: price === null || Number.isNaN(Number(price)) ? null : Number(price),
+		position: intAttr(el, 'hpRecoPosition') ?? index + 1,
+	};
+}
+
+/**
+ * Watch recommendation rails and report the impression and the clicks that came out of it.
+ *
+ * One Recommendations Viewed per rail (per request id), fired when its first tile meets the
+ * viewability standard, or before the first click on one of its tiles if that comes sooner,
+ * carrying the whole ordered list. The emit is deferred one turn so tiles
+ * that became viewable together all land in `viewable`, which is a lower bound: tiles swiped in
+ * later are not added.
+ *
+ * @param {object} analytics An SDK instance from createAnalytics.
+ * @param {object} [options]
+ * @param {string} [options.selector] Which elements are recommendation rails.
+ * @param {string} [options.tileSelector] Which elements inside a rail are product tiles.
+ * @param {(el: Element) => object|null} [options.resolveRail] Rail element -> spec fields.
+ * @param {(el: Element, index: number) => object|null} [options.resolveTile] Tile -> product.
+ * @param {number} [options.visibleRatio]
+ * @param {number} [options.dwellMs]
+ * @param {Document|Element} [options.root]
+ * @returns {() => void} Teardown.
+ */
+export function trackRecommendationRails(analytics, options = {}) {
+	if (typeof window === 'undefined' || typeof document === 'undefined')
+		return () => {};
+
+	const {
+		selector = '[data-hp-reco-request]',
+		tileSelector = '[data-hp-reco-product]',
+		resolveRail = defaultResolveRail,
+		resolveTile = defaultResolveTile,
+		visibleRatio = DEFAULT_VISIBLE_RATIO,
+		dwellMs = DEFAULT_DWELL_MS,
+		root = document,
+	} = options;
+
+	// Keyed by request id, which survives a re-render and a rail duplicated into a sticky header.
+	const reported = new Set();
+	/** request id -> position -> viewable entry, so a tile counts once at its own rank. */
+	const viewableByRail = new Map();
+	/** request id -> deferred emit, so simultaneously-viewable tiles land on one event. */
+	const scheduled = new Map();
+
+	const safely = (fn, ...args) => {
+		try {
+			return fn(...args);
+		} catch {
+			// A resolver that throws on one odd rail must not stop the rest of the page reporting.
+			return null;
+		}
+	};
+
+	const railFor = (el) =>
+		typeof el.closest === 'function' ? el.closest(selector) : null;
+
+	const tilesOf = (rail) => Array.from(rail.querySelectorAll(tileSelector));
+
+	const emit = (rail, fields) => {
+		scheduled.delete(fields.recommendation_request_id);
+		if (reported.has(fields.recommendation_request_id)) return;
+
+		const products = tilesOf(rail)
+			.map((tile, i) => safely(resolveTile, tile, i))
+			.filter((p) => p?.product_id);
+		// An empty `products` would fail validation at the ingest.
+		if (products.length === 0) return;
+
+		reported.add(fields.recommendation_request_id);
+
+		const viewable = [
+			...(viewableByRail.get(fields.recommendation_request_id)?.values() ?? []),
+		].sort((a, b) => a.position - b.position);
+
+		analytics.recommendationsViewed({ ...fields, products, viewable });
+	};
+
+	const stopWatching = watchViewability({
+		// Tiles inside a rail only, so a listing grid on the same page is never counted as exposure.
+		selector: `${selector} ${tileSelector}`,
+		root,
+		visibleRatio,
+		dwellMs,
+		onViewable(tile) {
+			const rail = railFor(tile);
+			if (!rail) return true;
+
+			const fields = safely(resolveRail, rail);
+			if (!fields) return true;
+
+			const requestId = fields.recommendation_request_id;
+			const product = safely(resolveTile, tile, tilesOf(rail).indexOf(tile));
+			if (product?.product_id) {
+				if (!viewableByRail.has(requestId))
+					viewableByRail.set(requestId, new Map());
+				const entries = viewableByRail.get(requestId);
+				if (!entries.has(product.position)) {
+					entries.set(product.position, {
+						position: product.position,
+						product_id: product.product_id,
+						viewable_at: new Date().toISOString(),
+					});
+				}
+			}
+
+			if (!reported.has(requestId) && !scheduled.has(requestId)) {
+				scheduled.set(
+					requestId,
+					setTimeout(() => emit(rail, fields), 0),
+				);
+			}
+			return true;
+		},
+	});
+
+	// Capture phase, as for promotions. Reported as Product Clicked carrying the request id, which
+	// says which ranked list the click came out of. A click counts when it follows a link in the
+	// tile, or lands on an affordance the markup names (`data-hp-reco-interaction="quick_buy"`); a
+	// wishlist heart or a carousel arrow is neither.
+	const onClick = (event) => {
+		const target = event.target;
+		if (!target || typeof target.closest !== 'function') return;
+		const tile = target.closest(tileSelector);
+		if (!tile) return;
+		const tagged = target.closest('[data-hp-reco-interaction]');
+		const anchor = target.closest('a[href]');
+		const onLink = anchor && (tile.contains(anchor) || anchor.contains(tile));
+		if (!(tagged && tile.contains(tagged)) && !onLink) return;
+		const rail = railFor(tile);
+		if (!rail) return;
+
+		const fields = safely(resolveRail, rail);
+		if (!fields) return;
+		const product = safely(resolveTile, tile, tilesOf(rail).indexOf(tile));
+		if (!product?.product_id) return;
+
+		// A click is proof the rail was seen, even when it came before the dwell did (a quick scroll
+		// and a tap). Its impression goes first, or the click names a request id no impression
+		// carries and joins nothing: the gap recommendation_exposure's click check fails on.
+		const requestId = fields.recommendation_request_id;
+		if (!reported.has(requestId)) {
+			clearTimeout(scheduled.get(requestId));
+			emit(rail, fields);
+		}
+
+		// No list_id: the spec keeps it for listings, and the request id is what joins the click to
+		// its rail's impression.
+		analytics.productClicked({
+			recommendation_request_id: fields.recommendation_request_id,
+			interaction: firstAttr(tagged ?? tile, 'hpRecoInteraction') ?? 'navigate',
+			products: [product],
+		});
+	};
+
+	document.addEventListener('click', onClick, true);
+
+	return () => {
+		document.removeEventListener('click', onClick, true);
+		for (const timer of scheduled.values()) clearTimeout(timer);
+		scheduled.clear();
+		stopWatching();
+	};
+}

package/src/auto/viewability.js

@@ -0,0 +1,150 @@
+/**
+ * 50% of pixels for one continuous second: the MRC/IAB Viewable Ad Impression standard.
+ * https://www.iab.com/wp-content/uploads/2015/06/MRC-Viewable-Ad-Impression-Measurement-Guideline.pdf
+ * The standard's 30% relaxation for large creatives is not implemented; 50% never overstates.
+ */
+export const DEFAULT_VISIBLE_RATIO = 0.5;
+export const DEFAULT_DWELL_MS = 1000;
+
+/** Callbacks at every tenth, so a ratio measured against the viewport is re-checked as it changes. */
+const THRESHOLDS = Array.from({ length: 11 }, (_, i) => i / 10);
+
+/**
+ * Whether enough of an element is on screen. The share is of the element or of the viewport,
+ * whichever is smaller: half of a widget taller than two screens can never be visible, so measured
+ * against itself it could never count as seen while its clicks still would.
+ */
+function meetsRatio(entry, visibleRatio) {
+	if (!entry.isIntersecting) return false;
+	const {
+		intersectionRect: seen,
+		boundingClientRect: box,
+		rootBounds: screen,
+	} = entry;
+	if (!seen || !box) return true;
+	const shown = seen.width * seen.height;
+	const whole = box.width * box.height;
+	const fits = screen ? Math.min(whole, screen.width * screen.height) : whole;
+	return fits > 0 && shown / fits >= visibleRatio;
+}
+
+/**
+ * The viewability engine, shared by every impression this module reports so they all use one
+ * definition of "seen".
+ *
+ * @param {object} options
+ * @param {string} options.selector Which elements to watch.
+ * @param {(el: Element) => boolean} options.onViewable Called when an element meets the standard.
+ *   Return true to stop watching the element.
+ * @param {number} [options.visibleRatio]
+ * @param {number} [options.dwellMs]
+ * @param {Document|Element} [options.root]
+ * @returns {() => void} Teardown.
+ */
+export function watchViewability(options) {
+	const {
+		selector,
+		onViewable,
+		visibleRatio = DEFAULT_VISIBLE_RATIO,
+		dwellMs = DEFAULT_DWELL_MS,
+		root = document,
+	} = options;
+
+	const pending = new Map();
+	const watched = new WeakSet();
+	/** Elements currently intersecting, so tab focus changes can restart their clocks. */
+	const visible = new Set();
+
+	// Anything that interrupts visibility clears the timer, so the dwell must be continuous.
+	const beginDwell = (el) => {
+		if (pending.has(el)) return;
+		pending.set(
+			el,
+			setTimeout(() => {
+				pending.delete(el);
+				if (onViewable(el)) {
+					impressionObserver?.unobserve(el);
+					visible.delete(el);
+				}
+			}, dwellMs),
+		);
+	};
+
+	const cancelDwell = (el) => {
+		clearTimeout(pending.get(el));
+		pending.delete(el);
+	};
+
+	const impressionObserver =
+		typeof IntersectionObserver === 'undefined'
+			? null
+			: new IntersectionObserver(
+					(entries) => {
+						for (const entry of entries) {
+							const el = entry.target;
+							if (!meetsRatio(entry, visibleRatio)) {
+								visible.delete(el);
+								cancelDwell(el);
+								continue;
+							}
+							visible.add(el);
+							if (!isTabVisible()) continue;
+							beginDwell(el);
+						}
+					},
+					{ threshold: THRESHOLDS },
+				);
+
+	// IntersectionObserver ignores whether the tab is frontmost; the MRC standard requires a visible
+	// tab. Clocks are cancelled on hide and restarted on show.
+	const isTabVisible = () =>
+		typeof document === 'undefined' || document.visibilityState !== 'hidden';
+
+	const onVisibilityChange = () => {
+		if (isTabVisible()) {
+			for (const el of visible) beginDwell(el);
+		} else {
+			for (const el of visible) cancelDwell(el);
+		}
+	};
+
+	document.addEventListener('visibilitychange', onVisibilityChange);
+
+	const scan = () => {
+		for (const el of root.querySelectorAll(selector)) {
+			if (watched.has(el)) continue;
+			watched.add(el);
+			impressionObserver?.observe(el);
+		}
+	};
+
+	// Widgets hydrate and lazy-load after this runs (a recommendation rail always does), so re-scan
+	// on every DOM change.
+	const mutationObserver =
+		typeof MutationObserver === 'undefined'
+			? null
+			: new MutationObserver(() => scan());
+
+	const begin = () => {
+		scan();
+		mutationObserver?.observe(root === document ? document.body : root, {
+			childList: true,
+			subtree: true,
+		});
+	};
+	// Started from <head> (a cached bootstrap, a synchronous tag) there is no body to watch yet.
+	const beforeBody = root === document && !document.body;
+	if (beforeBody)
+		document.addEventListener('DOMContentLoaded', begin, { once: true });
+	else begin();
+
+	return () => {
+		if (beforeBody) document.removeEventListener('DOMContentLoaded', begin);
+		document.removeEventListener('visibilitychange', onVisibilityChange);
+		impressionObserver?.disconnect();
+		mutationObserver?.disconnect();
+		for (const timer of pending.values()) clearTimeout(timer);
+		pending.clear();
+		visible.clear();
+	};
+}

package/src/auto.js

@@ -0,0 +1,13 @@
+/**
+ * Declarative auto-instrumentation: the events you can get from markup alone.
+ *
+ * Promotion and recommendation impressions never reach a server, so the browser must report them.
+ * Slots describe themselves in the DOM and one observer reads them; `selector` and `resolve` let a
+ * host point it at its own attribute convention. A slot with no resolvable id is skipped rather
+ * than given a generated one, which would make impressions and clicks unjoinable.
+ */
+
+export { trackExposures } from './auto/exposures.js';
+export { trackProductLists } from './auto/lists.js';
+export { trackPromotions } from './auto/promotions.js';
+export { trackRecommendationRails } from './auto/rails.js';