@chottulink/web-sdk

v1.0.10

Published

a month ago

ChottuLink Web SDK — attribution, identify, and event tracking for the browser.

0High
0Medium
0Low

ChottuLink Web SDK

The ChottuLink Web SDK provides attribution, identity mapping, and event tracking for web applications. It allows you to unify your mobile and web funnels, attributing web visits to the short-link clicks that brought the visitor.

Features

First-touch Attribution: Automatically attributes web visits back to the ChottuLink short-link click.
Identity Unification: Maps anonymous browser IDs to your customer identifiers (customer_id, email) across the entire funnel.
Event Tracking: Track signups (leads), conversions (sales/revenue), and custom events.
Optimized Performance: Small footprint with signal-gated initialization to minimize backend traffic.
Privacy Focused: Supports PII hashing and respects browser prefetch headers.

Installation

NPM

npm install @chottulink/web-sdk

Script Tag (CDN)

Add the following script to the <head> or bottom of the <body> of your website:

<script
  src="https://chottulink.com/downloads/sdks/web/v1.0.10/chottulink.iife.js"
  crossorigin="anonymous">
</script>

OR with integrity check

<script
  src="https://chottulink.com/downloads/sdks/web/v1.0.10/chottulink.iife.js"
  integrity="sha384-LTbMxZbtAQXF48yCk0NAXUVvF4HHg7dymHgIQlRXHqBR8iRN8R+P6YyF7Cdha7b3"
  crossorigin="anonymous">
</script>

Quick Start

import ChottuLink from '@chottulink/web-sdk';

// Initialize the SDK
await ChottuLink.init({
  apiKey: 'YOUR_PUBLIC_API_KEY'
});

// Identify the user
ChottuLink.identify({
  customer_id: 'user_12345',
  email: '[email protected]'
});

// Track a signup/lead
await ChottuLink.trackLead({
  email: '[email protected]',
  name: 'John Doe'
});

// Track a conversion with revenue
await ChottuLink.trackConversion({
  revenue: 49.99,
  currency: 'USD',
  transaction_id: 'TXN_001'
});

// Track a custom event
await ChottuLink.trackEvent('add_to_cart', {
  product_id: 'SKU_123'
});

Core API Reference

init(options)

Initializes the SDK and processes attribution if a signal is present.

await ChottuLink.init({
  apiKey: string,               // Required: Your organization public API key
  baseUrl?: string,             // Optional: Custom backend URL
  cookieDomain?: string,        // Optional: Root domain for the device ID cookie
  autoPageTracking?: boolean,   // Optional: Auto-track SPA route changes (default: true)
  allowIframe?: boolean,        // Optional: Allow tracking inside iframes (default: false)
  consentMode?: 'required' | 'not_required', // Optional: Buffer until consent (default: 'not_required')
  debug?: boolean               // Optional: Enable console logging
});

identify(options)

Maps the current device to a known user in your system. Stores identity locally (sessionStorage) for subsequent track calls AND sends an identify request to /web/identify so the server can link cl_device_id to your customer_id. State survives SPA navigation within the tab.

ChottuLink.identify({
  customer_id: string,          // Required: Your internal player/user ID
  email?: string,               // User email (will be hashed before sending)
  phone?: string,               // User phone number (will be hashed before sending)
  name?: string,                // User display name
  email_sha256?: string,        // Pre-hashed email
  phone_sha256?: string         // Pre-hashed phone number
});

Behavior notes:

The method is sync-callable (returns void); the network send happens in the background.
Identical successive calls (same customer_id + _sha256 fields + name) are deduped — only the first one in a session reaches the network.
If called before init() resolves, the request is queued and replayed after init.
If consent is required and not yet granted, the request is buffered and replayed on grant.
Calls from inside an iframe (without allowIframe) are no-ops.

trackLead(options)

Tracks a signup or lead generation event. Maps to track_signup on the backend.

await ChottuLink.trackLead({
  customer_id?: string,
  email?: string,
  phone?: string,
  name?: string,
  email_sha256?: string,
  phone_sha256?: string,
  metadata?: Record<string, any>,
  event_id?: string,            // Unique ID for deduplication
  client_timestamp?: string     // ISO-8601 timestamp
});

trackConversion(options)

Tracks a conversion or purchase event involving revenue. Maps to track_conversion on the backend.

await ChottuLink.trackConversion({
  revenue: number,              // Required: Amount in major units (e.g., 49.99)
  currency: string,             // Required: ISO-4217 code (e.g., "USD")
  transaction_id: string,       // Unique ID used for deduplication
  customer_id?: string,
  product_id?: string,
  metadata?: Record<string, any>,
  event_id?: string,
  client_timestamp?: string
});

trackEvent(name, options)

Tracks a custom event.

await ChottuLink.trackEvent('event_name', {
  product_id?: string,
  revenue?: number,
  currency?: string,
  transaction_id?: string,
  metadata?: Record<string, any>,
  event_id?: string,
  client_timestamp?: string
});

getAttribution()

Returns the current attribution context synchronized after initialization.

const ctx = ChottuLink.getAttribution();
/* Returns:
{
  cl_link_id: string | null,
  utm_source: string | null,
  utm_medium: string | null,
  utm_campaign: string | null,
  utm_term: string | null,
  utm_content: string | null,
  custom_data: Record<string, any> | null
} | null
*/

Consent Management

If consentMode is set to required, all cookies and API calls are buffered until grantConsent() is called.

grantConsent(): Enables tracking and flushes the buffer.
denyConsent(): Disables tracking and discards the buffer.
hasConsent(): Returns the current consent status.

Utilities

trackPageView(): Manually trigger a page view track. Useful if autoPageTracking is disabled.
reset(): Clears all cookies, session storage, and in-memory state.
version: Returns the current SDK version string.

Architecture and Behavior

Attribution Signal Gating

To limit unnecessary network requests, the SDK only calls the backend if:

No cl_device_id cookie exists (first-ever visit).
The URL contains an attribution signal (e.g., cl_link_id, utm_source, gclid, fbclid, etc.).

Subsequent page navigations within the same session that do not carry new signals do not trigger additional attribution calls, reducing backend load while preserving first-touch accuracy.

Safari ITP and Cookie Caps

Due to Safari's Intelligent Tracking Prevention (ITP), first-party cookies set via JavaScript are typically capped at 7 days. Attribution for returning visits after 7 days may degrade to organic if no new attribution signal is present.

Security

The SDK communicates with the ChottuLink backend via a secure POST API. Ensure your domain is added to the "Allowed Web Origins" list in the ChottuLink Dashboard to prevent CORS errors.

Development

Building the SDK

Requirement: Node.js 18+

npm install
npm run build

Running Tests

npm test