Developer Zone

Advanced Event Tracking Reports

These reports are meant to provide more insight about how events are used by your users. For events to be available in these reports, they must be selected as advanced events in the events management page.

Event Usage Frequency Report

This report provides a detailed view into how users are using your tracked events. It is available only for events tracked as advanced. This report contains data about how many users used each event, many times each event occurred in total, how many times each user performed each event on average, etc. It also returns a histogram for each event showing the distribution of how many times each user performed each event.

Request/response parameters summary

POST /reporting/eventTracking/advanced/fullReport

The request and reponse are both JSON objects. The following is a summary of the properties inside the request and response objects.

Request JSON Object:
 
  • user (string) – The username of your Usage Intelligence user account. Required only for non-cookie authentication.
  • sessionId (string) – The sessionId obtained via POST /auth/login. Required only for non-cookie authentication.
  • productId (integer) – The product ID on which this request is being done.
  • startDate (string) – The first date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • stopDate (string) – The last date of the date range on which to base the report. This is to be formatted as YYYY-MM-DD.
  • globalFilters (object) – JSON object containing the filters to be applied to the available data. Details about these filters can be found in the Global Filters section.
  • segmentBy (string) – The field with which to segment the data. Details about segmentation can be found in the Data Segmentation section.
  • segments (array) – Optional JSON array that describes how data is to be split into segments. Refer to the Data Segmentation section.
  • sort (string) – Optional property to specify how the segments are to be sorted. Possible values are alpha or eventCounts. 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.
  • events (array) – Array of objects specifying which events or combination of events to base the report on. Please refer to the events Property section.
Response JSON Object:
 
  • status (string) – Contains OK if successful or SYNTAX ERROR or AUTH ERROR
  • reason (string) – Present only if status is not OK. Contains error message (reason)
  • results (object) – Contains the results as requested represented as a JSON object. The result format is described below.

Global Filters

Most of the available filter properties are string-based. This means that when applying a filter, the requested field can be represented as a string, stringArray or regex. There are also some filters which are numeric. These filters should be represented as number or numberRange.

String-based filters

The following properties are stored as strings:

  • machineId *
  • clientId *
  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • licenseType
  • formFactor *
  • osLanguage
  • osWordLength *
  • cpuType *
  • dotNetVersion *
  • javaVersion *
  • javaVendor *
  • javaRuntime *
  • javaGraphics *
  • javaVmVersion *
  • javaVmName *
  • vm *
  • C01 .. C20 (Custom properties)
  • licenseKey * **

The type field in the above filters needs to be string, stringArray or regex. A value field is always required. The contents of this field should be according to the specified type. If string is specified, then the value field must contain a single string that needs to be matched precisely with the stored data. If stringArray is specified, then the value field must contain an array of strings where one of which needs to match precisely with the stored data. If specifying a regex, the value field should contain a string which is treated as a regular expression and the stored data will be matched against it using regular expression rules.

* These marked properties are based on the current (latest known) values.
** licenseKey requires a special user permission to filter by license key.

Example filter using a string value

In this example, the product build value needs to be exactly “3014.int-12214”:

{
      "prodBuild":
          {
              "type": "string",
              "value": "3014.int-12214"
          }
 }

Example filter using a string array

In this example, the product build value needs to be either “3014.int-12214”, “3017.enx-57718”, or “4180.vrx-81059”. Note that since the type is declared as stringArray, the value field needs to contain an array. Consider all elements in the array to have an OR logical expression between them.:

{
    "prodBuild":
        {
            "type": "stringArray",
            "value": ["3014.int-12214", "3017.enx-57718", "4180.vrx-81059"]
        }
}

Example filter using a regular expression

In this example, the product build value needs to start with “30” and end with “18” whilst having 10 characters in between:

{
     "prodBuild":
         {
             "type": "regex",
             "value": "^30.{10}18$"
         }
}

Numeric filters

The following properties are stored as numeric values:

  • cpuCores *
  • displayCount *
  • ram *
  • resolutionWidth *
  • resolutionHeight *
  • lifetimeRuntimeMinutes *
  • lifetimeSessionCount *

* These marked properties are based on the current (latest known) values.

