@dataxamas/tracker-js 2.3.0 → 2.5.0

package/README.md

@@ -201,10 +201,35 @@ Begin collecting. Waits for `DOMContentLoaded` if the document is still loading,
 - **`CLICK`** — element `tagName`, `text`, `href`, `id`, `classes`, plus heat-map coordinates (viewport ratios, scroll offsets, layout fingerprint) when `heatMapEnabled`.
 - **`SCROLL`** — scroll-depth percentage (debounced).
 
-Events are queued and flushed to `POST /api/v1/events` with a 4s spacing. Every request sends `Authorization: Bearer <apiKey>`. The key is visible to anyone who opens the page, and it can also read events through `GET /api/v1/events` — treat it as public and rotate it from the dashboard if abused. A visitor session id is generated once and stored in `localStorage` under `@dataxamas/session`.
+Events are queued and flushed to `POST /api/v1/events` with a 4s spacing. Every request sends `Authorization: Bearer <apiKey>`. The key is visible to anyone who opens the page, and it can also read events through `GET /api/v1/events` — treat it as public and rotate it from the dashboard if abused. Nothing is stored in the browser to identify the visitor: the server derives the session id from `sha256(daily salt + IP + user agent + websiteId)`, and the salt is replaced every day. A second key with a monthly salt links a visitor's visits to the same site within the month, for retention cohorts.
 
 If `replayEnabled` is on and the server config allows it, session replay starts: `rrweb` is lazy-imported and recordings are sent to `POST /api/v1/replay`.
 
+#### `track(name, data?)`
+
+Sends a custom event. No-op outside the browser.
+
+```ts
+tracking.track("signup", { plan: "pro" });
+```
+
+#### `identify(userId)`
+
+Ties the next events to a user of your system, so retention recognizes the same person across months, browsers and devices. No-op outside the browser.
+
+```ts
+// After sign-in, on every page load
+tracking.identify(user.id);
+
+// On sign-out
+tracking.identify(null);
+```
+
+- The id travels with each event, but the server stores only `sha256(websiteId + userId)` — never the raw value.
+- It lives in memory only: call it again on every page load.
+- Use an opaque, stable id — never an email or a name.
+- Script tag: `window.dataxamas.track(name, data)` and `window.dataxamas.identify(userId)`.
+
 **Behavior notes**
 
 - Throws `"DataxamasTracking: This SDK can only be used in a browser environment."` if called on the server.
@@ -250,7 +275,7 @@ Exported for use in your own typings:
 ## Notes
 
 - **Default endpoint:** `https://dataxamas.com`. Override with `baseUrl`.
-- **Session storage key:** `localStorage["@dataxamas/session"]`.
+- **Visitor identity:** computed server-side, no cookies or `localStorage` — a daily key for the visit, a monthly key (or the `identify()` hash) for retention. Only replay touches the browser, in `sessionStorage["@dataxamas/replay-recording"]`, and only for sampled visitors.
 - **Event flush spacing:** 4 seconds between queued analytics events.
 - **Replay masking classes:** `dx-mask` (text) and `dx-block` (element); all inputs masked by default.
 - **Bundle:** `rrweb` is bundled but split into its own async chunk, loaded only when replay starts — the server/import path never touches it.

package/dist/index.cjs

