@clianta/sdk 1.6.1 → 1.6.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 CHANGED
@@ -1,62 +1,33 @@
1
1
  # Clianta SDK
2
2
 
3
- Client-side tracking and CRM SDK for lead generation. Installs on your customer's website and automatically tracks visitors, captures forms, identifies leads, and writes data to your CRM all from the frontend, no API key required.
3
+ **Plug-and-play tracking for your CRM.** Install add one line done. Everything auto-tracks.
4
4
 
5
- ## Key Features
5
+ No manual tracking code needed. The SDK automatically captures page views, form submissions, clicks, scroll depth, downloads, engagement, exit intent, errors, and performance — and auto-identifies visitors from email fields in forms.
6
6
 
7
- - 📊 **Auto-Tracking** — Page views, clicks, forms, scroll depth, downloads, engagement, exit intent, errors, performance
8
- - 🔍 **Auto-Identify** — Detects email fields in forms and links anonymous visitors to CRM contacts
9
- - 🏢 **Group & Alias** — Associate visitors with companies (`group()`) and merge identities across devices (`alias()`)
10
- - 📱 **Screen Views** — Track mobile-first PWA / SPA screens with `screen()`
11
- - 🔧 **Event Middleware** — Intercept, transform, or drop events before they're sent with `use()`
12
- - 📝 **Public CRM API** — Create contacts, submit forms, log activities, create opportunities — secured by domain whitelist
13
- - 🔒 **GDPR Compliant** — Built-in consent management with event buffering, anonymous mode, cookie-less mode
14
- - ⚡ **Framework Support** — React, Next.js, Vue, Angular, Svelte, or vanilla JS
15
- - 🛡️ **Error Boundary** — React ErrorBoundary ensures SDK crashes never break your client's app
16
- - 📦 **~8KB gzipped** — Lightweight, zero dependencies
7
+ ---
8
+
9
+ ## Setup (2 minutes)
17
10
 
18
- ## Installation
11
+ ### React / Next.js
19
12
 
20
13
  ```bash
21
14
  npm install @clianta/sdk
22
- # or
23
- yarn add @clianta/sdk
24
15
  ```
25
16
 
26
- ### Script Tag (HTML, WordPress, Webflow)
27
-
28
- ```html
29
- <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js"></script>
30
17
  ```
31
-
32
- ---
33
-
34
- ## Quick Start
35
-
36
- ### React / Next.js (Recommended)
37
-
38
- ```tsx
39
- // clianta.config.ts
40
- import type { CliantaConfig } from '@clianta/sdk';
41
-
42
- const config: CliantaConfig = {
43
- projectId: 'YOUR_WORKSPACE_ID',
44
- debug: process.env.NODE_ENV === 'development',
45
- };
46
-
47
- export default config;
18
+ # .env.local
19
+ NEXT_PUBLIC_CLIANTA_ID=your-project-id
48
20
  ```
49
21
 
50
22
  ```tsx
51
23
  // app/layout.tsx
52
24
  import { CliantaProvider } from '@clianta/sdk/react';
53
- import cliantaConfig from '../clianta.config';
54
25
 
55
- export default function RootLayout({ children }: { children: React.ReactNode }) {
26
+ export default function RootLayout({ children }) {
56
27
  return (
57
28
  <html lang="en">
58
29
  <body>
59
- <CliantaProvider config={cliantaConfig} onError={(err) => console.error(err)}>
30
+ <CliantaProvider projectId={process.env.NEXT_PUBLIC_CLIANTA_ID!}>
60
31
  {children}
61
32
  </CliantaProvider>
62
33
  </body>
@@ -65,373 +36,152 @@ export default function RootLayout({ children }: { children: React.ReactNode })
65
36
  }
66
37
  ```
67
38
 