The type field in the above filters needs to be number or numberRange. If number is specified, then a value field must also be present. The value field should contain a number, which may contain a decimal point if required. If numberRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum number to be included in the report. If only one limit needs to be set, the other property is to be left out. Therefore, if you want to include installations with up to 2 display devices, you would not specify a min value, but instead specify only a max and set it as 2.

Example filter using a number value

In this example, the number of display devices needs to be exactly 3:

{
      "displayCount":
          {
              "type": "number",
              "value": 3
          }
 }

Example filter using a number value

In this example, the RAM needs to be between 1025MB and 4096MB (both included):

{
      "ram":
          {
              "type": "numberRange",
              "min": 1024,
              "max": 4096
          }
 }

Date Range filters

The following properties are stored as dates:

  • dateInstalled
  • dateLastSeen

The type field in the above filters needs to be date or dateRange. If date is specified, then a value field must also be present. The value field should contain a date. If dateRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum dates to be included in the report. If only one limit needs to be set, the other property is to be left out. In the following example, users installed after January 1st 2018 are to be shown:

{
    "dateInstalled":
        {
            "min": "2018-01-01"
        }
}

Note that all dates must be in ISO 8601 format.

Special filters

Some filters need to be represented in a special format due to their unique requirements. These special filters are:

Special filter: licenseStatus

The licenseStatus filter is made up of 4 sub-values: activated, blacklisted, expired and whitelisted. These are presented as boolean values. Unlike other filters, this filter is presented as an array of JSON objects. Each object can contain a subset (or all) of these 4 boolean values. Consider the following example. In this example, for a client to be included, the license has to either be activated AND whitelisted, or else it can be not whitelisted AND expired. In other words, ( (activated AND whitelisted) OR ((NOT)whitelisted AND expired) ).

{
    "licenseStatus":
        [
            {
                "activated": true,
                "whitelisted": true
            },
            {
                "whitelisted": false,
                "expired": true
            }
        ]
}
Special filter: os

The os filter is made up of 3 granularity levels. These are platform, version, and edition. These are meant to split the OS name into levels of detail as required by the user. Consider the following:

  • platform: Microsoft Windows
  • version: Microsoft Windows 7
  • edition: Microsoft Windows 7 Professional

If a filter is set on the version “Microsoft Windows 7”, the result would include all editions of Windows 7. One or more of these granularity levels may be specified. If more than 1 granularity level is specified, the values are ORed together.

In the following example, all editions of “Microsoft Windows 7” are included, and also “Microsoft Windows Vista Home Premium”:

{
    "type": "string",
    "version": "Microsoft Windows 7",
    "edition": "Microsoft Windows Vista Home Premium"
}

In the following example, the type is stringArray. Note that an array needs to be passed if the type is set as such, even if it is to contain only 1 element. In this case, the version can be either “Microsoft Windows 7” or “Microsoft Windows 8” (which are ORed together). Also, clients running on “Microsoft Windows XP Professional” are to be included.

{
    "type": "stringArray",
    "version": ["Microsoft Windows 7", "Microsoft Windows 8"],
    "edition": ["Microsoft Windows XP Professional"]
}
Special filter: geography

The geography filter is made up of 3 granularity levels. These are continent, country, and usState. The usState value applies only to United States. Continents and countries are presented in 2-letter codes. Countries follow ISO standard 3166-1 alpha-2. US states are presented in ISO 3166-2:US format.

In the following example, the clients have to be either:

  • In the continents Asia or Oceania
  • In the country Germany
  • In the US states New York, New Jersey, or Kansas
{
    "type": "stringArray",
    "continent": ["AS", "OC"],
    "country": ["DE"],
    "usState": ["US-NY", "US-NJ", "US-KS"]
}

IMPORTANT: In this filter, the type can be string or stringArray. Regular expressions are not supported in geography filters.

Special filter: gpu

The gpu filter is made up of 2 granularity levels. These are vendor and model. Both are represented as string values.

In the following example, the clients have to have a GPU:

  • From the vendors NVIDIA or Intel
  • With the model AMD Radeon HD 4600
{
    "type": "stringArray",
    "vendor": ["NVIDIA", "Intel"],
    "model": ["AMD Radeon HD 4600"]
}
Special filters: optOut and backOff

