@clianta/sdk 1.6.2 → 1.6.3

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.
Files changed (14) hide show
  1. package/README.md +185 -63
  2. package/dist/angular.cjs.js +1 -1
  3. package/dist/angular.esm.js +1 -1
  4. package/dist/clianta.cjs.js +1 -1
  5. package/dist/clianta.esm.js +1 -1
  6. package/dist/clianta.umd.js +1 -1
  7. package/dist/clianta.umd.min.js +1 -1
  8. package/dist/react.cjs.js +1 -1
  9. package/dist/react.esm.js +1 -1
  10. package/dist/svelte.cjs.js +1 -1
  11. package/dist/svelte.esm.js +1 -1
  12. package/dist/vue.cjs.js +1 -1
  13. package/dist/vue.esm.js +1 -1
  14. package/package.json +1 -1
package/README.md CHANGED
@@ -1,33 +1,47 @@
1
1
  # Clianta SDK
2
2
 
3
- **Plug-and-play tracking for your CRM.** Install → add one line → done. Everything auto-tracks.
3
+ > **Enterprise-grade visitor intelligence for your CRM.**
4
+ > Auto-captures every interaction on your website and feeds it directly into Clianta CRM — zero manual tracking code required.
4
5
 
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
+ [![npm](https://img.shields.io/npm/v/@clianta/sdk)](https://www.npmjs.com/package/@clianta/sdk)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
6
8
 
7
9
  ---
8
10
 
9
- ## Setup (2 minutes)
11
+ ## Quick Start
10
12
 
11
- ### React / Next.js
13
+ ### 1. Install
12
14
 
13
15
  ```bash
14
16
  npm install @clianta/sdk
15
17
  ```
16
18
 
19
+ ### 2. Integrate
20
+
21
+ Pick your framework below. Each section includes the correct env vars and file paths for that framework.
22
+
23
+ ---
24
+
25
+ #### Next.js (App Router)
26
+
27
+ **Environment Variables** — set in `.env` or your hosting dashboard (Vercel, Netlify, etc.):
28
+
29
+ ```bash
30
+ NEXT_PUBLIC_CLIANTA_PROJECT_ID=your-project-id
31
+ NEXT_PUBLIC_CLIANTA_API_ENDPOINT=https://your-crm-backend.com
17
32
  ```
18
- # .env.local
19
- NEXT_PUBLIC_CLIANTA_ID=your-project-id
20
- ```
33
+
34
+ **Integration** — wrap your app in `app/layout.tsx`:
21
35
 
22
36
  ```tsx
23
37
  // app/layout.tsx
24
38
  import { CliantaProvider } from '@clianta/sdk/react';
25
39
 
26
- export default function RootLayout({ children }) {
40
+ export default function RootLayout({ children }: { children: React.ReactNode }) {
27
41
  return (
28
42
  <html lang="en">
29
43
  <body>
30
- <CliantaProvider projectId={process.env.NEXT_PUBLIC_CLIANTA_ID!}>
44
+ <CliantaProvider projectId={process.env.NEXT_PUBLIC_CLIANTA_PROJECT_ID!}>
31
45
  {children}
32
46
  </CliantaProvider>
33
47
  </body>
@@ -36,104 +50,181 @@ export default function RootLayout({ children }) {
36
50
  }
37
51
  ```
38
52
 
39
- **That's it.** Everything auto-tracks. No other code needed.
40
-
41
53
  ---
42
54
 
43
- ### Script Tag (HTML / WordPress / Webflow / Shopify)
55
+ #### React (Vite)
44
56
 
45
- One line. Paste before `</head>`:
57
+ **Environment Variables** — set in `.env` or your hosting dashboard:
46
58
 
47
- ```html
48
- <script src="https://cdn.clianta.online/sdk/v1/clianta.min.js" data-project-id="YOUR_PROJECT_ID"></script>
59
+ ```bash
60
+ VITE_CLIANTA_PROJECT_ID=your-project-id
61
+ VITE_CLIANTA_API_ENDPOINT=https://your-crm-backend.com
49
62
  ```
50
63
 
51
- **That's it.** The SDK auto-initializes from the `data-project-id` attribute.
64
+ **Integration** — wrap your app in `src/main.tsx`:
65
+
66
+ ```tsx
67
+ // src/main.tsx
68
+ import React from 'react';
69
+ import ReactDOM from 'react-dom/client';
70
+ import { CliantaProvider } from '@clianta/sdk/react';
71
+ import App from './App';
72
+
73
+ ReactDOM.createRoot(document.getElementById('root')!).render(
74
+ <React.StrictMode>
75
+ <CliantaProvider projectId={import.meta.env.VITE_CLIANTA_PROJECT_ID}>
76
+ <App />
77
+ </CliantaProvider>
78
+ </React.StrictMode>
79
+ );
80
+ ```
52
81
 
53
82
  ---
54
83
 
55
- ### Vue 3
84
+ #### Vue 3 (Vite)
85
+
86
+ **Environment Variables** — set in `.env` or your hosting dashboard:
56
87
 
57
88
  ```bash
58
- npm install @clianta/sdk
89
+ VITE_CLIANTA_PROJECT_ID=your-project-id
90
+ VITE_CLIANTA_API_ENDPOINT=https://your-crm-backend.com
59
91
  ```
60
92
 
93
+ **Integration** — register the plugin in `src/main.ts`:
94
+
61
95
  ```typescript
62
- // main.ts
96
+ // src/main.ts
97
+ import { createApp } from 'vue';
63
98
  import { CliantaPlugin } from '@clianta/sdk/vue';
99
+ import App from './App.vue';
64
100
 
65
- app.use(CliantaPlugin, { projectId: 'YOUR_PROJECT_ID' });
101
+ const app = createApp(App);
102
+ app.use(CliantaPlugin, {
103
+ projectId: import.meta.env.VITE_CLIANTA_PROJECT_ID,
104
+ });
105
+ app.mount('#app');
66
106
  ```
67
107
 
68
108
  ---
69
109
 
70
- ### Angular
110
+ #### Angular 16+
111
+
112
+ **Environment Variables** — set in `src/environments/environment.ts`:
113
+
114
+ ```typescript
115
+ // src/environments/environment.ts
116
+ export const environment = {
117
+ production: false,
118
+ cliantaProjectId: 'your-project-id',
119
+ cliantaApiEndpoint: 'https://your-crm-backend.com',
120
+ };
121
+ ```
122
+
123
+ **Integration** — create a service at `src/app/clianta.service.ts`:
71
124
 
72
125
  ```typescript
73
- // clianta.service.ts
74
- import { createCliantaTracker } from '@clianta/sdk/angular';
126
+ // src/app/clianta.service.ts
127
+ import { Injectable, OnDestroy } from '@angular/core';
128
+ import { createCliantaTracker, CliantaTrackerInstance } from '@clianta/sdk/angular';
129
+ import { environment } from '../environments/environment';
75
130
 
76
131
  @Injectable({ providedIn: 'root' })
77
132
  export class CliantaService implements OnDestroy {
78
- private instance = createCliantaTracker({ projectId: 'YOUR_PROJECT_ID' });
133
+ private instance: CliantaTrackerInstance;
134
+
135
+ constructor() {
136
+ this.instance = createCliantaTracker({
137
+ projectId: environment.cliantaProjectId,
138
+ apiEndpoint: environment.cliantaApiEndpoint,
139
+ });
140
+ }
141
+
79
142
  get tracker() { return this.instance.tracker; }
143
+
144
+ track(eventType: string, eventName: string, properties?: Record<string, unknown>) {
145
+ this.instance.tracker?.track(eventType, eventName, properties);
146
+ }
147
+
148
+ identify(email: string, traits?: Record<string, unknown>) {
149
+ return this.instance.tracker?.identify(email, traits);
150
+ }
151
+
80
152
  ngOnDestroy() { this.instance.destroy(); }
81
153
  }
82
154
  ```
83
155
 
84
156
  ---
85
157
 
86
- ### Svelte
158
+ #### Svelte / SvelteKit
159
+
160
+ **Environment Variables** — set in `.env` or your hosting dashboard:
161
+
162
+ ```bash
163
+ VITE_CLIANTA_PROJECT_ID=your-project-id
164
+ VITE_CLIANTA_API_ENDPOINT=https://your-crm-backend.com
165
+ ```
166
+
167
+ **Integration** — initialize in `src/routes/+layout.svelte`:
87
168
 
88
169
  ```svelte
170
+ <!-- src/routes/+layout.svelte -->
89
171
  <script>
90
172
  import { initClianta } from '@clianta/sdk/svelte';
91
173
  import { setContext } from 'svelte';
92
- setContext('clianta', initClianta({ projectId: 'YOUR_PROJECT_ID' }));
174
+
175
+ const clianta = initClianta({
176
+ projectId: import.meta.env.VITE_CLIANTA_PROJECT_ID,
177
+ apiEndpoint: import.meta.env.VITE_CLIANTA_API_ENDPOINT,
178
+ });
179
+
180
+ setContext('clianta', clianta);
93
181
  </script>
182
+
94
183
  <slot />
95
184
  ```
96
185
 
186
+ **Done.** Every visitor interaction on your website is now flowing into your CRM.
187
+
97
188
  ---
98
189
 
99
- ## What Happens Automatically
190
+ ## What Gets Captured Automatically
100
191
 
101
- Once installed, the SDK captures everything with **zero code**:
192
+ Once integrated, the SDK captures the following with **zero additional code**:
102
193
 
103
- | Auto-Tracked | What It Does |
194
+ | Category | What It Captures |
104
195
  |---|---|
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) |
115
-
116
- Every event is enriched with: `visitorId`, `sessionId`, `contactId` (after auto-identify), UTM params, device info, and `websiteDomain`.
196
+ | **Page Views** | Every page load + SPA route changes (history API) |
197
+ | **Form Submissions** | All forms auto-captured with field data |
198
+ | **Visitor Identity** | Detects email fields in forms → auto-links visitor to CRM contact |
199
+ | **Scroll Depth** | 25%, 50%, 75%, 100% milestones |
200
+ | **Click Tracking** | Buttons, CTAs, navigation links |
201
+ | **File Downloads** | PDF, ZIP, DOC, XLSX, CSV, and more |
202
+ | **Engagement** | Active time on page vs idle time |
203
+ | **Exit Intent** | Mouse leaving viewport (desktop) |
204
+ | **JavaScript Errors** | Error message, stack trace, source file |
205
+ | **Core Web Vitals** | LCP, FCP, CLS, TTFB, FID |
206
+
207
+ Every event is enriched with: `visitorId`, `sessionId`, `contactId` (after auto-identify), UTM parameters, device/browser info, and `websiteDomain`.
117
208
 
118
209
  ---
119
210
 
120
- ## Advanced (Optional)
211
+ ## Optional: Advanced Features
121
212
 
122
- These are **optional** — the SDK works perfectly without any of this.
213
+ The SDK works perfectly without any of the following. These are for teams that want deeper control.
123
214
 
124
- ### Custom Events
215
+ ### Custom Event Tracking
125
216
 
126
217
  ```typescript
127
218
  import { useClianta } from '@clianta/sdk/react';
128
219
 
129
220
  const tracker = useClianta();
130
- tracker?.track('purchase', 'Order Completed', { value: 99 });
221
+ tracker?.track('purchase', 'Order Completed', { value: 99, currency: 'USD' });
131
222
  ```
132
223
 
133
- ### Manual Identify
224
+ ### Manual Identification
134
225
 
135
226
  ```typescript
136
- tracker?.identify('user@example.com', { firstName: 'John' });
227
+ tracker?.identify('user@example.com', { firstName: 'John', company: 'Acme' });
137
228
  ```
138
229
 
139
230
  ### Company Association
@@ -146,29 +237,35 @@ tracker?.group('company-123', { name: 'Acme Inc', plan: 'enterprise' });
146
237
 
147
238
  ```typescript
148
239
  tracker?.use((event, next) => {
149
- delete event.properties.sensitiveField;
240
+ // Strip sensitive data before sending
241
+ delete event.properties.creditCard;
150
242
  next();
151
243
  });
152
244
  ```
153
245
 
154
- ### Public CRM API (No API Key Needed)
246
+ ### Frontend CRM Operations
155
247
 
156
248
  ```typescript
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 });
249
+ // Create or update a contact (secured by domain whitelist, no API key needed)
250
+ await tracker?.createContact({ email: 'lead@example.com', firstName: 'Jane', company: 'Acme' });
251
+
252
+ // Submit a form programmatically
253
+ await tracker?.submitForm('demo-request', { email: 'visitor@co.com', message: 'Demo please' });
254
+
255
+ // Create a sales opportunity
256
+ await tracker?.createOpportunity({ title: 'Enterprise Deal', contactEmail: 'vp@acme.com', value: 50000 });
160
257
  ```
161
258
 
162
- ### GDPR / Consent
259
+ ### GDPR / Consent Management
163
260
 
164
- ```typescript
165
- // Buffer events until consent:
261
+ ```tsx
262
+ // Buffer events until consent is given:
166
263
  <CliantaProvider projectId="xxx" config={{ consent: { waitForConsent: true } }}>
167
264
 
168
- // Then in your cookie banner:
169
- tracker?.consent({ analytics: true });
265
+ // In your cookie banner:
266
+ tracker?.consent({ analytics: true, marketing: false });
170
267
 
171
- // Delete all data:
268
+ // Right to erasure:
172
269
  tracker?.deleteData();
173
270
  ```
174
271
 
@@ -176,16 +273,41 @@ tracker?.deleteData();
176
273
 
177
274
  ## TypeScript
178
275
 
179
- Full type support:
276
+ Full type support included:
180
277
 
181
278
  ```typescript
182
- import { type TrackerCore, type CliantaConfig, type GroupTraits, type MiddlewareFn } from '@clianta/sdk';
279
+ import type { TrackerCore, CliantaConfig, GroupTraits, MiddlewareFn } from '@clianta/sdk';
183
280
  ```
184
281
 
185
282
  ---
186
283
 
284
+ ## Configuration Reference
285
+
286
+ | Option | Type | Default | Description |
287
+ |---|---|---|---|
288
+ | `projectId` | `string` | — | Your project ID from Clianta dashboard |
289
+ | `apiEndpoint` | `string` | Auto-detect from env vars | CRM backend URL |
290
+ | `debug` | `boolean` | `false` | Enable verbose console logging |
291
+ | `plugins` | `PluginName[]` | All enabled | Plugins to activate |
292
+ | `consent` | `ConsentConfig` | `undefined` | GDPR consent configuration |
293
+ | `cookielessMode` | `boolean` | `false` | Session-only storage (no persistence) |
294
+ | `sessionTimeout` | `number` | `1800000` | Session timeout in ms (default: 30 min) |
295
+ | `batchSize` | `number` | `10` | Events to batch before sending |
296
+ | `flushInterval` | `number` | `5000` | Auto-flush interval in ms |
297
+
298
+ ---
299
+
300
+ ## Security
301
+
302
+ - **Domain Whitelisting** — Only requests from your registered domains are accepted
303
+ - **No API Keys on Frontend** — CRM write operations are secured by project ID + domain whitelist
304
+ - **Rate Limiting** — 100 requests/minute per IP
305
+ - **Field Whitelisting** — Only safe fields accepted (no `leadScore`, `assignedTo`, etc.)
306
+
307
+ ---
308
+
187
309
  ## Support
188
310
 
189
- - Documentation: https://docs.clianta.online
190
- - Issues: https://github.com/clianta/sdk/issues
191
- - Email: support@clianta.online
311
+ - **Documentation**: [docs.clianta.online](https://docs.clianta.online)
312
+ - **NPM**: [@clianta/sdk](https://www.npmjs.com/package/@clianta/sdk)
313
+ - **Email**: support@clianta.online
package/dist/angular.cjs.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/angular.esm.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/clianta.cjs.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/clianta.esm.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/clianta.umd.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/clianta.umd.min.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/react.cjs.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/react.esm.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/svelte.cjs.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/svelte.esm.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/vue.cjs.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/dist/vue.esm.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /*!
2
- * Clianta SDK v1.6.2
2
+ * Clianta SDK v1.6.3
3
3
  * (c) 2026 Clianta
4
4
  * Released under the MIT License.
5
5
  */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@clianta/sdk",
3
- "version": "1.6.2",
3
+ "version": "1.6.3",
4
4
  "type": "module",
5
5
  "description": "Professional CRM SDK for Clianta - Track visitors, manage contacts, opportunities, and analyze behavior",
6
6
  "main": "dist/clianta.cjs.js",