@mfeflow/analytics 0.1.0 → 0.3.0

package/README.md

@@ -34,11 +34,21 @@ export const tracker = createTracker('cart', { events: ['add_to_cart'] });
 tracker.track('add_to_cart', { sku: 'A1' });
 ```
 
+To run a second provider (Microsoft Clarity, which loads only after analytics consent), join it with `addProvider`; both then get every call:
+
+```ts
+import { addProvider } from '@mfeflow/analytics/providers';
+import { createClarityProvider } from '@mfeflow/analytics/clarity';
+
+addProvider(createGtmProvider({ containerId: 'GTM-ABC123' }));
+addProvider(createClarityProvider({ projectId: 'k3x9m2abcd' }));
+```
+
 The GTM provider pushes the four consent signals as `denied` to `dataLayer` before it requests `gtm.js`, and drops parameters that look like personal data.
 
 ## Module Federation sharing
 
-Bucket: **singleton**. Share `@mfeflow/analytics` and `@mfeflow/analytics/react` (`@mfeflow/rsbuild` does). State also lives on `globalThis`, so a second copy still talks to the one provider. `@mfeflow/analytics/gtm` is imported by the shell only.
+Bucket: **singleton**. Share `@mfeflow/analytics` and `@mfeflow/analytics/react` (`@mfeflow/rsbuild` does). State also lives on `globalThis`, so a second copy still talks to the one provider. `@mfeflow/analytics/gtm`, `/clarity` and `/providers` are imported by the shell only; `addProvider` lives in its own entry point so the shared module that remotes load stays small.
 
 ## Links
 

package/dist/clarity.d.ts

@@ -0,0 +1,18 @@
+import type { AnalyticsProvider } from './types.js';
+export interface ClarityOptions {
+    /** The Clarity project id, like `k3x9m2abcd`. From the runtime config, never baked into the bundle. */
+    projectId: string;
+    /** Default Clarity's own `https://www.clarity.ms/tag/`. Tests point it elsewhere. */
+    scriptUrl?: string | undefined;
+    /** Send the id given to `identify` as Clarity's custom user id. Off by default; traits are never sent. */
+    sendUserId?: boolean | undefined;
+}
+export declare const CLARITY_SCRIPT_URL = "https://www.clarity.ms/tag/";
+export declare const CLARITY_SCRIPT_ATTRIBUTE = "data-mfeflow-clarity";
+/**
+ * Microsoft Clarity behind the analytics interface, gated on consent. Nothing is requested, and no cookie is
+ * set, until `analytics_storage` is `granted`: the script is added on that choice (now, or on a later visit
+ * when the stored consent arrives in `init`). A later `denied` tells Clarity to stop and clear its cookies.
+ * Until then every call is dropped, never kept for later.
+ */
+export declare function createClarityProvider(options: ClarityOptions): AnalyticsProvider;

package/dist/clarity.js

@@ -0,0 +1,66 @@
+const PROJECT_ID = /^[a-z0-9]{8,12}$/;
+const CLARITY_SCRIPT_URL = 'https://www.clarity.ms/tag/';
+const CLARITY_SCRIPT_ATTRIBUTE = 'data-mfeflow-clarity';
+const isClarity = (value)=>'function' == typeof value;
+function clarityFunction() {
+    const existing = Reflect.get(globalThis, 'clarity');
+    if (isClarity(existing)) return existing;
+    const queue = function() {
+        (queue.q ??= []).push(arguments);
+    };
+    Reflect.set(globalThis, 'clarity', queue);
+    return queue;
+}
+function createClarityProvider(options) {
+    const { projectId } = options;
+    if (!PROJECT_ID.test(projectId)) throw new Error(`"${projectId}" is not a Clarity project id (8 to 12 lowercase letters and digits)`);
+    let consent = {};
+    let started = false;
+    const sendConsent = ()=>{
+        clarityFunction()('consentv2', {
+            ad_Storage: consent.ad_storage ?? 'denied',
+            analytics_Storage: consent.analytics_storage ?? 'denied'
+        });
+    };
+    const start = ()=>{
+        if (started) return;
+        started = true;
+        const selector = `script[${CLARITY_SCRIPT_ATTRIBUTE}="${projectId}"]`;
+        clarityFunction();
+        sendConsent();
+        if (document.querySelector(selector)) return;
+        const script = document.createElement("script");
+        script.async = true;
+        script.setAttribute(CLARITY_SCRIPT_ATTRIBUTE, projectId);
+        const base = options.scriptUrl ?? CLARITY_SCRIPT_URL;
+        script.src = new URL(projectId, base.endsWith('/') ? base : `${base}/`).href;
+        document.head.append(script);
+    };
+    const apply = (update)=>{
+        consent = {
+            ...consent,
+            ...update
+        };
+        if (started) sendConsent();
+        else if ('granted' === consent.analytics_storage) start();
+    };
+    return {
+        name: 'clarity',
+        init (stored) {
+            apply(stored);
+        },
+        track (event) {
+            if (started && 'granted' === consent.analytics_storage) clarityFunction()('event', event);
+        },
+        page (path) {
+            if (started && 'granted' === consent.analytics_storage) clarityFunction()('set', 'page_path', path);
+        },
+        identify (userId) {
+            if (true === options.sendUserId && started && 'granted' === consent.analytics_storage) clarityFunction()('identify', userId);
+        },
+        setConsent (update) {
+            apply(update);
+        }
+    };
+}
+export { CLARITY_SCRIPT_ATTRIBUTE, CLARITY_SCRIPT_URL, createClarityProvider };