The opt-out mechanism was introduced in SDK version 5.1.0. With this feature, vendors can have their application report to the Revulytics servers that a user does not want to be tracked. Using this property, vendors can filter out installations that were opted-out. Similarly, backoff filtering was introduced with version 5.0.0. Backoff is when a product account runs over-quota and the server starts rejecting data. Although filtering for backed-off installations was introduced with version 5, it was also backported to previous versions. However, when a new installation with an SDK prior to version 5 tries to register with the server and is rejected, it is not marked as being once backed-off when it is eventually accepted by the server. With version 5 onwards, the server flags an installation as being historically backed-off in such cases.

Both backOff and optOut filters are made up of 2 boolean sub-values: historical and current. The historical value refers to installations that were once backed-off or opted-out. These may include installations that are still currently backed-off or opted-out. The current value refers to the status during the last time that the client called the server. Therefore, if an installation was opted-out yesterday but got opted-in today, it will be marked as historically opted-out but not currently opted-out.

In the following example, for a client to be included, the optOut status has to either be historical AND not current, or else it can be not historical (i.e. users have to be currently opted-in but used to be opted-out at some point or never opted out).

{
    "optOut":
        [
            {
                "historical": true,
                "current": false
            },
            {
                "historical": false
            }
        ]
}
Special filter: lifetimeEventUsage

Using lifetime event usage filters, clients can be filtered based on whether a particular event or set of events occurred or not within the client’s lifetime. Alternatively, one can set a filter based on the number of times an event has occurred.

In the following example, clients that are included must have done the “File Operations - Open” event at least 5 times to be counted.

{
     "category": "File Operations",
     "name": "Open",
     "min": 5
}

In the following example, clients must have done either “File Operations - Open” or “File Operations - Save” for a combined total of between 10 to 50 times.

{
    "combiArray": [
                     {
                       "categoryType": "string",
                       "nameType": "string",
                       "category": "File Operations",
                       "name": "Open"
                     },
                     {
                       "categoryType": "string",
                       "nameType": "string",
                       "category": "File Operations",
                       "name": "Save",
                     }
                  ],
    "min": 10,
    "max": 50
}

In the following example, clients must have done any event within the “File Operations” category for a combined total of not more than 100 times. This is done using a regular expression in the name.

{
    "combiArray":  [
                      {
                        "categoryType": "string",
                        "nameType": "regex",
                        "category": "File Operations",
                        "name": ".*"
                      }
                   ],
    "max": 100
}
Special filter: reachOutDeliveries

Using ReachOut delivery filters, clients can be filtered based on whether a particular ReachOut message or a combination of ReachOut messages were delivered or not within the client’s lifetime.

The filter consists of a JSON array that includes one or more objects. Each object is a combination of delivered and undelivered campaigns, and the different combinations are ORed together. Therefore, it is possible to show users that either received ReachOut message 1 but not 2, or else received 3 but not 4 as in the following example:

In the following example, we are looking for clients who either received campaign 1 but not 2, OR received campaign 2 but not 3.

[
     {"auto": {"delivered": ["1"], "undelivered":["2"]}},
     {"auto": {"delivered": ["2"], "undelivered":["3"]}}
]

The above example contains only “auto” ReachOut campaigns. Manual campaigns can be specified using “manual” instead of “auto” as in the above example. Each object can contain a mix of “auto” and “manual” campaigns.

<NULL> values

Most of the available properties can include null values. There are different reasons why a value would be null. When these are properties that are set by the application, the possible reasons why a value would be null are cases where the value has not been set by the application (such as prodBuild never being set), and cases where values are set to an empty string (“”) or to a string containing “<NULL>”. One other reason is that although these values have been set, the SDK has not yet had time to sync with the servers to provide this new information. In cases where the properties are set automatically such as hardware or OS related information, the values would be null if the SDK failed to retrieve that value from the OS or if the server failed to identify the value retrieved by the SDK. Other reasons include cases where Java version is requested from an application that does not use the Java SDK, US state is requested for users who are not running within the US, etc.

The following are the properties that support null values:
  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • machineId
  • formFactor
  • vm
  • cpuType
  • cpuCores
  • ram
  • resolutionWidth
  • resolutionHeight
  • javaVersion
  • javaVmVersion
  • javaVmName
  • javaVendor
  • javaRuntime
  • javaGraphics
  • osLanguage
  • licenseKey
  • C01 .. C20 (Custom properties)
  • os
  • geography
  • gpu

