Skip to main content

​
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 each group (similar to People, but scoped to that group entity).
Group APIs live on the root Trodo object. Membership uses set_group / add_group / remove_group. Profile updates use get_group(groupKey, groupId) and call methods on the returned object.

​
Core concepts

TermMeaning
Group keyA string you choose for the type of group (e.g. company, team, active_team).
Group IDThe identifier for one specific instance of that type (e.g. acme-inc, team-uuid-123).
MembershipWhich group IDs the current user belongs to, per group key. Stored in localStorage and synced with the server.
Active contextThe group the user is currently working in, used for event attribution.
Group profileProperties attached to a specific (groupKey, groupId) pair, updated via get_group(...).set().

​
How event attribution works

Every event fired after group membership is set gets stamped with the user’s current group context. This is how Trodo knows which group’s timeline an event belongs to.
  • add_group → adds a group to the user’s membership list. All subsequent events are attributed to all current memberships for that key.
  • set_group → updates active context for that key in the SDK and ensures the provided group(s) are attached on the server. Events fired after the switch use the new context.
  • Only events fired after a group call are attributed to the updated context. No historical backfill is performed.
This means the group timeline in Trodo shows exactly the events that happened while a user was in that group — not all events by all current members.

​
Group membership

​
Trodo.set_group(groupKey, groupId)

Sets the active context for groupKey to one ID (or an array of IDs) in the SDK and ensures those groups are attached for the user on the server. Use this when the user switches their active context (e.g. switching from one team to another). 
// User switches to a different team — active context changes
await Trodo.set_group('active_team', 'team-b-id');

// Also accepts an array to set multiple IDs at once
await Trodo.set_group('team', ['engineering', 'design']);
​
groupKey
string
required
Namespace for this group type (e.g. active_team, company).
​
groupId
string | string[]
required
Single ID or array of IDs. Updates the active context for that key.
What happens internally:
  • Updates localStorage immediately (optimistic).
  • Sends to the server and ensures the provided group(s) exist and are attached for this user.
  • Does not remove historical memberships or rewrite old events. Event attribution changes from this point onward only.

​
Trodo.add_group(groupKey, groupId)

Adds one group ID to the user’s existing list for groupKey without removing others. Safe to call multiple times — calling with the same ID twice has no effect. Use this when a user joins a group permanently (e.g. joining a team or organisation they will always be a member of). 
// User is a permanent member of this company
await Trodo.add_group('company', 'acme-inc');

// User is also a member of this team — both are kept
await Trodo.add_group('team', 'engineering');
await Trodo.add_group('team', 'design');
​
groupKey
string
required
Namespace for this group type.
​
groupId
string
required
Must be a single string (not an array). Use set_group for arrays.
What happens internally:
  • Updates localStorage, appending the new ID if not already present.
  • Sends to the server, which adds the user to the group’s member list (deduplicated).
  • Does not rewrite historical events.

​
Trodo.remove_group(groupKey, groupId)

Removes one specific group ID from the user’s list for groupKey. 
await Trodo.remove_group('team', 'design');
If no IDs remain for that key after removal, the key is deleted from localStorage. What happens internally:
  • Removes the user from the group’s member list on the server.
  • Does not rewrite historical events.
Most B2B apps have users who belong to multiple teams permanently but only work in one team at a time. Use two separate group keys:
KeyMethodPurpose
teamadd_groupPermanent membership — all teams the user belongs to
active_teamset_groupCurrent active workspace — drives event attribution
// On login — user joins their teams permanently
await Trodo.add_group('team', 'team-a-id');
await Trodo.add_group('team', 'team-b-id');

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

// User switches to Team B
await Trodo.set_group('active_team', 'team-b-id');
// → events fired from here are attributed to team-b only
// → events fired earlier stay attributed to team-a
Result in Trodo:
  • The team group page for team-a shows the user as a member (permanent).
  • The active_team group page for team-a shows only events fired while team-a was active.
  • The active_team group page for team-b shows only events fired while team-b was active.

​
Group profile (properties per group)

​
Trodo.get_group(groupKey, groupId)

Returns a synchronous handle with profile methods. Each method sends a network request when called. This is for setting properties on the group entity itself — not for event attribution. 
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();
MethodDescription
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 one value from a list property.
append(property, value)Append a value to a list property (allows duplicates).
increment(property, value)Increment a numeric property by value (default: 1).
unset(property)Remove one property from the group profile.
delete()Delete the entire group profile.
Returns null if groupKey or groupId is missing.
get_group is only for profile operations — setting properties on the group entity. It has no effect on event attribution. To control which events are attributed to a group, use set_group or add_group.

​
identify() and cross-device membership

When identify() completes, the server returns group_memberships and the SDK hydrates local membership from that payload. This ensures the same user has consistent group assignments when logging in on a new device or browser. See Identify for when to call identify().

​
Full example: SaaS app login flow

// 1. Identify the user
await Trodo.identify(user.id);

// 2. Set user profile properties
Trodo.people.set({
  email: user.email,
  name: user.name,
  plan: user.plan
});

// 3. Add permanent team memberships (all teams this user belongs to)
for (const team of user.teams) {
  await Trodo.add_group('team', team.id);
}

// 4. Set the active team context (drives event attribution)
await Trodo.set_group('active_team', user.currentTeamId);

// 5. Set properties on the active team's profile
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
});

// 6. Track events — these are attributed to the active team
Trodo.track('dashboard_opened', { section: 'overview' });

// 7. When user switches team
await Trodo.set_group('active_team', newTeamId);
// → all subsequent events attributed to newTeamId

​
Comparison: People vs Groups

PeopleGroups
What it describesThe end userAn organization, team, or entity the user belongs to
NamespaceTrodo.people.*Trodo.set_group / add_group / get_group on root
Typical first stepTrodo.identify(id)Trodo.add_group('team', id) or Trodo.set_group(...)
Profile updatesTrodo.people.set({...})Trodo.get_group(key, id).set({...})
MembershipSingle user, always 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