@webority/analytics 0.3.0 → 0.5.0

package/dist/webority-analytics-site.global.js

@@ -0,0 +1 @@
+var WeborityAnalytics=(()=>{var m=Object.defineProperty;var M=Object.getOwnPropertyDescriptor;var $=Object.getOwnPropertyNames;var j=Object.prototype.hasOwnProperty;var G=(t,e)=>{for(var n in e)m(t,n,{get:e[n],enumerable:!0})},K=(t,e,n,o)=>{if(e&&typeof e=="object"||typeof e=="function")for(let r of $(e))!j.call(t,r)&&r!==n&&m(t,r,{get:()=>e[r],enumerable:!(o=M(e,r))||o.enumerable});return t};var P=t=>K(m({},"__esModule",{value:!0}),t);var ct={};G(ct,{CONSENT_CHANGE_EVENT:()=>y,CONSENT_COOKIE_NAME:()=>u,captureAttribution:()=>x,getAttribution:()=>R,getConsent:()=>a,initConsent:()=>N,loadTags:()=>q,onConsentChange:()=>c,requiresOptIn:()=>b,saveConsent:()=>L});var p=Object.freeze(["AT","BE","BG","HR","CY","CZ","DK","EE","FI","FR","DE","GR","HU","IE","IT","LV","LT","LU","MT","NL","PL","PT","RO","SK","SI","ES","SE","IS","LI","NO","GB","CH"]);function b(t){let e=typeof t=="string"?t.trim().toUpperCase():"";return e.length!==2||e==="XX"||e==="T1"?!0:p.includes(e)}var u="webority_cookie_consent",y="webority-consent-change",H=365,i={initialized:!1,requiresOptIn:!0,cookieDomain:null,saved:null},g=new Set;function N(t){if(typeof t?.requiresOptIn!="boolean")throw new Error("@webority/analytics: initConsent needs requiresOptIn (true or false), decided from the visitor's country.");if(t.cookieDomain!==void 0&&(typeof t.cookieDomain!="string"||!t.cookieDomain.trim()))throw new Error('@webority/analytics: initConsent cookieDomain must be a domain such as ".example.com", or left out.');i.initialized=!0,i.requiresOptIn=t.requiresOptIn,i.cookieDomain=t.cookieDomain?.trim()??null,i.saved=X(),B(),i.saved&&v(i.saved)}function l(){return i.initialized}function a(){k("getConsent");let t=i.saved;if(t)return{essential:!0,analytics:t.analytics,functional:t.functional,marketing:t.marketing,decided:!0};let e=!i.requiresOptIn;return{essential:!0,analytics:e,functional:e,marketing:e,decided:!1}}function L(t){k("saveConsent");let e={essential:!0,analytics:t?.analytics===!0,functional:t?.functional===!0,marketing:t?.marketing===!0,timestamp:new Date().toISOString()};J(e),i.saved=e,v(e),Y(a())}function c(t){return g.add(t),()=>g.delete(t)}function Y(t){for(let e of g)try{e(t)}catch(n){queueMicrotask(()=>{throw n})}typeof window?.dispatchEvent=="function"&&typeof CustomEvent=="function"&&window.dispatchEvent(new CustomEvent(y,{detail:t}))}function k(t){if(!i.initialized)throw new Error(`@webority/analytics: call initConsent before ${t}.`)}function w(){window.dataLayer=window.dataLayer||[],window.dataLayer.push(arguments)}function B(){w("consent","default",{ad_storage:"denied",ad_user_data:"denied",ad_personalization:"denied",analytics_storage:"denied",functionality_storage:"denied",personalization_storage:"denied",security_storage:"granted",wait_for_update:500,region:[...p]}),w("consent","default",{ad_storage:"granted",ad_user_data:"granted",ad_personalization:"granted",analytics_storage:"granted",functionality_storage:"granted",personalization_storage:"granted",security_storage:"granted"})}function v(t){let e=n=>n?"granted":"denied";w("consent","update",{analytics_storage:e(t.analytics),functionality_storage:e(t.functional),personalization_storage:e(t.functional),ad_storage:e(t.marketing),ad_user_data:e(t.marketing),ad_personalization:e(t.marketing)})}function X(){let t=`${u}=`,e=(document.cookie||"").split(";").map(n=>n.trim()).find(n=>n.startsWith(t));if(!e)return null;try{let n=JSON.parse(decodeURIComponent(e.slice(t.length)));return!n||typeof n!="object"?null:{essential:!0,analytics:n.analytics===!0,functional:n.functional===!0,marketing:n.marketing===!0,timestamp:n.timestamp??null}}catch{return null}}function J(t){let e=new Date(Date.now()+H*24*60*60*1e3).toUTCString(),n=i.cookieDomain?`;domain=${i.cookieDomain}`:"",o=window.location?.protocol==="https:"?";Secure":"";document.cookie=`${u}=${encodeURIComponent(JSON.stringify(t))};expires=${e};path=/${n};SameSite=Lax${o}`}var f="webority_attribution",V=2160*60*60*1e3,Q=200,C=500,W=Object.freeze({utm_source:"utmSource",utm_medium:"utmMedium",utm_campaign:"utmCampaign",utm_content:"utmContent",utm_term:"utmTerm",gclid:"gclid",gbraid:"gbraid",wbraid:"wbraid",fbclid:"fbclid",msclkid:"msclkid",li_fat_id:"liFatId"}),A=!1;function x(){U("captureAttribution"),et();let t=Z();if(!t)return;let e=I(_());z(_(),{firstTouch:e?.firstTouch??t,lastTouch:t})}function R(){return U("getAttribution"),I(_())}function Z(){let t=new URLSearchParams(window.location.search),e={};for(let[o,r]of Object.entries(W)){let O=d(t.get(o),Q);O&&(e[r]=O)}let n=d(t.get("referrer"),C)||tt();return n&&(e.referrer=n),Object.keys(e).length===0?null:(e.landingPage=d(window.location.pathname,C),e.capturedDateTimeUtc=new Date().toISOString(),e)}function tt(){let t=document.referrer;if(!t)return"";try{return new URL(t).hostname===window.location.hostname?"":d(t,C)}catch{return""}}function et(){A||(A=!0,c(t=>{let e=t.marketing?T():h(),n=t.marketing?h():T(),o=I(e);nt(e),o&&z(n,o)}))}function _(){return a().marketing?h():T()}function h(){try{return window.localStorage}catch{return null}}function T(){try{return window.sessionStorage}catch{return null}}function I(t){try{let e=t?.getItem(f);if(!e)return null;let n=JSON.parse(e),o=D(n?.firstTouch),r=D(n?.lastTouch);return!o&&!r?(t.removeItem(f),null):{firstTouch:o??r,lastTouch:r??o}}catch{return null}}function z(t,e){try{t?.setItem(f,JSON.stringify(e))}catch{}}function nt(t){try{t?.removeItem(f)}catch{}}function D(t){if(!t||typeof t!="object")return null;let e=Date.parse(t.capturedDateTimeUtc);return Number.isFinite(e)&&Date.now()-e<=V?t:null}function d(t,e){let n=String(t??"").trim();return n?n.slice(0,e):""}function U(t){if(!l())throw new Error(`@webority/analytics: call initConsent before ${t}.`)}var ot=["scroll","mousemove","touchstart","keydown","pointerdown"],F=1500,rt=3e3,it=100,s={loaded:!1,clarityId:null,clarityLoaded:!1};function q(t={}){if(!l())throw new Error("@webority/analytics: call initConsent before loadTags.");if(s.loaded)return;s.loaded=!0;let{gtmId:e,clarityId:n,ahrefsKey:o}=t;o&&S("https://analytics.ahrefs.com/analytics.js",{"data-key":o}),e&&at(()=>{window.dataLayer=window.dataLayer||[],window.dataLayer.push({"gtm.start":Date.now(),event:"gtm.js"}),S(`https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(e)}`)}),n&&(s.clarityId=n,a().analytics&&st(),c(r=>{r.analytics&&E()}))}function at(t){let e=!1,n=()=>{e||(e=!0,t())};for(let o of ot)window.addEventListener(o,n,{once:!0,passive:!0});document.readyState==="complete"?setTimeout(n,F):window.addEventListener("load",()=>setTimeout(n,F),{once:!0})}function st(){let t=()=>{window.scrollY>it&&(window.removeEventListener("scroll",t),E())};window.addEventListener("scroll",t,{passive:!0}),setTimeout(E,rt)}function E(){s.clarityLoaded||!s.clarityId||(s.clarityLoaded=!0,window.clarity=window.clarity||function(){window.clarity.q=window.clarity.q||[],window.clarity.q.push(arguments)},S(`https://www.clarity.ms/tag/${encodeURIComponent(s.clarityId)}`,{crossorigin:"anonymous"}))}function S(t,e={}){let n=document.createElement("script");n.async=!0,n.src=t;for(let[o,r]of Object.entries(e))n.setAttribute(o,r);document.head.appendChild(n)}return P(ct);})();

