Groups

Groups are what your users belong to, such as the company or workspace they use your app as part of. Once the SDK knows a user's group, every event carries it, so Studio can count active companies, split charts by plan and list who in a company uses your app.

Put the user in a group

Call group() with the group type, the group's key and, optionally, its properties, for example after sign-in or when the user switches workspace:

await voidhash.group("company", "acme", { name: "Acme", plan: "pro", seats: 40 });
await voidhash.group("team", "acme-design");

• A group type is a key such as company: a lower-case letter, then up to 63 lower-case letters, digits or underscores. A project keeps up to 5 types.
• A group key is your own ID for the group, 1 to 256 characters. A number is kept as text.
• The user belongs to one group of each type: calling group() again with another key moves them.
• Properties are strings, numbers or booleans. name is what Studio shows as the group's name.

group() rejects an invalid type or key with VoidhashInvalidArgumentError. While analytics consent is not granted, the group is kept as the distinct ID is, and nothing is sent.

What the SDK sends

Every later event carries the user's groups in its $groups property, such as { company: "acme", team: "acme-design" }. A group an event names itself wins for its type:

await voidhash.track("report_shared", { $groups: { team: "acme-sales" } });

group() also sends a $groupidentify event, which sets the group's properties, when you pass properties or when the user's group of that type changed. A later change of a property wins. Properties you know on your server are better set from there, with groupIdentify.

Read and clear groups

voidhash.getGroups(); // { company: "acme", team: "acme-design" }
await voidhash.resetGroups(); // later events carry no groups

Groups are stored in the browser with the user's distinct ID, so they last across page loads and other tabs of your site follow a change. signOut() and reset() clear them with the identity; the $sign_out event still carries the groups of the user who signed out.

Next steps

• Groups
• Track events
• Reference