Before you can use account-level reporting, you will have to instrument it. The specific steps involved in the process depend on how you're sending data to Amplitude.
Once you've instrumented groups, a new dropdown will be visible in the right module of the chart control panel for certain charts. You will then be able to perform account-level reporting and designate whether you want to see events triggered by users or by groups.
NOTE: Amplitude has a limit of five group types per project.
SDKs
You can set up account-level reporting in Amplitude's SDKs by following these specific instructions, depending on which SDK you are using:
Identify API
If you are sending data to Amplitude server-side, use the groups
key in your identification object. This will associate a particular user in a certain group. Please see the Identify API documentation for more information on how to instrument groups via Amplitude's Identify API.
HTTP API
If you are sending data to Amplitude server-side, use the groups
key in your event object. This will add event-level groups (groups that only persist on that specific event). Please see the HTTP API documentation for more information on how to instrument groups via Amplitude's HTTP API.
Segment
NOTE: The Segment <> Amplitude cloud (any of Segment's server-side sources or the unbundled client-side integration) and device mode integration (bundled Segment-Amplitude integration) now support setting both group types and group properties through Segment's group
call. See the Segment documentation here for more details
To set group types in Amplitude via Segment, you must enable the following Amplitude destination settings and provide them with the appropriate values:
- Group Type Trait: This specifies what trait in your Segment
group
calls will contain the desired group type. - Group Value Trait: This specifies what trait in your Segment
group
calls will contain the desired group value.
For example, if you have the following code:
analytics.group("placeholder", {
groupType: "org name", // Segment trait "groupType" groupValue: "Amplitude", // Segment trait "groupValue" employees: "120" // group property });
And this in Segment's Amplitude destination settings:
Then the integration will create org name
as a group type in Amplitude and associate the current user with org name
= Amplitude
.
NOTE: What you pass in as the groupID
(in the above code, "placeholder"
) in the group call will not matter, as this value is not mapped to anything on Amplitude's side.
To set group properties via instrumentation code, you will need at least one source in Segment using the Segment <> Amplitude cloud mode integration (any of Segment's server libraries as well as the unbundled client-side integration). Data in Amplitude having the user property [Amplitude] Library = segment
will be sent via a cloud mode integration. You can use this user property to verify the type of integration you have installed in Amplitude for each of your Segment sources. Alternatively, you can also call the Amplitude SDK's functions to set group properties:
analytics.ready(function() { var groupIdentify = new amplitude.Identify().set('employees', 100); amplitude.getInstance().groupIdentify('orgId', '1234', groupIdentify);
});
Any additional traits that are passed into the group
call will appear in Amplitude as group properties. For example, from the above code, employees
will be set as an group property in Amplitude:
You can set groups and group properties using Segment's group
method. Note that via this method, every user event will include the group. That means this call is more appropriate to set user-level groups (such as CompanyID
) than for event-level grouping.
If you set groups within Segment's track
call, you can assign events to a group but you cannot set and update group properties within the call. To send group properties, call the Amplitude Group Identify API directly, outside of the Segment integration.
To assign groups via Segment's track
call, navigate to the Mappings tab within your Segment destination settings, and assign them there.
Create groups using the Group Identify API
Using the Group Identify API, you can create a new group tied with all expected group properties or update group properties for an existing group. In the example requests, the parameters and keys are italicized. The underlined values are what you need to replace with the parameters you are specifically interested in.
In addition, group property operations ($set
, $setOnce
, $add
, $append
, $unset
) are supported in this Group Identify API.
Request Format
Send a POST or GET request to https://api.amplitude.com/groupidentify
with two request parameters:
Parameter | Description |
---|---|
api_key (required) |
API Key from your project's Settings page. "040062a5d38552315b98302ba4f2f" |
identification (required) | A single JSON identification object (see below for fields). |
Example Request (single)
curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data 'identification={"group_properties":{"org csm":"Lucas","org plan":"Enterprise","org owner":"Luis"},"group_value":"1234","group_type":"org id"}' https://api.amplitude.com/groupidentify
Example Request (batch)
curl --data 'api_key=040062a5d38552315b98302ba4f2f' --data 'identification=[{"group_properties":{"org csm":"Lucas","org plan":"Enterprise","org owner":"Luis"},"group_value":"success","group_type":"org id"},{"group_properties":{"org csm":"Sarah","org plan":"Growth","org owner":"Sandy"},"group_value":"1234","group_type":"org id"}]' https://api.amplitude.com/groupidentify
NOTE: The upload limits listed here will apply to these requests.
Keys for the identification
Parameter
The following keys can be sent within the JSON identification object. Note that both group_type
and group_value
are required.
Key | Description |
---|---|
group_type (required) string |
One type of group (e.g. account or company).
|
group_value (required) string |
One specific value of the above group type. "group_type" : "org id", "group_value" : "12345678" or "group_type" : "account name", "group_value" : "Acme Corp" |
group_properties (optional) dictionary |
A dictionary of key-value pairs that represent additional data tied to the group. Each distinct value will show up as a group segment on the Amplitude dashboard. You can store property values in an array, and date values are transformed into string values. In addition, group property operations ( {"arr" : "10000", "cs": ["Justin", "Ben"], "renewal_date": “01/01/2018" } |