Groups — Voidhash Docs

Analyze the companies, workspaces or teams your users belong to, with properties of their own.

A group is something people belong to in your product, such as the company or workspace they use it as part of. Each kind of group is a group type, named by a key such as company. Events name the groups they happened in, and each group has properties of its own, such as its name, plan or number of seats. Studio then counts companies as well as people, splits charts by plan, and lists who in a company is active.

A group is not a person: it has no purchases or perks, and a person can belong to one group of each type at a time.

Name an event's groups

An event names its groups in the $groups property, by group type:

{ "event": "report_exported", "properties": { "format": "pdf", "$groups": { "company": "acme" } } }

The web, Swift, Kotlin and React Native SDKs add it to every event once you call group(), and the server libraries take a groups option on each capture:

await voidhash.group("company", "acme", { name: "Acme", plan: "pro", seats: 40 });
await voidhash.track("report_exported", { format: "pdf" }); // carries $groups: { company: "acme" }

await voidhash.group(type: "company", key: "acme", properties: ["name": .string("Acme")])
await voidhash.capture("report_exported", properties: ["format": .string("pdf")])

voidhash.group("company", "acme", mapOf("name" to "Acme"))
voidhash.capture("report_exported", mapOf("format" to "pdf"))

await voidhash.client.group("company", "acme", { name: "Acme" });
voidhash.client.capture("report_exported", { format: "pdf" });

await voidhash.eventCapture.capture({
  distinctId: "user_123",
  event: "report_exported",
  timestamp: new Date().toISOString(),
  groups: { company: "acme" },
});

The SDKs in apps keep the user's groups on the device with their distinct ID, and clear them on sign-out. See the groups page of Web, Swift, Kotlin and React Native, and the persons and events page of Node.js, PHP, Go and Rust.

Set a group's properties

A $groupidentify event sets a group's properties. The SDKs send it for you: group() in the web and app SDKs when you pass properties, and groupIdentify in the server libraries. Studio and the API can set them too.

Each property is a string, a number or a boolean. Nested values are left out.
A later change of a property wins, by the time it happened, so an older change that arrives late does not undo a newer one.
Set once properties fill only properties the group has no value for, such as the plan it started on.
name is what Studio shows as the group's name; without it, Studio shows its key.

A $groupidentify event belongs to no person, whichever distinct ID sent it, and never creates or changes one.

Rules and limits

Rule	Limit
Group type key	A lower-case letter, then up to 63 lower-case letters, digits or underscores: `company`, `team_2`.
Group key	Text of 1 to 256 characters. A number is accepted and kept as text.
Group types per project	5. A sixth type is left off the events that name it.
Groups of one type per event	1.

Voidhash keeps an event whose $groups it cannot fully read and leaves out only the entries it cannot: a type that isn't a valid key, or a key that isn't text or a number. Events whose groups of a sixth type were left out are counted in Data health, under Group types over the limit.

A project's group types and groups appear the first time an event names them. A group's first seen time is that of the first event that named it.

Delete a group

Deleting a group in Studio or with the API removes it and its properties. Its events stay and still name its key, and events that keep naming it do not bring it back. A later $groupidentify for it does, with only the properties it sets.

Next steps