@loopkit/javascript

LoopKit JavaScript SDK

A JavaScript SDK for LoopKit analytics that works in both browser and Node.js environments.

📖 Complete Documentation

🔗 View the complete JavaScript SDK documentation →

Installation

npm install @loopkit/javascript

CDN

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

Quick Start

Browser

import LoopKit from '@loopkit/javascript';

// Initialize
LoopKit.init('your-api-key-here');

// Track an event
LoopKit.track('button_clicked', {
  button_name: 'signup',
  page: '/homepage',
});

// Identify a user
LoopKit.identify('user_123', {
  email: '[e-mail]',
  plan: 'pro',
});

Node.js

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',
});

API Reference

Initialization

LoopKit.init(apiKey, options?)

Initialize the SDK with your API key and optional configuration.

LoopKit.init('your-api-key', {
  debug: false,
  batchSize: 50,
  flushInterval: 30,
  enableAutoCapture: false,
  enableErrorTracking: false,
});

Event Tracking

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

Track a custom event with optional properties.

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

Note: 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.

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.

LoopKit.identify('user_123', {
  email: '[e-mail]',
  plan: 'enterprise',
  signup_date: '2024-01-15',
});

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

Associate the user with an organization or group.

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

Queue Management

LoopKit.flush()

Manually flush all queued events.

await LoopKit.flush();

LoopKit.getQueueSize()

Get the current number of events in the queue.

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

Configuration Options

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)
  enableAutoCapture: false, // Auto-track page views
  enableErrorTracking: false, // 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);
  },
});

Development

Building

# Install dependencies
npm install

# Build the SDK
npm run build

# Build and watch for changes
npm run build:watch

Testing

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

Linting

# Lint code
npm run lint

# Format code
npm run format

Deploying

# 1. Increment version in package.json

# 2. Deploy to CDN
yarn deploy:cdn

# 3. Publish to NPM
npm publish --access public

License

MIT License. See LICENSE for details.