package/dist/combine.d.ts

@@ -0,0 +1,8 @@
+import type { AnalyticsProvider } from './types.js';
+/** The providers a combined provider sends to (itself, if it is not a combination). */
+export declare function partsOf(provider: AnalyticsProvider): readonly AnalyticsProvider[];
+/**
+ * One provider that forwards every call to all of `providers`, in order. A provider that throws is
+ * reported once and skipped for that call, so a failing tag cannot stop the others.
+ */
+export declare function combineProviders(...providers: AnalyticsProvider[]): AnalyticsProvider;

package/dist/combine.js

@@ -0,0 +1,48 @@
+import { warnOnce } from "./validate.js";
+const members = new WeakMap();
+function partsOf(provider) {
+    return members.get(provider) ?? [
+        provider
+    ];
+}
+function combineProviders(...providers) {
+    const parts = providers.flatMap(partsOf);
+    const each = (what, call)=>{
+        for (const part of parts)try {
+            call(part);
+        } catch (error) {
+            warnOnce(`${part.name}: ${what} failed (${error instanceof Error ? error.message : 'unknown error'})`);
+        }
+    };
+    const combined = {
+        name: parts.map((p)=>p.name).join('+'),
+        init: (consent)=>{
+            each('init', (p)=>{
+                p.init(consent);
+            });
+        },
+        track: (event, params)=>{
+            each('track', (p)=>{
+                p.track(event, params);
+            });
+        },
+        page: (path, params)=>{
+            each('page', (p)=>{
+                p.page(path, params);
+            });
+        },
+        identify: (userId, traits)=>{
+            each('identify', (p)=>{
+                p.identify(userId, traits);
+            });
+        },
+        setConsent: (update)=>{
+            each('setConsent', (p)=>{
+                p.setConsent(update);
+            });
+        }
+    };
+    members.set(combined, parts);
+    return combined;
+}
+export { combineProviders, partsOf };

package/dist/core.d.ts

@@ -4,6 +4,16 @@ import type { AnalyticsProvider, ConsentUpdate, EventParams } from './types.js';
  * (a second mount, StrictMode, a remote running on its own) do nothing and return false.
  */
 export declare function initAnalytics(provider: AnalyticsProvider): boolean;
+/** The provider that is running, if any. Used by `addProvider` in `./providers`. */
+export declare function runningProvider(): AnalyticsProvider | undefined;
+/** For `./providers`: from now on, keep the first calls (for ten seconds, at most 100) for providers that join later. */
+export declare function keepCallsForJoiners(): void;
+/**
+ * Starts `added` with the stored consent, and only then makes `joined` (a combination that includes it) the
+ * running provider, so a provider whose `init` throws leaves the running one as it was and can be added
+ * again. Then sends it the calls made since analytics began, if they are still kept.
+ */
+export declare function joinProvider(joined: AnalyticsProvider, added: AnalyticsProvider): void;
 export declare function isAnalyticsReady(): boolean;
 export declare function providerName(): string;
 export declare function track(event: string, params?: EventParams): void;

package/dist/core.js