Null values can be requested either on their own or as part of a filter containing other values.

The following example would return only cases where the prodVersion is null:

{
      "prodVersion":
          {
              "includeNull": true
          }
}

The following example would return cases where the prodVersion is either 1.1, 1.2 or null:

{
      "prodVersion":
          {
              "type": "stringArray",
              "value": ["1.1", "1.2"],
              "includeNull": true
          }
}

By default, when specifying a filter, null values would not be included. Therefore, in the following example, only clients with prodVersion set to 1.1 or 1.2 will be included, while null values are excluded:

{
      "prodVersion":
          {
              "type": "stringArray",
              "value": ["1.1", "1.2"]
          }
}

However, if no filter is specified, then nulls are included by default. Therefore, if you want to include any value of prodVersion as long as it is not null, a prodVersion filter needs to be included as follows:

{
      "prodVersion":
          {
              "type": "regex",
              "value": ".*",
              "includeNull": false
          }
}

In the case of filters that use sub-properties (os, geography, and gpu), the includeNull filter is to be included in the sub-property and applies to that specific sub-property only. In order to be able to include the includeNull property, instead of providing the value as a string or an array of strings, the value of the sub-property must be a JSON object that cointains a property named “value”, and another named “includeNull”. Each of these properties is optional, but at least one of them must be present.

In the case of geography, this has a very particular meaning. Requesting for null “country” value does not return all cases where the country could not be retrieved, but only cases where the continent could be retrieved but the country could not. Similarly, requesting null “usState” returns cases where the continent and country could be retrieved but the US state could not. This does not include clients that are not situated in the US. If you are interested in finding clients where we could not detect any geographical data, the includeNull filter needs to be applied in the continent sub-property.

In the following example, we are requesting cases where we know that the client is within the US but the state could not be identified:

{
      "geography":
          {
              "type": "string",
              "country": "US",
              "usState":
                  {
                      "includeNull": true
                  }
          }
}

In the following example, we are requesting cases where the GPU is either “NVIDIA”, “AMD” or null (unidentified):

{
      "gpu":
          {
              "type": "stringArray",
              "vendor":
                  {
                      "value": ["NVIDIA", "AMD"],
                      "includeNull": true
                  }
          }
}

Data Segmentation

Optionally, data may be segmented by 1 level. When using segmentation, events data is split based on the segment property requested. In order to select a segmentation property, specify any metadata property in the segmentBy field. The way segments are to be generated must be specified in the segments field. The segments field should contain a JSON array containing objects with the following properties:

  • type (string) - The data type of the value. Can be string, stringArray, regex, number or numberRange based on whether the property is string-based or numeric.
  • value (string/array/number) - An exact string, an array of strings, a regular expression or a numeric value. This property should not be used if type is numberRange. Format is based on whether the property is string-based or numeric.
  • min (number) - Used only if the type is numberRange. Contains the minimum numeric value to include in this segment. May be combined with max.
  • max (number) - Used only if the type is numberRange. Contains the maximum numeric value to include in this segment. May be combined with min.
  • split (boolean) - Used only if the type is stringArray or regex. This specifies whether to split the returned data based on each different value matched by the regular expression or array (true), or to join all the clients that match the value as 1 table value or series (false).
  • segmentLabel (string) - Used only if split is false or if type is numberRange. This is required to give a name to a series when not splitting by value. It is important that the name given is unique.
  • limit (integer) - Optional property to set the limit on the maximum number of table values or serieses that should be produced by this set of values. To be used only if split is true.

String-based segmentation properties

The following properties are stored as strings:

  • machineId *
  • clientId *
  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • licenseType
  • formFactor *
  • osLanguage
  • osWordLength *
  • cpuType *
  • javaVersion *
  • javaVendor *
  • javaRuntime *
  • javaGraphics *
  • javaVmVersion *
  • javaVmName *
  • vm
  • C01 .. C20 (Custom properties)
  • licenseKey * **
* These marked properties are based on the current (latest known) values.
** licenseKey requires a special user permission to be used for segmentation.

