Groups

Groups let you associate users with a shared entity — a company, workspace, or team — and analyze behavior at that level. Instead of asking "what did Jane do?", you can ask "what is Acme Inc doing?"

This pattern is particularly useful for B2B SaaS products where a single paying account has many users.

How groups work

There are two distinct concepts:

1. The group entity — created or updated with upsertGroup(). Stores metadata about the group (name, plan, seat count, etc.).
2. Group membership — established with setGroup() or setGroups(). Links a user profile to one or more groups and automatically attaches those group IDs to every subsequent track() call.

Creating or updating a group

Call upsertGroup() to create a group or update its properties. The group is identified by its id and type combination.

hl.upsertGroup({
  id: 'org_acme',        // Unique identifier for this group
  type: 'company',       // Group category (company, workspace, team, etc.)
  name: 'Acme Inc',      // Human-readable display name
  properties: {
    plan: 'enterprise',
    seats: 25,
    industry: 'logistics',
  },
});

Group payload

Managing groups in the dashboard

Groups can be created, edited, and deleted directly from the Groups section of your Helion dashboard. Use upsertGroup() when group properties are dynamic and sourced from your own data — for example, syncing a customer's current plan, seat count, or MRR at login time.

Assigning a user to a group

After identifying a user, call setGroup() to link them to a group. This also attaches the group ID to all future track() calls in the current session.

// After login
hl.identify({ profileId: 'user_123' });

// Link the user to their organization
hl.setGroup('org_acme');

For users that belong to multiple groups:

hl.setGroups(['org_acme', 'team_engineering']);

Full login flow

setGroup() does not require the group to exist beforehand. Passing only an ID will tag events with that group ID immediately — you can create the group later from the dashboard or via upsertGroup().

// 1. Identify the user
hl.identify({
  profileId: 'user_123',
  firstName: 'Jane',
  email: 'jane@acme.com',
});

// 2. Assign the user to the group
hl.setGroup('org_acme');

// 3. All subsequent events are tagged with the group automatically
hl.track('dashboard_viewed');  // → includes groups: ['org_acme']
hl.track('report_exported');   // → includes groups: ['org_acme']

To sync dynamic group properties from your backend at the same time:

hl.identify({ profileId: 'user_123', email: 'jane@acme.com' });

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

hl.setGroup('org_acme');

Per-event group override

Attach group IDs to a specific event without modifying the SDK's persistent group state:

hl.track('file_shared', {
  filename: 'q4-report.pdf',
  groups: ['org_acme', 'org_partner'], // Applies to this event only
});

Groups passed in track() are merged with any groups already set on the SDK instance.

Clearing groups on logout

clear() resets the profile, device, session, and all group associations. Always call it on logout.

function handleLogout() {
  hl.clear();
  // redirect to login...
}

Common patterns

B2B SaaS — company accounts

// On login
hl.identify({ profileId: user.id, email: user.email });
hl.upsertGroup({
  id: user.organizationId,
  type: 'company',
  name: user.organizationName,
  properties: { plan: user.plan, mrr: user.mrr },
});
hl.setGroup(user.organizationId);

Multi-tenant — workspaces

// When a user switches workspace
hl.upsertGroup({
  id: workspace.id,
  type: 'workspace',
  name: workspace.name,
});
hl.setGroup(workspace.id);

Teams within a company

// User belongs to both a company and a specific team
hl.setGroups([user.organizationId, user.teamId]);

API reference

upsertGroup(payload)

Creates the group if it does not exist, or merges properties into the existing group record.

hl.upsertGroup({
  id: string;       // Required
  type: string;     // Required
  name: string;     // Required
  properties?: Record<string, unknown>;
});

setGroup(groupId)

Adds a single group ID to the SDK's internal group list and dispatches an assign_group event to link the current profile to that group.

hl.setGroup('org_acme');

setGroups(groupIds)

Equivalent to setGroup() but accepts an array of group IDs.

hl.setGroups(['org_acme', 'team_engineering']);

What to avoid

• Calling upsertGroup() on every event or page view — call it on login or when group properties actually change. Use the dashboard for static group management.
• Omitting setGroup() after identify() — without it, events will not be tagged with the group and group-level analytics will be incomplete.
• Skipping clear() on logout — group IDs persist on the SDK instance, which means a new user logging in on the same browser session will inherit the previous user's group associations.
• Using upsertGroup() to link a user to a group — upsertGroup() manages the group entity only. Use setGroup() to associate a user profile with it.