What type of data can I store in Custom Properties?
Apart from the default properties that are included in every 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 that 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 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 as a request may generate millions of series that cannot be plotted on a chart. The limitations include:
- You cannot retrieve a full list of unique values in a single metadata request
- Once the number of values stored in a Type 3 property exceeds 100, a filter which narrows down the number of values to be returned is required to:
- Generate a Top X report
- Generate a report with regex/wildcard segments
This means that in most cases rather than requesting a "show me all values" report, you must filter the report by the same Type 3 property or any other property which reduces the dataset.
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.