The type field when using one of the above properties needs to be string, stringArray or regex. A value field is always required. The contents of this field should be according to the specified type. If string is specified, then the value field must contain a single string that needs to be matched precisely with the stored data. If stringArray is specified, then the value field must contain an array of strings where one of which needs to match precisely with the stored data. If specifying a regex, the value field should contain a string which is treated as a regular expression and the stored data will be matched against it using regular expression rules.

Example using segmentation by string, stringArray, and regex values

{
    "segmentBy": "prodVersion",
    "segments": [
        {
            "type": "string",
            "value": "1.0"
        },
        {
            "type": "stringArray",
            "value": ["2.0", "2.1", "3.1"],
            "split": false,
            "segmentLabel": "Versions 2 and 3"
        },
        {
            "type": "regex",
            "value": "^4\..*",
            "split": false,
            "segmentLabel": "All version 4"
        },
        {
            "type": "regex",
            "value": "^5\..*",
            "split": true
        }
    ]
}

In the above example, we are requesting a report with multiple segments. The first segment contains installations running version 1.0. Notice how this does not require a “split” property since there is only 1 value and therefore no further splitting is possible. The second segment contains versions 2.0, 2.1 and 3.1. In this case, the “split” property is required, and since we are requesting the API to combine these 3 versions, we must provide a “segmentLabel” value so that the returned data can be identified. The third segment is similar, although in this case the request is built using a regular expression. In this case, all versions starting with “4.” are to be included into one combined segment.

The last segment is different from the rest because we are requesting the API to split the data (split is set to true). Therefore, this can produce much more than 1 segment. In this case, we could see segments such as “5.1”, “5.2”, etc. Notice how since we are splitting, we should not provide a segmentLabel value since the labels are built using the different values that are found in the data.

Numeric segmentation properties

The following properties are stored as numeric values:

  • cpuCores
  • displayCount
  • ram
  • resolutionWidth
  • resolutionHeight

The type field in the above properties needs to be number or numberRange. If number is specified, then a value field must also be present. The value field should contain a number, which may contain a decimal point if required. If numberRange is specified, then the value field should NOT be used. Instead, the properties min and max are to be used. These refer to the minimum and maximum number to be included in the report. If only one limit needs to be set, the other property is to be left out. Therefore, if you want to include installations with up to 2 display devices, you would not specify a min value, but instead specify only a max and set it as 2.

Example using segmentation by number, and numberRange values

{
    "segmentBy": "cpuCores",
    "segments": [
        {
            "type": "number",
            "value": 1,
        },
        {
            "type": "numberRange",
            "min": 2,
            "max": 4,
            "segmentLabel": "2 - 4"
        },
        {
            "type": "numberRange",
            "min": 5,
            "segmentLabel": "5 +"
        }
    ]
}

In the above example, we are requesting a report with 3 segments. The first segment contains only installations running on 1 CPU core, the second segments contains installations running on 2, 3, or 4 cores (range 2 - 4), while the last segment contains all installations which are running on a machine with 5 or more CPU cores. Note how when the type was numberRange, we had do specify a segmentLabel which is a free string that will be used by the user to identify what is being included in that specific segment.

Special segmentation properties

Some properties need to be represented in a special format due to their unique requirements. These special properties are:

Special segmentation format: licenseStatus

The licenseStatus value is made up of 4 sub-values: activated, blacklisted, expired and whitelisted. These are presented as boolean values. Any number of segments can be defined, and each segment can contain any subset of the 4 sub-values. These values are ANDed together. A segmentLabel value is required.

In the following example, 2 segments are specified - the first one showing blacklisted AND not expired and the second one showing whitelisted AND activated:

[
    {
        "segmentLabel": "BL and not EXP",
        "blacklisted": true,
        "expired": false
    },
    {
        "segmentLabel": "WL and ACT",
        "whitelisted": true,
        "expired": true
    }
]
Special segmentation format: os

The os value is made up of 3 granularity levels - platform, version, and edition. A particular level needs to be selected, and this is to be included in the property name such as os.version or os.edition. For a description of the differences between the 3 granularity levels, refer to the os special filter section.

The following example requests data segmented by all OS versions:

