Groups

Overview

Groups let you model B2B-style relationships: companies, workspaces, teams, departments, or any entity your product has. You assign the current user to groups, track events in the context of a specific group, and optionally set persistent properties on the group itself (similar to People, but scoped to the group entity).

Backend is stateless. Node.js and Python require distinctId / distinct_id as the first argument on every group call. The browser SDK uses the stored identity automatically.

Core concepts

Term	Meaning
Group key	Namespace for a type of group — `company`, `team`, `active_team`.
Group ID	Identifier of one instance — `acme-inc`, `team-uuid-123`.
Membership	Which group IDs the current user belongs to, per key. Persisted server-side; browser also mirrors to `localStorage`.
Active context	The group the user is currently working in. Drives event attribution.
Group profile	Properties on a `(groupKey, groupId)` pair, updated via `get_group(...)` helpers.

How event attribution works

Every event fired after a group call gets stamped with the user’s current group context — that’s how Trodo knows which group’s timeline it belongs to.

add_group → appends a membership. Subsequent events are attributed to all current memberships for that key.
set_group → replaces the active context for that key. Events fired after the switch use the new context.
Event attribution changes only for events fired after the call. No historical rewrite.

Method map

Operation	Browser	Node.js	Python
set_group	`Trodo.set_group('team', 'eng')`	`trodo.set_group('user-42', 'team', 'eng')`	`trodo.set_group("user-42", "team", "eng")`
add_group	`Trodo.add_group('team', 'eng')`	`trodo.add_group('user-42', 'team', 'eng')`	`trodo.add_group("user-42", "team", "eng")`
remove_group	`Trodo.remove_group('team', 'eng')`	`trodo.remove_group('user-42', 'team', 'eng')`	`trodo.remove_group("user-42", "team", "eng")`
get_group (profile)	`Trodo.get_group('team', 'eng')`	`trodo.forUser('user-42').get_group('team', 'eng')`	`trodo.for_user("user-42").get_group("team", "eng")`

Group membership

set_group — switch active context

Use when the user switches which group they’re working in. Accepts a single id or an array.

JavaScript (browser)
Node.js
Python

await Trodo.set_group('active_team', 'team-b-id');

// Or multiple ids at once
await Trodo.set_group('team', ['engineering', 'design']);

await trodo.set_group('user-42', 'active_team', 'team-b-id');

await trodo.set_group('user-42', 'team', ['engineering', 'design']);

trodo.set_group("user-42", "active_team", "team-b-id")

trodo.set_group("user-42", "team", ["engineering", "design"])

add_group — permanent membership

Use when a user joins a group they’ll always belong to. Idempotent — adding the same id twice is a no-op.

JavaScript (browser)
Node.js
Python

await Trodo.add_group('company', 'acme-inc');
await Trodo.add_group('team', 'engineering');

await trodo.add_group('user-42', 'company', 'acme-inc');
await trodo.add_group('user-42', 'team', 'engineering');

trodo.add_group("user-42", "company", "acme-inc")
trodo.add_group("user-42", "team", "engineering")

remove_group

JavaScript (browser)
Node.js
Python

await Trodo.remove_group('team', 'design');

await trodo.remove_group('user-42', 'team', 'design');

trodo.remove_group("user-42", "team", "design")

Recommended pattern for multi-team SaaS apps

Most B2B apps have users belonging to multiple teams permanently but working in one team at a time. Use two separate group keys:

Key	Method	Purpose
`team`	`add_group`	All teams the user permanently belongs to
`active_team`	`set_group`	Current active workspace — drives event attribution

JavaScript (browser)
Node.js
Python

// On login — user joins all their teams permanently
await Trodo.add_group('team', 'team-a-id');
await Trodo.add_group('team', 'team-b-id');

// Set the currently active team
await Trodo.set_group('active_team', 'team-a-id');

// Later — user switches workspace
await Trodo.set_group('active_team', 'team-b-id');

const distinctId = 'user-42';

await trodo.add_group(distinctId, 'team', 'team-a-id');
await trodo.add_group(distinctId, 'team', 'team-b-id');

await trodo.set_group(distinctId, 'active_team', 'team-a-id');

// On team switch
await trodo.set_group(distinctId, 'active_team', 'team-b-id');

distinct_id = "user-42"

trodo.add_group(distinct_id, "team", "team-a-id")
trodo.add_group(distinct_id, "team", "team-b-id")

trodo.set_group(distinct_id, "active_team", "team-a-id")

# On team switch
trodo.set_group(distinct_id, "active_team", "team-b-id")

Result in Trodo:

The team page for team-a shows the user as a permanent member.
The active_team page for team-a shows only events fired while team-a was active.
The active_team page for team-b shows only events fired while team-b was active.

Group profile — properties per group

get_group(groupKey, groupId) returns a handle with profile methods. Each call writes to the group entity itself — not to the user, and not to event attribution.

JavaScript (browser)
Node.js
Python

const team = Trodo.get_group('team', 'team-a-id');