68
- ```tsx
69
- // Any component
70
- import { useClianta, useCliantaReady } from '@clianta/sdk/react';
71
-
72
- function PricingPage() {
73
- const tracker = useClianta();
74
- const { isReady } = useCliantaReady();
75
-
76
- const handleClick = () => {
77
- tracker?.track('button_click', 'Get Started', { plan: 'pro' });
78
- };
79
-
80
- return <button onClick={handleClick}>Get Started</button>;
81
- }
82
- ```
83
-
84
- ### NPM Module (Vanilla)
39
+ **That's it.** Everything auto-tracks. No other code needed.
85
40
 
86
- ```typescript
87
- import { clianta } from '@clianta/sdk';
88
-
89
- const tracker = clianta('YOUR_WORKSPACE_ID', {
90
- debug: true,
91
- });
41
+ ---
92
42
 
93
- tracker.track('button_click', 'Signup Button', { location: 'hero' });
94
- tracker.identify('user@example.com', { firstName: 'John' });
95
- ```
43
+ ### Script Tag (HTML / WordPress / Webflow / Shopify)
96
44
 
97
- ### Script Tag (Any Website)
45
+ One line. Paste before `</head>`:
98
46
 
99
47
  ```html
100
- <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js"></script>
101
- <script>
102
- var tracker = clianta('YOUR_WORKSPACE_ID');
103
- </script>
48
+ <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js" data-project-id="YOUR_PROJECT_ID"></script>
104
49
  ```
105
50
 
106
- **WordPress**: Add to `Appearance > Theme Editor > header.php` before `</head>`
107
- **Webflow**: Add to `Project Settings > Custom Code > Head Code`
108
- **Shopify**: Add to `Online Store > Themes > Edit Code > theme.liquid`
51
+ **That's it.** The SDK auto-initializes from the `data-project-id` attribute.
109
52
 
110
53
  ---
111
54
 
112
- ## Framework Integrations
113
-
114
55
  ### Vue 3
115
56
 
57
+ ```bash
58
+ npm install @clianta/sdk
59
+ ```
60
+
116
61
  ```typescript
117
62
  // main.ts
118
- import { createApp } from 'vue';
119
63
  import { CliantaPlugin } from '@clianta/sdk/vue';
120
- import App from './App.vue';
121
64
 
122
- const app = createApp(App);
123
- app.use(CliantaPlugin, {
124
- projectId: 'YOUR_WORKSPACE_ID',
125
- });
126
- app.mount('#app');
65
+ app.use(CliantaPlugin, { projectId: 'YOUR_PROJECT_ID' });
127
66
  ```
128
67
 
129
- ```vue
130
- <script setup>
131
- import { useClianta, useCliantaTrack } from '@clianta/sdk/vue';
132
-
133
- const tracker = useClianta();
134
- const track = useCliantaTrack();
135
-
136
- track('button_click', 'CTA Clicked', { page: 'home' });
137
- </script>
138
- ```
68
+ ---
139
69
 
140
70
  ### Angular
141
71
 
142
72
  ```typescript
143
73
  // clianta.service.ts
144
- import { Injectable, OnDestroy } from '@angular/core';
145
- import { createCliantaTracker, type CliantaTrackerInstance } from '@clianta/sdk/angular';
74
+ import { createCliantaTracker } from '@clianta/sdk/angular';
146
75
 
147
76
  @Injectable({ providedIn: 'root' })
148
77
  export class CliantaService implements OnDestroy {
149
- private instance: CliantaTrackerInstance;
150
-
151
- constructor() {
152
- this.instance = createCliantaTracker({
153
- projectId: environment.cliantaProjectId,
154
- });
155
- }
156
-
78
+ private instance = createCliantaTracker({ projectId: 'YOUR_PROJECT_ID' });
157
79
  get tracker() { return this.instance.tracker; }
158
-
159
- track(eventType: string, eventName: string, props?: Record<string, unknown>) {
160
- this.instance.tracker?.track(eventType, eventName, props);
161
- }
162
-
163
80
  ngOnDestroy() { this.instance.destroy(); }
164
81
  }
165
82
  ```
