@li2/analytics 0.1.9 → 0.2.1

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 (10) hide show
  1. package/README.md +358 -358
  2. package/dist/index.d.mts +49 -5
  3. package/dist/index.d.ts +49 -5
  4. package/dist/index.global.js +1 -1
  5. package/dist/index.js +1 -1
  6. package/dist/index.mjs +1 -1
  7. package/dist/outbound.global.js +1 -1
  8. package/dist/outbound.js +1 -1
  9. package/dist/outbound.mjs +1 -1
  10. package/package.json +1 -1
package/README.md CHANGED
@@ -1,358 +1,358 @@
1
- # @li2/analytics
2
-
3
- Conversion tracking SDK for Li2.ai. Track leads and sales from your marketing campaigns with automatic click ID attribution.
4
-
5
- ## Installation
6
-
7
- ```bash
8
- npm install @li2/analytics
9
- # or
10
- pnpm add @li2/analytics
11
- # or
12
- yarn add @li2/analytics
13
- ```
14
-
15
- ## Client-Side SDK
16
-
17
- The client-side SDK automatically captures click IDs from URLs (`?uid=...`) and cookies, making it easy to track conversions in the browser. You don't need to pass `clickId` manually - it's auto-detected.
18
-
19
- > **Note:** If you need to track conversions on the server (e.g., after a webhook or server-side payment confirmation), use `getClickId()` to capture the click ID on the client and pass it to your server. See [Server-Side SDK](#server-side-sdk) for details.
20
-
21
- ### Installation Snippet
22
-
23
- Add this snippet to your `<head>` tag. It loads the SDK asynchronously and queues any tracking calls made before the script loads.
24
-
25
- ```html
26
- <script>
27
- !(function (c, n) {
28
- c[n] = c[n] || function () { (c[n].q = c[n].q || []).push(arguments); };
29
- ["trackLead", "trackSale"].forEach((t) => (c[n][t] = (...a) => c[n](t, ...a)));
30
- var s = document.createElement("script");
31
- s.defer = 1;
32
- s.src = "https://unpkg.com/@li2/analytics/dist/index.global.js";
33
- s.setAttribute("data-publishable-key", "li2_pk_...");
34
- document.head.appendChild(s);
35
- })(window, "li2Analytics");
36
- </script>
37
- ```
38
-
39
- ### Script Tag Usage
40
-
41
- ```html
42
- <script
43
- src="https://unpkg.com/@li2/analytics/dist/index.global.js"
44
- data-publishable-key="li2_pk_..."
45
- ></script>
46
-
47
- <script>
48
- // Track a lead
49
- li2Analytics.trackLead({
50
- eventName: 'signup',
51
- customerExternalId: 'user_123',
52
- customerName: 'John Doe',
53
- customerEmail: 'john@example.com',
54
- })
55
-
56
- // Track a sale
57
- li2Analytics.trackSale({
58
- customerExternalId: 'user_123',
59
- amount: 4999, // $49.99 in cents
60
- eventName: 'purchase',
61
- invoiceId: 'inv_abc123',
62
- })
63
- </script>
64
- ```
65
-
66
- ### Script Tag Attributes
67
-
68
- | Attribute | Description |
69
- | --------- | ----------- |
70
- | `data-publishable-key` | Your publishable API key (`li2_pk_...`) |
71
- | `data-api-url` | Custom API endpoint (default: `https://api.li2.ai`) |
72
- | `data-debug` | Enable debug logging (presence enables, no value needed) |
73
- | `data-cookie-options` | JSON object for cookie customization (see below) |
74
- | `data-outbound` | JSON array of domains for outbound link tracking (e.g., `["partner.com"]`) |
75
-
76
- ### Cookie Options
77
-
78
- By default, the SDK stores the click ID in a cookie scoped to the current domain with a 30-day expiration. Use `data-cookie-options` for cross-domain tracking or custom expiration.
79
-
80
- ```html
81
- <script
82
- src="https://unpkg.com/@li2/analytics/dist/index.global.js"
83
- data-publishable-key="li2_pk_..."
84
- data-cookie-options='{"domain":".example.com","expiresInDays":60}'
85
- ></script>
86
- ```
87
-
88
- | Property | Type | Default | Description |
89
- | -------- | ---- | ------- | ----------- |
90
- | `domain` | string | (current domain) | Cookie domain for cross-subdomain tracking (e.g., `.example.com`) |
91
- | `expiresInDays` | number | `30` | Days until the cookie expires |
92
- | `path` | string | `"/"` | Cookie path |
93
-
94
- **Cross-domain tracking example:** If users land on `www.example.com` but convert on `app.example.com`, set `domain` to `.example.com` to share the click ID across subdomains.
95
-
96
- ### Outbound Link Tracking
97
-
98
- Automatically append click IDs to outbound links and iframes pointing to specified domains. This is useful for tracking conversions across multiple domains or passing attribution data to partner sites.
99
-
100
- **Key Benefits:**
101
- - ✅ **Reduced bundle size** - Only loads when configured (separate module)
102
- - ✅ **Automatic tracking** - No manual link modification needed
103
- - ✅ **Dynamic content support** - Tracks links added after page load
104
- - ✅ **SPA compatible** - Works with client-side routing
105
-
106
- #### Script Tag Usage
107
-
108
- Add the `data-outbound` attribute with a JSON array of domains to track:
109
-
110
- ```html
111
- <script
112
- src="https://unpkg.com/@li2/analytics/dist/index.global.js"
113
- data-publishable-key="li2_pk_..."
114
- data-outbound='["partner.com", "checkout.example.com"]'
115
- ></script>
116
- ```
117
-
118
- The SDK will automatically:
119
- 1. Find all `<a>` and `<iframe>` elements pointing to the specified domains
120
- 2. Append the click ID as a `uid` query parameter
121
- 3. Monitor for dynamically added links (SPAs, AJAX content)
122
-
123
- #### Module Import Usage
124
-
125
- ```typescript
126
- import { init } from '@li2/analytics'
127
-
128
- init({
129
- publishableKey: 'li2_pk_...',
130
- outbound: ['partner.com', 'checkout.example.com'],
131
- })
132
- ```
133
-
134
- #### Example
135
-
136
- **Before tracking:**
137
- ```html
138
- <a href="https://partner.com/signup">Sign up</a>
139
- ```
140
-
141
- **After tracking (automatic):**
142
- ```html
143
- <a href="https://partner.com/signup?uid=abc123xyz">Sign up</a>
144
- ```
145
-
146
- The partner site can then read the `uid` parameter and use it for server-side conversion tracking.
147
-
148
- #### How It Works
149
-
150
- 1. **Domain matching**: Links are tracked if their hostname ends with any configured domain
151
- 2. **Normalization**: `www.` prefixes are automatically stripped for matching
152
- 3. **Deduplication**: Each link is only modified once to avoid duplicate parameters
153
- 4. **Periodic scanning**: New links are detected every 2 seconds
154
- 5. **History API support**: Links are re-scanned on navigation in SPAs
155
-
156
- **Note:** The outbound module is loaded dynamically only when the `outbound` option is configured, keeping your bundle size minimal when not needed.
157
-
158
- ### Module Import Usage
159
-
160
- ```typescript
161
- import { init, trackLead, trackSale } from '@li2/analytics'
162
-
163
- // Initialize with your publishable key
164
- init({
165
- publishableKey: 'li2_pk_...',
166
- debug: true, // optional: enable console logging
167
- })
168
-
169
- // Track a lead conversion
170
- const leadResult = await trackLead({
171
- eventName: 'signup',
172
- customerExternalId: 'user_123',
173
- customerName: 'John Doe',
174
- customerEmail: 'john@example.com',
175
- })
176
-
177
- if (leadResult.success) {
178
- console.log('Lead tracked:', leadResult.customerId)
179
- }
180
-
181
- // Track a sale conversion
182
- const saleResult = await trackSale({
183
- customerExternalId: 'user_123',
184
- amount: 4999, // Amount in cents ($49.99)
185
- eventName: 'purchase',
186
- paymentProcessor: 'stripe',
187
- invoiceId: 'inv_abc123',
188
- currency: 'usd',
189
- })
190
-
191
- if (saleResult.success) {
192
- console.log('Sale tracked:', saleResult.saleEventId)
193
- }
194
- ```
195
-
196
- ### Utility Functions
197
-
198
- ```typescript
199
- import { isTrackingAvailable, getClickId } from '@li2/analytics'
200
-
201
- // Check if a click ID is available for attribution
202
- if (isTrackingAvailable()) {
203
- console.log('Click ID:', getClickId())
204
- }
205
-
206
- // Use getClickId() to pass the click ID to your server for server-side tracking
207
- const clickId = getClickId() // Returns null if no click ID is available
208
- ```
209
-
210
- ## Server-Side SDK
211
-
212
- The server-side SDK is for use in Node.js, Next.js API routes, server actions, and other backend environments. It requires an API key for authentication.
213
-
214
- ### Passing Click ID from Client to Server
215
-
216
- Unlike the client-side SDK, the server cannot auto-detect the click ID. You need to capture it on the client and include it in your server requests:
217
-
218
- ```typescript
219
- // Client-side: capture the click ID
220
- import { getClickId } from '@li2/analytics'
221
-
222
- const clickId = getClickId()
223
-
224
- // Include clickId when calling your server
225
- fetch('/api/checkout', {
226
- method: 'POST',
227
- body: JSON.stringify({ clickId, ...otherData }),
228
- })
229
- ```
230
-
231
- ### Setup
232
-
233
- ```typescript
234
- import { initServer } from '@li2/analytics'
235
-
236
- const li2 = initServer({
237
- apiKey: 'li2_sk_...', // Your secret API key
238
- debug: true, // optional: enable console logging
239
- })
240
- ```
241
-
242
- ### Track Lead (Server-Side)
243
-
244
- ```typescript
245
- // clickId must be captured from the client and passed to your server
246
- const result = await li2.trackLead({
247
- clickId: 'abc123', // Required for server-side tracking
248
- eventName: 'signup',
249
- customerExternalId: 'user_123',
250
- customerName: 'John Doe',
251
- customerEmail: 'john@example.com',
252
- metadata: {
253
- plan: 'pro',
254
- source: 'landing_page',
255
- },
256
- })
257
-
258
- if (result.success) {
259
- console.log('Lead tracked:', result.customerId)
260
- }
261
- ```
262
-
263
- ### Track Sale (Server-Side)
264
-
265
- ```typescript
266
- const result = await li2.trackSale({
267
- clickId: 'abc123', // Required for server-side tracking
268
- customerExternalId: 'user_123',
269
- amount: 9900, // Amount in cents ($99.00)
270
- eventName: 'subscription',
271
- paymentProcessor: 'stripe',
272
- invoiceId: 'inv_xyz789',
273
- currency: 'usd',
274
- metadata: {
275
- plan: 'annual',
276
- coupon: 'SAVE20',
277
- },
278
- })
279
-
280
- if (result.success) {
281
- console.log('Sale tracked:', result.saleEventId)
282
- }
283
- ```
284
-
285
- ### Next.js Example
286
-
287
- ```typescript
288
- // app/api/checkout/route.ts
289
- import { initServer } from '@li2/analytics'
290
-
291
- const li2 = initServer({ apiKey: process.env.LI2_API_KEY! })
292
-
293
- export async function POST(request: Request) {
294
- const { clickId, userId, amount, invoiceId } = await request.json()
295
-
296
- // Track the sale after successful payment
297
- const result = await li2.trackSale({
298
- clickId,
299
- customerExternalId: userId,
300
- amount,
301
- invoiceId,
302
- paymentProcessor: 'stripe',
303
- })
304
-
305
- return Response.json({ success: result.success })
306
- }
307
- ```
308
-
309
- ## API Reference
310
-
311
- ### Client-Side
312
-
313
- | Function | Description |
314
- | ---------------------- | ---------------------------------------- |
315
- | `init(config)` | Initialize the SDK with configuration |
316
- | `trackLead(params)` | Track a lead conversion event |
317
- | `trackSale(params)` | Track a sale conversion event |
318
- | `isTrackingAvailable()`| Check if click ID is available |
319
- | `getClickId()` | Get the current click ID |
320
-
321
- ### Server-Side
322
-
323
- | Function | Description |
324
- | ---------------------- | ---------------------------------------- |
325
- | `initServer(config)` | Create a server-side SDK instance |
326
- | `trackLead(params)` | Track a lead (clickId required) |
327
- | `trackSale(params)` | Track a sale (clickId required) |
328
-
329
- ### TrackLead Parameters
330
-
331
- | Parameter | Type | Required | Description |
332
- | -------------------- | -------- | -------- | ------------------------------------- |
333
- | `clickId` | string | Server only | Click ID for attribution |
334
- | `eventName` | string | Yes | Name of the lead event |
335
- | `customerExternalId` | string | Yes | Your unique customer identifier |
336
- | `customerName` | string | No | Customer's name |
337
- | `customerEmail` | string | No | Customer's email |
338
- | `customerAvatar` | string | No | URL to customer's avatar |
339
- | `metadata` | object | No | Additional data (max 10,000 chars) |
340
-
341
- ### TrackSale Parameters
342
-
343
- | Parameter | Type | Required | Description |
344
- | -------------------- | -------- | -------- | ------------------------------------- |
345
- | `clickId` | string | Server only | Click ID for attribution |
346
- | `customerExternalId` | string | Yes | Your unique customer identifier |
347
- | `amount` | number | Yes | Amount in smallest currency unit |
348
- | `eventName` | string | No | Name of sale event (default: "Purchase") |
349
- | `paymentProcessor` | string | No | Payment processor (e.g., "stripe") |
350
- | `invoiceId` | string | No | Your invoice/transaction ID |
351
- | `currency` | string | No | Currency code (default: "usd") |
352
- | `customerName` | string | No | Customer's name |
353
- | `customerEmail` | string | No | Customer's email |
354
- | `metadata` | object | No | Additional data (max 10,000 chars) |
355
-
356
- ## License
357
-
358
- MIT
1
+ # @li2/analytics
2
+
3
+ Conversion tracking SDK for Li2.ai. Track leads and sales from your marketing campaigns with automatic click ID attribution.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @li2/analytics
9
+ # or
10
+ pnpm add @li2/analytics
11
+ # or
12
+ yarn add @li2/analytics
13
+ ```
14
+
15
+ ## Client-Side SDK
16
+
17
+ The client-side SDK automatically captures click IDs from URLs (`?uid=...`) and cookies, making it easy to track conversions in the browser. You don't need to pass `clickId` manually - it's auto-detected.
18
+
19
+ > **Note:** If you need to track conversions on the server (e.g., after a webhook or server-side payment confirmation), use `getClickId()` to capture the click ID on the client and pass it to your server. See [Server-Side SDK](#server-side-sdk) for details.
20
+
21
+ ### Installation Snippet
22
+
23
+ Add this snippet to your `<head>` tag. It loads the SDK asynchronously and queues any tracking calls made before the script loads.
24
+
25
+ ```html
26
+ <script>
27
+ !(function (c, n) {
28
+ c[n] = c[n] || function () { (c[n].q = c[n].q || []).push(arguments); };
29
+ ["trackLead", "trackSale", "identify"].forEach((t) => (c[n][t] = (...a) => c[n](t, ...a)));
30
+ var s = document.createElement("script");
31
+ s.defer = 1;
32
+ s.src = "https://unpkg.com/@li2/analytics/dist/index.global.js";
33
+ s.setAttribute("data-publishable-key", "li2_pk_...");
34
+ document.head.appendChild(s);
35
+ })(window, "li2Analytics");
36
+ </script>
37
+ ```
38
+
39
+ ### Script Tag Usage
40
+
41
+ ```html
42
+ <script
43
+ src="https://unpkg.com/@li2/analytics/dist/index.global.js"
44
+ data-publishable-key="li2_pk_..."
45
+ ></script>
46
+
47
+ <script>
48
+ // Track a lead
49
+ li2Analytics.trackLead({
50
+ eventName: 'signup',
51
+ customerExternalId: 'user_123',
52
+ customerName: 'John Doe',
53
+ customerEmail: 'john@example.com',
54
+ })
55
+
56
+ // Track a sale
57
+ li2Analytics.trackSale({
58
+ customerExternalId: 'user_123',
59
+ amount: 4999, // $49.99 in cents
60
+ eventName: 'purchase',
61
+ invoiceId: 'inv_abc123',
62
+ })
63
+ </script>
64
+ ```
65
+
66
+ ### Script Tag Attributes
67
+
68
+ | Attribute | Description |
69
+ | --------- | ----------- |
70
+ | `data-publishable-key` | Your publishable API key (`li2_pk_...`) |
71
+ | `data-api-url` | Custom API endpoint (default: `https://api.li2.ai`) |
72
+ | `data-debug` | Enable debug logging (presence enables, no value needed) |
73
+ | `data-cookie-options` | JSON object for cookie customization (see below) |
74
+ | `data-outbound` | JSON array of domains for outbound link tracking (e.g., `["partner.com"]`) |
75
+
76
+ ### Cookie Options
77
+
78
+ By default, the SDK stores the click ID in a cookie scoped to the current domain with a 30-day expiration. Use `data-cookie-options` for cross-domain tracking or custom expiration.
79
+
80
+ ```html
81
+ <script
82
+ src="https://unpkg.com/@li2/analytics/dist/index.global.js"
83
+ data-publishable-key="li2_pk_..."
84
+ data-cookie-options='{"domain":".example.com","expiresInDays":60}'
85
+ ></script>
86
+ ```
87
+
88
+ | Property | Type | Default | Description |
89
+ | -------- | ---- | ------- | ----------- |
90
+ | `domain` | string | (current domain) | Cookie domain for cross-subdomain tracking (e.g., `.example.com`) |
91
+ | `expiresInDays` | number | `30` | Days until the cookie expires |
92
+ | `path` | string | `"/"` | Cookie path |
93
+
94
+ **Cross-domain tracking example:** If users land on `www.example.com` but convert on `app.example.com`, set `domain` to `.example.com` to share the click ID across subdomains.
95
+
96
+ ### Outbound Link Tracking
97
+
98
+ Automatically append click IDs to outbound links and iframes pointing to specified domains. This is useful for tracking conversions across multiple domains or passing attribution data to partner sites.
99
+
100
+ **Key Benefits:**
101
+ - ✅ **Reduced bundle size** - Only loads when configured (separate module)
102
+ - ✅ **Automatic tracking** - No manual link modification needed
103
+ - ✅ **Dynamic content support** - Tracks links added after page load
104
+ - ✅ **SPA compatible** - Works with client-side routing
105
+
106
+ #### Script Tag Usage
107
+
108
+ Add the `data-outbound` attribute with a JSON array of domains to track:
109
+
110
+ ```html
111
+ <script
112
+ src="https://unpkg.com/@li2/analytics/dist/index.global.js"
113
+ data-publishable-key="li2_pk_..."
114
+ data-outbound='["partner.com", "checkout.example.com"]'
115
+ ></script>
116
+ ```
117
+
118
+ The SDK will automatically:
119
+ 1. Find all `<a>` and `<iframe>` elements pointing to the specified domains
120
+ 2. Append the click ID as a `uid` query parameter
121
+ 3. Monitor for dynamically added links (SPAs, AJAX content)
122
+
123
+ #### Module Import Usage
124
+
125
+ ```typescript
126
+ import { init } from '@li2/analytics'
127
+
128
+ init({
129
+ publishableKey: 'li2_pk_...',
130
+ outbound: ['partner.com', 'checkout.example.com'],
131
+ })
132
+ ```
133
+
134
+ #### Example
135
+
136
+ **Before tracking:**
137
+ ```html
138
+ <a href="https://partner.com/signup">Sign up</a>
139
+ ```
140
+
141
+ **After tracking (automatic):**
142
+ ```html
143
+ <a href="https://partner.com/signup?uid=abc123xyz">Sign up</a>
144
+ ```
145
+
146
+ The partner site can then read the `uid` parameter and use it for server-side conversion tracking.
147
+
148
+ #### How It Works
149
+
150
+ 1. **Domain matching**: Links are tracked if their hostname ends with any configured domain
151
+ 2. **Normalization**: `www.` prefixes are automatically stripped for matching
152
+ 3. **Deduplication**: Each link is only modified once to avoid duplicate parameters
153
+ 4. **Periodic scanning**: New links are detected every 2 seconds
154
+ 5. **History API support**: Links are re-scanned on navigation in SPAs
155
+
156
+ **Note:** The outbound module is loaded dynamically only when the `outbound` option is configured, keeping your bundle size minimal when not needed.
157
+
158
+ ### Module Import Usage
159
+
160
+ ```typescript
161
+ import { init, trackLead, trackSale } from '@li2/analytics'
162
+
163
+ // Initialize with your publishable key
164
+ init({
165
+ publishableKey: 'li2_pk_...',
166
+ debug: true, // optional: enable console logging
167
+ })
168
+
169
+ // Track a lead conversion
170
+ const leadResult = await trackLead({
171
+ eventName: 'signup',
172
+ customerExternalId: 'user_123',
173
+ customerName: 'John Doe',
174
+ customerEmail: 'john@example.com',
175
+ })
176
+
177
+ if (leadResult.success) {
178
+ console.log('Lead tracked:', leadResult.customerId)
179
+ }
180
+
181
+ // Track a sale conversion
182
+ const saleResult = await trackSale({
183
+ customerExternalId: 'user_123',
184
+ amount: 4999, // Amount in cents ($49.99)
185
+ eventName: 'purchase',
186
+ paymentProcessor: 'stripe',
187
+ invoiceId: 'inv_abc123',
188
+ currency: 'usd',
189
+ })
190
+
191
+ if (saleResult.success) {
192
+ console.log('Sale tracked:', saleResult.saleEventId)
193
+ }
194
+ ```
195
+
196
+ ### Utility Functions
197
+
198
+ ```typescript
199
+ import { isTrackingAvailable, getClickId } from '@li2/analytics'
200
+
201
+ // Check if a click ID is available for attribution
202
+ if (isTrackingAvailable()) {
203
+ console.log('Click ID:', getClickId())
204
+ }
205
+
206
+ // Use getClickId() to pass the click ID to your server for server-side tracking
207
+ const clickId = getClickId() // Returns null if no click ID is available
208
+ ```
209
+
210
+ ## Server-Side SDK
211
+
212
+ The server-side SDK is for use in Node.js, Next.js API routes, server actions, and other backend environments. It requires an API key for authentication.
213
+
214
+ ### Passing Click ID from Client to Server
215
+
216
+ Unlike the client-side SDK, the server cannot auto-detect the click ID. You need to capture it on the client and include it in your server requests:
217
+
218
+ ```typescript
219
+ // Client-side: capture the click ID
220
+ import { getClickId } from '@li2/analytics'
221
+
222
+ const clickId = getClickId()
223
+
224
+ // Include clickId when calling your server
225
+ fetch('/api/checkout', {
226
+ method: 'POST',
227
+ body: JSON.stringify({ clickId, ...otherData }),
228
+ })
229
+ ```
230
+
231
+ ### Setup
232
+
233
+ ```typescript
234
+ import { initServer } from '@li2/analytics'
235
+
236
+ const li2 = initServer({
237
+ apiKey: 'li2_sk_...', // Your secret API key
238
+ debug: true, // optional: enable console logging
239
+ })
240
+ ```
241
+
242
+ ### Track Lead (Server-Side)
243
+
244
+ ```typescript
245
+ // clickId must be captured from the client and passed to your server
246
+ const result = await li2.trackLead({
247
+ clickId: 'abc123', // Required for server-side tracking
248
+ eventName: 'signup',
249
+ customerExternalId: 'user_123',
250
+ customerName: 'John Doe',
251
+ customerEmail: 'john@example.com',
252
+ metadata: {
253
+ plan: 'pro',
254
+ source: 'landing_page',
255
+ },
256
+ })
257
+
258
+ if (result.success) {
259
+ console.log('Lead tracked:', result.customerId)
260
+ }
261
+ ```
262
+
263
+ ### Track Sale (Server-Side)
264
+
265
+ ```typescript
266
+ const result = await li2.trackSale({
267
+ clickId: 'abc123', // Required for server-side tracking
268
+ customerExternalId: 'user_123',
269
+ amount: 9900, // Amount in cents ($99.00)
270
+ eventName: 'subscription',
271
+ paymentProcessor: 'stripe',
272
+ invoiceId: 'inv_xyz789',
273
+ currency: 'usd',
274
+ metadata: {
275
+ plan: 'annual',
276
+ coupon: 'SAVE20',
277
+ },
278
+ })
279
+
280
+ if (result.success) {
281
+ console.log('Sale tracked:', result.saleEventId)
282
+ }
283
+ ```
284
+
285
+ ### Next.js Example
286
+
287
+ ```typescript
288
+ // app/api/checkout/route.ts
289
+ import { initServer } from '@li2/analytics'
290
+
291
+ const li2 = initServer({ apiKey: process.env.LI2_API_KEY! })
292
+
293
+ export async function POST(request: Request) {
294
+ const { clickId, userId, amount, invoiceId } = await request.json()
295
+
296
+ // Track the sale after successful payment
297
+ const result = await li2.trackSale({
298
+ clickId,
299
+ customerExternalId: userId,
300
+ amount,
301
+ invoiceId,
302
+ paymentProcessor: 'stripe',
303
+ })
304
+
305
+ return Response.json({ success: result.success })
306
+ }
307
+ ```
308
+
309
+ ## API Reference
310
+
311
+ ### Client-Side
312
+
313
+ | Function | Description |
314
+ | ---------------------- | ---------------------------------------- |
315
+ | `init(config)` | Initialize the SDK with configuration |
316
+ | `trackLead(params)` | Track a lead conversion event |
317
+ | `trackSale(params)` | Track a sale conversion event |
318
+ | `isTrackingAvailable()`| Check if click ID is available |
319
+ | `getClickId()` | Get the current click ID |
320
+
321
+ ### Server-Side
322
+
323
+ | Function | Description |
324
+ | ---------------------- | ---------------------------------------- |
325
+ | `initServer(config)` | Create a server-side SDK instance |
326
+ | `trackLead(params)` | Track a lead (clickId required) |
327
+ | `trackSale(params)` | Track a sale (clickId required) |
328
+
329
+ ### TrackLead Parameters
330
+
331
+ | Parameter | Type | Required | Description |
332
+ | -------------------- | -------- | -------- | ------------------------------------- |
333
+ | `clickId` | string | Server only | Click ID for attribution |
334
+ | `eventName` | string | Yes | Name of the lead event |
335
+ | `customerExternalId` | string | Yes | Your unique customer identifier |
336
+ | `customerName` | string | No | Customer's name |
337
+ | `customerEmail` | string | No | Customer's email |
338
+ | `customerAvatar` | string | No | URL to customer's avatar |
339
+ | `metadata` | object | No | Additional data (max 10,000 chars) |
340
+
341
+ ### TrackSale Parameters
342
+
343
+ | Parameter | Type | Required | Description |
344
+ | -------------------- | -------- | -------- | ------------------------------------- |
345
+ | `clickId` | string | Server only | Click ID for attribution |
346
+ | `customerExternalId` | string | Yes | Your unique customer identifier |
347
+ | `amount` | number | Yes | Amount in smallest currency unit |
348
+ | `eventName` | string | No | Name of sale event (default: "Purchase") |
349
+ | `paymentProcessor` | string | No | Payment processor (e.g., "stripe") |
350
+ | `invoiceId` | string | No | Your invoice/transaction ID |
351
+ | `currency` | string | No | Currency code (default: "usd") |
352
+ | `customerName` | string | No | Customer's name |
353
+ | `customerEmail` | string | No | Customer's email |
354
+ | `metadata` | object | No | Additional data (max 10,000 chars) |
355
+
356
+ ## License
357
+
358
+ MIT