await team.set({ name: 'Engineering', plan: 'enterprise', seat_count: 50 });
await team.set_once({ created_at: '2024-01-01' });
await team.union('tags', ['b2b', 'saas']);
await team.remove('tags', 'b2b');
await team.increment('seat_count', 5);
await team.unset('plan');
await team.delete();

// Bind to a user first — group profile calls are still made on behalf of a user
const team = trodo.forUser('user-42').get_group('team', 'team-a-id');

await team.set({ name: 'Engineering', plan: 'enterprise', seat_count: 50 });
await team.set_once({ created_at: '2024-01-01' });
await team.union('tags', ['b2b', 'saas']);
await team.remove('tags', 'b2b');
await team.increment('seat_count', 5);
await team.unset('plan');
await team.delete();

team = trodo.for_user("user-42").get_group("team", "team-a-id")

team.set({"name": "Engineering", "plan": "enterprise", "seat_count": 50})
team.set_once({"created_at": "2024-01-01"})
team.union("tags", ["b2b", "saas"])
team.remove("tags", "b2b")
team.increment("seat_count", 5)
team.unset("plan")
team.delete()

Method	Description
`set(properties)`	Set or overwrite group properties
`set_once(properties)`	Set only if the property is not already set
`union(listName, values)`	Add unique values to a list property
`remove(listName, value)`	Remove a value from a list property
`append(property, value)`	Append to a list (allows duplicates)
`increment(property, value)`	Increment a numeric property
`unset(property)`	Remove one property from the group profile
`delete()`	Delete the entire group profile

get_group is only for profile operations. It has no effect on event attribution — use set_group or add_group for that.

identify() and cross-device membership (browser)

When identify() completes on the browser, the server returns group_memberships and the SDK hydrates local state from that payload. The same user gets consistent group assignments across devices. Backend SDKs don’t mirror state — they only write, so this doesn’t apply. See Identify.

JavaScript (browser)
Node.js
Python

await Trodo.identify(user.id);

Trodo.people.set({ email: user.email, name: user.name, plan: user.plan });

for (const team of user.teams) {
  await Trodo.add_group('team', team.id);
}

await Trodo.set_group('active_team', user.currentTeamId);

const activeTeam = Trodo.get_group('active_team', user.currentTeamId);
await activeTeam.set({
  name: user.currentTeam.name,
  plan: user.currentTeam.plan,
  member_count: user.currentTeam.memberCount,
});

Trodo.track('dashboard_opened', { section: 'overview' });

const ctx = trodo.forUser(user.id);

await trodo.identify(user.id);
await ctx.people.set({ email: user.email, name: user.name, plan: user.plan });

for (const team of user.teams) {
  await ctx.add_group('team', team.id);
}

await ctx.set_group('active_team', user.currentTeamId);

await ctx.get_group('active_team', user.currentTeamId).set({
  name: user.currentTeam.name,
  plan: user.currentTeam.plan,
  member_count: user.currentTeam.memberCount,
});

await ctx.track('dashboard_opened', { section: 'overview' });

ctx = trodo.for_user(user.id)

trodo.identify(user.id)
ctx.people.set({"email": user.email, "name": user.name, "plan": user.plan})

for team in user.teams:
    ctx.add_group("team", team.id)

ctx.set_group("active_team", user.current_team_id)

ctx.get_group("active_team", user.current_team_id).set({
    "name": user.current_team.name,
    "plan": user.current_team.plan,
    "member_count": user.current_team.member_count,
})

ctx.track("dashboard_opened", {"section": "overview"})

People vs. Groups

	People	Groups
What it describes	The end user	An org, team, or entity the user belongs to
Browser namespace	`Trodo.people.*`	`Trodo.set_group` / `add_group` / `get_group`
Server (Node/Python)	`trodo.people.*(distinctId, ...)`	`trodo.{set_group, add_group, get_group}(distinctId, ...)`
Profile updates	`people.set({...})`	`get_group(key, id).set({...})`
Membership	Single user, tied to `identify`	One user can belong to many groups across many keys

People

User profile properties

Identify

User identity and cross-device merge

Track

Custom events

Auto-Events

Automatic event capture

INTRO

DATA IN

BEST PRACTICES

Overview

Core concepts

How event attribution works

Method map

Group membership

set_group — switch active context

add_group — permanent membership

remove_group

Recommended pattern for multi-team SaaS apps

Group profile — properties per group

identify() and cross-device membership (browser)

People vs. Groups

People

Identify

Track

Auto-Events

INTRO

DATA IN

BEST PRACTICES

Documentation Index

​Overview

​Core concepts

​How event attribution works

​Method map

​Group membership

​set_group — switch active context

​add_group — permanent membership

​remove_group

​Recommended pattern for multi-team SaaS apps

​Group profile — properties per group

​identify() and cross-device membership (browser)

​Full example — SaaS login flow

​People vs. Groups

​Related

People

Identify

Track

Auto-Events

Overview

Core concepts

How event attribution works

Method map

Group membership

set_group — switch active context

add_group — permanent membership

remove_group

Recommended pattern for multi-team SaaS apps

Group profile — properties per group

identify() and cross-device membership (browser)

Full example — SaaS login flow

People vs. Groups

Related