@li2/analytics - npm explorer

@li2/analytics

v0.2.3TypeScript

Li2 Analytics SDK for conversion tracking

li2 analytics conversion tracking

279/weekUpdated 4 days agoMITUnpacked: 650.6 KB

Published by Li2

npm install @li2/analytics

@li2/analytics

Conversion tracking SDK for Li2.ai. Track leads and sales from your marketing campaigns with automatic click ID attribution.

Installation

``bash npm install @li2/analytics

`or`


pnpm add @li2/analytics
or

yarn add @li2/analytics

`


Client-Side SDK

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.

> 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 for details.

`$3`

Add this snippet to your tag. It loads the SDK asynchronously and queues any tracking calls made before the script loads.

`html`

`$3`

`html src="https://unpkg.com/@li2/analytics/dist/index.global.js" data-publishable-key="li2_pk_..." >

`

`$3`

| Attribute | Description | | --------- | ----------- | |data-publishable-key | Your publishable API key (li2_pk_...) | |data-api-url | Custom API endpoint (default: https://api.li2.ai) | |data-debug| Enable debug logging (presence enables, no value needed) | |data-cookie-options| JSON object for cookie customization (see below) | |data-outbound | JSON array of domains for outbound link tracking (e.g., ["partner.com"]) |

`$3`

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.

`html src="https://unpkg.com/@li2/analytics/dist/index.global.js" data-publishable-key="li2_pk_..." data-cookie-options='{"domain":".example.com","expiresInDays":60}' >`

| Property | Type | Default | Description | | -------- | ---- | ------- | ----------- | |domain | string | (current domain) | Cookie domain for cross-subdomain tracking (e.g., .example.com) | |expiresInDays | number | 30| Days until the cookie expires | |path | string | "/" | Cookie path |

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.

`$3`

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.

Key Benefits: - ✅ Reduced bundle size - Only loads when configured (separate module) - ✅ Automatic tracking - No manual link modification needed - ✅ Dynamic content support - Tracks links added after page load - ✅ SPA compatible - Works with client-side routing

#### Script Tag Usage

Add the data-outbound attribute with a JSON array of domains to track:

`html src="https://unpkg.com/@li2/analytics/dist/index.global.js" data-publishable-key="li2_pk_..." data-outbound='["partner.com", "checkout.example.com"]' >`

The SDK will automatically: 1. Find all and <code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> elements pointing to the specified domains<br />2. Append the click ID as a </code>uid<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> query parameter<br />3. Monitor for dynamically added links (SPAs, AJAX content)</p><p class="my-3">#### Module Import Usage</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />import { init } from '@li2/analytics'</p><p class="my-3">init({<br /> publishableKey: 'li2_pk_...',<br /> outbound: ['partner.com', 'checkout.example.com'],<br />})<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">#### Example</p><p class="my-3"><strong>Before tracking:</strong><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">html<br /><a href="https://partner.com/signup">Sign up</a><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><strong>After tracking (automatic):</strong><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">html<br /><a href="https://partner.com/signup?uid=abc123xyz">Sign up</a><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">The partner site can then read the </code>uid<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> parameter and use it for server-side conversion tracking.</p><p class="my-3">#### How It Works</p><p class="my-3">1. <strong>Domain matching</strong>: Links are tracked if their hostname ends with any configured domain<br />2. <strong>Normalization</strong>: </code>www.<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> prefixes are automatically stripped for matching<br />3. <strong>Deduplication</strong>: Each link is only modified once to avoid duplicate parameters<br />4. <strong>Periodic scanning</strong>: New links are detected every 2 seconds<br />5. <strong>History API support</strong>: Links are re-scanned on navigation in SPAs</p><p class="my-3"><strong>Note:</strong> The outbound module is loaded dynamically only when the </code>outbound<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> option is configured, keeping your bundle size minimal when not needed.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />import { init, trackLead, trackSale } from '@li2/analytics'</p><p class="my-3">// Initialize with your publishable key<br />init({<br /> publishableKey: 'li2_pk_...',<br /> debug: true, // optional: enable console logging<br />})</p><p class="my-3">// Track a lead conversion<br />const leadResult = await trackLead({<br /> eventName: 'signup',<br /> customerExternalId: 'user_123',<br /> customerName: 'John Doe',<br /> customerEmail: 'john@example.com',<br />})</p><p class="my-3">if (leadResult.success) {<br /> console.log('Lead tracked:', leadResult.customerId)<br />}</p><p class="my-3">// Track a sale conversion<br />const saleResult = await trackSale({<br /> customerExternalId: 'user_123',<br /> amount: 4999, // Amount in cents ($49.99)<br /> eventName: 'purchase',<br /> paymentProcessor: 'stripe',<br /> invoiceId: 'inv_abc123',<br /> currency: 'usd',<br />})</p><p class="my-3">if (saleResult.success) {<br /> console.log('Sale tracked:', saleResult.saleEventId)<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />import { isTrackingAvailable, getClickId } from '@li2/analytics'</p><p class="my-3">// Check if a click ID is available for attribution<br />if (isTrackingAvailable()) {<br /> console.log('Click ID:', getClickId())<br />}</p><p class="my-3">// Use getClickId() to pass the click ID to your server for server-side tracking<br />const clickId = getClickId() // Returns null if no click ID is available<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Server-Side SDK</h2></p><p class="my-3">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.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">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:</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />// Client-side: capture the click ID<br />import { getClickId } from '@li2/analytics'</p><p class="my-3">const clickId = getClickId()</p><p class="my-3">// Include clickId when calling your server<br />fetch('/api/checkout', {<br /> method: 'POST',<br /> body: JSON.stringify({ clickId, ...otherData }),<br />})<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />import { initServer } from '@li2/analytics'</p><p class="my-3">const li2 = initServer({<br /> apiKey: 'li2_sk_...', // Your secret API key<br /> debug: true, // optional: enable console logging<br />})<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />// clickId must be captured from the client and passed to your server<br />const result = await li2.trackLead({<br /> clickId: 'abc123', // Required for server-side tracking<br /> eventName: 'signup',<br /> customerExternalId: 'user_123',<br /> customerName: 'John Doe',<br /> customerEmail: 'john@example.com',<br /> metadata: {<br /> plan: 'pro',<br /> source: 'landing_page',<br /> },<br />})</p><p class="my-3">if (result.success) {<br /> console.log('Lead tracked:', result.customerId)<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />const result = await li2.trackSale({<br /> clickId: 'abc123', // Required for server-side tracking<br /> customerExternalId: 'user_123',<br /> amount: 9900, // Amount in cents ($99.00)<br /> eventName: 'subscription',<br /> paymentProcessor: 'stripe',<br /> invoiceId: 'inv_xyz789',<br /> currency: 'usd',<br /> metadata: {<br /> plan: 'annual',<br /> coupon: 'SAVE20',<br /> },<br />})</p><p class="my-3">if (result.success) {<br /> console.log('Sale tracked:', result.saleEventId)<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">typescript<br />// app/api/checkout/route.ts<br />import { initServer } from '@li2/analytics'</p><p class="my-3">const li2 = initServer({ apiKey: process.env.LI2_API_KEY! })</p><p class="my-3">export async function POST(request: Request) {<br /> const { clickId, userId, amount, invoiceId } = await request.json()</p><p class="my-3"> // Track the sale after successful payment<br /> const result = await li2.trackSale({<br /> clickId,<br /> customerExternalId: userId,<br /> amount,<br /> invoiceId,<br /> paymentProcessor: 'stripe',<br /> })</p><p class="my-3"> return Response.json({ success: result.success })<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">API Reference</h2></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">| Function | Description |<br />| ---------------------- | ---------------------------------------- |<br />| </code>init(config)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Initialize the SDK with configuration |<br />| </code>trackLead(params)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Track a lead conversion event |<br />| </code>trackSale(params)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Track a sale conversion event |<br />| </code>isTrackingAvailable()<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">| Check if click ID is available |<br />| </code>getClickId()<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Get the current click ID |</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">| Function | Description |<br />| ---------------------- | ---------------------------------------- |<br />| </code>initServer(config)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Create a server-side SDK instance |<br />| </code>trackLead(params)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Track a lead (clickId required) |<br />| </code>trackSale(params)<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | Track a sale (clickId required) |</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">| Parameter | Type | Required | Description |<br />| -------------------- | -------- | -------- | ------------------------------------- |<br />| </code>clickId<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | Server only | Click ID for attribution |<br />| </code>eventName<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | Yes | Name of the lead event |<br />| </code>customerExternalId<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | Yes | Your unique customer identifier |<br />| </code>customerName<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Customer's name |<br />| </code>customerEmail<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Customer's email |<br />| </code>customerAvatar<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | URL to customer's avatar |<br />| </code>metadata<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | object | No | Additional data (max 10,000 chars) |</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3></p><p class="my-3">| Parameter | Type | Required | Description |<br />| -------------------- | -------- | -------- | ------------------------------------- |<br />| </code>clickId<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | Server only | Click ID for attribution |<br />| </code>customerExternalId<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | Yes | Your unique customer identifier |<br />| </code>amount<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | number | Yes | Amount in smallest currency unit |<br />| </code>eventName<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Name of sale event (default: "Purchase") |<br />| </code>paymentProcessor<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Payment processor (e.g., "stripe") |<br />| </code>invoiceId<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Your invoice/transaction ID |<br />| </code>currency<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Currency code (default: "usd") |<br />| </code>customerName<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Customer's name |<br />| </code>customerEmail<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> | string | No | Customer's email |<br />| </code>metadata` | object | No | Additional data (max 10,000 chars) |</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">License</h2></p><p class="my-3">MIT<br /></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"26:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n27:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^5.0.0\"}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>