group()

The group() method associates the current user with a company, organization, or account. This is primarily used in B2B applications where you need to track activity at the account level in addition to the individual user level.

Syntax

_df.group(groupId, traits?)

Parameters

Parameter	Type	Required	Description
`groupId`	`string`	Yes	A unique identifier for the company or organization
`traits`	`Record<string, unknown>`	No	Key-value pairs describing the group (name, plan, industry, etc.)

Returns

void

Basic usage

_df.group('company-456');

With traits

_df.group('company-456', {
  name: 'Acme Corp',
  plan: 'enterprise',
  industry: 'Technology',
  employees: 250,
  createdAt: '2024-06-01T00:00:00Z',
});

When to call group()

Call group() whenever the user’s account association becomes known or changes:

Scenario	Example
After login	User signs in and their company is known
After onboarding	User completes setup and selects or creates a company
On workspace switch	User switches between workspaces or accounts
On plan change	The account’s subscription plan changes

// After login, identify the user and their company
_df.identify('user-123', { email: 'jane@acme.com', name: 'Jane Doe' });
_df.group('company-456', { name: 'Acme Corp', plan: 'enterprise' });

How group works

When group() is called:

The groupId is stored in memory and included in all subsequent events
The traits are merged with any previously set group traits
A group event is sent to the Ingestion Gateway
The server associates the groupId with the current user

All subsequent page() and track() events will include the groupId, enabling account-level reporting and segmentation in your vendor destinations.

Trait merging

Like identify(), group traits are merged across multiple calls:

// First call
_df.group('company-456', { name: 'Acme Corp', plan: 'starter' });
 
// Later call -- plan is updated, name is preserved
_df.group('company-456', { plan: 'enterprise', employees: 250 });
 
// Internal state now: { name: 'Acme Corp', plan: 'enterprise', employees: 250 }

Common group traits

Trait	Type	Description
`name`	`string`	Company or organization name
`plan`	`string`	Subscription plan or tier
`industry`	`string`	Industry vertical
`employees`	`number`	Number of employees
`createdAt`	`string`	ISO 8601 date when the account was created
`website`	`string`	Company website URL
`mrr`	`number`	Monthly recurring revenue
`arr`	`number`	Annual recurring revenue

Event payload

A group() call produces an event with type: "group":

{
  "type": "group",
  "groupId": "company-456",
  "anonymousId": "a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d",
  "userId": "user-123",
  "traits": {
    "name": "Acme Corp",
    "plan": "enterprise",
    "industry": "Technology",
    "employees": 250
  },
  "context": {
    "page": {
      "url": "https://example.com/settings/account",
      "path": "/settings/account",
      "referrer": "https://example.com/dashboard",
      "title": "Account Settings",
      "search": ""
    },
    "screen": { "width": 1920, "height": 1080 },
    "locale": "en-US",
    "timezone": "America/New_York",
    "userAgent": "Mozilla/5.0 ...",
    "library": { "name": "@datafly/collector", "version": "0.1.0" }
  },
  "timestamp": "2026-02-25T14:22:00.000Z",
  "messageId": "df-d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f8a"
}

Multi-account users

If a user belongs to multiple accounts and can switch between them, call group() each time they switch:

// User switches to a different workspace
function onWorkspaceSwitch(workspace) {
  _df.group(workspace.id, {
    name: workspace.name,
    plan: workspace.plan,
  });
}

The group() method is optional. If your application is B2C or does not have an account/organization concept, you do not need to call group(). All other tracking methods work independently.

identify()Consent Management