@@ -328,7 +328,7 @@ var REPLAY_RECORDING_KEY = `${STORAGE_PREFIX}/replay-recording`;
 function isStoredRecording(value) {
   if (typeof value !== "object" || value === null) return false;
   const stored = value;
-  return typeof stored.id === "string" && typeof stored.sessionId === "string" && typeof stored.startedAt === "string" && typeof stored.startedAtMs === "number" && typeof stored.seq === "number" && typeof stored.events === "number" && typeof stored.lastActivityAt === "number" && typeof stored.capped === "boolean";
+  return typeof stored.id === "string" && typeof stored.startedAt === "string" && typeof stored.startedAtMs === "number" && typeof stored.seq === "number" && typeof stored.events === "number" && typeof stored.lastActivityAt === "number" && typeof stored.capped === "boolean";
 }
 var KEEPALIVE_LIMIT_BYTES = 60 * 1024;
 var DataxamasTracking = class {
@@ -356,14 +356,15 @@ var DataxamasTracking = class {
     this.apiKey = options.apiKey;
     this.baseUrl = _nullishCoalesce(options.baseUrl, () => ( BASE_URL));
     this.allowLocalhost = _nullishCoalesce(options.allowLocalhost, () => ( false));
-    this.sessionId = null;
+    this.started = false;
     this.currentPage = isBrowser() ? window.location.pathname : "";
+    this.userId = null;
     this.heatMapEnabled = _nullishCoalesce(options.heatMapEnabled, () => ( true));
     this.replayEnabled = _nullishCoalesce(options.replayEnabled, () => ( true));
     this.webVitalsEnabled = _nullishCoalesce(options.webVitalsEnabled, () => ( true));
     this.pendingVitals = /* @__PURE__ */ new Map();
     this.vitalsPath = "";
-    this.replaySampleRate = 1;
+    this.replaySampled = false;
     this.eventQueue = [];
     this.isProcessing = false;
     this.rrwebRecord = null;
@@ -386,21 +387,6 @@ var DataxamasTracking = class {
   isLocalhost() {
     return window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1";
   }
-  getSessionId() {
-    try {
-      return window.localStorage.getItem(`${STORAGE_PREFIX}/session`);
-    } catch (_) {
-      return null;
-    }
-  }
-  createSessionId() {
-    const id = crypto.randomUUID();
-    try {
-      window.localStorage.setItem(`${STORAGE_PREFIX}/session`, id);
-    } catch (_) {
-    }
-    return id;
-  }
   async processQueue() {
     if (this.isProcessing || this.eventQueue.length === 0) return;
     this.isProcessing = true;
@@ -436,14 +422,14 @@ var DataxamasTracking = class {
     path = this.currentPage,
     data = {}
   }) {
-    if (!this.sessionId) return;
+    if (!this.started) return;
     this.eventQueue.push({
       name,
       path,
       referrer: document.referrer,
       query: name === "PAGE_VIEW" ? this.utmQuery() : void 0,
-      sessionId: this.sessionId,
-      data
+      data,
+      userId: _nullishCoalesce(this.userId, () => ( void 0))
     });
     await this.processQueue();
   }
@@ -468,9 +454,7 @@ var DataxamasTracking = class {
       const cfg = await res.json();
       if (typeof cfg.heatMapEnabled === "boolean") this.heatMapEnabled = cfg.heatMapEnabled;
       if (typeof cfg.replayEnabled === "boolean") this.replayEnabled = cfg.replayEnabled;
-      if (typeof cfg.replaySampleRate === "number" && cfg.replaySampleRate >= 0 && cfg.replaySampleRate <= 1) {
-        this.replaySampleRate = cfg.replaySampleRate;
-      }
+      if (typeof cfg.replaySampled === "boolean") this.replaySampled = cfg.replaySampled;
     } catch (_) {
     }
   }
@@ -551,14 +535,13 @@ var DataxamasTracking = class {
     });
   }
   flushVitals() {
-    if (!this.sessionId || this.pendingVitals.size === 0) return;
+    if (this.pendingVitals.size === 0) return;
     const metrics = Array.from(this.pendingVitals.values());
     this.pendingVitals.clear();
     window.fetch(`${this.baseUrl}/api/v1/vitals`, {
       method: "POST",
       headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
       body: JSON.stringify({
-        sessionId: this.sessionId,
         path: this.vitalsPath,
         viewportWidth: window.innerWidth,
         metrics
@@ -602,27 +585,6 @@ var DataxamasTracking = class {
     const layoutFingerprint = `${this.currentPage}:${Math.round(pageWidth / 100)}x${Math.round(pageHeight / 100)}`;
     return { viewportWidth, viewportHeight, pageWidth, pageHeight, layoutFingerprint };
   }
-  /**
-   * Sorteio por visitante, não por gravação: quem entrou no sorteio tem a sessão inteira, em vez
-   * de um replay picotado que não dá para assistir.
-   */
-  isReplaySampled() {
-    const rate = this.replaySampleRate;
-    if (rate >= 1) return true;
-    if (rate <= 0) return false;
-    const key = `${STORAGE_PREFIX}/replay-sample`;
-    try {
-      const [storedRate, storedDecision] = (_nullishCoalesce(window.localStorage.getItem(key), () => ( ""))).split(":");
-      if (Number(storedRate) === rate && (storedDecision === "1" || storedDecision === "0")) {
-        return storedDecision === "1";
-      }
-      const sampled = Math.random() < rate;
-      window.localStorage.setItem(key, `${rate}:${sampled ? "1" : "0"}`);
-      return sampled;
-    } catch (_) {
-      return Math.random() < rate;
-    }
-  }
   isRecording() {
     return Boolean(this.stopRrweb);
   }
@@ -638,10 +600,9 @@ var DataxamasTracking = class {
     }
   }
   saveRecording() {
-    if (!this.sessionId || !this.recordingId || !this.recordingStartedAt) return;
+    if (!this.recordingId || !this.recordingStartedAt) return;
     const stored = {
       id: this.recordingId,
-      sessionId: this.sessionId,
       startedAt: this.recordingStartedAt,
       startedAtMs: this.recordingStartedAtMs,
       seq: this.recordingSeq,
@@ -667,7 +628,7 @@ var DataxamasTracking = class {
   /** Reload ou navegação completa na mesma aba continua a gravação, se a visita ainda estiver ativa. */
   resumeOrRotateRecording() {
     const stored = this.loadRecording();
-    if (!stored || stored.capped || stored.sessionId !== this.sessionId || Date.now() - stored.lastActivityAt >= REPLAY_IDLE_TIMEOUT_MS) {
+    if (!stored || stored.capped || Date.now() - stored.lastActivityAt >= REPLAY_IDLE_TIMEOUT_MS) {
       this.rotateRecording();
       return;
     }
@@ -690,7 +651,6 @@ var DataxamasTracking = class {
     const events = this.replayBuffer;
     this.replayBuffer = [];
     const payload = JSON.stringify({
-      sessionId: this.sessionId,
       recordingId: this.recordingId,
       path: this.currentPage,
       startedAt: this.recordingStartedAt,
@@ -839,15 +799,15 @@ var DataxamasTracking = class {
     });
   }
   startTracking() {
-    this.sessionId = _nullishCoalesce(this.getSessionId(), () => ( this.createSessionId()));
-    this.resumeOrRotateRecording();
+    this.started = true;
     this.sendEvent({ name: "PAGE_VIEW" });
     this.trackPageChanges();
     this.trackClicks();
     this.trackScroll();
     this.trackWebVitals();
     this.fetchWebsiteConfig().then(() => {
-      if (!this.replayEnabled || !this.isReplaySampled()) return;
+      if (!this.replayEnabled || !this.replaySampled) return;
+      this.resumeOrRotateRecording();
       this.setupReplayLifecycle();
     });
   }
@@ -856,6 +816,14 @@ var DataxamasTracking = class {
     if (!isBrowser()) return;
     void this.sendEvent({ name, data });
   }
+  /**
+   * Liga os próximos eventos ao usuário logado no site (o id do seu sistema), para a retenção reconhecer quem volta
+   * em outro navegador ou depois da virada do mês. O servidor guarda só um hash. `null` desfaz, no logout.
+   */
+  identify(userId) {
+    if (!isBrowser()) return;
+    this.userId = _optionalChain([userId, 'optionalAccess', _29 => _29.trim, 'call', _30 => _30()]) || null;
+  }
   start() {
     if (!isBrowser()) {
       throw new Error("DataxamasTracking: This SDK can only be used in a browser environment.");

package/dist/index.d.cts

@@ -109,14 +109,15 @@ declare class DataxamasTracking {
     private apiKey;
     private baseUrl;
     private allowLocalhost;
-    private sessionId;
+    private started;
     private currentPage;
+    private userId;
     private heatMapEnabled;
     private replayEnabled;
     private webVitalsEnabled;
     private pendingVitals;
     private vitalsPath;
-    private replaySampleRate;
+    private replaySampled;
     private eventQueue;
     private isProcessing;
     private rrwebRecord;
@@ -137,8 +138,6 @@ declare class DataxamasTracking {
     private lastActivitySavedAt;
     constructor(options: DataxamasTrackingOptions);
     private isLocalhost;
-    private getSessionId;
-    private createSessionId;
     private processQueue;
     private utmQuery;
     private sendEvent;
@@ -153,11 +152,6 @@ declare class DataxamasTracking {
     private flushVitals;
     private trackWebVitals;
     private measureReplay;
-    /**
-     * Sorteio por visitante, não por gravação: quem entrou no sorteio tem a sessão inteira, em vez
-     * de um replay picotado que não dá para assistir.
-     */
-    private isReplaySampled;
     private isRecording;
     private exceededReplayCaps;
     private loadRecording;
@@ -190,6 +184,11 @@ declare class DataxamasTracking {
     private startTracking;
     /** Evento customizado (ex.: `signup_done`), usado em metas e funis. Antes do `start()` não envia nada. */
     track(name: string, data?: Record<string, unknown>): void;
+    /**
+     * Liga os próximos eventos ao usuário logado no site (o id do seu sistema), para a retenção reconhecer quem volta
+     * em outro navegador ou depois da virada do mês. O servidor guarda só um hash. `null` desfaz, no logout.
+     */
+    identify(userId: string | null): void;
     start(): void;
 }
 

package/dist/index.d.ts

@@ -109,14 +109,15 @@ declare class DataxamasTracking {
     private apiKey;
     private baseUrl;
     private allowLocalhost;
-    private sessionId;
+    private started;
     private currentPage;
+    private userId;
     private heatMapEnabled;
     private replayEnabled;
     private webVitalsEnabled;
     private pendingVitals;
     private vitalsPath;
-    private replaySampleRate;
+    private replaySampled;
     private eventQueue;
     private isProcessing;
     private rrwebRecord;
@@ -137,8 +138,6 @@ declare class DataxamasTracking {
     private lastActivitySavedAt;
     constructor(options: DataxamasTrackingOptions);
     private isLocalhost;
-    private getSessionId;
-    private createSessionId;
     private processQueue;
     private utmQuery;
     private sendEvent;
@@ -153,11 +152,6 @@ declare class DataxamasTracking {
     private flushVitals;
     private trackWebVitals;
     private measureReplay;
-    /**
-     * Sorteio por visitante, não por gravação: quem entrou no sorteio tem a sessão inteira, em vez
-     * de um replay picotado que não dá para assistir.
-     */
-    private isReplaySampled;
     private isRecording;
     private exceededReplayCaps;
     private loadRecording;
@@ -190,6 +184,11 @@ declare class DataxamasTracking {
     private startTracking;
     /** Evento customizado (ex.: `signup_done`), usado em metas e funis. Antes do `start()` não envia nada. */
     track(name: string, data?: Record<string, unknown>): void;
+    /**
+     * Liga os próximos eventos ao usuário logado no site (o id do seu sistema), para a retenção reconhecer quem volta
+     * em outro navegador ou depois da virada do mês. O servidor guarda só um hash. `null` desfaz, no logout.
+     */
+    identify(userId: string | null): void;
     start(): void;
 }
 

package/dist/index.js

@@ -328,7 +328,7 @@ var REPLAY_RECORDING_KEY = `${STORAGE_PREFIX}/replay-recording`;
 function isStoredRecording(value) {
   if (typeof value !== "object" || value === null) return false;
   const stored = value;
-  return typeof stored.id === "string" && typeof stored.sessionId === "string" && typeof stored.startedAt === "string" && typeof stored.startedAtMs === "number" && typeof stored.seq === "number" && typeof stored.events === "number" && typeof stored.lastActivityAt === "number" && typeof stored.capped === "boolean";
+  return typeof stored.id === "string" && typeof stored.startedAt === "string" && typeof stored.startedAtMs === "number" && typeof stored.seq === "number" && typeof stored.events === "number" && typeof stored.lastActivityAt === "number" && typeof stored.capped === "boolean";
 }
 var KEEPALIVE_LIMIT_BYTES = 60 * 1024;
 var DataxamasTracking = class {
@@ -356,14 +356,15 @@ var DataxamasTracking = class {
     this.apiKey = options.apiKey;
     this.baseUrl = options.baseUrl ?? BASE_URL;
     this.allowLocalhost = options.allowLocalhost ?? false;
-    this.sessionId = null;
+    this.started = false;
     this.currentPage = isBrowser() ? window.location.pathname : "";
+    this.userId = null;
     this.heatMapEnabled = options.heatMapEnabled ?? true;
     this.replayEnabled = options.replayEnabled ?? true;
     this.webVitalsEnabled = options.webVitalsEnabled ?? true;
     this.pendingVitals = /* @__PURE__ */ new Map();
     this.vitalsPath = "";
-    this.replaySampleRate = 1;
+    this.replaySampled = false;
     this.eventQueue = [];
     this.isProcessing = false;
     this.rrwebRecord = null;
@@ -386,21 +387,6 @@ var DataxamasTracking = class {
   isLocalhost() {
     return window.location.hostname === "localhost" || window.location.hostname === "127.0.0.1";
   }
-  getSessionId() {
-    try {
-      return window.localStorage.getItem(`${STORAGE_PREFIX}/session`);
-    } catch (_) {
-      return null;
-    }
-  }
-  createSessionId() {
-    const id = crypto.randomUUID();
-    try {
-      window.localStorage.setItem(`${STORAGE_PREFIX}/session`, id);
-    } catch (_) {
-    }
-    return id;
-  }
   async processQueue() {
     if (this.isProcessing || this.eventQueue.length === 0) return;
     this.isProcessing = true;
@@ -436,14 +422,14 @@ var DataxamasTracking = class {
     path = this.currentPage,
     data = {}
   }) {
-    if (!this.sessionId) return;
+    if (!this.started) return;
     this.eventQueue.push({
       name,
       path,
       referrer: document.referrer,
       query: name === "PAGE_VIEW" ? this.utmQuery() : void 0,
-      sessionId: this.sessionId,
-      data
+      data,
+      userId: this.userId ?? void 0
     });
     await this.processQueue();
   }
@@ -468,9 +454,7 @@ var DataxamasTracking = class {
       const cfg = await res.json();
       if (typeof cfg.heatMapEnabled === "boolean") this.heatMapEnabled = cfg.heatMapEnabled;
       if (typeof cfg.replayEnabled === "boolean") this.replayEnabled = cfg.replayEnabled;
-      if (typeof cfg.replaySampleRate === "number" && cfg.replaySampleRate >= 0 && cfg.replaySampleRate <= 1) {
-        this.replaySampleRate = cfg.replaySampleRate;
-      }
+      if (typeof cfg.replaySampled === "boolean") this.replaySampled = cfg.replaySampled;
     } catch (_) {
     }
   }
@@ -551,14 +535,13 @@ var DataxamasTracking = class {
     });
   }
   flushVitals() {
-    if (!this.sessionId || this.pendingVitals.size === 0) return;
+    if (this.pendingVitals.size === 0) return;
     const metrics = Array.from(this.pendingVitals.values());
     this.pendingVitals.clear();
     window.fetch(`${this.baseUrl}/api/v1/vitals`, {
       method: "POST",
       headers: { Authorization: `Bearer ${this.apiKey}`, "Content-Type": "application/json" },
       body: JSON.stringify({
-        sessionId: this.sessionId,
         path: this.vitalsPath,
         viewportWidth: window.innerWidth,
         metrics
@@ -602,27 +585,6 @@ var DataxamasTracking = class {
     const layoutFingerprint = `${this.currentPage}:${Math.round(pageWidth / 100)}x${Math.round(pageHeight / 100)}`;
     return { viewportWidth, viewportHeight, pageWidth, pageHeight, layoutFingerprint };
   }
-  /**
-   * Sorteio por visitante, não por gravação: quem entrou no sorteio tem a sessão inteira, em vez
-   * de um replay picotado que não dá para assistir.
-   */
-  isReplaySampled() {
-    const rate = this.replaySampleRate;
-    if (rate >= 1) return true;
-    if (rate <= 0) return false;
-    const key = `${STORAGE_PREFIX}/replay-sample`;
-    try {
-      const [storedRate, storedDecision] = (window.localStorage.getItem(key) ?? "").split(":");
-      if (Number(storedRate) === rate && (storedDecision === "1" || storedDecision === "0")) {
-        return storedDecision === "1";
-      }
-      const sampled = Math.random() < rate;
-      window.localStorage.setItem(key, `${rate}:${sampled ? "1" : "0"}`);
-      return sampled;
-    } catch (_) {
-      return Math.random() < rate;
-    }
-  }
   isRecording() {
     return Boolean(this.stopRrweb);
   }
@@ -638,10 +600,9 @@ var DataxamasTracking = class {
     }
   }
   saveRecording() {
-    if (!this.sessionId || !this.recordingId || !this.recordingStartedAt) return;
+    if (!this.recordingId || !this.recordingStartedAt) return;
     const stored = {
       id: this.recordingId,
-      sessionId: this.sessionId,
       startedAt: this.recordingStartedAt,
       startedAtMs: this.recordingStartedAtMs,
       seq: this.recordingSeq,
@@ -667,7 +628,7 @@ var DataxamasTracking = class {
   /** Reload ou navegação completa na mesma aba continua a gravação, se a visita ainda estiver ativa. */
   resumeOrRotateRecording() {
     const stored = this.loadRecording();
-    if (!stored || stored.capped || stored.sessionId !== this.sessionId || Date.now() - stored.lastActivityAt >= REPLAY_IDLE_TIMEOUT_MS) {
+    if (!stored || stored.capped || Date.now() - stored.lastActivityAt >= REPLAY_IDLE_TIMEOUT_MS) {
       this.rotateRecording();
       return;
     }
@@ -690,7 +651,6 @@ var DataxamasTracking = class {
     const events = this.replayBuffer;
     this.replayBuffer = [];
     const payload = JSON.stringify({
-      sessionId: this.sessionId,
       recordingId: this.recordingId,
       path: this.currentPage,
       startedAt: this.recordingStartedAt,
@@ -839,15 +799,15 @@ var DataxamasTracking = class {
     });
   }
   startTracking() {
-    this.sessionId = this.getSessionId() ?? this.createSessionId();
-    this.resumeOrRotateRecording();
+    this.started = true;
     this.sendEvent({ name: "PAGE_VIEW" });
     this.trackPageChanges();
     this.trackClicks();
     this.trackScroll();
     this.trackWebVitals();
     this.fetchWebsiteConfig().then(() => {
-      if (!this.replayEnabled || !this.isReplaySampled()) return;
+      if (!this.replayEnabled || !this.replaySampled) return;
+      this.resumeOrRotateRecording();
       this.setupReplayLifecycle();
     });
   }
@@ -856,6 +816,14 @@ var DataxamasTracking = class {
     if (!isBrowser()) return;
     void this.sendEvent({ name, data });
   }
+  /**
+   * Liga os próximos eventos ao usuário logado no site (o id do seu sistema), para a retenção reconhecer quem volta
+   * em outro navegador ou depois da virada do mês. O servidor guarda só um hash. `null` desfaz, no logout.
+   */
+  identify(userId) {
+    if (!isBrowser()) return;
+    this.userId = userId?.trim() || null;
+  }
   start() {
     if (!isBrowser()) {
       throw new Error("DataxamasTracking: This SDK can only be used in a browser environment.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dataxamas/tracker-js",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Node.js SDK for Dataxamas Analytics API",
   "license": "MIT",