Apart from the default properties that are included in every Revulytics Usage Intelligence subscription such as Product Version, Country, amount of RAM, etc., Usage Intelligence also offers the possibility of tracking extra custom properties that are related to your software or the environment that it runs on. To offer maximum flexibility, these custom properties are offered in 3 types - depending on the type of data that you need to collect and how you plan to use it in your reporting.
Most of the default properties available out of the box are of Type 1 and 2, with the exception of "License Keys" which is of Type 3. Refer to this KBase article to learn how this affects report filtering and segmentation.
Note that Custom Properties must be enabled on your account before you can use them. Contact support with the following details for each property you would like enabled:
- Name - The dashboard label that you want to use for this property.
- Index - The index of the custom property. Most products include 5 custom properties so this would be a value from 1 to 5 and which is used to set the value of the custom property from the Usage Intelligence SDK.
- Type - Type 1, 2, or 3 as detailed below.
Custom Property of Type 1
These are the most commonly-used custom properties. Type 1 custom properties are kept on a daily basis along with other user details such as product version, OS version, etc. This means that if they are used as filters in timeline reports, a user will be displayed in the report only on those days in which the value of this property matches the filter being requested. Therefore, these custom properties should be used in cases where their value is prone to change along the user's lifetime and you are interested in such value at any given time. However, these types of properties should only be used for data which is common between a number of users and where the number of unique string values stored in this property (across your entire install base) is not planned to exceed 2000. For example, if you are tracking the latest version of Active-X installed on the user machine, then you may safely store the value in a Type 1 custom property. However, if you are trying to track a unique value such as the serial number of the GPU or a unique username, then Type 1 and Type 2 should not be used and instead you should revert to using Type 3.
Custom Property of Type 2
These custom properties are similar to Type 1 in the sense that they are designed to collect string values which are common between users and where the total number of unique values collected across your install base is not planned to exceed 2000 values. The difference however is that in Type 2, only the last known value is kept. Therefore, if you are generating a timeline and you filter for a specific value, if a user matches that value at the moment, it would be included in that timeline even if that user's custom value never matched the requested value at any point within the requested date range. Therefore, Type 2 should not be used in cases where the value is prone to change and you are interested in such changes. However, it is useful for cases where the value rarely changes and even if it does, knowing the current user's value would be enough.
Custom Property of Type 3
These custom properties are meant for tracking unique data. Similarly to Type 2, they are meant for values that rarely or never change because only the last known value is stored in the system. However, Type 3 custom properties are meant to be used for values that are normally unique or almost unique to each particular user such as user IDs, usernames, serial numbers, etc.
The number of unique values that can be stored in Type 3 custom properties is virtually unlimited so they can grow into the millions. This implies that they have some UI and usability limitations when compared to Type 1 or Type 2 properties. For example you will not be able to retrieve a full list of unique values in a single metadata request. Another limitation is that you cannot generate Top X reports for these properties or segment reports by Type 3 property values whilst using wildcards, since this may generate millions of series that cannot be plotted on a chart. Therefore in most cases when working with Type 3 properties you must specify the string/s you are searching/filtering for before generating the report, rather than requesting a "show me all values" report. When using the Web reporting API, Type 3 custom properties have some limitations when using regular expressions. If you are an advanced user of the Usage Intelligence Reporting API, you can request more detailed info from our support.
Using Custom Properties within the Reporting Dashboard
For details on how custom properties can be used for filtering and segmentation, please refer to this KBase article.