LoopKit JavaScript SDK

A complete analytics SDK for tracking events, user identification, and behavioral analytics in web applications. Now built with TypeScript for better developer experience and type safety.

📦 NPM Package | 🔧 GitHub Repository

React Developers

If you're using React, check out our dedicated React SDK → for a more integrated experience with hooks and providers.

Features

🔧 TypeScript Support: Full TypeScript support with comprehensive type definitions
👤 User Identification: Identify users and track their journey
👥 Group Analytics: Associate users with organizations/groups
🔄 Zero-Config Auto Tracking: Automatic page views, clicks, and error tracking (enabled by default)
💾 Local Storage: Persist events offline with automatic retry
🌐 Cross-Platform: Works in browsers, Node.js, and React applications
📦 Multiple Formats: ES modules, CommonJS, UMD builds available

Installation

NPM (Recommended)

bash

npm install @loopkit/javascript

CDN

html

<script src="https://cdn.loopkit.ai/js/loopkit.min.js"></script>

Quick Start

Browser

javascript

import LoopKit from '@loopkit/javascript';

// Initialize - auto tracking starts immediately!
LoopKit.init('your-api-key-here');
// ✅ automatically tracking page views, clicks, and errors

// Identify a user
LoopKit.identify('user_123', {
  email: 'user@example.com',
  plan: 'pro',
});

Node.js

javascript

const LoopKit = require('@loopkit/javascript');

// Initialize with configuration
LoopKit.init('your-api-key-here', {
  debug: true,
  batchSize: 50,
  flushInterval: 30,
});

// Track server-side events
LoopKit.track('user_signup', {
  method: 'email',
  source: 'landing_page',
});

Browser Script Tag

html

<!DOCTYPE html>
<html>
  <head>
    <title>My App</title>
  </head>
  <body>
    <!-- Your app content -->

    <script src="https://cdn.loopkit.ai/js/loopkit.min.js"></script>
    <script>
      // Initialize LoopKit - auto tracking starts immediately!
      LoopKit.init('your-api-key-here');
      // ✅ automatically tracking page views, clicks, and errors
    </script>
  </body>
</html>

Auto Tracking Features (Enabled by Default)

LoopKit automatically tracks common user interactions and events out of the box. All auto tracking features are enabled by default for zero-configuration setup:

📋 Quick Reference

Feature	Default	Event Type	Description
`enableAutoCapture`	✅ `true`	`page_view`	Page loads and navigation
`enableAutoClickTracking`	✅ `true`	`click`	Button, link, and element clicks
`enableErrorTracking`	✅ `true`	`error`	JavaScript errors and exceptions

📊 Page View Tracking (`enableAutoCapture: true`)

What it tracks: Automatically captures page views on initial load and navigation
Events generated: page_view events with URL, path, title, and referrer
When it triggers:
- Initial page load
- Browser navigation (back/forward buttons)
- Single Page App (SPA) route changes
Event properties: url, path, search, title, referrer

🖱️ Click Tracking (`enableAutoClickTracking: true`)

What it tracks: Automatically captures clicks on interactive elements
Events generated: click events with element details and page context
Elements tracked: Buttons, links, form inputs, and clickable elements
Event properties: element_type, element_text, element_id, element_class, element_tag, element_href, page, page_title, page_url, position

🚨 Error Tracking (`enableErrorTracking: true`)

What it tracks: Automatically captures JavaScript errors and exceptions
Events generated: error events with error details and stack traces
Error types: Runtime errors, syntax errors, and unhandled promise rejections
Event properties: message, filename, lineno, colno, stack, timestamp

Zero-Config Example

javascript

// Just initialize with your API key - auto tracking starts immediately!
LoopKit.init('your-api-key');

// The SDK will now automatically track:
// ✅ Page views when users navigate
// ✅ Clicks on buttons, links, etc.
// ✅ JavaScript errors that occur
// ✅ Session management

Customizing Auto Tracking

You can disable specific auto tracking features if needed:

javascript