package/package.json

@@ -1,25 +1,32 @@
 {
     "name": "@webority/analytics",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "license": "MIT",
     "type": "module",
     "main": "src/index.js",
     "exports": {
-        ".": "./src/index.js"
+        ".": "./src/index.js",
+        "./site": "./src/site.js",
+        "./dist/webority-analytics-site.global.js": "./dist/webority-analytics-site.global.js"
     },
     "files": [
-        "src"
+        "src",
+        "dist"
     ],
     "scripts": {
+        "build": "esbuild src/site.js --bundle --format=iife --global-name=WeborityAnalytics --target=es2020 --minify --outfile=dist/webority-analytics-site.global.js",
+        "prepack": "npm run build",
         "lint": "biome lint ./src ./test",
         "format": "biome format --write ./src ./test",
         "check": "biome check ./src ./test",
-        "test": "node test/smoke.mjs"
+        "test": "node test/smoke.mjs && node test/site.mjs && npm run build --silent && node test/bundle.mjs"
     },
-    "dependencies": {
-        "posthog-js": "1.417.1"
+    "peerDependencies": {
+        "posthog-js": "^1.417.1"
     },
     "devDependencies": {
-        "@biomejs/biome": "2.5.8"
+        "@biomejs/biome": "2.5.8",
+        "esbuild": "0.28.2",
+        "posthog-js": "1.417.1"
     }
 }

package/src/analytics.js

@@ -1,8 +1,23 @@
+import { isConsentInitialized, onConsentChange } from "./consent.js";
 import { ensurePosthogInitialized } from "./posthog-bridge.js";
-import { hasConsent, isActive, isEligible, resetState, state } from "./state.js";
+import { hasConsent, isActive, isEligible, resetState, state, WARNED_EVENT_LIMIT } from "./state.js";
 import { EVENT_NAME_PATTERN } from "./vocabulary.js";
 
+let stopFollowingConsent = null;
+
+/**
+ * Starts PostHog capture. initConsent must run first: capture follows the visitor's analytics
+ * consent and nothing else, so a surface with no consent source would capture under a choice
+ * nobody was offered.
+ */
 export function initAnalytics(config) {
+    if (!isConsentInitialized()) {
+        throw new Error("@webority/analytics: call initConsent before initAnalytics.");
+    }
+
+    stopFollowingConsent?.();
+    stopFollowingConsent = onConsentChange((consent) => followConsent(consent.analytics));
+
     resetState({
         host: config.host,
         clientKey: config.clientKey,
@@ -10,7 +25,6 @@ export function initAnalytics(config) {
         surface: config.surface,
         environment: config.environment,
         enabled: config.enabled ?? true,
-        getConsent: config.getConsent ?? null,
         logger: config.logger ?? null,
         // Off unless the product asks: replay records page content, so turning it on is the
         // product's disclosed decision, never a package default.
@@ -35,9 +49,7 @@ function warmUp() {
     });
 }
 
-export function setConsent(granted) {
-    state.consentOverride = granted;
-
+function followConsent(granted) {
     if (granted && isEligible()) {
         // A prior revoke leaves an already-initialized instance opted out, so re-granting must undo it.
         if (state.posthogInstance) {
@@ -110,11 +122,42 @@ export function registerEvents(names) {
 
 export function trackEvent(name, props = {}) {
     if (!state.registeredEvents.has(name)) {
-        throw new Error(`@webority/analytics: event "${name}" is not registered. Call registerEvents() first.`);
+        warnUnregisteredOnce(name);
+        return;
     }
     capture(name, props);
 }
 
+// Parity with IAnalyticsClient.Track on the server half: the same developer mistake never
+// throws there, it is logged and the event is dropped. A throw here runs inside the user's
+// browser and can take out the handler that raised it, so the browser half must not be the
+// harsher one. Once per name, because a misregistered event usually sits in a hot path.
+function warnUnregisteredOnce(name) {
+    if (state.warnedUnregisteredEvents.has(name)) {
+        return;
+    }
+    if (state.warnedUnregisteredEvents.size < WARNED_EVENT_LIMIT) {
+        state.warnedUnregisteredEvents.add(name);
+    }
+
+    const logger = state.config?.logger;
+    const message = `@webority/analytics: event "${name}" is not registered, so it was dropped. Call registerEvents() first.`;
+    if (typeof logger?.warn === "function") {
+        logger.warn(message);
+        return;
+    }
+    if (typeof logger?.info === "function") {
+        logger.info(message);
+        return;
+    }
+
+    // The no-console rule exists to stop debug logging, and passing no logger is the default.
+    // Routing the one diagnostic this package emits to a logger nobody passed would hide exactly
+    // the mistake the warning exists to surface.
+    // biome-ignore lint/suspicious/noConsole: the package's one diagnostic must be visible by default
+    console.warn(message);
+}
+
 function capture(name, props) {
     if (!isActive()) {
         logInactive(name, props);

package/src/attribution.js

@@ -0,0 +1,187 @@
+import { getConsent, isConsentInitialized, onConsentChange } from "./consent.js";
+
+export const ATTRIBUTION_STORAGE_KEY = "webority_attribution";
+const RETENTION_MS = 90 * 24 * 60 * 60 * 1000;
+const MAX_LENGTH = 200;
+const MAX_URL_LENGTH = 500;
+
+// Field names match Webority.Analytics' MarketingTouch, so the server binds this JSON as it is.
+const PARAM_TO_FIELD = Object.freeze({
+    utm_source: "utmSource",
+    utm_medium: "utmMedium",
+    utm_campaign: "utmCampaign",
+    utm_content: "utmContent",
+    utm_term: "utmTerm",
+    gclid: "gclid",
+    gbraid: "gbraid",
+    wbraid: "wbraid",
+    fbclid: "fbclid",
+    msclkid: "msclkid",
+    li_fat_id: "liFatId",
+});
+
+let followingConsent = false;
+
+/**
+ * Records how the visitor arrived: campaign parameters, click ids and an outside referrer.
+ * Call on every page load, before a client-side router strips the query string. The first
+ * touch is kept for 90 days; the last touch is replaced by each later campaign or referral
+ * visit. A direct visit changes nothing. Stored in localStorage only with marketing consent,
+ * otherwise for this tab alone.
+ */
+export function captureAttribution() {
+    ensureConsentInitialized("captureAttribution");
+    followConsent();
+
+    const touch = touchFromLocation();
+    if (!touch) {
+        return;
+    }
+
+    const current = readFrom(activeStore());
+    writeTo(activeStore(), { firstTouch: current?.firstTouch ?? touch, lastTouch: touch });
+}
+
+/** { firstTouch, lastTouch }, or null when no campaign or referral visit is on record. */
+export function getAttribution() {
+    ensureConsentInitialized("getAttribution");
+    return readFrom(activeStore());
+}
+
+function touchFromLocation() {
+    const params = new URLSearchParams(window.location.search);
+    const touch = {};
+    for (const [param, field] of Object.entries(PARAM_TO_FIELD)) {
+        const value = clip(params.get(param), MAX_LENGTH);
+        if (value) {
+            touch[field] = value;
+        }
+    }
+
+    // A referrer query parameter carries the original referrer across a hop between our own
+    // domains (marketing site to portal), where document.referrer would name our own site.
+    const referrer = clip(params.get("referrer"), MAX_URL_LENGTH) || outsideReferrer();
+    if (referrer) {
+        touch.referrer = referrer;
+    }
+
+    if (Object.keys(touch).length === 0) {
+        return null;
+    }
+
+    // The path only: a query string can carry personal data a visitor typed into a form.
+    touch.landingPage = clip(window.location.pathname, MAX_URL_LENGTH);
+    touch.capturedDateTimeUtc = new Date().toISOString();
+    return touch;
+}
+
+function outsideReferrer() {
+    const referrer = document.referrer;
+    if (!referrer) {
+        return "";
+    }
+    try {
+        return new URL(referrer).hostname === window.location.hostname ? "" : clip(referrer, MAX_URL_LENGTH);
+    } catch {
+        return "";
+    }
+}
+
+// Moves the record when consent changes: into localStorage when marketing is granted, back to
+// this tab's storage when it is withdrawn, so a revoke leaves nothing behind for 90 days.
+function followConsent() {
+    if (followingConsent) {
+        return;
+    }
+    followingConsent = true;
+
+    onConsentChange((consent) => {
+        const from = consent.marketing ? sessionStore() : localStore();
+        const to = consent.marketing ? localStore() : sessionStore();
+        const record = readFrom(from);
+        removeFrom(from);
+        if (record) {
+            writeTo(to, record);
+        }
+    });
+}
+
+function activeStore() {
+    return getConsent().marketing ? localStore() : sessionStore();
+}
+
+// Storage access throws in some private modes and sandboxed frames. Attribution is then lost for
+// this visit, which is the whole cost: the page and the product carry on.
+function localStore() {
+    try {
+        return window.localStorage;
+    } catch {
+        return null;
+    }
+}
+
+function sessionStore() {
+    try {
+        return window.sessionStorage;
+    } catch {
+        return null;
+    }
+}
+
+function readFrom(store) {
+    try {
+        const raw = store?.getItem(ATTRIBUTION_STORAGE_KEY);
+        if (!raw) {
+            return null;
+        }
+        const parsed = JSON.parse(raw);
+        const firstTouch = fresh(parsed?.firstTouch);
+        const lastTouch = fresh(parsed?.lastTouch);
+        if (!firstTouch && !lastTouch) {
+            store.removeItem(ATTRIBUTION_STORAGE_KEY);
+            return null;
+        }
+        return { firstTouch: firstTouch ?? lastTouch, lastTouch: lastTouch ?? firstTouch };
+    } catch {
+        return null;
+    }
+}
+
+function writeTo(store, record) {
+    try {
+        store?.setItem(ATTRIBUTION_STORAGE_KEY, JSON.stringify(record));
+    } catch {
+        // Quota or a blocked store: see localStore.
+    }
+}
+
+function removeFrom(store) {
+    try {
+        store?.removeItem(ATTRIBUTION_STORAGE_KEY);
+    } catch {
+        // See localStore.
+    }
+}
+
+function fresh(touch) {
+    if (!touch || typeof touch !== "object") {
+        return null;
+    }
+    const captured = Date.parse(touch.capturedDateTimeUtc);
+    return Number.isFinite(captured) && Date.now() - captured <= RETENTION_MS ? touch : null;
+}
+
+function clip(value, maxLength) {
+    const trimmed = String(value ?? "").trim();
+    return trimmed ? trimmed.slice(0, maxLength) : "";
+}
+
+function ensureConsentInitialized(caller) {
+    if (!isConsentInitialized()) {
+        throw new Error(`@webority/analytics: call initConsent before ${caller}.`);
+    }
+}
+
+export function resetAttributionForTests() {
+    followingConsent = false;
+}

package/src/consent-regions.js

@@ -0,0 +1,47 @@
+// The EEA, the UK and Switzerland: visitors here opt in before any non-essential cookie.
+// Webority.Analytics' ConsentRegion carries the same list for server-rendered pages, and a test
+// on that side holds the two in step.
+export const OPT_IN_COUNTRIES = Object.freeze([
+    "AT",
+    "BE",
+    "BG",
+    "HR",
+    "CY",
+    "CZ",
+    "DK",
+    "EE",
+    "FI",
+    "FR",
+    "DE",
+    "GR",
+    "HU",
+    "IE",
+    "IT",
+    "LV",
+    "LT",
+    "LU",
+    "MT",
+    "NL",
+    "PL",
+    "PT",
+    "RO",
+    "SK",
+    "SI",
+    "ES",
+    "SE",
+    "IS",
+    "LI",
+    "NO",
+    "GB",
+    "CH",
+]);
+
+// An unknown country opts in: guessing "granted" for a visitor who is really in the EEA is the
+// failure with a legal cost. XX and T1 are Cloudflare's markers for an unplaced country and a Tor exit.
+export function requiresOptIn(countryCode) {
+    const code = typeof countryCode === "string" ? countryCode.trim().toUpperCase() : "";
+    if (code.length !== 2 || code === "XX" || code === "T1") {
+        return true;
+    }
+    return OPT_IN_COUNTRIES.includes(code);
+}

package/src/consent.js

@@ -0,0 +1,196 @@
+import { OPT_IN_COUNTRIES } from "./consent-regions.js";
+
+export const CONSENT_COOKIE_NAME = "webority_cookie_consent";
+export const CONSENT_CHANGE_EVENT = "webority-consent-change";
+const CONSENT_COOKIE_DAYS = 365;
+
+const consentState = {
+    initialized: false,
+    requiresOptIn: true,
+    cookieDomain: null,
+    saved: null,
+};
+const listeners = new Set();
+
+/**
+ * Sets Google Consent Mode's defaults and applies the visitor's saved choice. Call once, first,
+ * before initAnalytics, loadTags or captureAttribution. requiresOptIn comes from the host, which
+ * knows the visitor's country (requiresOptIn(countryCode)); guessing it in the browser misplaces
+ * VPN users. cookieDomain (".capnix.ai") shares one choice between the website and every portal
+ * subdomain; without it the choice stays on the current host.
+ */
+export function initConsent(options) {
+    if (typeof options?.requiresOptIn !== "boolean") {
+        throw new Error("@webority/analytics: initConsent needs requiresOptIn (true or false), decided from the visitor's country.");
+    }
+    if (options.cookieDomain !== undefined && (typeof options.cookieDomain !== "string" || !options.cookieDomain.trim())) {
+        throw new Error('@webority/analytics: initConsent cookieDomain must be a domain such as ".example.com", or left out.');
+    }
+
+    consentState.initialized = true;
+    consentState.requiresOptIn = options.requiresOptIn;
+    consentState.cookieDomain = options.cookieDomain?.trim() ?? null;
+    consentState.saved = readConsentCookie();
+
+    pushConsentDefaults();
+    if (consentState.saved) {
+        pushConsentUpdate(consentState.saved);
+    }
+}
+
+export function isConsentInitialized() {
+    return consentState.initialized;
+}
+
+/**
+ * The visitor's current consent. Before they choose (decided: false) every optional category
+ * follows the region default: denied where opt-in is required, granted everywhere else.
+ */
+export function getConsent() {
+    ensureInitialized("getConsent");
+
+    const saved = consentState.saved;
+    if (saved) {
+        return { essential: true, analytics: saved.analytics, functional: saved.functional, marketing: saved.marketing, decided: true };
+    }
+
+    const granted = !consentState.requiresOptIn;
+    return { essential: true, analytics: granted, functional: granted, marketing: granted, decided: false };
+}
+
+/** Records the visitor's choice, tells Google, and notifies every listener. */
+export function saveConsent(preferences) {
+    ensureInitialized("saveConsent");
+
+    const saved = {
+        essential: true,
+        analytics: preferences?.analytics === true,
+        functional: preferences?.functional === true,
+        marketing: preferences?.marketing === true,
+        // The cookie's existing field name: visitors already hold cookies in this shape.
+        timestamp: new Date().toISOString(),
+    };
+    writeConsentCookie(saved);
+    consentState.saved = saved;
+
+    pushConsentUpdate(saved);
+    notify(getConsent());
+}
+
+/** Calls listener with the new consent after every saveConsent. Returns an unsubscribe function. */
+export function onConsentChange(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+
+function notify(consent) {
+    for (const listener of listeners) {
+        try {
+            listener(consent);
+        } catch (error) {
+            // One broken listener must not stop the others or the save. Rethrown on its own
+            // turn so it still reaches the page's error reporting instead of vanishing.
+            queueMicrotask(() => {
+                throw error;
+            });
+        }
+    }
+
+    // Pages without a module loader (plain Razor scripts) listen on window instead.
+    if (typeof window?.dispatchEvent === "function" && typeof CustomEvent === "function") {
+        window.dispatchEvent(new CustomEvent(CONSENT_CHANGE_EVENT, { detail: consent }));
+    }
+}
+
+function ensureInitialized(caller) {
+    if (!consentState.initialized) {
+        throw new Error(`@webority/analytics: call initConsent before ${caller}.`);
+    }
+}
+
+// Consent Mode reads the real Arguments object; a plain array is ignored.
+function gtag() {
+    window.dataLayer = window.dataLayer || [];
+    // biome-ignore lint/complexity/noArguments: Consent Mode reads the Arguments object, not an array.
+    window.dataLayer.push(arguments);
+}
+
+// Defaults must reach dataLayer before the Tag Manager container loads, or its tags fire ungated.
+function pushConsentDefaults() {
+    gtag("consent", "default", {
+        ad_storage: "denied",
+        ad_user_data: "denied",
+        ad_personalization: "denied",
+        analytics_storage: "denied",
+        functionality_storage: "denied",
+        personalization_storage: "denied",
+        security_storage: "granted",
+        wait_for_update: 500,
+        region: [...OPT_IN_COUNTRIES],
+    });
+    gtag("consent", "default", {
+        ad_storage: "granted",
+        ad_user_data: "granted",
+        ad_personalization: "granted",
+        analytics_storage: "granted",
+        functionality_storage: "granted",
+        personalization_storage: "granted",
+        security_storage: "granted",
+    });
+}
+
+function pushConsentUpdate(saved) {
+    const state = (granted) => (granted ? "granted" : "denied");
+    gtag("consent", "update", {
+        analytics_storage: state(saved.analytics),
+        functionality_storage: state(saved.functional),
+        personalization_storage: state(saved.functional),
+        ad_storage: state(saved.marketing),
+        ad_user_data: state(saved.marketing),
+        ad_personalization: state(saved.marketing),
+    });
+}
+
+function readConsentCookie() {
+    const prefix = `${CONSENT_COOKIE_NAME}=`;
+    const entry = (document.cookie || "")
+        .split(";")
+        .map((part) => part.trim())
+        .find((part) => part.startsWith(prefix));
+    if (!entry) {
+        return null;
+    }
+
+    try {
+        const parsed = JSON.parse(decodeURIComponent(entry.slice(prefix.length)));
+        if (!parsed || typeof parsed !== "object") {
+            return null;
+        }
+        return {
+            essential: true,
+            analytics: parsed.analytics === true,
+            functional: parsed.functional === true,
+            marketing: parsed.marketing === true,
+            timestamp: parsed.timestamp ?? null,
+        };
+    } catch {
+        // A cookie we cannot read is treated as no choice made: the banner asks again.
+        return null;
+    }
+}
+
+function writeConsentCookie(saved) {
+    const expires = new Date(Date.now() + CONSENT_COOKIE_DAYS * 24 * 60 * 60 * 1000).toUTCString();
+    const domain = consentState.cookieDomain ? `;domain=${consentState.cookieDomain}` : "";
+    const secure = window.location?.protocol === "https:" ? ";Secure" : "";
+    // biome-ignore lint/suspicious/noDocumentCookie: the Cookie Store API is missing from browsers our visitors use.
+    document.cookie = `${CONSENT_COOKIE_NAME}=${encodeURIComponent(JSON.stringify(saved))};expires=${expires};path=/${domain};SameSite=Lax${secure}`;
+}
+
+export function resetConsentForTests() {
+    consentState.initialized = false;
+    consentState.requiresOptIn = true;
+    consentState.cookieDomain = null;
+    consentState.saved = null;
+    listeners.clear();
+}

package/src/index.js

@@ -1,3 +1,15 @@
-export { identify, initAnalytics, registerEvents, resetIdentity, setConsent, trackEvent } from "./analytics.js";
+export { identify, initAnalytics, registerEvents, resetIdentity, trackEvent } from "./analytics.js";
+export {
+    CONSENT_CHANGE_EVENT,
+    CONSENT_COOKIE_NAME,
+    captureAttribution,
+    getAttribution,
+    getConsent,
+    initConsent,
+    loadTags,
+    onConsentChange,
+    requiresOptIn,
+    saveConsent,
+} from "./site.js";
 export { track } from "./track-helpers.js";
 export { events } from "./vocabulary.js";

package/src/posthog-bridge.js

@@ -1,7 +1,7 @@
 import { hasConsent, state } from "./state.js";
 
 // Dynamic import keeps posthog-js out of the module graph entirely for callers that
-// never go active (e.g. Local environment) — it assumes browser globals at init time.
+// never go active (e.g. Local environment), because it assumes browser globals at init time.
 export async function ensurePosthogInitialized() {
     if (state.posthogInstance) {
         return state.posthogInstance;

package/src/site.js

@@ -0,0 +1,6 @@
+// Public websites: consent, marketing tags and attribution, without PostHog. The main entry
+// re-exports all of this for portals that also capture product events.
+export { captureAttribution, getAttribution } from "./attribution.js";
+export { CONSENT_CHANGE_EVENT, CONSENT_COOKIE_NAME, getConsent, initConsent, onConsentChange, saveConsent } from "./consent.js";
+export { requiresOptIn } from "./consent-regions.js";
+export { loadTags } from "./tags.js";

package/src/state.js

@@ -1,19 +1,25 @@
+import { getConsent as getSiteConsent, isConsentInitialized } from "./consent.js";
 import { events } from "./vocabulary.js";
 
 export const state = {
     config: null,
-    consentOverride: null,
     posthogInstance: null,
     posthogInitPromise: null,
     registeredEvents: new Set(Object.values(events)),
+    warnedUnregisteredEvents: new Set(),
 };
 
+// The warning exists to reach a developer once. After this many distinct bad names the message
+// has landed, and a product building names from data must not grow the set for the life of the tab.
+export const WARNED_EVENT_LIMIT = 50;
+
 // registeredEvents is deliberately not reset: an event name is part of the product's
 // vocabulary, not of one analytics session, so a product that registers at module scope and
-// starts analytics later in a bootstrap effect keeps its registrations.
+// starts analytics later in a bootstrap effect keeps its registrations. warnedUnregisteredEvents
+// follows it for the same reason: the warning is about the code, not about one session, so
+// re-initializing must not make the same mistake shout again.
 export function resetState(config) {
     state.config = config;
-    state.consentOverride = null;
     state.posthogInstance = null;
     state.posthogInitPromise = null;
 }
@@ -26,15 +32,9 @@ export function isEligible() {
     return Boolean(config.enabled && config.clientKey && config.environment !== "Local");
 }
 
+// The visitor's analytics consent is the only thing that gates capture.
 export function hasConsent() {
-    if (state.consentOverride !== null) {
-        return state.consentOverride;
-    }
-    const getConsent = state.config?.getConsent;
-    if (typeof getConsent === "function") {
-        return Boolean(getConsent());
-    }
-    return true;
+    return isConsentInitialized() && getSiteConsent().analytics;
 }
 
 export function isActive() {

package/src/tags.js

@@ -0,0 +1,120 @@
+import { getConsent, isConsentInitialized, onConsentChange } from "./consent.js";
+
+const INTERACTION_EVENTS = ["scroll", "mousemove", "touchstart", "keydown", "pointerdown"];
+const DEFER_AFTER_LOAD_MS = 1500;
+const CLARITY_FALLBACK_MS = 3000;
+const CLARITY_SCROLL_PX = 100;
+
+const tagState = {
+    loaded: false,
+    clarityId: null,
+    clarityLoaded: false,
+};
+
+/**
+ * Loads the marketing tags. Tag Manager waits for the first interaction, or 1.5s after load,
+ * so its download never competes with the page's largest paint; Consent Mode (set by
+ * initConsent) gates what its tags may do. Clarity records sessions, so it loads only with
+ * analytics consent, and a revoke takes effect from the next page. Ahrefs is cookieless and
+ * loads straight away. GA4 is deliberately absent: it runs inside the Tag Manager container,
+ * and loading it here as well counts every page view twice.
+ */
+export function loadTags(options = {}) {
+    if (!isConsentInitialized()) {
+        throw new Error("@webority/analytics: call initConsent before loadTags.");
+    }
+    if (tagState.loaded) {
+        return;
+    }
+    tagState.loaded = true;
+
+    const { gtmId, clarityId, ahrefsKey } = options;
+
+    if (ahrefsKey) {
+        appendScript("https://analytics.ahrefs.com/analytics.js", { "data-key": ahrefsKey });
+    }
+
+    if (gtmId) {
+        runAfterFirstInteraction(() => {
+            window.dataLayer = window.dataLayer || [];
+            window.dataLayer.push({ "gtm.start": Date.now(), event: "gtm.js" });
+            appendScript(`https://www.googletagmanager.com/gtm.js?id=${encodeURIComponent(gtmId)}`);
+        });
+    }
+
+    if (clarityId) {
+        tagState.clarityId = clarityId;
+        if (getConsent().analytics) {
+            scheduleClarity();
+        }
+        onConsentChange((consent) => {
+            if (consent.analytics) {
+                loadClarity();
+            }
+        });
+    }
+}
+
+function runAfterFirstInteraction(callback) {
+    let ran = false;
+    const run = () => {
+        if (ran) {
+            return;
+        }
+        ran = true;
+        callback();
+    };
+
+    for (const eventName of INTERACTION_EVENTS) {
+        window.addEventListener(eventName, run, { once: true, passive: true });
+    }
+    if (document.readyState === "complete") {
+        setTimeout(run, DEFER_AFTER_LOAD_MS);
+    } else {
+        window.addEventListener("load", () => setTimeout(run, DEFER_AFTER_LOAD_MS), { once: true });
+    }
+}
+
+function scheduleClarity() {
+    const onScroll = () => {
+        if (window.scrollY > CLARITY_SCROLL_PX) {
+            window.removeEventListener("scroll", onScroll);
+            loadClarity();
+        }
+    };
+    window.addEventListener("scroll", onScroll, { passive: true });
+    setTimeout(loadClarity, CLARITY_FALLBACK_MS);
+}
+
+function loadClarity() {
+    if (tagState.clarityLoaded || !tagState.clarityId) {
+        return;
+    }
+    tagState.clarityLoaded = true;
+
+    // Clarity's own queue: calls made before its script arrives are replayed once it does.
+    window.clarity =
+        window.clarity ||
+        function clarityQueue() {
+            window.clarity.q = window.clarity.q || [];
+            // biome-ignore lint/complexity/noArguments: Clarity's stub queues the Arguments object, as its own snippet does.
+            window.clarity.q.push(arguments);
+        };
+    appendScript(`https://www.clarity.ms/tag/${encodeURIComponent(tagState.clarityId)}`, { crossorigin: "anonymous" });
+}
+
+function appendScript(src, attributes = {}) {
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = src;
+    for (const [name, value] of Object.entries(attributes)) {
+        script.setAttribute(name, value);
+    }
+    document.head.appendChild(script);
+}
+
+export function resetTagsForTests() {
+    tagState.loaded = false;
+    tagState.clarityId = null;
+    tagState.clarityLoaded = false;
+}