groups

import { groups } from "@spoar/sdk/plugins";
import type { Groups, TraitsArgs } from "@spoar/sdk/plugins";

Declare the group types and their traits once, and set autocompletes both:

import { createAnalytics } from "@spoar/sdk";
import type { NoProps } from "@spoar/sdk";
import { groups } from "@spoar/sdk/plugins";

type WorkspaceGroups = {
  company: { plan: "free" | "pro"; seats: number };
  team: NoProps;
};

export const workspace = groups<WorkspaceGroups>();

export const analytics = createAnalytics({
  project: "example.com",
  key: "pk_...",
  endpoint: "/_ra",
  plugins: [workspace],
});

workspace.set("company", "acme", { plan: "pro", seats: 12 });
workspace.set("team", "design");
workspace.leave("team");

OptionsCopy Anchor Link

groups<Map>() takes no arguments. The type parameter maps each group type to its traits; a type declared with NoProps takes no traits. Without it, any type and traits are accepted.

It returns the plugin with two methods:

Groups<Map> is the type of the returned object and TraitsArgs<Map, Type> the type of the optional traits argument.

LimitsCopy Anchor Link

set ignores a call with an invalid type, an empty id, or a sixth type while 5 are joined.

SendsCopy Anchor Link

workspace.set("company", "acme", { plan: "pro", seats: 12 }) sends:

{ plan: "pro", seats: 12, groupType: "company", groupId: "acme" }

Every later event, the group event included, carries the joined groups in its groups field:

{ company: "acme", team: "design" }

BehaviourCopy Anchor Link

• Groups live in memory. Call set on every page load, where the signed-in user is known.
• Groups belong to the visitor that joined them. After reset() or a revoked consent, events carry them no more.
• set may be called before the client starts; the group events are sent once the plugin starts.

In reportsCopy Anchor Link

Reports read groups as the group:<type> dimension, for breakdowns and filters: breakdown/group:company, filter[group:company]=acme. The traits are props of the group event, so breakdown/prop:plan with filter[event]=group reads them.