Developer Zone

Runtime Activity Reports for Lost Installations

These reports provide histograms based on the total lifetime runtime hours, total number of sessions, or total lifetime (in days) of lost users.

Request/response parameters summary

Histograms can be requested for number of sessions before a user is lost, number of runtime hours, or number of days. This is selectable by requesting one of the 3 URLs listed below.

POST /reporting/churn/histogram/sessions
POST /reporting/churn/histogram/runtime
POST /reporting/churn/histogram/days
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.
  • daysUntilDeclaredLost (integer) – This specifies the number of consecutive days of inactivity that have to pass until a client installation is declared lost.
  • dateReportedLost (string) – When an installation is lost, it can either be shown as lost on the date it last contacted the Revulytics servers (dateLastSeen) or else it can be shown as lost when it was declared lost (last date when it contacted Revulytics + the number of days specified in daysUntilDeclaredLost) (dateDeclaredLost). Therefore, the permitted values are dateLastSeen and dateDeclaredLost.
  • 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.
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

These filters are common between both reports documented above. 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.

The data used for the filters in these reports is the latest-known data, or data when lost. Therefore, if a user started using version 1 and then switched to version 2 before getting lost, that user will show up if filtering for version 2 and not for version 1.

String-based filters

The following properties are stored as strings:

  • prodVersion
  • prodEdition
  • prodBuild
  • prodLanguage
  • licenseType
  • formFactor
  • osLanguage
  • osWordLength
  • cpuType
  • dotNetVersion
  • 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.

** 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 “”:

              "type": "string",
              "value": ""

Example filter using a string array

In this example, the product build value needs to be either “”, “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.:

            "type": "stringArray",
            "value": ["", "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:

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

Numeric filters

The following properties are stored as numeric values:

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

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:

              "type": "number",
              "value": 3

Example filter using a number value

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

              "type": "numberRange",
              "min": 1024,
              "max": 4096

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) ).

                "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 have a GPU:

  • From the vendors NVIDIA or Intel
  • With the model number AMD Radeon HD 4600
    "type": "stringArray",
    "vendor": ["NVIDIA", "Intel"],
    "model": ["AMD Radeon HD 4600"]

Special filters: optOut and backOff

The opt-out 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. With this feature, 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.

                "historical": true,
                "current": false
                "historical": false

Results format

The results are formatted in a JSON object which contains an element for each histogram bin. Each of these elements contains a numeric value which represents the number of installations which fall under this bin.

Example request:

POST /reporting/churn/histogram/runtime  HTTP/1.1
Content-Type: application/json
Accept: application/json

    "user": "",
    "sessionId": "VSB8E2BzSC2eZSJm4QmTpA",
    "productId": 12345678901,
    "startDate": "2015-10-01",
    "stopDate": "2015-12-31",
    "daysUntilDeclaredLost": 30,
    "globalFilters": {}

Example response:

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

    "status": "OK",
    "results": {
            "\u2264 0:50": 90,
            "0:51 - 1:00": 2,
            "1:01 - 1:15": 53,
            "1:16 - 1:30": 11,
            "1:31 - 1:45": 51,
            "1:46 - 2:00": 52,
            "2:01 - 2:15": 12,
            "2:16 - 2:30": 41,
            "2:31 - 2:44": 9,
            "2:45 - 3:00": 35,
            "3:01 - 3:30": 49,
            "3:31 - 4:00": 69,
            "4:01 - 4:30": 40,
            "4:31 - 5:00": 35,
            "5:01 - 5:30": 28,
            "5:31 - 6:00": 42,
            "6:01 - 6:30": 26,
            "6:31 - 7:00": 28,
            "7:01 - 7:30": 21,
            "7:31 - 8:00": 28,
            "8:01 - 8:30": 20,
            "8:31 - 9:00": 14,
            "9:01 - 9:30": 20,
            "9:31 - 10:00": 19,
            "10:01 - 10:30": 9,
            "10:31 - 11:00": 19,
            "11:01 - 11:30": 13,
            "11:31 - 12:00": 16,
            "12:01 - 13:00": 23,
            "13:01 - 14:00": 27,
            "14:01 - 15:00": 19,
            "15:01 - 16:00": 17,
            "16:01 - 17:00": 11,
            "17:01 - 18:00": 14,
            "18:01 - 21:00": 36,
            "21:01 - 24:00": 37,
            "24:01 - 27:00": 30,
            "27:01 - 30:00": 28,
            "30:01 - 33:00": 40,
            "33:01 - 36:00": 33,
            "36:01 - 39:00": 16,
            "\u2265 39:01": 69

The above example, since the report is based on runtime, the bins are titled using hours:minutes format. If requesting a sessions or days report, these bins would be numeric.