@@ -2,6 +2,8 @@ import { CONSENT_STORAGE_KEY, cleanConsent, readStoredConsent, writeStoredConsen
 import { noopProvider } from "./noop.js";
 const KEY = Symbol.for('mfeflow.analytics');
 const QUEUE_LIMIT = 100;
+const BOOT_WINDOW_MS = 10000;
+let keepCalls = false;
 function isState(value) {
     return 'object' == typeof value && null !== value && 'queue' in value && 'listeners' in value;
 }
@@ -13,13 +15,23 @@ function state() {
         queue: [],
         consent: readStoredConsent(),
         listeners: new Set(),
-        lastPage: void 0
+        lastPage: void 0,
+        replay: keepCalls ? {
+            calls: [],
+            since: void 0
+        } : void 0
     };
     Reflect.set(globalThis, KEY, fresh);
     return fresh;
 }
 function send(call) {
     const s = state();
+    const keep = s.replay;
+    if (keep) {
+        keep.since ??= Date.now();
+        if (Date.now() - keep.since > BOOT_WINDOW_MS) s.replay = void 0;
+        else if (keep.calls.length < QUEUE_LIMIT) keep.calls.push(call);
+    }
     if (s.provider) call(s.provider);
     else if (s.queue.length < QUEUE_LIMIT) s.queue.push(call);
 }
@@ -34,6 +46,27 @@ function initAnalytics(provider) {
     for (const call of queued)call(provider);
     return true;
 }
+function runningProvider() {
+    return state().provider;
+}
+function keepCallsForJoiners() {
+    keepCalls = true;
+    const s = state();
+    s.replay ??= {
+        calls: [],
+        since: void 0
+    };
+}
+function joinProvider(joined, added) {
+    const s = state();
+    added.init({
+        ...s.consent
+    });
+    s.provider = joined;
+    for (const call of s.replay?.calls ?? [])try {
+        call(added);
+    } catch  {}
+}
 function isAnalyticsReady() {
     return void 0 !== state().provider;
 }
@@ -93,4 +126,4 @@ function resetAnalyticsForTests() {
         localStorage.removeItem(CONSENT_STORAGE_KEY);
     } catch  {}
 }
-export { getConsent, hasConsentChoice, identify, initAnalytics, isAnalyticsReady, page, pageOnce, providerName, resetAnalyticsForTests, subscribeConsent, track, updateConsent };
+export { getConsent, hasConsentChoice, identify, initAnalytics, isAnalyticsReady, joinProvider, keepCallsForJoiners, page, pageOnce, providerName, resetAnalyticsForTests, runningProvider, subscribeConsent, track, updateConsent };

package/dist/providers.d.ts

@@ -0,0 +1,13 @@
+import { combineProviders } from './combine.js';
+import type { AnalyticsProvider } from './types.js';
+export { combineProviders };
+/**
+ * Starts analytics with a provider, or joins one that is already running: from then on both get every
+ * call, and the newcomer first gets the calls made in the first ten seconds (at most 100), so the first page view reaches it
+ * whichever provider started first. A provider drops what it must, by its own rule (Clarity drops events from before consent). Returns false if a provider with
+ * this name is already there. Use it where several features may start a provider in either order.
+ *
+ * This lives in its own entry point, for the shell only, so the shared `@mfeflow/analytics` module that
+ * every remote loads stays as small as it was.
+ */
+export declare function addProvider(provider: AnalyticsProvider): boolean;

package/dist/providers.js

@@ -0,0 +1,11 @@
+import { combineProviders, partsOf } from "./combine.js";
+import { initAnalytics, joinProvider, keepCallsForJoiners, runningProvider } from "./core.js";
+keepCallsForJoiners();
+function addProvider(provider) {
+    const running = runningProvider();
+    if (!running) return initAnalytics(provider);
+    if (partsOf(running).some((p)=>p.name === provider.name)) return false;
+    joinProvider(combineProviders(running, provider), provider);
+    return true;
+}
+export { addProvider, combineProviders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mfeflow/analytics",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Analytics for micro-frontends behind one provider interface: typed events, a tracker that stamps mfe_name, Consent Mode v2, and a Google Tag Manager provider.",
   "keywords": [
     "micro-frontend",
@@ -32,6 +32,16 @@
       "import": "./dist/gtm.js",
       "default": "./dist/gtm.js"
     },
+    "./clarity": {
+      "types": "./dist/clarity.d.ts",
+      "import": "./dist/clarity.js",
+      "default": "./dist/clarity.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.js",
+      "default": "./dist/providers.js"
+    },
     "./react": {
       "types": "./dist/react.d.ts",
       "import": "./dist/react.js",