166
83
 
84
+ ---
85
+
167
86
  ### Svelte
168
87
 
169
88
  ```svelte
170
- <!-- +layout.svelte -->
171
89
  <script>
172
90
  import { initClianta } from '@clianta/sdk/svelte';
173
91
  import { setContext } from 'svelte';
174
-
175
- const clianta = initClianta({
176
- projectId: 'YOUR_WORKSPACE_ID',
177
- });
178
-
179
- setContext('clianta', clianta);
92
+ setContext('clianta', initClianta({ projectId: 'YOUR_PROJECT_ID' }));
180
93
  </script>
181
-
182
94
  <slot />
183
95
  ```
184
96
 
185
- ```svelte
186
- <!-- Any component -->
187
- <script>
188
- import { getContext } from 'svelte';
189
- const clianta = getContext('clianta');
190
-
191
- function handleClick() {
192
- clianta.track('button_click', 'CTA', { page: 'home' });
193
- }
194
- </script>
195
-
196
- <button on:click={handleClick}>Click Me</button>
197
- ```
198
-
199
97
  ---
200
98
 
201
- ## Configuration
99
+ ## What Happens Automatically
202
100
 
203
- ```typescript
204
- const tracker = clianta('WORKSPACE_ID', {
205
- debug: false,
206
- autoPageView: true,
207
-
208
- plugins: [
209
- 'pageView', // Page views with SPA support
210
- 'forms', // Auto-detect & identify from forms
211
- 'scroll', // Scroll depth (25%, 50%, 75%, 100%)
212
- 'clicks', // Button/CTA clicks
213
- 'engagement', // User engagement detection
214
- 'downloads', // File download tracking
215
- 'exitIntent', // Exit intent detection
216
- 'errors', // JavaScript error tracking
217
- 'performance', // Web Vitals (LCP, FCP, CLS)
218
- ],
219
-
220
- batchSize: 10,
221
- flushInterval: 5000,
222
- sessionTimeout: 30 * 60 * 1000,
223
-
224
- consent: {
225
- waitForConsent: true,
226
- anonymousMode: true,
227
- },
228
-
229
- cookielessMode: false,
230
- });
231
- ```
232
-
233
- ---
101
+ Once installed, the SDK captures everything with **zero code**:
234
102
 
235
- ## API Reference
103
+ | Auto-Tracked | What It Does |
104
+ |---|---|
105
+ | 📄 **Page Views** | Every page load + SPA navigation |
106
+ | 📝 **Form Submissions** | All forms auto-captured |
107
+ | 🔗 **Auto-Identify** | Detects email fields in forms → links visitor to CRM contact |
108
+ | 📜 **Scroll Depth** | 25%, 50%, 75%, 100% milestones |
109
+ | 🖱️ **Clicks** | Buttons, CTAs, links |
110
+ | 📥 **Downloads** | PDF, ZIP, DOC, etc. |
111
+ | ⏱️ **Engagement** | Active time on page vs idle |
112
+ | 🚪 **Exit Intent** | Mouse leaving viewport |
113
+ | ❌ **JS Errors** | Error message + stack trace |
114
+ | ⚡ **Performance** | LCP, FCP, CLS, TTFB (Core Web Vitals) |
236
115
 
237
- ### Tracking
116
+ Every event is enriched with: `visitorId`, `sessionId`, `contactId` (after auto-identify), UTM params, device info, and `websiteDomain`.
238
117
 
239
- ```typescript
240
- // Custom events
241
- tracker.track('purchase', 'Order Completed', { orderId: '123', value: 99.99 });
118
+ ---
242
119
 
243
- // Page views (auto-tracked, or manual)
244
- tracker.page('Pricing Page', { plan: 'enterprise' });
120
+ ## Advanced (Optional)
245
121
 
246
- // Screen views (mobile PWAs / SPAs)
247
- tracker.screen('Dashboard', { section: 'analytics' });
248
- ```
122
+ These are **optional** the SDK works perfectly without any of this.
249
123
 
