Segmentation and Levels (Date-Range Reports)

Report data may be segmented in up to 3 levels. Each level represents a property. Using multi-level segmentation, you can create hierarchical reports that are used to drill down based on the property values. For example, you can create a report that splits all the users based on which edition they are using. Then, you can split the user counts for each edition based on product version on level 2. Finally, the user counts for each product version can be split up by product build on level 3.

Such multi-level reporting is available only when not splitting by date. Splitting by date is meant to be used in timeline reports, and creating such a hierarchy for each date would result in a huge data set which would only have limited use. When date splitting is used, segmentation with 1 level is still allowed, however. This allows creating timeline reports where each line represents a property value, such as comparing usage trend for version 1 vs version 2.

Segmentation is optional. In order not to split data by any property, you may either not include a levels property in the request object, or else leave the levels object empty. The following examples show the difference between not requesting any segmentation, requesting a single level, and requesting 2 levels:

Segmentation and Levels

Number of Levels

Description

0 Levels

New Users: 30
Active Users: 100
Lost Users: 20

1 Level

Product Versions: 

Version 1:
New Users: 10
Active Users: 30
Lost Users: 8
Version 2:
New Users: 20
Active Users: 70
Lost Users: 12

2 Levels

Product Versions: 

Version 1:
New Users: 10
Active Users: 30
Lost Users: 8

Product Editions: 

Premium:
New Users: 4
Active Users: 13
Lost Users: 1
Standard:
New Users: 6
Active Users: 17
Lost Users: 7

Product Versions: 

Version 2:
New Users: 20
Active Users: 70
Lost Users: 12

Product Editions: 

Premium:
New Users: 5
Active Users: 40
Lost Users: 4
Standard:
New Users: 15
Active Users: 30
Lost Users: 8

In the above examples, the first example, 0 Levels, is showing a case where no segmentation is being applied.

The second example, 1 Level, is showing a response where a single level of segmentation has been requested. In this case, segmentation is being done based on product versions. For each product version, one can see the number of new, active, and lost users within the specified date range. Segmenting by 1 level is also possible in reports that use date splitting, so, in a similar example, one would be able to see how many users were using a specific version on each day within the date range.

The third example, 2 Levels, shows 2 levels of segmentation. In this example, one can see how many new, active, and lost users were using each version, and then, that data is further split by product edition. A further level is also allowed, so, for example one may choose to segment each product edition by product language.

The properties that are available for segmentation are the same ones that are used for Global Filters. There are 4 properties that require special formatting. These are described below.

Segment levels are to be defined in a property inside the main JSON object named “levels”. This property should contain a JSON object which contains the following members:

property (string)—The name of the property by which to segment. Note that in case of os, geography, licenseStatus and gpu, a special format is used.
segments (array)—An array containing a number of JSON objects. The format of these object is described in the Level Segments Format section below.
sort (string)—Optional property to specify how the segments in this level are to be sorted. Possible values are alpha, new, active, and lost. alpha refers to alphabetical sorting which is based on the segment label. The other 3 are based on the client statuses. Note that if sorting by new, active, or lost users, that particular client status must be included in the clientStatus array. If this property is not included, the data is sorted alphabetically by default.
sortDirection (string)—Optional property to specify whether to sort in ascending or descending order. Possible values are asc and desc. If not specified, data is sorted in ascending order by default.

For more information, see:

Level Segments Format
String-Based Segmentation Properties
Numeric Segmentation Properties
Boolean Segmentation Properties
Special Segmentation Properties
<NULL> Values in Segmentation and Levels (Date-Range Reports)