{
    "segmentBy": "os.version",
    "segments": [
        {
            "type": "regex",
            "value": ".*",
            "split": true
        }
    ]

}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in all OS versions to be returned.

Special segmentation format: geography

The geography value is made up of 3 granularity levels - continent, country, and usState. These granularity levels are explained in the geography special filter section. A particular level needs to be selected, and this is to be included in the property name such as geography.continent or geography.country.

The following example requests data segmented by all country:

{
    "segmentBy": "geography.country",
    "segments": [
        {
            "type": "regex",
            "value": ".*",
            "split": true
        }
    ]
}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in all countries to be returned.

Special segmentation format: gpu

The gpu value is made up of 2 granularity levels - vendor and model. These granularity levels are explained in the gpu special filter section. A particular level needs to be selected, and this is to be included in the property name, namely gpu.vendor or gpu.model.

The following example requests data segmented by all GPU vendor:

{
    "segmentBy": "gpu.vendor",
    "segments": [
        {
            "type": "regex",
            "value": ".*",
            "split": true
        }
    ]

}

In the above example, no filtering is being done, and instead, a regular expression to include everything is set as the value. This will result in all the GPU vendors to be returned.

Special segmentation format: optOut and backOff

Both backOff and optOut values are made up of 2 boolean sub-values: historical and current. Any number of segments can be defined, and each segment can contain any subset of the 2 sub-values. These values are ANDed together. A segmentLabel value is required.

In the following example, 2 segments are specified - the first one showing historical AND not current and the second one showing not historical (i.e. never opted-out):

[
    {
        "segmentLabel": "HISTORICAL and not CURRENT",
        "historical": true,
        "current": false
    },
    {
        "segmentLabel": "Never opted-out",
        "historical": false
    }
]

<NULL> values

Null values in segmentation are to be requested in a similar way to null values in filters. The same properties that support null in filtering also support null in segmentation.

By default, when segmenting, null values are not included within the segments, since only the values that have been specified in each segment are included. Null values don’t match any regular expression, so the only way to request null values to be included is to specify “includeNull” as true in a similar way to filtering. In segmentation, null values are returned as “<NULL>”. The API considers all cases where the data has never been set from the SDK, set as an empty string, or set as a string containing “<NULL>” to be the same.

The following example requests all values of prodBuild including null:

{
    "level1": {
        "property": "prodBuild",
        "segments": [
            {
                "type": "regex",
                "value": ".*",
                "includeNull": true
            }
        ]
    }
}

In the case of segmentation properties that use sub-properties (os, geography, and gpu), the includeNull value is to be included in the sub-property and applies to that specific sub-property only. In order to be able to include the includeNull property, instead of providing the value as a string or an array of strings, the value of the sub-property must be a JSON object that cointains a property named “value”, and another named “includeNull”. Each of these properties is optional, but at least one of them must be present. The same rules that apply for filtering these types of properties for null values also apply to segmentation.

In the following example, we are requesting segmentation by continent and are also requesting the number of clients where we could not detect the geographical location:

{
    "level1": {
        "property": "geography",
        "segments": [
            {
                "type": "regex",
                "continent": {
                                 "value": ".*",
                                 "includeNull": true
                             }
            }
        ]
    }
}

events Property

This property should be formatted as an array of objects. In each object, one must specify either a single event or a combination of events.

To specify a single event, the inner object should look like the following example:

{
     "category": "File Operations",
     "name":"Open"
}

To specify a combination of events, the inner object should look like the following:

{
     "combiLabel":  "Open and Save",
     "combiArray":  [
                       {
                         "categoryType": "string",
                         "nameType": "string",
                         "category": "File Operations",
                         "name": "Open"
                       },
                       {
                         "categoryType": "string",
                         "nameType": "string",
                         "category": "File Operations",
                         "name": "Save",
                       }
                    ]
}

In the above example, we are combining the data from the Open and Save events, both under the File Operations category. In this example, “string” is being used both as categoryType and nameType. The other possible value is “regex”. The following example shows a case where all events under the File Operations category are being combined:

{
     "combiLabel":  "All File Operations",
     "combiArray":  [
                       {
                         "categoryType": "string",
                         "nameType": "regex",
                         "category": "File Operations",
                         "name": ".*"
                       }
                    ]
}

