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.client.group("company", "acme", { name: "Acme", plan: "pro", seats: 40 });
await voidhash.client.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() resolves to a Result: an invalid type or key is an INVALID_ARGUMENT error. Like identify(), it waits for init() and runs in call order with identify(), reset() and signOut().

Set every group at once

When your app knows all of a user's groups, pass them to setGroups() in one call. It replaces the whole set, so you don't track which group the user joined or left:

await voidhash.client.setGroups({
  company: { id: "acme", name: "Acme", plan: "pro", seats: 40 }, // the ID, with the properties
  team: "acme-design", // an ID alone
});

• Each entry is a group's ID, or an object with the id and the group's properties beside it.
• A type you leave out, or set to null or undefined, is dropped. {} does what resetGroups() does.
• Types and IDs follow the rules of group(). An entry that breaks them is left out. An object without an id is an INVALID_ARGUMENT error, and nothing changes.

Call it whenever the groups might have changed, such as on every launch or after your user data refreshes. Calling it again with the same groups sends nothing. Like group(), it resolves to a Result and runs in call order with identify(), reset() and signOut().

What the SDK sends

Every event captured after group() resolves carries the user's groups in its $groups property, such as { company: "acme", team: "acme-design" }. capture() is synchronous, so await group() before capturing an event that must name the group. A group an event names itself wins for its type:

voidhash.client.capture("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. setGroups() sends one only for a group whose ID changed or whose properties differ from the ones it last sent; leaving a group sends nothing. A later change of a property wins.

A group and its properties are what your app says about the user, not what the user did, so they are sent whatever the analytics consent. While consent is not granted, the $groupidentify goes out at once on its own, with only the group's type, ID and properties: no session or device details. It is not retried if it fails; the next setGroups() call sends it again. The $groups property still travels only on events, which need consent. Properties you know on your server are better set from there, with groupIdentify.

Read and clear groups

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

getGroups() returns {} before init() resolves. Groups are stored on the device with the user's distinct ID by the native iOS and Android SDKs, so they last across launches and identify() keeps them. signOut() and reset() clear them with the identity whenever they act; the $sign_out event still carries the groups of the user who signed out.

Next steps

• Groups
• Capture analytics
• Reference