250
- ### Identification
124
+ ### Custom Events
251
125
 
252
126
  ```typescript
253
- // Identify visitor by email → creates/links CRM contact
254
- const contactId = await tracker.identify('john@example.com', {
255
- firstName: 'John',
256
- lastName: 'Doe',
257
- company: 'Acme Inc',
258
- phone: '+1234567890',
259
- });
127
+ import { useClianta } from '@clianta/sdk/react';
128
+
129
+ const tracker = useClianta();
130
+ tracker?.track('purchase', 'Order Completed', { value: 99 });
260
131
  ```
261
132
 
262
- ### Company Association (ABM)
133
+ ### Manual Identify
263
134
 
264
135
  ```typescript
265
- // Associate visitor with a company
266
- tracker.group('company-123', {
267
- name: 'Acme Inc',
268
- industry: 'SaaS',
269
- employees: 200,
270
- plan: 'enterprise',
271
- });
272
- // All subsequent events include groupId
136
+ tracker?.identify('user@example.com', { firstName: 'John' });
273
137
  ```
274
138
 
275
- ### Identity Merging
139
+ ### Company Association
276
140
 
277
141
  ```typescript
278
- // Merge anonymous visitor with a known user (cross-device)
279
- await tracker.alias('known-user-456');
280
-
281
- // Or merge two specific IDs
282
- await tracker.alias('new-id', 'old-anonymous-id');
142
+ tracker?.group('company-123', { name: 'Acme Inc', plan: 'enterprise' });
283
143
  ```
284
144
 
285
145
  ### Event Middleware
286
146
 
287
147
  ```typescript
288
- // Strip PII before sending events
289
- tracker.use((event, next) => {
290
- delete event.properties.email;
291
- delete event.properties.phone;
292
- next(); // pass through — or don't call next() to drop the event
293
- });
294
-
295
- // Add custom context to all events
296
- tracker.use((event, next) => {
297
- event.properties.appVersion = '2.1.0';
298
- event.properties.environment = 'production';
148
+ tracker?.use((event, next) => {
149
+ delete event.properties.sensitiveField;
299
150
  next();
300
151
  });
301
152
  ```
302
153
 
303
- ### Lifecycle
154
+ ### Public CRM API (No API Key Needed)
304
155
 
305
156
  ```typescript
306
- // Wait for SDK to be ready
307
- tracker.onReady(() => {
308
- console.log('Clianta SDK initialized!');
309
- });
310
-
311
- // Check if ready synchronously
312
- if (tracker.isReady()) {
313
- tracker.track('ready_check', 'SDK Ready');
314
- }
315
-
316
- // React hook
317
- const { isReady, tracker } = useCliantaReady();
157
+ await tracker?.createContact({ email: 'lead@example.com', firstName: 'Jane' });
158
+ await tracker?.submitForm('contact-form', { email: 'visitor@co.com', message: 'Demo please' });
159
+ await tracker?.createOpportunity({ title: 'Deal', contactEmail: 'lead@co.com', value: 50000 });
318
160
  ```
319
161
 
320
- ### Public CRM API
321
-
322
- Write CRM data directly from the frontend — no API key needed, secured by domain whitelist:
162
+ ### GDPR / Consent
323
163
 
