Overview

The Group method allows you to associate a user with a single or multiple groups, with each group assigned their own unique groupId. Groups of users could represent the organization, company or account they are a part of, or any other type of group you’d like to associate with a subset of users. A Group ID can be assigned traits when this event method is called, enabling you to describe the group in more detail as well, including the name of the group, subscription type the organization has purchased, and more.

Some destinations may not accept a Group ID or associated traits. Please refer to integration documentation to determine whether you need a Group ID.

How It Works

The Group call is typically paired with an Identify call, which identifies the particular user. This allows the Group call to collect additional traits that may be provided by the user, especially during account signup. You will want to populate the Group call with a Group ID from your own database if the organization, company, or other group entity already is represented within your database

The Group call function looks like this:

analytics.group("example_group_id", {
	name: "Don Draper",
	industry: "Advertising",
	employees: 63,
	plan: "premium",
});

This call could produce the below payload, without common fields:

{
  "type": "group",
  "groupId": "example_group_id",
  "traits": {
    "name": "Don Draper",
    "industry": "Advertising",
    "employees": 63,
    "plan": "premium"
  }

The payload could look like this with common fields:

{
    "timestamp": "2024-01-29T22:19:20.175Z",
    "integrations": {},
    "userId": "example_user_id",
    "anonymousId": "f8cc0f85-cb4d-4f73-b16f-c251384fdf74",
    "type": "group",
    "traits": {
        "plan": "Premium",
        "name": "Don Draper",
        "industry": "Advertising",
        "employees": 63
    },
    "groupId": "example_group_id",
    "context": {
        "page": {
            "path": "/",
            "referrer": "",
            "search": "",
            "title": "Account Signup",
            "url": "https://demo.metarouter.io/"
        },
        "providers": {},
        "globalPrivacyControl": false,
        "consent": {
            "optOut": {
                "C0001": false,
                "C0002": false,
                "C0003": false,
                "C0004": false,
                "C0005": false
            }
        },
        "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36",
        "locale": "en-US",
        "library": {
            "name": "analytics.js",
            "version": "npm:next-1.51.3-mr.3"
        }
    },
    "messageId": "f18af79c35add5833d8fcaa50f9e0687",
    "writeKey": "mr-demo-team_product_sandbox_matt",
    "sentAt": "2024-01-29T22:19:20.184Z",
    "_metadata": {
        "bundled": [],
        "unbundled": [],
        "bundledIds": []
    }
}

Traits

Traits are pieces of information associated with the group that are passed along within the call. The following list contains common Group call traits. We recommend using these whenever one of these fields covers what you are trying to track.

Trait	Data Type	Description
`address`	Object	Street address of a group. This should contain optional city, country, postalCode, state, or street fields as well.
`avatar`	String	URL to an avatar image for the group.
`createdAt`	Date	Date that the group account was first created. ISO-8601 date strings are recommended.
`description`	String	Description of the group, like a bio.
`email`	String	Email address of group.
`employees`	String	Number of employees within a group
`id`	String	Unique ID in your database for the given group.
`industry`	String	Industry the group is a part of.
`name`	String	Name of the group.
`phone`	String	Phone number of the group.
`website`	String	Website of the group.
`plan`	String	Plan that a group is in or subscribed to.

Additional Considerations

Like the Page method, the Group method can also accept parameters for options and callback functions.