@dataxamas/tracker-js 2.4.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. 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.
+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`.
-- **Visitor identity:** computed server-side, no cookies or `localStorage`. Only replay touches the browser, in `sessionStorage["@dataxamas/replay-recording"]`, and only for sampled visitors.
+- **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

@@ -358,6 +358,7 @@ var DataxamasTracking = class {
     this.allowLocalhost = _nullishCoalesce(options.allowLocalhost, () => ( false));
     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));
@@ -427,7 +428,8 @@ var DataxamasTracking = class {
       path,
       referrer: document.referrer,
       query: name === "PAGE_VIEW" ? this.utmQuery() : void 0,
-      data
+      data,
+      userId: _nullishCoalesce(this.userId, () => ( void 0))
     });
     await this.processQueue();
   }
@@ -814,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

@@ -111,6 +111,7 @@ declare class DataxamasTracking {
     private allowLocalhost;
     private started;
     private currentPage;
+    private userId;
     private heatMapEnabled;
     private replayEnabled;
     private webVitalsEnabled;
@@ -183,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

@@ -111,6 +111,7 @@ declare class DataxamasTracking {
     private allowLocalhost;
     private started;
     private currentPage;
+    private userId;
     private heatMapEnabled;
     private replayEnabled;
     private webVitalsEnabled;
@@ -183,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

@@ -358,6 +358,7 @@ var DataxamasTracking = class {
     this.allowLocalhost = options.allowLocalhost ?? false;
     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;
@@ -427,7 +428,8 @@ var DataxamasTracking = class {
       path,
       referrer: document.referrer,
       query: name === "PAGE_VIEW" ? this.utmQuery() : void 0,
-      data
+      data,
+      userId: this.userId ?? void 0
     });
     await this.processQueue();
   }
@@ -814,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.4.0",
+  "version": "2.5.0",
   "type": "module",
   "description": "Node.js SDK for Dataxamas Analytics API",
   "license": "MIT",