LoopKit.init('your-api-key', {
  enableAutoCapture: false, // Disable page view tracking
  enableAutoClickTracking: false, // Disable click tracking
  enableErrorTracking: false, // Disable error tracking
});

TypeScript Support

The SDK is built with TypeScript and exports comprehensive type definitions:

Core Types

typescript

import type {
  // Configuration
  LoopKitConfig,
  LogLevel,
  RetryBackoff,

  // Events
  TrackEvent,
  IdentifyEvent,
  GroupEvent,
  ClickEventProperties,
  BatchEventInput,
  TrackOptions,

  // Interfaces
  ILoopKit,
  IStorageManager,
  ISessionManager,
  IQueueManager,
  INetworkManager,

  // Convenience aliases
  Config,
  Event,
  Options,
} from '@loopkit/javascript';

Configuration Types

typescript

const config: LoopKitConfig = {
  apiKey: 'your-key',
  baseURL: 'https://api.example.com',
  batchSize: 50,
  flushInterval: 30,
  debug: true,
  logLevel: 'info',

  // Auto tracking (all enabled by default)
  enableAutoCapture: true, // Page view tracking
  enableAutoClickTracking: true, // Click tracking
  enableErrorTracking: true, // Error tracking

  respectDoNotTrack: true,
  onBeforeTrack: (event) => {
    // Modify event before tracking
    return { ...event, timestamp: new Date().toISOString() };
  },
  onAfterTrack: (event, success) => {
    if (!success) {
      console.warn('Failed to track event:', event);
    }
  },
  onError: (error) => {
    console.error('LoopKit error:', error);
  },
};

Type-Safe Event Tracking

typescript

interface UserSignupProperties {
  method: 'email' | 'google' | 'github';
  source: string;
  plan?: 'free' | 'pro' | 'enterprise';
}

// Type-safe event tracking
LoopKit.track('user_signup', {
  method: 'email',
  source: 'homepage',
  plan: 'pro',
} as UserSignupProperties);

API Reference

Initialization

`LoopKit.init(apiKey, options?)`

Initialize the SDK with your API key and optional configuration.

javascript

LoopKit.init('your-api-key', {
  debug: false,
  batchSize: 50,
  flushInterval: 30,

  // Auto tracking features (enabled by default - shown here for reference)
  enableAutoCapture: true, // Auto page view tracking
  enableAutoClickTracking: true, // Auto click tracking
  enableErrorTracking: true, // Auto error tracking
});

Event Tracking

`LoopKit.track(eventName, properties?, options?)`

Track a custom event with optional properties.

javascript

LoopKit.track('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
  product_id: 'pro_plan',
});

Automatic Timestamps

Timestamps are automatically added to all events. You don't need to manually include timestamp in your properties - the SDK handles this automatically at the event level.

`LoopKit.trackBatch(events)`

Track multiple events in a single batch.

javascript

LoopKit.trackBatch([
  { name: 'page_view', properties: { page: '/home' } },
  { name: 'button_clicked', properties: { button: 'cta' } },
]);

User Management

`LoopKit.identify(userId, properties?)`

Associate events with a specific user.

javascript

LoopKit.identify('user_123', {
  email: 'user@example.com',
  plan: 'enterprise',
  signup_date: '2024-01-15',
});

`LoopKit.group(groupId, properties?, groupType?)`

Associate the user with an organization or group.

javascript

LoopKit.group(
  'company_abc',
  {
    name: 'Acme Corp',
    plan: 'enterprise',
    employee_count: 500,
  },
  'organization'
);

Queue Management

`LoopKit.flush()`

Manually flush all queued events.

javascript

await LoopKit.flush();

`LoopKit.getQueueSize()`

Get the current number of events in the queue.

javascript

const queueSize = LoopKit.getQueueSize();
console.log(`${queueSize} events queued`);

`LoopKit.reset()`

Reset the SDK state (useful for logout).

javascript

LoopKit.reset();

Configuration Options

javascript