The combiLabel property should contain any user-friendly unique string value to identify each events combination.

Results format

If segmentation is not being used, the results are presented in an array of objects. Each object inside the array represents an event or a combination of events as requested. If segmentation is used, the data is presented as a JSON object. This object would contain an element for each segment, where the key would be the segment name, and the value would be an array containing event data as described above.

The inner objects inside the array/s contain the following elements:

  • eventCounts - The total number of recorded occurrences of this event
  • averageEventCountPerSessionUsedAtLeastOnce - The average number of event occurrences per runtime session from installations which performed this event at least once within the specified date range
  • averageEventCountPerSessionAll - The average number of event occurrences per runtime session from all installations (including installations who did not perform this event)
  • averageEventCountPerUserAtLeastOnce - The average number of event occurrences per installations which performed this event at least once within the specified date range
  • averageEventCountPerUserAll - The average number of event occurrences per installation (including installations who did not perform this event)
  • uniqueUsersUsedAtLeastOnce - The number of unique installations/users who used this event at least once within the specified date range
  • uniqueUsersNeverUsed - The number of unique installations/users who never used this event within the specified date range
  • usageFrequency - Histogram data showing the number of times the event occurred by how many users.

In the example below, no segmentation is being used. As described above, when segmentation is used, the results are presented in an object which contains an element for each segment having an array in the same format as below as the value.

Example request:

POST /reporting/eventTracking/advanced/fullReport  HTTP/1.1
Host: api.revulytics.com
Content-Type: application/json
Accept: application/json

{
    "user": "testuser@test.com",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "startDate": "2018-10-01",
    "stopDate": "2018-12-31",
    "events": [
                  {
                      "category": "File Operations",
                      "name":"Open"
                  },
                  {
                      "category": "File Operations",
                      "name":"Save"
                  }
              ]
}

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "OK",
    "segmentBy": null,
    "results": {
            "detailedReport": [{
                    "category": "File Operations",
                    "name": "Save",
                    "data": {
                            "eventCounts": 81223,
                            "averageEventCountPerSessionUsedAtLeastOnce": 0.35,
                            "averageEventCountPerSessionAll": 0.28,
                            "averageEventCountPerUserAtLeastOnce": 27.46,
                            "averageEventCountPerUserAll": 22.85,
                            "uniqueUsersUsedAtLeastOnce": 2958,
                            "uniqueUsersNeverUsed": 596,
                            "usageFrequency": {
                                    "1 - 5": 314,
                                    "6 - 10": 352,
                                    "11 - 15": 334,
                                    "16 - 20": 315,
                                    "21 - 25": 292,
                                    "26 - 30": 316,
                                    "31 - 35": 257,
                                    "36 - 40": 214,
                                    "41 - 45": 142,
                                    "46 - 50": 116,
                                    "51 - 60": 98,
                                    "61 - 70": 51,
                                    "\u2265 71": 157
                            }
                    }
            }, {
                    "category": "File Operations",
                    "name": "Open",
                    "data": {
                            "eventCounts": 211161,
                            "averageEventCountPerSessionUsedAtLeastOnce": 0.73,
                            "averageEventCountPerSessionAll": 0.73,
                            "averageEventCountPerUserAtLeastOnce": 59.7,
                            "averageEventCountPerUserAll": 59.42,
                            "uniqueUsersUsedAtLeastOnce": 3537,
                            "uniqueUsersNeverUsed": 17,
                            "usageFrequency": {
                                    "1 - 5": 192,
                                    "6 - 10": 232,
                                    "11 - 15": 211,
                                    "16 - 20": 221,
                                    "21 - 25": 210,
                                    "26 - 30": 177,
                                    "31 - 35": 178,
                                    "36 - 40": 169,
                                    "41 - 45": 153,
                                    "46 - 50": 120,
                                    "51 - 60": 252,
                                    "61 - 70": 211,
                                    "71 - 80": 173,
                                    "81 - 90": 184,
                                    "91 - 100": 156,
                                    "101 - 110": 135,
                                    "111 - 120": 107,
                                    "121 - 130": 94,
                                    "131 - 140": 69,
                                    "141 - 150": 79,
                                    "\u2265 151": 214
                            }
                    }
            }]
    }
}