324
164
  ```typescript
325
- // Create or upsert a contact
326
- await tracker.createContact({
327
- email: 'lead@example.com',
328
- firstName: 'Jane',
329
- source: 'website',
330
- });
165
+ // Buffer events until consent:
166
+ <CliantaProvider projectId="xxx" config={{ consent: { waitForConsent: true } }}>
331
167
 
332
- // Submit a form (auto-creates/updates contact)
333
- await tracker.submitForm('contact-form', {
334
- email: 'visitor@example.com',
335
- firstName: 'Alex',
336
- message: 'I want a demo',
337
- });
338
-
339
- // Log an activity
340
- await tracker.logActivity({
341
- contactId: 'contact-123',
342
- type: 'meeting',
343
- subject: 'Product Demo',
344
- });
168
+ // Then in your cookie banner:
169
+ tracker?.consent({ analytics: true });
345
170
 
346
- // Create an opportunity
347
- await tracker.createOpportunity({
348
- title: 'Enterprise Deal',
349
- contactEmail: 'lead@example.com',
350
- value: 50000,
351
- pipelineId: 'pipeline-1',
352
- });
353
- ```
354
-
355
- ### Consent & GDPR
356
-
357
- ```typescript
358
- // Wait for consent — events are buffered until granted
359
- const tracker = clianta('WORKSPACE_ID', {
360
- consent: { waitForConsent: true },
361
- });
362
-
363
- tracker.track('page_view', 'Home'); // buffered
364
-
365
- // User accepts cookies
366
- tracker.consent({ analytics: true, marketing: false });
367
- // → buffered events flush automatically
368
-
369
- // Get current consent state
370
- const state = tracker.getConsentState();
371
-
372
- // Delete all stored data (GDPR right-to-erasure)
373
- tracker.deleteData();
374
-
375
- // Cookie-less mode (session only, no persistent storage)
376
- const tracker = clianta('WORKSPACE_ID', { cookielessMode: true });
377
- ```
378
-
379
- ### Utility
380
-
381
- ```typescript
382
- tracker.getVisitorId(); // Current anonymous visitor ID
383
- tracker.getSessionId(); // Current session ID
384
- tracker.getWorkspaceId(); // Workspace this tracker belongs to
385
- await tracker.flush(); // Force send queued events
386
- tracker.reset(); // Reset visitor (for logout)
387
- tracker.debug(true); // Enable console logging
171
+ // Delete all data:
172
+ tracker?.deleteData();
388
173
  ```
389
174
 
390
175
  ---
391
176
 
392
177
  ## TypeScript
393
178
 
394
- Full TypeScript support with type exports:
179
+ Full type support:
395
180
 
396
181
  ```typescript
397
- import {
398
- clianta,
399
- type TrackerCore,
400
- type CliantaConfig,
401
- type ConsentState,
402
- type TrackingEvent,
403
- type GroupTraits,
404
- type MiddlewareFn,
405
- type PublicContactData,
406
- type PublicFormSubmission,
407
- type PublicCrmResult,
408
- } from '@clianta/sdk';
182
+ import { type TrackerCore, type CliantaConfig, type GroupTraits, type MiddlewareFn } from '@clianta/sdk';
409
183
  ```
410
184
 
411
- ---
412
-
413
- ## What Gets Auto-Tracked
414
-
415
- Once installed, the SDK automatically captures (no code needed):
416
-
417
- | Event | Data Collected |
418
- |-------|---------------|
419
- | **Page Views** | URL, title, referrer, SPA navigation |
420
- | **Form Submissions** | All form fields, auto-identifies by email |
421
- | **Scroll Depth** | 25%, 50%, 75%, 100% milestones |
422
- | **Button Clicks** | Element text, ID, CSS selector |
423
- | **Downloads** | File URL, extension, click source |
424
- | **Engagement** | Time on page, active vs idle |
425
- | **Exit Intent** | Mouse leaving viewport (desktop) |
426
- | **Errors** | Error message, stack trace, URL |
427
- | **Performance** | LCP, FCP, CLS, TTFB (Web Vitals) |
428
-
429
- Every event is enriched with: `visitorId`, `sessionId`, `contactId` (if identified), `groupId` (if grouped), UTM parameters, device info, and `websiteDomain`.
430
-
431
- ---
432
-
433
-
434
-
435
185
  ---
436
186
 
437
187
  ## Support
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.1
2
+ * Clianta SDK v1.6.2
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
@@ -10,7 +10,7 @@
10
10
  * @see SDK_VERSION in core/config.ts