LoopKit.configure({
  // API Settings
  baseURL: 'https://api.loopkit.ai/v1',

  // Batching
  batchSize: 50, // Events per batch
  flushInterval: 30, // Seconds between flushes
  maxQueueSize: 1000, // Maximum events to queue

  // Performance
  enableCompression: true, // Gzip requests
  requestTimeout: 10000, // Request timeout (ms)

  // Debugging
  debug: false, // Enable debug logs
  logLevel: 'info', // 'error', 'warn', 'info', 'debug'

  // Auto-capture (Browser only) - All enabled by default for zero-config setup
  enableAutoCapture: true, // Auto-track page views
  enableAutoClickTracking: true, // Auto-track click events
  enableErrorTracking: true, // Auto-track JS errors

  // Privacy
  respectDoNotTrack: true, // Honor DNT header
  enableLocalStorage: true, // Use localStorage for persistence

  // Retry Logic
  maxRetries: 3, // Number of retry attempts
  retryBackoff: 'exponential', // 'exponential' or 'linear'

  // Callbacks
  onBeforeTrack: (event) => {
    // Modify event before tracking
    return event;
  },
  onAfterTrack: (event, success) => {
    // Handle tracking result
    console.log(`Event ${event.name} ${success ? 'sent' : 'failed'}`);
  },
  onError: (error) => {
    // Handle errors
    console.error('LoopKit error:', error);
  },
});

Common Use Cases

Page View Tracking

javascript

// Manual page view tracking (when auto-capture is disabled)
LoopKit.track('page_view', {
  page: window.location.pathname,
  title: document.title,
  referrer: document.referrer,
});

// Auto-track page views (SPA) - handled automatically by default
// But you can manually trigger for custom navigation:
window.addEventListener('popstate', () => {
  LoopKit.track('page_view', {
    page: window.location.pathname,
    title: document.title,
  });
});

User Lifecycle Events

javascript

// User registration
LoopKit.track('user_signup', {
  method: 'email',
  source: 'homepage',
  plan: 'free',
});

// User login
LoopKit.track('user_login', {
  method: 'email',
  session_id: 'session_abc123',
});

// Feature usage
LoopKit.track('feature_used', {
  feature: 'data_export',
  success: true,
  duration: 1200, // milliseconds
});

E-commerce Events

javascript

// Product view
LoopKit.track('product_viewed', {
  product_id: 'product_123',
  product_name: 'Pro Plan',
  category: 'subscription',
  price: 99.99,
  currency: 'USD',
});

// Purchase
LoopKit.track('purchase_completed', {
  order_id: 'order_456',
  total_amount: 99.99,
  currency: 'USD',
  item_count: 1,
  payment_method: 'card',
});

Framework Integration

Vue.js

javascript

// Vue.js plugin
const LoopKitPlugin = {
  install(app, options) {
    LoopKit.init(options.apiKey);

    app.config.globalProperties.$track = LoopKit.track;
    app.provide('$track', LoopKit.track);
  },
};

// Use plugin
app.use(LoopKitPlugin, { apiKey: 'your-api-key' });

// In components
export default {
  methods: {
    handleClick() {
      this.$track('button_clicked', {
        button_name: 'submit',
        form: 'contact',
      });
    },
  },
};

jQuery

javascript

// jQuery plugin
$.fn.trackClick = function (eventName, properties = {}) {
  return this.on('click', function () {
    LoopKit.track(eventName, {
      ...properties,
      element: this.tagName.toLowerCase(),
      text: $(this).text().trim(),
    });
  });
};

// Usage
$('.signup-button').trackClick('signup_button_clicked', {
  location: 'header',
});

Error Handling

Automatic Error Tracking (Enabled by Default)

javascript

// Error tracking is enabled by default - no setup required!
LoopKit.init('your-api-key');
// ✅ JavaScript errors are now automatically tracked

// Manual error tracking for custom errors
LoopKit.track('application_error', {
  error_message: 'Failed to load user data',
  error_code: 'USER_LOAD_ERROR',
  endpoint: '/api/user/profile',
  user_action: 'profile_view',
});

