JavaScript / Node.js

Universal JavaScript and TypeScript SDK for server-side and Node.js applications.

Installation

Step 1: Install

npm install @helionlabs/sdk

Step 2: Initialize

Create a shared Helion instance and export it for use across your application:

helion.ts

import { Helion } from '@helionlabs/sdk';

export const hl = new Helion({
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
});

Options

Common options

apiUrl - The url of the helion API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Step 3: Usage

Import the shared instance and call tracking methods:

main.ts

import { hl } from './helion';

hl.track('my_event', { foo: 'bar' });

Usage

Tracking Events

Call hl.track() with an event name and optional properties. For HTML environments, data-track attributes on elements are tracked automatically when trackAttributes: true is set.

index.ts

import { hl } from './helion';

hl.track('my_event', { foo: 'bar' });

Identifying Users

Call hl.identify() to associate the current session with a known user profile.

index.ts

import { hl } from './helion';

hl.identify({
  profileId: '123', // Required
  firstName: 'Joe',
  lastName: 'Doe',
  email: 'joe@doe.com',
  properties: {
    tier: 'premium',
  },
});

Setting Global Properties

Properties set via setGlobalProperties are attached to every subsequent event automatically.

index.ts

import { hl } from './helion';

hl.setGlobalProperties({
  app_version: '1.0.2',
  environment: 'production',
});

Incrementing Properties

Increment a numeric property on a user profile. Omit value to increment by 1.

index.ts

import { hl } from './helion';

hl.increment({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});

Decrementing Properties

Decrement a numeric property on a user profile. Omit value to decrement by 1.

index.ts

import { hl } from './helion';

hl.decrement({
  profileId: '1',
  property: 'visits',
  value: 1, // optional
});

Working with Groups

Groups enable account-level or company-level analytics. See the Groups guide for the full walkthrough.

Create or update a group:

index.ts

import { hl } from './helion';

hl.upsertGroup({
  id: 'org_acme',
  type: 'company',
  name: 'Acme Inc',
  properties: { plan: 'enterprise' },
});

Assign the current user to a group (call after identify):

index.ts

import { hl } from './helion';

hl.setGroup('org_acme');
// Or multiple groups:
hl.setGroups(['org_acme', 'team_eng']);

Once group IDs are set, all subsequent track() calls include them automatically.

Clearing User Data

clear() resets the current user profile, device identity, session, and all group associations. Call it on logout.

index.ts

import { hl } from './helion';

hl.clear();

Common options

On this page