Overview

Group Identity allows you to group together users by a shared user attribute. For example, users who live in the same household can be associated by their household street address, or users who share the same account for a streaming service can be associated by their shared account ID.

A group identity can be given group attributes, which are user attributes you select from your data catalog that are given to all group members.

For example, imagine an online streaming service where each account can have multiple users who all log in using the same account ID, and you want to record on each user’s profile if they are a “premium subscriber”.

First, users who subscribe to the premium service should be given a user attribute called premium_subscriber set to true.

Next, create a new group definition using the account ID as the group ID and the user attribute premium_subscriber as a group attribute. Group attributes are differentiated from normal user attributes by a prefix set to the value of the group ID name.

Every week, mParticle runs a “grouping job” where users who share the same account ID are grouped together. For every instance of a group, the account_id:premium_subscriber group attribute is given to all group members if, and only if, one other member of the group already has the user attribute premium_subscriber with the value of true.

This results in two sets of groups: one set of groups that contain premium subscribers, and one set of groups that contain no premium subscribers.

After users have been added to a group, they will appear in the User Activity View when searching for the group ID or group attribute.

Group ID

When you create a group definition, you select a user attribute that becomes the group ID. Any user attribute can be used as a group ID, as long as it exists in your data catalog.

Every Monday, on a weekly recurring basis, mParticle processes all profiles and groups together any profiles who share the same value for a user attribute that is a designated group ID.

For example, if you create a group definition with account_id as the group ID, and three users all have the attribute account_id with a value of 1234, then all three users are added to a group that is identified by the group ID account_ID:1234.

Group IDs must be unique hexadecimal or numerical user attributes within the following constraints:

• Minimum 1 character
• Maximum 32 characters
• Includes only the alphanumeric characters a-z and 0-9

When you create a group definition, you are defining a set of criteria that is used to create multiple group instances, one for each value of the group ID. Using the example above, if mParticle ingested data for two more users who each had the attribute account_id with a value of 5678, they would be added to a separate group identified by account_id:5678.

Group attributes

A group attribute is a user attribute given to all members of a group. The value of a group attribute is the same for every profile in the group, but the value of a group attribute is calculated based on one of four possible aggregation functions.

When viewing a user profile, you can tell the difference between group attributes and other user attributes by a prefix equaling name of a group ID.

For example, all user profiles in a group with the group ID account_id:1234 and the group attribute premium_subscriber will display the new attribute account_id:premium_subscriber.

This naming convention prevents any conflicts between group attributes and user attributes. For example, a user may have a premium subscriber group attribute, showing that they are in a group with a premium subscriber, even though individually they are not marked as a premium subscriber.

Any user attribute that exists in your data catalog can be used as a group attribute.

Group attribute aggregation logic

The value of a group attribute is calculated by aggregating the values of each original user attribute in the group. The aggregation results from one of four functions that you specify when first creating a group attribute. These four aggregation functions are:

Aggregation logic	Supported data type	Description
boolean or	boolean	If any instance of the attribute equals true, the group attribute is set to true.
latest	boolean, string, number, integer	The group attribute is set to the value of the most recently updated attribute in the group.
sum	non-negative number or integer	The group attribute is set to the sum of all attributes in the group.
average	non-negative number or integer	The group attribute is set to the average of all attributes in the group.

Continue reading below for detailed descriptions and examples of each aggregation logic option.

Boolean or

Group members only inherit a boolean or group attribute when another member has the same user attribute with a value of true.

Only boolean user attributes can be used as boolean or group attributes.

For example, imagine a group with a source attribute has_dog. Let’s say this group contains three users and none of them had a dog when they joined the group, so each user’s instance of has_dog equals false.

If a new user with the has_dog attribute set to true joins the group, then the other members will all have their has_dog group attribute set to true the next time the grouping job runs.

Latest

The value of a latest group attribute is set to the most recently updated instance of the user attribute in the group. All members of a group with a latest group attribute inherit that attribute upon joining the group.

User attributes of any data type can be used as latest group attributes.

For example, imagine a household group with two members: John and Jane. The group has a latest group attribute called street_address which is set to 1234 Main Street.

Next, a new user, Cindy, joins John and Jane’s household group. Cindy’s profile would inherit the group attribute street_address:1234 Main Street.

Sum

The value of a sum group attribute is equal to the sum of all instances of the user attribute in the group.

Only non-negative numbers or integers can be used as sum group attributes.

Average

The value of an average group attribute is equal to the average of all instances of the user attribute in the group.

Only non-negative numbers or integers can be used as average group attributes.

Group Identity API

In addition to the mParticle UI, you can also create and manage group definitions programmatically using the Group Identity API. For more information, see the Group Identity API reference.

Limitations

• 1 group definition per workspace in your mParticle account.
• Each group definition can include up to 10 group attributes.
• Each group can contain up to 10 users.

• Group ID limits:

  • Minimum 1 character
  • Maximum 32 characters
  • Includes only the alphanumeric characters a-z and 0-9