alphana-sdk 1.9.0 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +31 -28
- package/dist/alphana-sdk.global.js +68 -4
- package/dist/index.d.mts +21 -1
- package/dist/index.d.ts +21 -1
- package/dist/index.js +69 -5
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +69 -5
- package/dist/index.mjs.map +1 -1
- package/dist/react/index.d.mts +20 -0
- package/dist/react/index.d.ts +20 -0
- package/dist/react/index.js +68 -4
- package/dist/react/index.js.map +1 -1
- package/dist/react/index.mjs +68 -4
- package/dist/react/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -2,14 +2,16 @@
|
|
|
2
2
|
|
|
3
3
|
Client-side analytics SDK for the [Alphana](https://alphana.ir) platform. Collects navigation, time-on-page, heatmap interactions, console errors, and feature-flag evaluations, then batches and sends them to your Alphana backend.
|
|
4
4
|
|
|
5
|
-
**NPM:** `[alphana-sdk](https://www.npmjs.com/package/alphana-sdk)` · **Version:** 0.
|
|
5
|
+
**NPM:** `[alphana-sdk](https://www.npmjs.com/package/alphana-sdk)` · **Version:** 2.0.2 · **License:** MIT
|
|
6
6
|
|
|
7
7
|
## Features
|
|
8
8
|
|
|
9
9
|
- **SPA navigation** — Monitors `history.pushState`, `replaceState`, and `popstate` for automatic page views and U-turn detection (quick bounces).
|
|
10
10
|
- **Time on page** — Cumulative dwell time per path, updated on tab hide and navigation.
|
|
11
11
|
- **Heatmaps** — Sampled mouse moves, clicks, scrolls, and rage-click bursts; coordinates stored as page percentages for resolution-independent replay.
|
|
12
|
-
- **
|
|
12
|
+
- **Element goals & revenue** — Optional dashboard-configured click tracking by HTML element `id` (WordPress / no-code friendly).
|
|
13
|
+
- **Cookie consent** — Optional dashboard widget; tracking waits for visitor acceptance when enabled.
|
|
14
|
+
- **Session identity** — Per-tab session ID plus a persistent `visitorId` in `localStorage` (after consent when required).
|
|
13
15
|
- **Batched ingest** — Events queue locally and flush on batch size, interval, or page unload (`sendBeacon`).
|
|
14
16
|
- **Heartbeats** — Keep-alive pings every 30s; deactivate signal when the tab is hidden.
|
|
15
17
|
- **Error logging** — Patches `console.info/warn/error`, `window.onerror`, and unhandled rejections (optional).
|
|
@@ -209,25 +211,26 @@ Publish the bundle with MinIO (see [CDN upload](#cdn-upload) below). The WordPre
|
|
|
209
211
|
|
|
210
212
|
All options are passed to `new UserTracker(config)` or `<UserTrackerProvider config={…} />`.
|
|
211
213
|
|
|
212
|
-
| Option
|
|
213
|
-
|
|
|
214
|
-
| `endpoint`
|
|
215
|
-
| `appId`
|
|
216
|
-
| `secretKey`
|
|
217
|
-
| `sessionId`
|
|
218
|
-
| `trackNavigation`
|
|
219
|
-
| `trackTime`
|
|
220
|
-
| `trackHeatmap`
|
|
221
|
-
| `trackLogs`
|
|
222
|
-
| `mouseSampleRate`
|
|
223
|
-
| `maxHeatmapPoints`
|
|
224
|
-
| `batchSize`
|
|
225
|
-
| `flushInterval`
|
|
226
|
-
| `compressPayloads`
|
|
227
|
-
| `compressionThresholdBytes` | `number`
|
|
228
|
-
| `collectEndpoint`
|
|
229
|
-
| `heatmapPages`
|
|
230
|
-
| `onEvent`
|
|
214
|
+
| Option | Type | Default | Description |
|
|
215
|
+
| --------------------------- | ---------------------- | ----------------------------------- | -------------------------------------------------------------------------------- |
|
|
216
|
+
| `endpoint` | `string` | `https://api.alphana.ir/api/events` | Events API base URL |
|
|
217
|
+
| `appId` | `string` | — | App identifier from the dashboard |
|
|
218
|
+
| `secretKey` | `string` | — | Bearer token for authenticated requests |
|
|
219
|
+
| `sessionId` | `string` | auto (`crypto.randomUUID`) | Override session ID |
|
|
220
|
+
| `trackNavigation` | `boolean` | `true` | SPA route / pageview tracking |
|
|
221
|
+
| `trackTime` | `boolean` | `true` | Time-on-page per path |
|
|
222
|
+
| `trackHeatmap` | `boolean` | `true` | Mouse, click, scroll sampling |
|
|
223
|
+
| `trackLogs` | `boolean` | `true` | Console and uncaught error capture |
|
|
224
|
+
| `mouseSampleRate` | `number` | `0.3` | Fraction of move/scroll events to record (0–1) |
|
|
225
|
+
| `maxHeatmapPoints` | `number` | `2000` | Max in-memory points per page |
|
|
226
|
+
| `batchSize` | `number` | `20` | Auto-flush when queue reaches this size |
|
|
227
|
+
| `flushInterval` | `number` | `5000` | Auto-flush interval in ms |
|
|
228
|
+
| `compressPayloads` | `boolean` | `true` | Gzip-compress large ingest bodies when the browser supports it |
|
|
229
|
+
| `compressionThresholdBytes` | `number` | `1024` | Minimum JSON size (bytes) before gzip is attempted |
|
|
230
|
+
| `collectEndpoint` | `string` | — | Override unified ingest URL (default: `{apiBase}/collect` from `endpoint`) |
|
|
231
|
+
| `heatmapPages` | `string[]` | — | Only capture heatmap data on these paths (from dashboard “Heatmap Pages”) |
|
|
232
|
+
| `onEvent` | `(event) => void` | — | Synchronous callback for every emitted event |
|
|
233
|
+
| `consentMode` | `"auto" \| "disabled"` | `auto` | Honor dashboard cookie-consent widget (`auto`) or track immediately (`disabled`) |
|
|
231
234
|
|
|
232
235
|
Example with heatmap path allowlist and custom sampling:
|
|
233
236
|
|
|
@@ -385,13 +388,13 @@ renderHeatmap(canvas, points, {
|
|
|
385
388
|
|
|
386
389
|
## Network behavior
|
|
387
390
|
|
|
388
|
-
| Traffic
|
|
389
|
-
|
|
|
390
|
-
| Collect (SDK ≥ 1.8) | `POST {apiBase}/collect`
|
|
391
|
-
| Event batch
|
|
392
|
-
| Heartbeat
|
|
393
|
-
| Logs
|
|
394
|
-
| Feature flags
|
|
391
|
+
| Traffic | Endpoint | When |
|
|
392
|
+
| ------------------- | --------------------------------------- | ---------------------------------------------------------- |
|
|
393
|
+
| Collect (SDK ≥ 1.8) | `POST {apiBase}/collect` | Event batches, heartbeats, and logs (multiplexed envelope) |
|
|
394
|
+
| Event batch | `POST {endpoint}/batch` | Legacy SDK < 1.8 — still supported on the backend |
|
|
395
|
+
| Heartbeat | `POST {endpoint}/heartbeat` | Legacy SDK < 1.8 |
|
|
396
|
+
| Logs | `POST {apiBase}/logs/ingest` | Legacy SDK < 1.8 |
|
|
397
|
+
| Feature flags | `POST {apiBase}/feature-flags/evaluate` | On init and after `identify()` |
|
|
395
398
|
|
|
396
399
|
All authenticated requests send `Authorization: Bearer {secretKey}`. Analytics failures are silent in production (no thrown errors to end users). Unload uses `navigator.sendBeacon` when available.
|
|
397
400
|
|