@unisights/analytics 0.0.4 → 0.0.6
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 +182 -71
- package/dist/unisights.min.js +2 -2
- package/package.json +32 -10
package/README.md
CHANGED
|
@@ -1,121 +1,232 @@
|
|
|
1
1
|
# Unisights Client SDK
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The Unisights Client SDK is a WebAssembly-powered analytics tracker built with Rust and TypeScript. It captures user interactions in the browser, encrypts data client-side, and sends it securely to your Unisights ingestion service — with minimal performance impact.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
## ✨ Why Unisights
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
- **WASM Performance** — Rust-compiled WASM offers faster execution and lower overhead than traditional JS trackers
|
|
10
|
+
- **Client-Side Encryption** — Data is encrypted in the browser before it ever leaves the client
|
|
11
|
+
- **Lightweight** — ~86KB gzipped, including WASM binary and web vitals tracking
|
|
12
|
+
- **Web Vitals Built-in** — Automatically tracks CLS, INP, LCP, FCP, and TTFB
|
|
13
|
+
- **SPA Ready** — Handles `pushState`, `replaceState`, and `popstate` for React, Next.js, Vue, etc.
|
|
10
14
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## 📦 Installation
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install @unisights/analytics
|
|
21
|
+
# or
|
|
22
|
+
pnpm add @unisights/analytics
|
|
23
|
+
# or
|
|
24
|
+
yarn add @unisights/analytics
|
|
18
25
|
```
|
|
19
26
|
|
|
20
|
-
|
|
21
|
-
- **`src/`**: Includes TypeScript files that wrap the WASM module and expose a simple JavaScript API for developers.
|
|
27
|
+
---
|
|
22
28
|
|
|
23
|
-
## 🚀
|
|
29
|
+
## 🚀 Usage
|
|
24
30
|
|
|
25
|
-
### 1
|
|
31
|
+
### Option 1 — CDN / Script Tag (Recommended)
|
|
26
32
|
|
|
27
|
-
-
|
|
28
|
-
- **Rust** (for building or modifying the WASM core)
|
|
29
|
-
- **WasmPack** (install with `cargo install wasm-pack` for development)
|
|
33
|
+
Add the script tag to your HTML `<head>`. The SDK auto-initializes and exposes `window.unisights`.
|
|
30
34
|
|
|
31
|
-
|
|
35
|
+
```html
|
|
36
|
+
<script
|
|
37
|
+
type="module"
|
|
38
|
+
id="unisights-script"
|
|
39
|
+
async
|
|
40
|
+
data-insights-id="your-insights-id"
|
|
41
|
+
data-secret="your-secret"
|
|
42
|
+
data-salt="your-salt"
|
|
43
|
+
src="https://cdn.yourdomain.com/unisights.min.js"
|
|
44
|
+
></script>
|
|
45
|
+
```
|
|
32
46
|
|
|
33
|
-
|
|
47
|
+
Then use it anywhere in your app:
|
|
34
48
|
|
|
35
|
-
```
|
|
36
|
-
|
|
49
|
+
```javascript
|
|
50
|
+
// Wait for SDK to be ready
|
|
51
|
+
window.unisights?.init();
|
|
52
|
+
|
|
53
|
+
// Log a custom event
|
|
54
|
+
window.unisights?.log("signup", { plan: "pro" });
|
|
55
|
+
|
|
56
|
+
// Flush events immediately
|
|
57
|
+
window.unisights?.flushNow();
|
|
58
|
+
|
|
59
|
+
// Register a custom event handler
|
|
60
|
+
const track = window.unisights?.registerEvent("click", (e) => {});
|
|
61
|
+
track("button_click", { id: "submit-btn" });
|
|
37
62
|
```
|
|
38
63
|
|
|
39
|
-
|
|
64
|
+
#### Usage in React / Next.js
|
|
40
65
|
|
|
41
|
-
|
|
66
|
+
```tsx
|
|
67
|
+
import { useEffect } from "react";
|
|
42
68
|
|
|
43
|
-
|
|
44
|
-
|
|
69
|
+
export default function Layout({ children }) {
|
|
70
|
+
useEffect(() => {
|
|
71
|
+
const script = document.getElementById(
|
|
72
|
+
"unisights-script",
|
|
73
|
+
) as HTMLScriptElement;
|
|
74
|
+
|
|
75
|
+
const initSDK = () => {
|
|
76
|
+
window.unisights?.init().catch(console.error);
|
|
77
|
+
};
|
|
78
|
+
|
|
79
|
+
if (window.unisights) {
|
|
80
|
+
initSDK();
|
|
81
|
+
} else {
|
|
82
|
+
script?.addEventListener("load", initSDK);
|
|
83
|
+
return () => script?.removeEventListener("load", initSDK);
|
|
84
|
+
}
|
|
85
|
+
}, []);
|
|
86
|
+
|
|
87
|
+
return <>{children}</>;
|
|
88
|
+
}
|
|
45
89
|
```
|
|
46
90
|
|
|
47
|
-
|
|
91
|
+
---
|
|
48
92
|
|
|
49
|
-
###
|
|
93
|
+
### Option 2 — Manual Init (Script Tag)
|
|
50
94
|
|
|
51
|
-
|
|
95
|
+
If you prefer to control when the SDK initializes, omit `data-insights-id` and call `init()` manually:
|
|
52
96
|
|
|
53
97
|
```html
|
|
54
98
|
<script
|
|
55
99
|
type="module"
|
|
56
100
|
id="unisights-script"
|
|
57
|
-
|
|
101
|
+
async
|
|
58
102
|
data-insights-id="your-insights-id"
|
|
59
|
-
data-secret="
|
|
60
|
-
data-salt="
|
|
61
|
-
src="
|
|
103
|
+
data-secret="your-secret"
|
|
104
|
+
data-salt="your-salt"
|
|
105
|
+
src="https://cdn.yourdomain.com/unisights.min.js"
|
|
62
106
|
></script>
|
|
107
|
+
|
|
108
|
+
<script type="module">
|
|
109
|
+
await window.unisights.init({
|
|
110
|
+
endpoint: "https://your-ingestion-endpoint.com/collect",
|
|
111
|
+
debug: true,
|
|
112
|
+
});
|
|
113
|
+
</script>
|
|
63
114
|
```
|
|
64
115
|
|
|
65
|
-
|
|
66
|
-
- **`id="unisights-script"`**: A unique identifier for the script tag.
|
|
67
|
-
- **`defer`**: Loads the script asynchronously without blocking HTML parsing.
|
|
68
|
-
- **`data-insights-id`**: Your Unisights API key for identifying the data source.
|
|
69
|
-
- **`src`**: Path to the compiled `analytics-bundle.min.js` file.
|
|
116
|
+
---
|
|
70
117
|
|
|
71
|
-
|
|
118
|
+
## ⚙️ Configuration
|
|
72
119
|
|
|
73
|
-
|
|
120
|
+
All options are passed to `init()` or via `data-analytics-config` on the script tag.
|
|
74
121
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
122
|
+
| Option | Type | Default | Description |
|
|
123
|
+
| ----------------- | --------- | --------------- | ------------------------------------- |
|
|
124
|
+
| `endpoint` | `string` | env var | URL to send analytics events to |
|
|
125
|
+
| `insightsId` | `string` | from script tag | Your Unisights project ID |
|
|
126
|
+
| `secret` | `string` | from script tag | Encryption secret key |
|
|
127
|
+
| `salt` | `string` | from script tag | Encryption salt |
|
|
128
|
+
| `debug` | `boolean` | `false` | Log events to the console |
|
|
129
|
+
| `flushIntervalMs` | `number` | `15000` | How often to flush events (ms) |
|
|
130
|
+
| `trackPageViews` | `boolean` | `true` | Auto-track page views |
|
|
131
|
+
| `trackClicks` | `boolean` | `true` | Auto-track click events |
|
|
132
|
+
| `trackScroll` | `boolean` | `true` | Auto-track scroll depth |
|
|
133
|
+
| `wasmPath` | `string` | inlined | Override wasm binary path (CDN usage) |
|
|
85
134
|
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## 🧩 API Reference
|
|
138
|
+
|
|
139
|
+
### `window.unisights.init(config?)`
|
|
140
|
+
|
|
141
|
+
Initializes the SDK. Must be called before using other methods if auto-init is disabled.
|
|
142
|
+
|
|
143
|
+
```javascript
|
|
144
|
+
await window.unisights.init({
|
|
145
|
+
endpoint: "https://your-endpoint.com/collect",
|
|
146
|
+
debug: true,
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### `window.unisights.log(name, data)`
|
|
151
|
+
|
|
152
|
+
Log a custom event with optional metadata.
|
|
153
|
+
|
|
154
|
+
```javascript
|
|
155
|
+
window.unisights.log("purchase", {
|
|
156
|
+
item: "pro-plan",
|
|
157
|
+
amount: 49.99,
|
|
158
|
+
currency: "USD",
|
|
159
|
+
});
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
### `window.unisights.flushNow()`
|
|
163
|
+
|
|
164
|
+
Immediately send all buffered events to the endpoint.
|
|
165
|
+
|
|
166
|
+
```javascript
|
|
167
|
+
window.unisights.flushNow();
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
### `window.unisights.registerEvent(eventType, handler)`
|
|
171
|
+
|
|
172
|
+
Register a DOM event listener and get back a function to log custom events.
|
|
173
|
+
|
|
174
|
+
```javascript
|
|
175
|
+
const track = window.unisights.registerEvent("click", (e) => {
|
|
176
|
+
console.log("click captured", e);
|
|
177
|
+
});
|
|
178
|
+
|
|
179
|
+
// Later, log an event tied to this listener
|
|
180
|
+
track("cta_click", { label: "Get Started" });
|
|
91
181
|
```
|
|
92
182
|
|
|
93
|
-
|
|
94
|
-
|
|
183
|
+
---
|
|
184
|
+
|
|
185
|
+
## 🏗 TypeScript Support
|
|
186
|
+
|
|
187
|
+
The package ships with type declarations. If you use the SDK via script tag and want `window.unisights` typed in your TypeScript project, install the package for types only:
|
|
188
|
+
|
|
189
|
+
```bash
|
|
190
|
+
npm install @unisights/analytics
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
TypeScript will automatically pick up the `Window` augmentation — no extra configuration needed.
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
// Fully typed — no @ts-ignore needed
|
|
197
|
+
window.unisights?.log("event", { data: "value" });
|
|
198
|
+
```
|
|
199
|
+
|
|
200
|
+
---
|
|
95
201
|
|
|
96
202
|
## 🛠 Development
|
|
97
203
|
|
|
98
|
-
###
|
|
204
|
+
### Prerequisites
|
|
99
205
|
|
|
100
|
-
-
|
|
101
|
-
-
|
|
206
|
+
- Node.js >= 16
|
|
207
|
+
- Rust + Cargo
|
|
208
|
+
- wasm-pack (`cargo install wasm-pack`)
|
|
102
209
|
|
|
103
|
-
###
|
|
210
|
+
### Build
|
|
104
211
|
|
|
105
|
-
|
|
106
|
-
|
|
212
|
+
```bash
|
|
213
|
+
# Install dependencies
|
|
214
|
+
pnpm install
|
|
107
215
|
|
|
108
|
-
|
|
216
|
+
# Build WASM core + JS bundle
|
|
217
|
+
pnpm build
|
|
218
|
+
```
|
|
109
219
|
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
220
|
+
### Local Dev Server
|
|
221
|
+
|
|
222
|
+
```bash
|
|
223
|
+
pnpm dev
|
|
224
|
+
```
|
|
114
225
|
|
|
115
|
-
|
|
226
|
+
Serves `dist/` at `http://localhost:9005`.
|
|
116
227
|
|
|
117
|
-
|
|
228
|
+
---
|
|
118
229
|
|
|
119
230
|
## 📜 License
|
|
120
231
|
|
|
121
|
-
|
|
232
|
+
MIT — see [LICENSE](./LICENSE) for details.
|