Documentation

Quick Start

Get up and running with JCHT in under five minutes. The SDK is lightweight (<8 KB gzipped) and supports all modern browsers and Node.js 16+.

Install via npm

npm install @jcht/sdk

Or include via CDN

Add the following script tag to your HTML. The SDK will be available globally as JCHT.

<script src="https://cdn.jcht.org/sdk/v2/jcht.min.js"></script>

Tip: When using the CDN version, the SDK automatically initializes in buffered mode. Events are queued until you call JCHT.init().

Initialization

After installing the SDK, initialize it with your project credentials. You can find your API key and project ID in the JCHT Dashboard under Settings → API Keys.

JavaScript

import JCHT from '@jcht/sdk';

JCHT.init({
  apiKey: 'your-api-key',
  projectId: 'your-project'
});

The init() method returns a promise that resolves once the SDK has established a connection. You can await it to ensure tracking is ready before proceeding:

Async initialization

async function bootstrap() {
  await JCHT.init({
    apiKey: 'your-api-key',
    projectId: 'your-project',
    debug: true
  });

  console.log('JCHT ready');
}

Tracking Events

Use JCHT.track() to record user actions and system events. Every event consists of a name and an optional properties object.

Basic event tracking

JCHT.track('button_click', {
  buttonId: 'signup',
  page: '/pricing'
});

You can track any custom event. Properties can include strings, numbers, booleans, and nested objects up to 3 levels deep.

Advanced example

JCHT.track('purchase_completed', {
  orderId: 'ord_8x92ka',
  total: 49.99,
  currency: 'USD',
  items: [
    { sku: 'SKU-001', qty: 1 },
    { sku: 'SKU-044', qty: 2 }
  ]
});

Identifying Users

Link events to a specific user with JCHT.identify(). Call this when a user signs in or when you first learn their identity. All subsequent events are automatically attributed to this user.

Identify a user

JCHT.identify('user-123', {
  email: 'jane@co.com',
  plan: 'pro'
});

User traits are merged with any previously set traits. To reset identity (e.g., on logout), call:

JCHT.reset();

Connecting Sources

JCHT aggregates data from multiple analytics platforms into a single view. You can connect third-party sources directly from the dashboard—no code required.

Navigate to Dashboard → Sources in your JCHT project.
Click Add Source and choose your provider (Google Analytics, Mixpanel, Amplitude, Segment, etc.).
Authenticate with your provider account using OAuth or paste your provider API key.
Select which properties and events to sync. JCHT will map them to your unified schema.
Data begins flowing within 60 seconds. Historical backfill completes within a few hours depending on data volume.

Note: You can also manage sources programmatically via the REST API. See the POST /api/v1/sources endpoint.

Configuration Options

The full set of options you can pass to JCHT.init():

Option	Type	Default	Description
`apiKey`	string	—	Your project API key. Required.
`projectId`	string	—	Your JCHT project identifier. Required.
`debug`	boolean	`false`	Enable verbose console logging for development.
`batchSize`	number	`25`	Number of events to batch before flushing to the server.
`flushInterval`	number	`5000`	Interval in milliseconds between automatic flushes.
`endpoint`	string	`"https://jcht.org/api/v1"`	Custom API endpoint. Use for self-hosted or proxy setups.

Full configuration example

JCHT.init({
  apiKey: 'jcht_live_a8Kx92mNqP',
  projectId: 'proj_frontend_web',
  debug: false,
  batchSize: 50,
  flushInterval: 3000,
  endpoint: 'https://jcht.org/api/v1'
});