11
11
  */
12
12
  /** SDK Version */
13
- const SDK_VERSION = '1.6.1';
13
+ const SDK_VERSION = '1.6.2';
14
14
  /** Default API endpoint — reads from env or falls back to localhost */
15
15
  const getDefaultApiEndpoint = () => {
16
16
  // Build-time env var (works with Next.js, Vite, CRA, etc.)
@@ -28,7 +28,7 @@ const getDefaultApiEndpoint = () => {
28
28
  }
29
29
  return 'http://localhost:5000';
30
30
  };
31
- /** Core plugins enabled by default */
31
+ /** Core plugins enabled by default — all auto-track with zero config */
32
32
  const DEFAULT_PLUGINS = [
33
33
  'pageView',
34
34
  'forms',
@@ -37,6 +37,8 @@ const DEFAULT_PLUGINS = [
37
37
  'engagement',
38
38
  'downloads',
39
39
  'exitIntent',
40
+ 'errors',
41
+ 'performance',
40
42
  ];
41
43
  /** Default configuration values */
42
44
  const DEFAULT_CONFIG = {
@@ -3212,7 +3214,7 @@ function clianta(workspaceId, config) {
3212
3214
  globalInstance = new Tracker(workspaceId, config);
3213
3215
  return globalInstance;
3214
3216
  }
3215
- // Attach to window for <script> tag usage
3217
+ // Attach to window for <script> tag usage + AUTO-INIT
3216
3218
  if (typeof window !== 'undefined') {
3217
3219
  window.clianta = clianta;
3218
3220
  window.Clianta = {
@@ -3220,6 +3222,32 @@ if (typeof window !== 'undefined') {
3220
3222
  Tracker,
3221
3223
  ConsentManager,
3222
3224
  };
3225
+ // ============================================
3226
+ // AUTO-INIT FROM SCRIPT TAG
3227
+ // ============================================
3228
+ // Enables true plug-and-play:
3229
+ // <script src="clianta.min.js" data-project-id="YOUR_ID"></script>
3230
+ // That's it — everything auto-tracks.
3231
+ const autoInit = () => {
3232
+ const scripts = document.querySelectorAll('script[data-project-id]');
3233
+ const script = scripts[scripts.length - 1]; // last matching script
3234
+ if (!script)
3235
+ return;
3236
+ const projectId = script.getAttribute('data-project-id');
3237
+ if (!projectId)
3238
+ return;
3239
+ const debug = script.hasAttribute('data-debug');
3240
+ const instance = clianta(projectId, { debug });
3241
+ // Expose the auto-initialized instance globally
3242
+ window.__clianta = instance;
3243
+ };
3244
+ // Run after DOM is ready
3245
+ if (document.readyState === 'loading') {
3246
+ document.addEventListener('DOMContentLoaded', autoInit);
3247
+ }
3248
+ else {
3249
+ autoInit();
3250
+ }
3223
3251
  }
3224
3252
 
3225
3253
  /**
@@ -3241,8 +3269,6 @@ if (typeof window !== 'undefined') {
3241
3269
  * constructor() {
3242
3270
  * this.instance = createCliantaTracker({
3243
3271
  * projectId: environment.cliantaProjectId,
3244
- * apiEndpoint: environment.cliantaApiEndpoint,
3245
- * debug: !environment.production,
3246
3272
  * });
3247
3273
  * }
3248
3274
  *
@@ -3270,7 +3296,6 @@ if (typeof window !== 'undefined') {
3270
3296
  * @example
3271
3297
  * const instance = createCliantaTracker({
3272
3298
  * projectId: 'your-project-id',
3273
- * apiEndpoint: environment.cliantaApiEndpoint || 'http://localhost:5000',
3274
3299
  * });
3275
3300
  *
3276
3301
  * instance.tracker?.track('page_view', 'Home Page');