@antelopejs/dms-marketing 0.5.1 → 0.6.0

package/frontend-vue/i18n/locales/marketing-en-GB.json

@@ -386,6 +386,7 @@
           "title": "Couldn't load your websites"
         },
         "idle": "Last event {ago}",
+        "imported": "Imported history · last event {ago}",
         "label": "Website and period",
         "live": "Live · last event {ago}",
         "no_website": "No website yet",
@@ -399,6 +400,7 @@
         "range_cut": "Only the last {days} days of this range are shown.",
         "refresh": "Refresh",
         "state": {
+          "imported": "Imported history only",
           "live": "Live",
           "paused": "Tracking paused for this website",
           "waiting": "Waiting for the first event"

package/frontend-vue/i18n/locales/marketing-fr-FR.json

@@ -386,6 +386,7 @@
           "title": "Impossible de charger vos sites"
         },
         "idle": "Dernier événement {ago}",
+        "imported": "Historique importé · dernier événement {ago}",
         "label": "Site et période",
         "live": "En direct · dernier événement {ago}",
         "no_website": "Aucun site pour l'instant",
@@ -399,6 +400,7 @@
         "range_cut": "Seuls les {days} derniers jours de cette plage sont affichés.",
         "refresh": "Actualiser",
         "state": {
+          "imported": "Historique importé uniquement",
           "live": "En direct",
           "paused": "Suivi en pause pour ce site",
           "waiting": "En attente du premier événement"

package/frontend-vue/tests/dashboard-tracking.test.ts

@@ -0,0 +1,219 @@
+import { describe, expect, it, vi } from 'vitest'
+import { nextTick, ref } from 'vue'
+import frontendModule from '../dms.frontend'
+import { MODULE_CONFIG_KEY } from '../app/constants'
+import {
+  applyDashboardTracker,
+  DASHBOARD_TRACKER_ELEMENT_ID,
+  dashboardTrackingOptions,
+  followDashboardSession,
+} from '../app/utils/dashboard-tracker'
+
+/** Just enough of a script element and a document for the tag helper. */
+class FakeElement {
+  id = ''
+  async = false
+  src = ''
+  readonly attributes = new Map<string, string>()
+  setAttribute(name: string, value: string) {
+    this.attributes.set(name, value)
+  }
+  removeAttribute(name: string) {
+    this.attributes.delete(name)
+  }
+}
+
+function fakeDocument() {
+  const appended: FakeElement[] = []
+  const doc = {
+    appended,
+    getElementById: (id: string) =>
+      appended.find((element) => element.id === id) ?? null,
+    createElement: () => new FakeElement(),
+    head: {
+      appendChild: (element: FakeElement) => {
+        appended.push(element)
+        return element
+      },
+    },
+  }
+  return doc as typeof doc & Parameters<typeof applyDashboardTracker>[0]
+}
+
+const SRC = 'https://dms.example.com/api/marketing/tracker.js'
+const EXCLUDED = ['/auth/**', '/settings/*']
+
+function sdk(publicOptions: Record<string, unknown>) {
+  return {
+    options: { public: publicOptions },
+    registerComponent: vi.fn(),
+    registerPage: vi.fn(),
+    registerDynamicPage: vi.fn(),
+    registerLayout: vi.fn(),
+    registerErrorPage: vi.fn(),
+    registerPlugin: vi.fn(),
+    registerMiddleware: vi.fn(),
+    provide: vi.fn(),
+    use: vi.fn(),
+  }
+}
+
+describe('dashboard tracking options', () => {
+  it('is off without the backend option', () => {
+    expect(dashboardTrackingOptions({})).toBeNull()
+    expect(dashboardTrackingOptions({ [MODULE_CONFIG_KEY]: {} })).toBeNull()
+  })
+
+  it('reads the excluded paths, strings only', () => {
+    expect(
+      dashboardTrackingOptions({
+        [MODULE_CONFIG_KEY]: {
+          dashboardTracking: { excludePaths: ['/auth/**', 3, '/a'] },
+        },
+      }),
+    ).toEqual({ excludePaths: ['/auth/**', '/a'] })
+    expect(
+      dashboardTrackingOptions({
+        [MODULE_CONFIG_KEY]: { dashboardTracking: {} },
+      }),
+    ).toEqual({ excludePaths: [] })
+  })
+
+  it('registers its client plugin only when the backend enables it', async () => {
+    const off = sdk({})
+    await frontendModule.setup(off)
+    expect(off.registerPlugin).toHaveBeenCalledTimes(1)
+
+    const on = sdk({
+      [MODULE_CONFIG_KEY]: { dashboardTracking: { excludePaths: EXCLUDED } },
+    })
+    await frontendModule.setup(on)
+    expect(on.registerPlugin).toHaveBeenCalledTimes(2)
+    for (const [, options] of on.registerPlugin.mock.calls) {
+      expect(options).toEqual({ clientOnly: true })
+    }
+  })
+})
+
+describe('the dashboard tag', () => {
+  it('is not inserted before there is a website to report to', () => {
+    const doc = fakeDocument()
+    applyDashboardTracker(doc, {
+      src: SRC,
+      websiteId: null,
+      excludePaths: EXCLUDED,
+    })
+    expect(doc.appended).toHaveLength(0)
+  })
+
+  it('is inserted once, then paused and retargeted in place', () => {
+    const doc = fakeDocument()
+    applyDashboardTracker(doc, {
+      src: SRC,
+      websiteId: 'site-a',
+      excludePaths: EXCLUDED,
+    })
+    expect(doc.appended).toHaveLength(1)
+    const tag = doc.appended[0]!
+    expect(tag.id).toBe(DASHBOARD_TRACKER_ELEMENT_ID)
+    expect(tag.src).toBe(SRC)
+    expect(tag.async).toBe(true)
+    expect(tag.attributes.get('data-website-id')).toBe('site-a')
+    expect(tag.attributes.get('data-exclude-paths')).toBe(
+      '/auth/**,/settings/*',
+    )
+
+    applyDashboardTracker(doc, {
+      src: SRC,
+      websiteId: null,
+      excludePaths: EXCLUDED,
+    })
+    expect(tag.attributes.has('data-website-id')).toBe(false)
+
+    applyDashboardTracker(doc, {
+      src: SRC,
+      websiteId: 'site-b',
+      excludePaths: EXCLUDED,
+    })
+    expect(doc.appended).toHaveLength(1)
+    expect(tag.attributes.get('data-website-id')).toBe('site-b')
+  })
+})
+
+describe('following the signed-in workspace', () => {
+  function binding(answers: Record<string, () => Promise<string>>) {
+    const workspace = ref<string | null>(null)
+    const applied: (string | null)[] = []
+    const provision = vi.fn(() => answers[workspace.value!]!())
+    const stop = followDashboardSession({
+      workspace: () => workspace.value,
+      provision,
+      apply: (websiteId) => applied.push(websiteId),
+    })
+    return { workspace, applied, provision, stop }
+  }
+
+  async function settle() {
+    await new Promise((resolve) => setTimeout(resolve, 0))
+    await nextTick()
+  }
+
+  it('asks nothing while nobody is signed in', async () => {
+    const { applied, provision, stop } = binding({})
+    await settle()
+    expect(provision).not.toHaveBeenCalled()
+    expect(applied).toEqual([null])
+    stop()
+  })
+
+  it('pauses at once on a change, then reports to the new website', async () => {
+    const { workspace, applied, stop } = binding({
+      t1: async () => 'site-1',
+      t2: async () => 'site-2',
+    })
+    workspace.value = 't1'
+    await settle()
+    expect(applied).toEqual([null, null, 'site-1'])
+
+    workspace.value = 't2'
+    // Synchronous: paused before the navigation that follows the switch.
+    expect(applied.at(-1)).toBeNull()
+    await settle()
+    expect(applied.at(-1)).toBe('site-2')
+
+    workspace.value = null
+    expect(applied.at(-1)).toBeNull()
+    await settle()
+    expect(applied.at(-1)).toBeNull()
+    stop()
+  })
+
+  it('drops an answer that arrives after another change', async () => {
+    let release: (id: string) => void = () => {}
+    const { workspace, applied, stop } = binding({
+      slow: () =>
+        new Promise<string>((resolve) => {
+          release = resolve
+        }),
+    })
+    workspace.value = 'slow'
+    workspace.value = null
+    release('site-slow')
+    await settle()
+    expect(applied).not.toContain('site-slow')
+    expect(applied.at(-1)).toBeNull()
+    stop()
+  })
+
+  it('stays paused when the backend refuses', async () => {
+    const { workspace, applied, stop } = binding({
+      t1: async () => {
+        throw new Error('404')
+      },
+    })
+    workspace.value = 't1'
+    await settle()
+    expect(applied.at(-1)).toBeNull()
+    stop()
+  })
+})

package/frontend-vue/tests/format.test.ts

@@ -46,6 +46,15 @@ describe('formatting', () => {
     expect(initials('docs')).toBe('DO')
   })
 
+  it('builds initials from letters and digits only', () => {
+    expect(initials('Acme — public site')).toBe('AP')
+    expect(initials('shop.acme.test')).toBe('SA')
+    expect(initials('— Acme')).toBe('AC')
+    expect(initials('42 · store')).toBe('4S')
+    expect(initials('Été à Liège')).toBe('ÉÀ')
+    expect(initials('—')).toBe('?')
+  })
+
   it('falls back to the raw code on a malformed region', () => {
     expect(displayName('FR', 'region', 'en')).toBe('France')
     expect(displayName('not a code!', 'region', 'en')).toBe('not a code!')

package/frontend-vue/tests/server-parity.test.ts

@@ -8,9 +8,14 @@ import { normalizeFunnelStepPath } from '../app/utils/step-path'
 import {
   MAX_WEBSITE_DOMAIN_LENGTH,
   MAX_WEBSITE_NAME_LENGTH,
+  MODULE_CONFIG_KEY,
 } from '../app/constants'
 
 describe('front rules mirror the server', () => {
+  it('reads its public options where the backend puts them', () => {
+    expect(MODULE_CONFIG_KEY).toBe(server.FRONTEND_CONFIG_KEY)
+  })
+
   it('caps a funnel draft as the server does', () => {
     expect(draft.MAX_NAME_LENGTH).toBe(server.MAX_NAME_LENGTH)
     expect(draft.MAX_STEPS).toBe(server.MAX_FUNNEL_STEPS)

package/frontend-vue/tests/stubs/frontend-module.ts

@@ -67,3 +67,10 @@ export function useDmsCookie<T>(
 ): { value: T } {
   return { value: options.default() }
 }
+
+export function useDmsUserSession(): {
+  loggedIn: { value: boolean }
+  session: { value: { activeTenantId?: string } | null }
+} {
+  return { loggedIn: { value: false }, session: { value: null } }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antelopejs/dms-marketing",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "First-party marketing analytics for the AntelopeJS DMS: traffic dashboards, conversion funnels with A/B splits and click heatmaps, without cookies or external services.",
   "keywords": [
     "ab-testing",
@@ -51,7 +51,7 @@
     "@antelopejs/interface-database": ">=0.1.10 <1.0.0",
     "@antelopejs/interface-database-decorators": ">=0.1.9 <1.0.0",
     "@antelopejs/interface-dms": ">=0.7.2 <1.0.0",
-    "@antelopejs/interface-dms-marketing": ">=0.4.1 <0.5.0",
+    "@antelopejs/interface-dms-marketing": ">=0.5.0 <0.6.0",
     "defu": "^6.1.4",
     "maxmind": "^5.0.7",
     "node-cron": "^4.2.1",

package/skills/dms-marketing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dms-marketing
-description: First-party, cookieless web analytics with the @antelopejs/dms-marketing module of the AntelopeJS DMS. Use when installing or configuring dms-marketing, embedding its tracker on a site, sending custom events or A/B variations from page code (dmsMarketing.track / variation), defining funnels or A/B tests, reading heatmaps from another module via GetClickHeatmap, or debugging missing, refused (403/404) or empty analytics.
+description: First-party, cookieless web analytics with the @antelopejs/dms-marketing module of the AntelopeJS DMS. Use when installing or configuring dms-marketing, embedding its tracker on a site, sending custom events or A/B variations from page code (dmsMarketing.track / variation), defining funnels or A/B tests, shipping websites, funnels or demo/migrated history from code (EnsureWebsite / EnsureFunnel / ImportAnalytics), reading heatmaps from another module via GetClickHeatmap, or debugging missing, refused (403/404) or empty analytics.
 icon: i-lucide-chart-line
 category: analytics
 tags: [analytics, tracking, funnels, ab-testing, heatmaps, dms-module]
@@ -19,7 +19,8 @@ https://dms.antelopejs.com/docs/modules/marketing (`architecture` holds the full
   0.4 is the DMS 0.8 line.
 - `ajs project modules add @antelopejs/dms-marketing`. Options: `trackerEnabled`, `rawEventsRetention`,
   `statisticsRetention`, `snapshotRetention`, `sessionIdleTimeout` (all ms), `heatmapSampleRate` (0-1),
-  `visitorHashSecret` (set it when running several instances), `geoipDatabasePath` (.mmdb, opt-in).
+  `visitorHashSecret` (set it when running several instances), `geoipDatabasePath` (.mmdb, opt-in),
+  `dashboardTracking` (see below).
   The Settings page overrides switch, retentions and sampling at runtime for the whole deployment.
 - Behind a proxy set the DMS `auth.trustedProxies`; the old `trustedProxyHops` option is gone.
 - One website row per tracked site (Websites page or `POST /api/marketing/websites {name, domain, extraDomains?}`).
@@ -41,6 +42,55 @@ const arm = await window.dmsMarketing?.variation("hero-cta");      // null = ren
 - Never `type="module"` (breaks `document.currentScript`). Always guard with `?.`.
 - Snapshots (heatmap backdrops) are opt-in per site; mask with `data-dms-marketing-mask` / `data-dms-marketing-block`.
 
+## Tracking the dashboard itself
+
+For a demo, a playground or a back office measuring its own admin, no tag to write:
+
+```typescript
+config: { dashboardTracking: { enabled: true, websiteName: "Dashboard", excludePaths: ["/settings/**"] } }
+```
+
+- Off by default. On, the module's frontend loads the tracker on every signed-in dashboard page and
+  `POST /api/marketing/dashboard-tracking` creates one website per tenant on first use (domain = the
+  dashboard's host; later hosts join `extraDomains`). Rename, pause or delete it like any site.
+- `/auth/**` is never counted; signing out pauses the tag, a workspace switch retargets it. SPA navigations
+  count. Restart `ajs dms dev` / rebuild the frontend after toggling the option.
+- Tracker attributes behind it, usable on any site: `data-exclude-paths="/x,/x/*,/x/**"`, and a live
+  `data-website-id` (changing it retargets, removing it pauses).
+
+## Content from code
+
+Never write the module's tables. From a module's `start()` (await) — or unawaited with a `.catch` in
+`construct()` / a DATABASE_INITIALIZED handler — use `@antelopejs/interface-dms-marketing`:
+
+```typescript
+const tenantId = "default"; // explicit, never implied
+await EnsureWebsite({ tenantId, id: "shop-site", name: "Shop", domain: "shop.example.com",
+  snapshotsEnabled: true }); // id = data-website-id, global
+await EnsureFunnel({ tenantId, id: "shop-quote", websiteId: "shop-site", name: "Quote",
+  steps: [{ kind: "url", value: "/pricing" }, { kind: "custom", value: "quote_submitted" }],
+  experiment: { key: "hero-cta", status: "running", startedAt: "2026-07-01T00:00:00Z",
+    variations: [{ key: "control", weight: 1 }, { key: "bold", weight: 1 }] } });
+await EnsurePageSnapshot({ tenantId, websiteId: "shop-site", url: "https://shop.example.com/pricing",
+  html, viewport: { width: 1280, height: 800 }, document: { width: 1280, height: 2600 } });
+await ImportAnalytics({ tenantId, importId: "shop-history", websiteId: "shop-site", sessions: [
+  { visitor: "v1", userAgent, country: "BE", events: [{ kind: "pageview", at: "2026-10-01T09:00:00Z", url }] }] });
+```
+
+- Ensure* answer `created` / `unchanged` / `updated` / `kept`: a record someone changed since the last
+  declaration (hash stored on the row) is never overwritten; delete it in the dashboard to re-take it.
+  Dashboard rules apply (hostnames, 1-10 steps, 2-8 arms, draft → running ⇄ stopped, arms frozen out of draft).
+- ImportAnalytics replays through the live collect pipeline with trusted timestamps (same sessions,
+  raw events and daily rows); once per importId + website, later calls `in_progress` (first still replaying, counts not final),
+  then `skipped` (or `failed`); ≤ 10,000 sessions and
+  1,000 events/session per call; drops future, past-retention, invalid and bot events and exposures of
+  draft splits. `startedAt` on a running split makes imported exposures count.
+- EnsurePageSnapshot: the heatmap backdrop of a page the tracker cannot capture (not online, imported
+  history); keyed by path + layout of `viewport` (desktop ≥ 1024, tablet ≥ 600, phone); sanitized like a
+  capture; needs `snapshotsEnabled`; a live capture replaces it and is never overwritten (`kept`).
+- `tenantId` is required on every content call: no default. Full contract: the interface package's
+  `docs/1.index.md`.
+
 ## Other modules
 
 Tenant users cannot open module pages. To show analytics to them, build a project page from DMS blocks

package/static/tracker.js

@@ -9,6 +9,14 @@
  *   data-host-url        override the collect origin (defaults to the script origin)
  *   data-heatmap-sample  0-1 click/scroll sampling rate; overrides the module setting
  *   data-do-not-track    "false" to ignore the browser DNT and GPC signals
+ *   data-exclude-paths   comma-separated pages left uncounted: `/x` (that
+ *                        page), `/x/*` (one segment below) or `/x/**` (the
+ *                        page and everything below)
+ *
+ * The tag stays live: changing its `data-website-id` sends what follows to
+ * that website, and removing it pauses collection until one is set again.
+ * The dashboard's own tag relies on it to follow sign-out and workspace
+ * switches without a reload.
  *
  * Cookieless by design: no identifier is generated or stored client-side —
  * the backend derives an anonymous visitor hash per request. Payload shape
@@ -118,11 +126,8 @@
     return Math.min(Math.max(rate, 0), 1);
   }
 
-  const websiteId = script.getAttribute("data-website-id");
-  if (!websiteId) {
-    publishApi();
-    return;
-  }
+  /** Null while the page removed it: nothing is collected meanwhile. */
+  let websiteId = script.getAttribute("data-website-id");
 
   // A tag included twice (theme and tag manager) would count everything twice.
   if (window[INSTALLED_GLOBAL]) {
@@ -151,6 +156,12 @@
     config,
   );
 
+  /** Patterns of `data-exclude-paths`, each a path starting with "/". */
+  const excludedPaths = (script.getAttribute("data-exclude-paths") || "")
+    .split(",")
+    .map((pattern) => pattern.trim())
+    .filter((pattern) => pattern.charAt(0) === "/");
+
   const heatmapSampled = Math.random() < sampleRate;
   const queue = [];
   let flushTimer = null;
@@ -193,6 +204,11 @@
   }
 
   function enqueue(event) {
+    // Attribute writes are synchronous; MutationObserver delivery is not.
+    // Until retargeting completes, never put new events in the old queue.
+    if (!websiteId || script.getAttribute("data-website-id") !== websiteId || pageExcluded) {
+      return;
+    }
     queue.push(event);
     if (queue.length >= MAX_BATCH) {
       flush();
@@ -203,9 +219,38 @@
     }
   }
 
+  // --- Excluded pages -------------------------------------------------------
+
+  function withoutTrailingSlash(path) {
+    return path.length > 1 && path.endsWith("/") ? path.slice(0, -1) : path;
+  }
+
+  function pathMatches(pattern, path) {
+    if (pattern.endsWith("/**")) {
+      const base = pattern.slice(0, -3);
+      return path === base || path.startsWith(`${base}/`);
+    }
+    if (pattern.endsWith("/*")) {
+      const base = pattern.slice(0, -2);
+      const rest = path.startsWith(`${base}/`)
+        ? path.slice(base.length + 1)
+        : "";
+      return rest !== "" && rest.indexOf("/") < 0;
+    }
+    return path === withoutTrailingSlash(pattern);
+  }
+
+  function isExcludedPath(pathname) {
+    const path = withoutTrailingSlash(pathname);
+    return excludedPaths.some((pattern) => pathMatches(pattern, path));
+  }
+
   // --- Pageviews (initial + SPA navigations) --------------------------------
 
   let lastPath = null;
+  /** The page on screen matches `data-exclude-paths`: nothing it does is
+   * sent, its clicks and scroll depth included. */
+  let pageExcluded = false;
   /** URL the scroll depth is being measured against — kept because a SPA
    * navigation rewrites `location` before the depth of the page being left
    * is flushed. */
@@ -219,8 +264,12 @@
     }
     flushScrollDepth();
     lastPath = location.pathname;
+    pageExcluded = isExcludedPath(lastPath);
     scrolledUrl = currentUrl();
     maxScrollDepth = -1;
+    if (!websiteId || pageExcluded) {
+      return;
+    }
     // The rate it applies, for the server's "recorded on N % of page loads":
     // counting scroll events against pageviews undercounts the views left
     // before their depth is sent.
@@ -440,6 +489,9 @@
   function requestSnapshot() {
     if (
       !heatmapSampled ||
+      !websiteId ||
+      script.getAttribute("data-website-id") !== websiteId ||
+      pageExcluded ||
       snapshotsRequested >= MAX_SNAPSHOTS_PER_LOAD ||
       window.top !== window ||
       document.visibilityState !== "visible" ||
@@ -562,7 +614,14 @@
     /** Assigned variation of a running experiment, or null. Reports the
      * exposure, so only call it where the variation is actually applied. */
     variation(experiment) {
+      const requestedWebsite = websiteId;
+      if (!requestedWebsite || script.getAttribute("data-website-id") !== requestedWebsite) {
+        return Promise.resolve(null);
+      }
       return loadAssignments().then((assignments) => {
+        if (websiteId !== requestedWebsite || script.getAttribute("data-website-id") !== requestedWebsite) {
+          return null;
+        }
         const assigned = assignments[experiment];
         if (typeof assigned !== "string") {
           return null;
@@ -590,5 +649,31 @@
     flush();
   });
 
+  /**
+   * The tag's website changed: what was collected so far leaves under the
+   * previous one, and the page on screen counts for the new one. The
+   * assignments were the previous website's experiments.
+   */
+  function followWebsiteId() {
+    const next = script.getAttribute("data-website-id") || null;
+    if (next === websiteId) {
+      return;
+    }
+    flushScrollDepth();
+    flush();
+    websiteId = next;
+    assignmentsPromise = null;
+    exposedExperiments.clear();
+    lastPath = null;
+    trackPageview();
+  }
+
+  if (typeof MutationObserver === "function") {
+    new MutationObserver(followWebsiteId).observe(script, {
+      attributes: true,
+      attributeFilter: ["data-website-id"],
+    });
+  }
+
   trackPageview();
 })();

package/frontend-vue/pnpm-workspace.yaml

@@ -1,2 +0,0 @@
-packages:
-  - '.'