Custom Error Handling

javascript

// Handle LoopKit errors
LoopKit.configure({
  onError: (error) => {
    console.error('LoopKit error:', error);
    // Send to your error monitoring service
    errorMonitor.captureException(error);
  },
});

Development

Building

bash

# Install dependencies
npm install

# Build the SDK
npm run build

# Build and watch for changes
npm run build:watch

Testing

bash

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Linting

bash

# Lint code
npm run lint

# Format code
npm run format

Privacy & Compliance

Do Not Track Support

javascript

// Respect Do Not Track (enabled by default)
LoopKit.configure({
  respectDoNotTrack: true,
});

// Manual privacy check
if (navigator.doNotTrack === '1') {
  console.log('User has Do Not Track enabled');
  // Don't initialize LoopKit or track events
} else {
  LoopKit.init('your-api-key');
}

Data Control

javascript

// Clear local queue
LoopKit.clearQueue();

// Reset user identity and SDK state
LoopKit.reset();

Next Steps

Need help with JavaScript integration? Join our Discord for developer support.

LoopKit JavaScript SDK ​

Features ​

Installation ​

NPM (Recommended) ​

CDN ​

Quick Start ​

Browser ​

Node.js ​

Browser Script Tag ​

Auto Tracking Features (Enabled by Default) ​

📋 Quick Reference ​

📊 Page View Tracking (enableAutoCapture: true) ​

🖱️ Click Tracking (enableAutoClickTracking: true) ​

🚨 Error Tracking (enableErrorTracking: true) ​

Zero-Config Example ​

Customizing Auto Tracking ​

TypeScript Support ​

Core Types ​

Configuration Types ​

Type-Safe Event Tracking ​

API Reference ​

Initialization ​

LoopKit.init(apiKey, options?) ​

Event Tracking ​

LoopKit.track(eventName, properties?, options?) ​

LoopKit.trackBatch(events) ​

User Management ​

LoopKit.identify(userId, properties?) ​

LoopKit.group(groupId, properties?, groupType?) ​

Queue Management ​

LoopKit.flush() ​

LoopKit.getQueueSize() ​

LoopKit.reset() ​

Configuration Options ​

Common Use Cases ​

Page View Tracking ​

User Lifecycle Events ​

E-commerce Events ​

Framework Integration ​

Vue.js ​

jQuery ​

Error Handling ​

Automatic Error Tracking (Enabled by Default) ​

Custom Error Handling ​

Development ​

Building ​

Testing ​

Linting ​

Privacy & Compliance ​

Do Not Track Support ​

Data Control ​

Next Steps ​

LoopKit JavaScript SDK

Features

Installation

NPM (Recommended)

CDN

Quick Start

Browser

Node.js

Browser Script Tag

Auto Tracking Features (Enabled by Default)

📋 Quick Reference

📊 Page View Tracking (`enableAutoCapture: true`)

🖱️ Click Tracking (`enableAutoClickTracking: true`)

🚨 Error Tracking (`enableErrorTracking: true`)

Zero-Config Example

Customizing Auto Tracking

TypeScript Support

Core Types

Configuration Types

Type-Safe Event Tracking

API Reference

Initialization

`LoopKit.init(apiKey, options?)`

Event Tracking

`LoopKit.track(eventName, properties?, options?)`

`LoopKit.trackBatch(events)`

User Management

`LoopKit.identify(userId, properties?)`

`LoopKit.group(groupId, properties?, groupType?)`

Queue Management

`LoopKit.flush()`

`LoopKit.getQueueSize()`

`LoopKit.reset()`

Configuration Options

Common Use Cases

Page View Tracking

User Lifecycle Events

E-commerce Events

Framework Integration

Vue.js

jQuery

Error Handling

Automatic Error Tracking (Enabled by Default)

Custom Error Handling

Development

Building

Testing

Linting

Privacy & Compliance

Do Not Track Support

Data Control

Next Steps