In the last article of this 3 part series, we will look at the license key management capabilities offered by Usage Intelligence. In addition to Software Analytics, Usage Intelligence provides a License Key Usage Tracking and Piracy Monitoring Service. This functionality is embedded as part of the Analytics SDK and allows you to validate keys on the client, track which license keys are in use as well as to detect and report abused keys. Please check out this blog post for a high-level overview of what is included with this service. SDK Integration - Getting Started with Usage Intelligence - Part 1 Event Tracking - Getting Started with Usage Intelligence - Part 2 Software License Usage Tracking - Getting Started with Usage Intelligence - Part 3 There are two modes of licensing management available, Client or Server managed (both explained later).  Each mode can be configured from the License Key Registry page as follows: Log in to the Usage Intelligence Dashboard, go to the Administration page, and under Product Settings click on License Key Registry Click on the Settings tab   Select the licensing management mode for each flag and click Save. By default, the licensing management is set to Client Managed. You may choose to have a mix of Client and Server managed for the license flags, for example, you might want to handle activation on the client-side while managing the rest on the server. Read on for more information on the different modes and when to use them. 1. Client Managed In this mode, your application notifies the server when the license status has changed, and the licensing mechanism is used for reporting purposes only. It is generally used when you already have a licensing management system in place that can identify whether a license key is valid, expired, blocked, etc. In the example below, we are notifying Usage Intelligence of a new license status when the user changes the license key in the application by using the SetLicenseData method. Note that the license key is not collected when using this method, but only the status flags are registered for reporting. Open the class where you handle the licensing key change At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Add the following code when the user enters a new key. In this example we are using the Click event of the Save button: private void btnSave_Click(object sender, EventArgs e) { //rui is your RUISDK instance rui.SetLicenseData(keyType: (int)RUILicenseKeyType.purchased, keyExpired: 0, keyActivated: 1, keyBlocked: 0, keyAllowed: 0); //The rest of your code… } The SetLicenseData() function has 5 required parameters: Key Type – A value from the RUILicenseKeyType enum representing the type of key Key Expired – An integer representing whether the license key is expired (1), not expired (0) or unchanged (-1) Key Activated - An integer representing whether the license key is activated (1), not activated (0) or unchanged (-1) Key Blocked – An integer representing whether the license key is blocked (1), not blocked (0) or unchanged (-1) Key Allowed – An integer representing whether the license key is allowed (1), not allowed (0) or unchanged (-1) Any license flags which do not apply to your license model can be set to -1. This function also accepts an optional string parameter for the session ID. In our example, we did not specify this value since our calculator application does not manage sessions itself. Build your solution, run the application, set the license data, and close the application From the Usage Intelligence Product Dashboard go to Product Metrics > Licenses in Use and License Status to view the licensing reports.   2. Server Managed In this mode, license keys are collected/stored on the Revulytics server and you can use the SDK to check the real-time status of a license key from within your application. In this mode, the Usage Intelligence server also keeps a count of the number of installations that are sharing each license key. This will enable you to sync with your CRM or licensing service to detect piracy or license key abuse. This mode is also ideal if you do not have a license key verification system in place already. Uploading keys from your CRM: To use Server Managed licensing you will need to submit your license keys and any information about these keys to the License Key Registry. You can do this by entering/editing license keys manually or through the Web API.  More info on using the Web API can be found in the documentation. You can view or manage the license keys that are available on the server by going to the dashboard, navigating to the Administration page and under Product Settings click on License Key Registry.     Once the license keys are in the registry, you are now ready to register and validate keys from your application. Validating a Key from the Client The following example uses the CheckLicenseKey method to retrieve the license key information from the server. Open the class where you handle the licensing key check At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_6_0 Add the following code when the user enters a new key. In this example we are using the Click event of the Submit button: private void btnSubmit_Click(object sender, EventArgs e) { List<int> licenseResult; //rui is your RUISDK instance RUIResult result = rui.CheckLicenseKey(txtKey.Text, out licenseResult); //The rest of your code… } The CheckLicenseKey() function has 2 required parameters, a string which is the license key you would like to validate, and a List<int> which will be filled with the returned result and will contain the following properties: Key Type – A value from the RUILicenseKeyType enum representing the key type (Evaluation, Purchased, Freeware, etc..) The license key flags with a value of 0 if false, 1 if true, and -1 if unknown: License Expired License Activated License Blocked License Allowed If the key does not exist on the server, all the status flags will be returned with a value of -1 If a status flag is set to Client managed, the returned value for that specific flag will always be -1 Registering a Key from the Client Registering a key is similar to validating a key, however, you need to use the SetLicenseKey method. Open the class where you handle the licensing key change At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Add the following code when the user enters a new key. In this example we are using the Click event of the Save button: private void btnSubmit_Click(object sender, EventArgs e) { List<int> licenseResult; //rui is your RUISDK instance RUIResult result = rui.SetLicenseKey(txtKey.Text, out licenseResult); //The rest of your code… } When a status flag is set to Client Managed, the returned value for that specific flag will always be -1. If the key does not exist on the server, it will return the license type as Unknown while the rest of the status flags will have a value of 0. The key will also be added to the License Key Registry and this makes it easy for you to track illegitimate keys by searching for Auto Collected keys with an Unknown type. To do this go to the Usage Intelligence Product Dashboard, navigate to Manage Product > License Key Registry and click on the Show Advanced Key Search. Once on the License Key Registry page click on the Filters tab, add your filters and click on the Apply Filter button.   This brings the Getting Started series of posts to an end. We recommend you review the full documentation available in the Developer Zone to benefit from the advanced features provided by the Usage Intelligence SDK. If you require any further assistance, contact us at our helpdesk and we would be happy to help! ... View more

String based properties support filtering using a regular expression. The reporting engine uses the Python re library to process regular expressions. For a complete reference, see the re module documentation.   A list of string based properties can be found in the Reporting API documentation.   Useful Links:   Python Regular Expression Howto Python Regular Expression Tester ... View more

There are instances when knowing the number of times that an event occurred is not enough, but you would like to collect further information that is custom to your application. This may include: Collecting configuration settings as specified by the user Recording the state of your application when a specific event occurred Collecting user feedback directly from your product Usage Intelligence gives you the ability to collect such information in the form of Custom Events, where you can collect free-text data, numeric values, or key/value pairs from your application. These events will be included with the events usage statistics reports, and additionally, you will be able to download the custom data in CSV format. In this blog post, we will see how easy it is to collect custom events and how to export and view your custom data. Collecting Custom Events Let’s take an example where we have the following set of application preferences and we want to collect how users are configuring these settings: Start the application automatically when Windows starts Sign in automatically when the application starts Automatically check for updates (including a check for updates frequency)     In the following example, we are using the .NET SDK with C# code. For other platforms visit the corresponding SDK documentation: We will demonstrate the steps to collect the settings as a list delimited by the “|” character. Open the class where you will be collecting the data from At the top of the file make sure you have the using RUISDK_<x_x_x>;  directive Create a string containing the piped list (text delimited by the | character) and log the event using the TrackEventText() function. Here we are logging the event whenever a user clicks the Save button, with "Settings" as the category and "Application Preferences" as the event name. private void btnSave_Click(object sender, EventArgs e) { StringBuilder configData = new StringBuilder(); //Add if auto start when Windows starts is enabled to the string configData.Append("Auto Start: " + chkAutoStart.Checked); //Add if automatic login is enabled to the string configData.Append(" | Auto Login: " + chkAutoLogin.Checked); //Add if check for updates is enabled to string configData.Append(" | Auto Update: " + chkAutoUpdates.Checked); //If check for updates is enabled, add frequency set if (chkAutoUpdates.Checked) configData.Append(" | " + cmbUpdates.GetItemText( cmbUpdates.SelectedItem)); //Log the event //rui is your RUISDK instance rui.TrackEventText("Settings", "Application Preferences", configData.ToString(), null); } Alternatively, you may use the TrackEventCustom() function to collect a set of key/value pairs. The values collected will be automatically formatted as (Key1:Value1)&&(Key2:Value2) by the SDK. More information on how to use this function can be found in the documentation. Build your solution, run the application and execute the relevant events Close the application From the Product Dashboard go to the Administration page and under Product Settings click on Event Tracking Management. If you have Auto-Approve enabled, tracking will already be enabled for ‘Settings – Application Preferences’, otherwise select it and Save settings. There are no specific limitations to the amount of data you can append to the event and you may use any characters and format you require to represent your data. However, if you would like to track string sizes >4KB, you will need to inform support to enable this on your specific product account. NOTES: Custom event tracking is included with the Advanced or Ultimate packages. If you are using a freeware account you may evaluate this functionality by clicking the Start Full Feature Trial button on the Usage Intelligence Dashboard Home page. By default, numeric values collected with TrackEventNumeric() are not included as custom events but can be enabled per product.  Contact support if you wish to enable this functionality for your product. Custom Events in the Product Dashboard Custom event usage statistics are available in the event tracking reports along with the other events you are collecting. These can be viewed from the Usage Intelligence Dashboard by going to Feature & Event Tracking > Event Usage Timeline or Lifetime Event Usage. You will also be able to filter the report by the Event Category that you specified in the API call when recording the custom event – in this case, we named the category “Settings”.   Exporting the RAW Data The custom data included with the events can be viewed and downloaded from the Usage Intelligence Dashboard by going to Feature & Event Tracking > Custom Events.   Recent Events The Recent Events tab shows you the last 30 custom events that have been logged. Clicking on an event will display the full event details with its metadata, including product details, operating system and architecture details, licensing info, and custom properties. This is useful when you’re initially including custom events in your product, so you can browse the latest incoming data for testing purposes.   Downloadable Archives The Downloadable Archives tab provides a list of zip files containing the archived custom events that were collected from your product. Each downloadable archive contains one or more CSV files that contain the custom event data.   The data in the CSV files is sorted by the timestamp according to when the event was submitted to the server, and besides the custom data, each event contains all the metadata related to the client’s installation. This includes all product details, operating system, architecture, and licensing info such as the version, build, license type, OS type, OS language, screen resolution, geolocation, etc. The metadata also includes a Client ID which represents the user installation that generated the event. This is a Usage Intelligence generated ID which is unique to each client installation, and while keeping the user anonymous it gives you the ability to group events by the installation that generated them. The Client ID is common between event tracking and exception tracking and can be cross-referenced to identify all events and exceptions generated by the same user.   Trying Out Custom Event Tracking You can try out custom event tracking for free on any free or premium product account by following the corresponding SDK Documentation for your platform. If you need further information or want to increase the quota or string size for custom events, contact us via our Helpdesk page and our Support guys will be happy to help. If you don’t have an account yet, you may sign up for a freeware account here. Using a freeware account you can collect data from 400 unique active installations and evaluate feature & event tracking with up to 300 unique events. ... View more

In the second article of this 3 part series, we will be using the Usage Analytics event tracking capabilities to log custom data from our calculator application. We will continue to use the simple calculator application and the .NET SDK with C# code examples to demonstrate these steps. SDK Integration - Getting Started with Usage Intelligence - Part 1 Event Tracking - Getting Started with Usage Intelligence - Part 2 Software License Usage Tracking - Getting Started with Usage Intelligence - Part 3 1. Tracking Events In this example, we will be using event tracking to record every time a user uses a particular feature. For our calculator application, we will be logging how many times the addition, subtraction, multiplication, and division features are used. Open the class where you will be adding the event tracking capabilities At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Add the following method which will be called every time you want to track an event:   private void TrackFeatureUsageEvent(string eventName) { //rui is your RUISDK instance rui.TrackEvent("Feature Usage", eventName); } The TrackEvent() method has 2 required string parameters, the category of the event being tracked and the name of the event, and an optional string parameter to specify the session ID. The category is used to group events in the reports and in this example, we have called it “Feature Usage”.   Since our application does not manage sessions itself we have not specified the session ID parameter. We will specify the name of the event when we call this method. Whenever you would like to track a feature usage event, add a call to the method we just created. In our calculator application we have added this in the Click event of the addition, subtraction, multiplication, and division buttons: private void btnPlus_Click(object sender, EventArgs e) { TrackFeatureUsageEvent("Addition"); //The rest of your code… } Build your solution, run the application, execute the events which trigger event tracking, and close the application Log in to your Usage Intelligence account, navigate to the Administration page, and under Product Settings click on Event Tracking Management Enable tracking for each event listed and click Save The next time you run the application and use these features, Usage Intelligence will collect the feature usage data To view your feature usage data, from your Usage Intelligence Product Dashboard go to Feature & Event Tracking > Event Usage Timeline or Lifetime Event Usage     2. Tracking Numeric Values Usage Intelligence gives you the capability to track and report on numeric values associated with events. In this example, we will be tracking the time it takes a user to complete a Configuration Wizard to configure settings for the calculator application. Open the class where you will be adding the event tracking capabilities. In our example, this is the class where we have the code for the Configuration Wizard At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Declare a private variable which will be used to save the time when the wizard was started: DateTime timeOpened; When the wizard starts, set the variable to the current time. We are setting this value in the Load event of the wizard: private void frmConfigWizard_Load(object sender, EventArgs e) { timeOpened = DateTime.Now; //The rest of your code…} Add the following code when the user has finished configuring the settings. In this example we are using the Click event of the Finish button: private void btnFinish_Click(object sender, EventArgs e) { //Calculate time difference in minutes since the wizard //was started double timeTaken = (DateTime.Now - timeOpened).TotalMinutes; //rui is your RUISDK instance rui.TrackEventNumeric("Config Time", "Config Wizard", Math.Round(timeTaken, 2)); } The TrackEventNumeric() method has 3 required parameters, the category of the event being tracked, the name of the event and a double value, and an optional parameter for the session ID. In this example, we have called the category “Config Time” and the event name “Config Wizard”. We specified the value as the total time in minutes (rounded to 2 decimal places) taken by the user to complete the Configuration Wizard. Since our calculator application does not manage sessions itself we have not specified the session ID parameter. Build your solution, run the application, execute the events which trigger event tracking, and close the application From the Usage Intelligence Product Dashboard go to the Administration page and under Product Settings click on Event Tracking Management to enable tracking for this event The next time the Configuration Wizard runs, Usage Intelligence will collect the configuration time data Numeric events can also be collected as custom data but this functionality needs to be enabled per product. Read the following section for more information on custom events and contact support if you wish to include numeric events with your product's custom data. 3. Tracking Custom Events There are times when you need to track events with free text data, for instance, to record the state of your application when an event occurs, or collect manual or automated feedback from the application. This can easily be done with Usage Intelligence and in the following examples, we will collect user feedback from the calculator application, and the settings chosen by users when completing the Configuration Wizard. Collecting User Feedback Open the class where you will be collecting user feedback. In our example, we have created a form with a textbox (txtFeedback) for users to enter their comments and a Submit button At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Add the following code to submit the user feedback to Usage Intelligence. In this example we have used the Click event of the submit button: private void btnSubmit_Click(object sender, EventArgs e) { //rui is your RUISDK instance rui.TrackEventText("Feedback", "User Comments", txtFeedback.Text); //The rest of your code… } The TrackEventText() method has 3 required parameters, the category of the event being tracked, the name of the event and a string value, and an optional parameter for the session ID. In this example, we have called the category “Feedback” and the event name “User Comments”. We have set the string value as the text that the user entered in the textbox and did not specify a session ID since our calculator application does not manage sessions itself. Build your solution, run the application, submit test feedback, and close the application From the Usage Intelligence Product Dashboard go to the Administration page and under Product Settings click on Event Tracking Management to enable tracking for this event The next time feedback is submitted from the application, Usage Intelligence will collect this data To view the feedback, from the Product Dashboard go to Feature & Event Tracking > Custom Events   The Recent Custom Events tab shows the latest events that have been logged. Click on an event to see the event information submitted to Usage Intelligence, as well as additional metadata for each event including the application version and build, operating system and language information, device type, screen resolution, and more The Downloadable Archives tab provides a list of zip files containing the collected data in the CSV format. These files can be downloaded for further analysis and contain all the event information and metadata described above Collecting Multiple Values In this example, we need to collect multiple values that represent the settings chosen by the user. This can be done by using a delimiter of your choice, and in this example, we chose to split our list using the “|” character. Open the class where you will be collecting the data from. In our example, this is the class where we have the code for the Configuration Wizard At the top of the file add the directive using RUISDK_<x_x_x>; where x_x_x is the SDK version you downloaded, e.g. 5_0_0 Create a string containing the piped list (text delimited by the | character) and log the event. In this example, we are tracking which configuration settings users are selecting in the Configuration Wizard, i.e. Normal or Scientific mode, the UI theme, and whether to keep a history or not: private void btnFinish_Click(object sender, EventArgs e) { StringBuilder configData = new StringBuilder(); configData.Append(rbStandard.Checked ? "Standard" : "Scientific"); configData.Append(" | " + cmbTheme.SelectedValue.ToString()); configData.Append(chkHistory.Checked ? " | Keep History" : " | Don't Keep History"); //rui is your RUISDK instance rui.TrackEventText("Config Settings", "Config Wizard", configData.ToString(), null); //The rest of your code… } Alternatively, you may use the TrackEventCustom() function to collect a set of key/value pairs. The values collected will be automatically formatted as (Key1:Value1)&&(Key2:Value2) by the SDK. More information on how to use this function can be found in the documentation. NOTE: rbStandard is the radio button to select Standard mode, cmbTheme is a combo box containing a list of themes, and chkHistory is a checkbox to select whether to keep a history or not. Build your solution, run the application, execute the events which trigger event tracking, and close the application From the Usage Intelligence Product Dashboard go to the Administration page and under Product Settings click on Event Tracking Management to enable tracking for this event To view the data, from the Product Dashboard go to Feature & Event Tracking > Custom Events That is it for event tracking. Check the next article on how you can manage your licensing with Usage Intelligence and track licensing specific events! ... View more

Lifetime Event Usage is a measurement of the number of times that a user-generated an event throughout their lifetime, i.e., starting from when the tracked application was installed until the last time that the user was active. The aim behind this is to gain an understanding of users’ awareness and interest in a particular feature while engaged with the software. In this blog post, we will provide an overview of the Lifetime Event Usage report and discuss how this report can be used to analyze user activity based on their lifetime event usage.  Lifetime Event Usage Report The Lifetime Event Usage report can be accessed by logging in to the Usage Intelligence Dashboard and navigating to Feature & Event Tracking > Lifetime Event Usage.   An important aspect to keep in mind when using this report is that it reports on those users who were active in the selected date range, but the statistics are based on how much an event is used during those users’ lifetime. Through this report you can see: The percentage of unique users who generated the event vs. the number of users who never generated the event. The total number of times that an event has been generated by all users. Out of the users that generated the event, how many times the event was generated in their lifetime as well as average daily, weekly, and monthly statistics. Data is presented in a tabular view as shown below, with the ability to drill down on selected events to build a graphical view of the event usage distribution.   These statistics are available for all the events enabled for standard tracking. You can manage which events are being tracked by going to the Admin page from the top menu and under Product Settings click on Event Tracking Management. Furthermore, the report supports both filtering and segmentation. This allows you to analyze event usage for different cohorts and help you to identify usage trends among your users. Here are some simple use case examples for using this report: Example 1 - Your product has two ways of opening a file, either from the ‘File Menu’ or by using a shortcut. Using this report, you can compare both events to find out which of them is more popular as well as what portion of users never actually find out about or use the shortcut option at all.     Example 2 - The latest version of your product included UI changes to make the export functionality more visible. Through this report, you can gauge how effective these changes were by grouping the events related to export and comparing usage statistics of the current version with the previous one.   Example 3 - You may also compare event usage based on different properties, such as users who have a freeware license with those using the Lite edition of your product.   Report Customization The Lifetime Event Usage report comes with various settings that allow you to customize your view of the report. To access these settings, open the widget context menu, and select Report Settings.   The Report Settings include: Choose between a flat view that displays the category with each event or a hierarchical view which groups events by their category. Sort events and segments alphabetically, by the number of unique users that generated the event, or by the total event count for all users. Select which events to include in the report. This is useful when you want to focus on a set of events only. Selecting a category will automatically add all events that fall under it.   Lifetime Event Usage for Churned Users The Churned User Activity report makes use of the same lifetime event usage concepts described in this blog post but applies exclusively to lost users, i.e., users who have stopped using your application. This allows you to analyze event usage trends for churned users and helps you gain an understanding of users’ behavior before they are declared lost.   This report can be accessed from the Usage Intelligence Dashboard by going to Churn Analysis > Churned User Activity.   Explore Lifetime Event Usage Analytics Sign up for a free account to gain access to a Demo Product and explore these reports using sample data. Need further information? Contact us and we would be happy to walk through your questions or schedule a demo. ... View more

You can block specific clients from contacting the Usage Intelligence server by adding their IP address to the Blocked Client IPs list. This is useful when you want to eliminate data coming from your company network or blocking rogue installations which might be skewing your data. When the server receives a sync message from a blocked IP address, it will not process the data and no information is saved from that request. You can manage your product’s IP blacklist from the Usage Intelligence Dashboard by going to the Admin page and under Data Management click on Blocked Client IPs. From here you can add new IPs or IP ranges, and modify or delete your current entries.     ... View more

Option 1 - Block internal IP addresses If you do not want to collect the data coming from your test environment at all, you may use the Blocked Client IPs to reject data coming from these clients. To manage the IP blocked list, log in to the Usage Intelligence Dashboard, go to the Admin page, and under Data Management click on Blocked Client IPs. Once an IP has been added to this list, the server will not process or save any data coming from it. NOTE: You must be a Product Administrator to be able to manage the Blocked Client IPs.  Option 2 – Include a data collection configuration setting in your product An option that gives you more control over when test data is collected is to include a hidden setting that signals your product not to track that installation. This may be a Windows registry setting or a setting in a configuration file. On startup your app will check for this setting and if found it will not start the Usage Intelligence tracking.     Option 3 – Separate test data from your customer data If you want to collect data from your test environment but would like to keep it separate from your customer data, you may create another product from the Usage Intelligence Dashboard and use that product ID for testing purposes. When using separate products it is important to make sure that the correct product ID is used for released builds. Revenera offers a free developer plan to all customers having a product on a paid plan. Contact support if you would like to switch a test product to the free developer plan and specify your test product ID. ... View more

When you invite a user to access your product you are asked to choose which access permissions will be applied to this user. To invite a new user or edit the permissions of an existing user log in to the Usage Intelligence Dashboard, from the top-right menu navigate to the Administration page, and under Product Settings click on Users & Permissions. The following is a list of the available permissions: Product Administrator Gives the user full access to the product, including permission to delete data and block clients / IP addresses. User Management Permission to view the User Management pages, invite new users, and update/delete current users available only to product administrators. Read-Only permission allows non-admin users to view current users without making changes or adding new users. Reporting Permission to access all reporting and analytics pages, including exported data. ReachOut  Permission to manage ReachOut campaigns. Read-Only permission allows users to view campaign details without making changes. Developer  Permission to access product configuration settings and full reporting, including call home URL, AES key, and event allowed. Read-Only permission allows users to view product settings without making changes. License Key Management  Permission to access the license key registry including adding, updating, and deleting license keys and updating registry settings. Read-Only permission allows users to view the license keys and settings only. License Key Filtering  Allows users to view license keys in filters, reports, and ReachOut campaigns. Quota Usage  Permission to view the quota usage information. Billing  Permission to view and change billing details, payment methods, and invoices. Read-Only permission allows users to view billing info without making any changes. Reporting API  Permission to access the reports and analytics data via the Web API. NOTE: Access to reporting via the Usage Intelligence Dashboard cannot be further broken down to specific reports. However, it is possible to request analytics data via the Reporting Web API to build custom charts or display in 3rd party systems. Documentation for the Reporting API is available here.   ... View more

Dashboard Reports By default, reports use the Client ID property as an identifier for an installation / user. This may be changed in some reports to use a different property as the identifier. When doing so, multiple installations sharing the same value of the selected property will be grouped as a single installation. For example, if I choose to group by the License Key property, two installations using the same license key will be counted as one installation in the reports. To change the identifier property, click on the “Group By” tab in the report toolbar, and select a property from the list.  The properties available for grouping are: Client ID (default) Machine ID License Key Custom properties of type 3 If an installation does not have a value set for the selected identifier property, that installation will not be included in the report.  NOTE: The Machine ID property was introduced in version 5 of the Usage Intelligence SDK. When grouping by Machine ID, clients using an older version of the SDK will therefore not be included in the report. The following is a list of reports that support the 'Group By' functionality: Distribution Reports Product Metrics OS & Platform Hardware Architecture Java Environment Geography Lifetime Event Usage Custom Report Builder Custom Timeline Builder Revenera Web API The following is a list of reports that support the 'Group By' option. More information on the request and response format is available in the Web API online documentation. Generic Current Report Generic Date-Range Report Lifetime Event Tracking Reports Related Articles How does Usage Intelligence identify unique users/installations? What type of data can I store in Custom Properties? ... View more

The Usage Intelligence Interactive Dashboard is a mine of information which provides runtime intelligence related to product usage, environment statistics, event tracking, licensing information as well as user engagement and churn reports. However, we understand that some customers might have custom reporting requirements as well as needs to export Business Intelligence data from Usage Intelligence to integrate with third-party products or platforms. For this reason, Revenera has developed a fully-fledged Reporting Web API that is available to all premium customers. The Reporting Web API gives you the flexibility to create your own custom reports according to your requirements and retrieve the data either in raw JSON format or as a readily formatted HTML chart or table. Such data can then be parsed and/or integrated directly into your own reporting platform, CRM, ERP solution, etc. In this blog post, we will introduce you to the Usage Intelligence Reporting Web API, explain the basics of building reports, and provide some example requests using JavaScript. By the end of the post you will learn how to: Authenticate with the Server Build Custom Reports Get Formatted Data Get Raw JSON Data The Basics The Reporting API handles data requests as JSON objects and can reply either with raw data as a JSON object or with a formatted chart or table wrapped in an HTML page. There are two request methods which you can use to get data from the server: HTTP POST – This is the preferred method since it is more suited for long data requests and should be used if you’re building a custom application that handles raw data. When using this method the JSON request object is sent as POST data. HTTP GET – This method is ideal when requesting formatted data to be included in an HTML page. When using this method the JSON request object is appended to the URL as a parameter. The complete URL can be used as the source of an iframe or can be manually entered in the address bar of the browser. When submitting a GET request, the following URL parameters are accepted: query – The JSON request object should be specified in this parameter. This value needs to be URL encoded. resultFormat – Specify the type of response required. The accepted values are “raw”, “highcharts”, and “table”. If not specified it will default to "raw". hcType – Only required if resultFormat is set to “highcharts” and is used to specify the type of chart. The accepted values are “pie”, "bar", "column", and "line". uiHcTitle – Optional parameter when resultFormat is set to "highcharts" or "table" to specify a title for the chart / table. All requests made to the Reporting API can be done both via a POST or GET request, with the exception of logging in which can only be done via a POST request. More information on POST vs GET requests can be found in the Reporting API documentation. Authenticating with the Server The first step to being able to generate reports is to authenticate with the server. The Web API supports two methods of authentication, either via a POST request to https://api.revulytics.com/auth/login, which returns a session ID as part of the JSON response, or else via cookies if getting formatted data. Logging In - Using a Session ID This method is preferred if the API is accessed from a script or application which needs to authenticate without using a web browser. The user and session ID are managed by the application and they will need to be sent with every request to the API as part of the JSON data. To log in using this method the request JSON object must specify the user and password, which are the email address and password you use to log in to your Usage Intelligence account, and useCookies set to false: { "user": "user@mycompany.com", "password": "mypassword", "useCookies": true } The JSON response will include the status which reflects whether the authentication was successful or not, and if successful it will include the sessionId to be used in all further requests: { "status": "OK", "sessionId": "VSB8E2BzSC2eZSJm4QmTpA" } Logging In - JavaScript Example In the following JavaScript example, we are making a POST request to log in and chose to manage the session ID within the script. The sessionId is retrieved from the JSON response and set as the value of a hidden field with ID "hSessionID". function login() { var request = new XMLHttpRequest(); var url = "https://api.revulytics.com/auth/login"; request.open("POST", url, true); request.setRequestHeader("Content-type", "application/json"); reques.setRequestHeader("Accept", "application/json"); request.onreadystatechange = function() { if (request.readyState == 4 && request.status == 200) { //Parse the response to a JSON object var json = JSON.parse(request.responseText); //Set value of hidden input field to the session ID for future use document.getElementById("hSessionID").value = json.sessionId; } } var data = JSON.stringify( { "user":"user@mycompany.com", "password":"mypassword", "useCookies":false }); request.send(data); } Logging In - Using Cookies If the API is accessed via a web browser and the data is requested as a formatted chart or table, this method is the most convenient way to manage the authentication session. When using cookies, the login is done by the user when viewing the page in their web browser. The first time data is requested, the API will return the Usage Intelligence login page and the requested chart or table will be displayed once you log in successfully. Once a cookie for api.revulytics.com which contains a valid session ID is created, subsequent requests for data will return the chart or table straight away.   Logging Out Logging out is done via a GET or POST request to https://api.revulytics.com/auth/logout, and this invalidates the session that was created when you logged in. If cookies were used to log in, then no JSON data should be sent and the request will simply delete the cookie and invalidate the session from the server. Otherwise, if the session was being managed by a script or application, JSON data should be sent with the request which includes the user and sessionId: { "user": "user@mycompany.com", "sessionId": "VSB8E2BzSC2eZSJm4QmTpA" } By default a GET request to log out returns a user friendly HTML message. However if a POST request was done the response will be a JSON object which includes the status, and if the request fails it will also include a reason. { "status": "OK" } Logging Out - JavaScript Example In the following example, we are making a POST request to log out and specifying the user and sessionId, which we saved as the value of the hidden field with ID "hSessionID" when we logged in. function logout() { var request = new XMLHttpRequest(); var url = "https://api.revulytics.com/auth/logout"; request.open("POST", url, true); request.setRequestHeader("Content-type", "application/json"); request.setRequestHeader("Accept", "application/json"); var data = JSON.stringify( { "user":"user@mycompany.com", "sessionId":document.getElementById("hSessionID").value }); request.send(data); } More information about Authentication is available in the Reporting API documentation. Building Custom Reports Once you have generated a session ID you can start requesting report data. The Reporting API currently supports six types of requests for data: Generic Reports - Get reporting data related to session runtimes, user profile info, user distribution, and activity for each product version, edition, and language, geolocation, operating system, and platform info, etc. This data can be retrieved for new, active, and lost users with various filtering and segmentation options. These reports can be generated for a past date range where you specify the start/end date or else on the latest known data of tracked users based on the date last seen. Event Tracking Management - Used to get a list of event names and categories that have been reported by your application and which of these are currently enabled for collection. Event Tracking Reports - Get report data on event usage, including event usage counts in the form of a data table or timeline, and advanced event tracking reports with filtering and segmentation options. Churn-Related Reports - Get user profile info related to lost users, including event usage and runtime statistics for the time they were still engaged with your product before they were declared lost. License Key Registry Management - Used to query the license key registry, retrieve license key usage details, get a list of abused keys, add new keys to the registry, or update license key properties for existing keys such as to sync data with your CRM or licensing server. Metadata Queries - Used to get a list of available filtering and segmentation properties or a list of possible property values that have been reported by your application. If you’re providing filtering and segmentation in your application, you can use this to populate the list of filtering and segmentation options that the user can choose from. In the next sections, we will go through some examples to get formatted and raw data by doing a request for Generic Reports. Getting Formatted Data If you would like to display data from Usage Intelligence in an HTML page, then getting formatted data will make this easy for you to show such data in the form of a chart or table. Let’s take an example where we need to get a chart of our product version distribution for current data, formatted as a bar chart like the following:   We can get this data by making a request for a Generic Report and in order to get a ready formatted chart, we must make a GET request. Building the Request JSON An explanation of each property that needs to be included in the request JSON can be found in the Reporting API documentation. The following is an example of the JSON object to get the Version Distribution report we need: { "productId": 2376158762, "startDate": "2015-12-18", "clientStatus": ["active", "new", "lost"], "levels": { "level1": { "sort": "active", "segments": [{ "limit": 10, "type": "regex", "split": true, "value": ".*" }], "property": "prodVersion", "sortDirection": "desc" } }, "daysUntilDeclaredLost": 30, "dateReportedLost": "dateDeclaredLost", "globalFilters": {} } Building the URL The request will need to be made to https://api.revulytics.com/reporting/generic and the following parameters must be included in the URL: query - Specify the request JSON object in this parameter resultFormat - Use "highcharts" as the result format hcType - In order to get a bar chart this value needs to be set to "bar" uiHcTitle - Specify the title of the chart, in our example, this is set to "Version Distribution" Getting Formatted Data - JavaScript Example In the following example, we are building the URL to get the formatted chart, and then set the source of an iframe with ID "chart" to that URL. function getFormattedData() { var json = { "productId": 2376158762, "startDate": "2015-12-18", "clientStatus": ["active", "new", "lost"], "levels": { "level1": { "sort": "active", "segments": [{ "limit": 10, "type": "regex", "split": true, "value": ".*" }], "property": "prodVersion", "sortDirection": "desc" } }, "daysUntilDeclaredLost": 30, "dateReportedLost": "dateDeclaredLost", "globalFilters": {} }; //Encode the JSON object var encodedJson = encodeURIComponent(JSON.stringify(json)); //Build the URL var url = "https://api.revulytics.com/reporting/generic/current"; url += "?query=" + encodedJson + "&amp;resultFormat=\"highcharts\""; url += "&amp;hcType=\"bar\"&amp;uiHcTitle=Version Distribution"; //Set the iframe source as the URL document.getElementById("chart").src=url; } More URL examples can be seen in the Dashboard by clicking on a chart’s context menu and selecting the URL option. From the URL you will be able to see the JSON object that was requested to build that chart.   Getting Raw Data If you are building a custom application then getting raw data as a JSON object will allow you to parse, format, and present the data in any way you need. In this example we want to give the users of our application the ability to enter a license key and retrieve the user profile data related to that key, similar to the following:   We can get each of these data by making a request for a Generic Report and specifying the property we need. There are two different types of properties available, those which are string-based such as the license type and status, and those which are numeric such as the RAM and display resolution. Depending on the type of property you are requesting, you will need to specify the segmentation accordingly. More information on segmentation and levels can be found in the Reporting API documentation. String Properties In the following JSON request, we are segmenting the report by operating system version using the os.version property, and filtering the results by the specified license key using the licenseKey filter.   { "user": "user@mycompany.com", "sessionId": "9AEH8SOY6EGD9U27SMV7Q61QYDTBCPH0", "productId": 2376158762, "startDate": "2015-12-14", "clientStatus": ["lost","active","new"], "levels": { "level1": { "sort": "active", "segments": [{ "limit": 10, "type": "regex", "split": true, "value": ".*" }], "property": "os.version", "sortDirection": "desc" } }, "daysUntilDeclaredLost": 30, "dateReportedLost": "dateDeclaredLost", "globalFilters": { "licenseKey": { "type": "string", "value": "1Yh5-JKQ2-73FD-BK55" } } } The following is an example of the expected JSON response. In this case, the license key specified has only been used on a Microsoft Windows 7 operating system, however, if the license key was used on multiple machines with a different operating system, these would have been included in the JSON response as well. { "status": "OK", "levelLabels": { "level1": "os.version" }, "results": { "level1": { "Microsoft Windows 7": { "totals": { "lost": 0, "active": 1, "new": 0 } } } } } Numeric Properties In the following JSON request, we are segmenting the report by RAM using the ram property, and filtering the results by the specified license key using the licenseKey filter. { "user": "user@mycompany.com", "sessionId": "9AEH8SOY6EGD9U27SMV7Q61QYDTBCPH0", "productId": 2376158762, "startDate": "2015-12-14", "clientStatus": ["lost","active","new"], "levels": { "level1": { "sort": "active", "segments": [{ "segmentLabel": "0 - 512 MB", "type": "numberRange", "max": 511 }, { "segmentLabel": "512 MB - 1GB", "type": "numberRange", "min": 512, "max": 1023 }, { "segmentLabel": "1GB - 2GB", "type": "numberRange", "min": 1024, "max": 2047 }, { "segmentLabel": "2GB - 4GB", "type": "numberRange", "min": 2048, "max": 4095 }, { "segmentLabel": "4GB - 8GB", "type": "numberRange", "min": 4096, "max": 8191 }, { "segmentLabel": "8GB - 16GB", "type": "numberRange", "min": 8192, "max": 16383 }, { "segmentLabel": "16GB+", "type": "numberRange", "min": 16384 }], "property": "ram", "sortDirection": "desc" } }, "daysUntilDeclaredLost": 30, "dateReportedLost": "dateDeclaredLost", "globalFilters": { "licenseKey": { "type": "string", "value": "1Yh5-JKQ2-73FD-BK55" } } } The following is an example of the expected JSON response. In this case, the license key specified has only been used on a device with 4GB – 8GB RAM, however, if the license key was used on multiple machines with different RAM, these would have been included in the JSON response as well. { "status": "OK", "levelLabels": { "level1": "ram" }, "results": { "level1": { "4GB - 8GB": { "totals": { "lost": 0, "active": 1, "new": 0 } } } } } Getting Raw Data - JavaScript Example In the following example, we are sending the JSON request to get the operating system versions filtered by the license key. Once we get the result, we are looping through the level1 properties to get all the operating systems that the key was used on and displaying these in a span with ID "sOS". function getRawData() { var licenseKey = "1Yh5-JKQ2-73FD-BK55"; var request = new XMLHttpRequest(); var url = "https://api.revulytics.com/reporting/generic/current"; request.open("POST", url, true); request.setRequestHeader("Content-type", "application/json"); request.setRequestHeader("Accept", "application/json"); request.onreadystatechange = function() { if (request.readyState == 4 && request.status == 200) { //Parse the response to JSON var json = JSON.parse(request.responseText); var strDisplay = ""; //Loop through the leve11 properties and add each key to a string var result = json.results.level1; for (var key in result) { strDisplay += key + " "; } //Set the text of span with ID sOS to the string document.getElementById("sOS").innerHTML = strDisplay; } } var data = JSON.stringify({ "user": "user@mycompany.com", "sessionId": "9AEH8SOY6EGD9U27SMV7Q61QYDTBCPH0", "productId": 2376158762, "startDate": "2015-12-14", "clientStatus": ["lost","active","new"], "levels": { "level1": { "sort": "active", "segments": [{ "limit": 10, "type": "regex", "split": true, "value": ".*" }], "property": "os.version", "sortDirection": "desc" } }, "daysUntilDeclaredLost": 30, "dateReportedLost": "dateDeclaredLost", "globalFilters": { "licenseKey": { "type": "string", "value": "1Yh5-JKQ2-73FD-BK55" } } }); request.send(data); } The full JavaScript example can be downloaded from the attached files.   ... View more

Following customer feedback, we are pleased to announce that Revenera is now offering out-of-the-box intelligence on .NET versions and graphics card models. These new properties are available for reporting in the Dashboard and through the Web API to help you gain insight on the .NET framework versions and graphics card vendors and models in use by your user base. These properties are available both for segmentation in the custom report and timeline builder as well as for filtering any other reports. Read on for more information on how to make use of these new properties to segment and filter your reports. .NET Framework and Graphics Card Data Collection To have .NET framework and graphics card statistics available for your product, your clients must be running a Usage Intelligence SDK version that supports the collection of this data. This information is collected by the SDK automatically and requires no further changes in your product. On Windows platforms, .NET framework versions are collected from SDK version 3.3.1 onwards while graphics card model information is collected from version 3.3.3 onwards. On Mac and Linux platforms, graphics card model information is collected from SDK version 4.0.1 onwards. View .NET Framework and Graphics Card Distribution Statistics To view distribution statistics on .NET framework versions or graphics card vendors and models you need to create a custom report by going to the Revenera Dashboard and from the product, menu select Custom Report Builder or Custom Timeline Builder.   Once on the Custom Builder page, click on the Segmentation option at the top and then click on the Add segment… drop down. You will find the new properties under Platform Properties.   For example, to generate a report on the graphics card vendors and models in use by your customers, in the Custom Report Builder add a segment for the GPU: Model property. This will result in a report similar to the following:   Similarly, you can create a report of .NET framework versions in use over time by going to the Custom Timeline Builder and adding a segment for .NET Version. In the following example, the chart is displaying a monthly view of the number of installations having .NET framework 4.5 and/or 4.5 Client Profile.   In the future, report widgets for .NET versions and graphics card models will be made available in the OS & Platform and Hardware Architecture reports respectively. Filter Dashboard Reports by .NET Framework Versions and Graphics Card Models All reports available in the Usage Intelligence Dashboard can be filtered by the new .NET framework and graphics card properties. To filter a report, open the respective report page and click on the Filter option at the top, then click on the Add Filter… drop down and under Platform Properties select the .NET Version or GPU property. Start typing or click on the filter textbox to see the available options. The following chart is an example of the Version Distribution report, showing the number of installation which are using Windows 7 and have .NET versions 4.6 and/or 4.6 Client Profile installed:   Filtering and Segmentation through the Usage Intelligence Web API Three new string based properties are available in the Web API for filtering and segmentation: dotNetVersion - .NET framework version gpu.vendor – graphics card vendor gpu.model – graphics card vendor / model Refer to the Web API online documentation for more information and examples of Filters and Segmentation Levels. Get started today with usage analytics! Register a free account and start touring analytics immediately. Then, simply integrate the SDK into your app to start your free trial.  ... View more

We recently announced the availability of the new Java SDK 5.1.0. This release enables software providers of Java 8+ applications which run on Windows, Mac, and Linux to integrate our Usage Intelligence solution with a native Java SDK and benefit from valuable software usage insights and in-application messaging. The Java SDK and documentation are available here. In this article, we will take a look at the new Java reporting capabilities made available with this release. New Java Reports in the Dashboard The Usage Intelligence Dashboard now includes new Java specific reports which can be accessed from the product menu by selecting Java Environment. The data in these reports is available exclusively for clients using the Java SDK.   Data for Java reports is collected out-of-the-box and will be available in the Dashboard as soon as you integrate your software with the Usage Intelligence SDK. These reports include: Java Version and Vendor    Java Runtime Version and AWT Graphics Environment   Java VM Details   Filter Dashboard Reports by Java Properties All reports available in the Usage Intelligence Dashboard can be filtered by new Java related properties. To apply a filter to a report, go to the respective report page and click on the Filter option in the toolbar. Click on the Add Filter Property dropdown and you will find the Java properties under Platform Properties.     Java properties are ‘current’ properties and therefore the last known value is saved for each client. For more information on ‘current’ properties check the following KBase article. Java Properties in ReachOut The same filtering properties available in reporting are also available for use in ReachOut campaigns. The Java properties can be found in the Recipient Profile Filter section under Platform Properties. Additionally, new ReachOut variables have been added so you can include the Java version, vendor, runtime version, AWT graphics environment, VM version and VM name in the message text or URL of your campaign. The list of Java variables can be found in the Message Content section under Platform Properties.   More information on ReachOut variables can be found in this KBase article. Filtering and Segmentation through the Revenera Web API The new Java properties are also available in the Web API for filtering and segmentation as string based properties: javaVersion – Java Version javaVendor – Java Vendor javaRuntime – Java Runtime Version javaGraphics – Java AWT Graphics Environment javaVmVersion – Java VM Version javaVmName – Java VM Name Refer to the Web API online documentation for more information and examples of Filtering and Segmentation Levels. ... View more

Providers of on-premise server applications can fully benefit from the advanced usage analytics provided by the Usage Intelligence solution. The implementation will depend on the type of application, and whether you are interested in tracking aggregate product usage by server installation or if you would like to track the individual users using your application. In this article, we will go over the implementation options for server applications and outline the benefits of each to help you decide which one is best for you. NOTE: Code examples in this article use the Usage Intelligence .NET SDK. We also offer SDKs for Java, C/C++ and Objective-C. Option 1 – Track aggregate usage per server installation This option is suitable if you want to collect aggregate usage data from different companies or on-premise server installations, rather than focusing on individual users who access your server application from their browser or desktop client. When choosing this option, the Usage Intelligence SDK is configured to operate in multi-session mode and your application must manage when a user session starts and stops. This typically means that a session is started when a user logs in and it is stopped when a user logs out.  In terms of integrating the SDK into your server application you would: Create the Usage Intelligence SDK instance bool defaultReachOut = false; string ruiPath = "<Path to Usage Intelligence DLLs>"; RUISDK rui = new RUISDK(defaultReachOut, ruiPath); Create the SDK configuration with multi-session enabled string filePath = "<Path were SDK config files will be saved>"; string productID = "<My Product ID>"; string appName = "<MyAppName>"; string productUrl = "<My Product URL>"; string aesHexKey = "<My AES Key>"; int ruiProtocol = (int)RUIProtocolType.httpPlusEncryption; bool multiSession = true; bool autoReachOut = false;   rui.CreateConfig(filePath, productID, appName, productUrl, ruiProtocol, aesHexKey, multiSession, autoReachOut); When the application starts also start the SDK rui.StartSDK(); For each user that logs in start a session and specify a unique session ID string sessionID_User1 = "<Unique session ID>"; rui.StartSession(sessionID_User1); When tracking events specify the relevant session ID for the user generating the event string eventCategory = "My Category"; string eventName = "My Event"; rui.TrackEvent(eventCategory, eventName, sessionID_User1); Once a user logs out or their session is terminated stop the session with the corresponding session ID rui.StopSession(sessionID_User1); When the application is stopped also stop the SDK rui.StopSDK(0); The value of this type of implementation is that performance and distribution metrics will reflect your customer base and the number of server applications they have installed. For example, if you have two companies ABC and XYZ which both have a single installation and 100 users each logging in to your application, the Usage Intelligence Dashboard will show statistics based on two installations, but the usage data from each of those two installations would reflect activity from the 200 users that are connected to those servers. When analyzing data you can compare user behavior across companies or sites. To achieve this, you can make use of a custom property to identify specific companies/sites and setting this in your application after creating the SDK configuration. If you prefer that the data remains anonymous you can use the Client ID to filter and segment data by installation. This will allow you to filter data by a specific company/installation only, or compare data between different companies. In the example below, a distribution report shows the OS Version for companies ABC and XYZ, where each of these have a single server installation.   If you go for this implementation option, event counts will reflect the total number of events generated by users for all installations. When looking at Basic Event Tracking statistics you must keep in mind that average event counts will be based on the number of server applications installed and not individual users. For example, if users at company ABC generated an event 100 times while users at company XYZ generated the same event 50 times, the total number of times that event was generated will be 150 with an average of 75 events per installation. To summarize: Product performance and distribution metrics will be based on number of application installs Event counts per user represent the aggregate number of events generated per installation Each application install can be associated with a company by using a custom property or anonymously group data per install by using the Client ID Option 2 – Track individual users If tracking individual users is important to you then you can implement the Usage Intelligence SDK in a way that simulates the different users which log in to your application. This option is suitable when you care more about the number of users using each installation and their individual usage and less about the number of server applications installed. If you choose this option, each user must have a different configuration path associated with it and a Usage Intelligence SDK instance is created each time a user logs in to the application.  This means that when integrating the SDK your application would do the following every time a user logs in: Create a Usage Intelligence SDK instance bool defaultReachOut = false; string ruiPath = "<Path to Usage Intelligence DLLs>"; RUISDK rui = new RUISDK(defaultReachOut, ruiPath); Check if the user has a folder associated with it, if not create one Create the SDK configuration with this folder and multi-session set to disabled so that a session will be automatically started once the SDK is started string userPath = "<Path where SDK config files will be saved for this user>"; string productID = "<My Product ID>"; string appName = "<MyAppName>"; string productUrl = "<My Product URL>"; string aesHexKey = "<My AES Key>"; int ruiProtocol = (int)RUIProtocolType.httpPlusEncryption; bool multiSession = false; bool autoReachOut = false;   rui.CreateConfig(userPath, productID, appName, productUrl, ruiProtocol, aesHexKey, multiSession, autoReachOut); Start the SDK rui.StartSDK(); When tracking events do not specify a session ID string eventCategory = "My Category"; string eventName = "My Event"; rui.TrackEvent(eventCategory, eventName, ""); Once a user logs out or their session is terminated stop the SDK instance. The session that was started automatically will also be stopped rui.StopSDK(0); When using this option, performance and distribution metrics in the Dashboard will reflect the number of individual users making use of your application, rather than the number of application installations. Therefore if companies ABC and XYZ both have a single installation and they each have 100 users logging in to your application, the Usage Intelligence Dashboard will show statistics based on 200 users. To identify which users belong to a specific company, you can use a custom property to associate a user with a company and in your application set this for each user after creating the SDK configuration. If you want the data to remain anonymous you can use the Machine ID to filter and segment data by installation. In the example below, an Event Usage Frequency report compares event usage of two events between companies ABC and XYZ. The actual report is showing the unique users that have connected to each company’s server and used the specific tracked events.   To summarize: Product performance and distribution metrics will be based on the number of users logging in your application at each install Event counts per user represent the number of users using the application across all installations Each application install can be associated with a company by using a custom property or anonymously group data per install by using the Machine ID We suggest you take a look at the Usage Intelligence dashboard to get a better understanding of the analytics data and reports available. You can sign up for an account to get access to our DEMO Product or start a free trial to experiment with your own test product. If you need further assistance to help you decide which implementation option is best for you, get in touch with us and we would be happy to discuss your use case. Further reading: What is multi-session mode and how should it be used? What type of data can I store in custom properties? ... View more

The Revenera Usage Intelligence platform allows you to extract a data set of Client IDs along with the profile data, usage data, and ReachOut in-app message deliveries for each. The Client Profile Report is available as an interactive report within Usage Intelligence as well as a full JSON export file that may be downloaded for offline use, archiving, or importing data into third-party systems. Accessing the Client Profile report The Client Profile report is accessible when you log into Usage Intelligence from the left-hand navigation by clicking on Client Profile. From here you will be able to configure the types of data you would like to retrieve and generate the report instantly or request a full JSON export.   Selecting Report Options When generating the Client Profile report you have the ability to choose what type of data you want to view or export. The report will return the Client ID together with any additional options which you choose to include from Current Profile Data, Lifetime Even Usage Data, ReachOut Message Deliveries, Daily Profile Data.   Report Filtering Besides returning a full client list, this report also comes with fully-fledged filtering capabilities and you may filter clients by any of the default Usage Intelligence properties as well as any custom properties you may have enabled for your product. This allows you to retrieve data on a subset of your clients for example: Getting a list of clients which are on a particular product version, edition or build Retrieving data for multiple installations on a single machine by filtering for a known Machine ID if you support multiple instances of your application to be installed Or getting data for a single client which you have identified by their Client ID, custom property or license key Report Data Visualization The Client Profile report will display a paged list of 200 clients' results per page. You can click on a Client ID from the list to view the client’s data. The reporting tabs available in the Client Profile Report will depend on the options selected when the report was generated. Current Profile Data All default Usage Intelligence properties and application-specific custom properties can be included in the Client Profile report, by selecting them in the Current Profile Data section. The value returned for each property will be the last known value for each client.   Lifetime Event Usage Data If you enable event tracking in Usage Intelligence, the Client Profile report will include a list of all the events a client generates during their lifetime and the total number of times each event was generated.   ReachOut Message Deliveries You may also choose to include a list of the ReachOut Messages that were delivered to each client. Existing campaigns will be listed by their ReachOut ID and campaign name, any deleted campaigns will only include the ReachOut ID.   Daily Profile Data When you select the Daily Profile Data option you need to select a date range to analyze. The report will include a timeline of all days on which users were active within that date range. You can choose which properties to retrieve for each active day, so you will be able to see how and when the user’s property values have changed over time. This is useful in cases where you want to determine when certain properties on a user changed for example: their license status, switched between product editions, or how they upgraded between different versions of your product.   The Daily Profile Data supports all standard and custom properties of type 1. More information on the difference between standard and current properties can be found in this KBase article. Exporting Report Data Individual Client ID Export A single client’s data can be viewed in JSON format by clicking on the JSON View tab. Each page can also be downloaded as a JSON file by clicking on the widget context menu and selecting the Export JSON option. The downloaded file will contain the JSON data for all clients included in the current page.   Full JSON Export A full JSON export consists of a file that contains the JSON data for all clients according to the selected client profile options and it can be requested by clicking on the Generate JSON Export button.   After you click on the button, you are requested to enter a description for the exported file, select whether you would like to receive an email notification when the file is ready for download and click on Proceed.   The export process is performed in the background and the time it takes to complete depends on the number of clients you have and the data that was requested. You can manage your exported files by going to the Admin page and under the Data Management section click on Exported Data Files. From this page you can monitor your pending exports as well as download, rename or delete files.   Browse Client Profile Sample Sign up for a free account to gain access to a Demo Product and explore this report using sample data. Need further information? Contact us with your questions and we would be happy to guide you. ... View more

You have collected a wealth of runtime intelligence via Revenera Usage Intelligence that has helped you unearth some interesting trends about your users. Your top concerns are that some of your main features are not being discovered by trial users, you have way too many customers still dragging their feet running older versions of your product and through conversion analytics, you discovered that users who do not convert to a purchased license within the first 20 days of evaluation have a big chance of turning into a lost lead. It is now time to start taking action and fix these problems, but what is the best way to get through to your users? Until today, Email was your only means of communicating with customers, but now you need a more engaging communication channel that offers 100% visibility. Luckily Usage Intelligence can make this easy for you with its ReachOut in-app messaging technology. What is In-App Messaging / In-App Marketing? In short, in-app messaging is a great way to interact with your users and share important information while they are engaged with your product. By having control over when to deliver the message, you are targeting users at the right time, when their attention is on the product and your brand is at the top of their mind. It also means that you are guaranteed that the user sees your message at the most critical time because they are engaged with your software, as opposed to running into the risks of email campaigns which are blocked by spam filters, lost in an inbox full of unread emails, bounce due to incorrect or inexistent email address, or simply reach the users at the wrong time when they are not interested in what you have to say. Why use Usage Intelligence ReachOut ? ReachOut in-app marketing is designed to work hand in hand with the runtime intelligence data you collect from Usage Intelligence and allows you to create personalized and highly targeted marketing campaigns by leveraging user profile data that is provided by the Usage Intelligence Analytics engine. In order to run an effective marketing campaign, the messages you send out should contain specific benefits for the recipient and thus should be relevant in context.  For example, a discount on renewals would be irrelevant to someone who is still evaluating the product and such a user would likely find the message annoying. The same is true if you try to upsell an advanced feature of your software to somebody who has not yet got his head around the basics. By using ReachOut you can create campaigns tailored specifically to match particular recipient profiles and make sure that each of your target users receives a message that resonates. This makes your campaign more personal and thus much more effective. Using ReachOut for Drip-Campaigns Marketing automation such as email followups or drip campaigns has been proven to help increase conversions and user engagement if timed well. However, one major problem with Email campaigns is that the only metric you can use to determine when to send a followup message is the number of days since download.  In reality, this metric has nothing to do with how much time the user has spent running your application. One user might run your application 10 times and spend hours experimenting with your software in a single day, whilst another busy user might spend 2 whole weeks without launching your software once. Clearly these 2 scenarios require a very different message when following up, which is practically impossible to achieve with email drip campaigns. With the Usage Intelligence framework, you can easily create customizable drip campaigns that can be pushed to your clients at very specific intervals based on how much time each user has spent engaged with your application and how many days they had it installed. This gives you the potential to create specific messages that resonate in each scenario. Audience Targeting with ReachOut Campaigns One of the major benefits of using ReachOut campaigns is that you can choose from a huge list of criteria to specifically select your target audience. Do you want to personalize your message and address users based on their primary language or geo location? With ReachOut this is easily achievable by using several filtering options, such as the country, operating system language, or the language your product is installed in if it supports that. You could also target users based on their runtime statistics or machine architecture, for example send out a message to all users who have downloaded your software from a specific landing page, have been running it for more than 30 days in trial mode, are running Windows 7 Pro on a desktop with a dual monitor, have at least 8GB of RAM and resolution of 1280px. The list of criteria that may be used to target a ReachOut campaign include: Geographical Region Country where the product is installed Days Installed Number of days the software has been installed Product Usage Number of hours the software has run since install, number of times the software has been executed Feature Usage The number of times the user engaged with a specific feature or set of features within your product Product Details Edition, version, build, language License License type (evaluation, purchased, freeware etc.), License Status (activated, expired, whitelisted, blacklisted), License Key OS Details Operating system, word length (32 bit / 64 bit), language, .NET Framework version Architecture Computer type (desktop, laptop / mobile), amount of memory, number of CPU cores, CPU type, graphics card vendor and model, virtual machine type and if touch screen is present Display Number of monitors, horizontal resolution, vertical resolution and screen pixels per inch Java Environment Java version, vendor, runtime, AWT graphics environment and VM details Custom Properties Clients matching any custom property value that you collect via the SDK Message Types and Delivery Method ReachOut provides you with two different delivery methods that can be customized for each campaign. These include: Manually from Code - A plain text message or URL is delivered to your application whenever it makes a request to the Usage Intelligence server. In this case, you have complete control when and how the message is displayed. This is useful if you have a news page in your application, or if you’d like to implement a built-in notification system for example. Automatically - A popup window is shown automatically when the application syncs with the Usage Intelligence server. An automatic sync is performed when the application starts and every 20 minutes after that. Your application can also control whether it should check for available campaigns during an automatic sync, with the option to suppress campaigns during critical phases of the application and turning them back on once normal operation resumes. The window can display a static or linkable image or a web page of your choice and supports customization of the window size and the position it is displayed on the screen. When using this option no coding is required whatsoever, so a Product Manager or Marketing person can simply create a campaign from the Usage Intelligence Dashboard and let ReachOut handle the rest, without involving the developers at any point. This can be beneficial in a myriad of situations across your organization.  Building your first ReachOut Campaign Let’s see how easy it is to create a campaign… Example 1 – Campaign to offer discounts to evaluation users You've been looking at your Conversion Funnel reports and you've learned that most users convert within the first 20 days of the 30 days evaluation, therefore there is a high risk that if the product is not purchased within that time frame you will lose the lead. You decide to monetize on these lost leads by offering these prospects the following discounts: If the product has been running for more than 20 days and is still using an evaluation license key, offer them a 20% discount If the product has been running for more than 25 days and it is still in evaluation, deliver a more aggressive promotional campaign by giving them a 40% discount Now let’s create the first campaign: Log in to your Usage Intelligence Dashboard and from the left navigation menu click on ReachOut   Make sure that the ReachOut Enabled option is set to Enabled Under Auto ReachOut Campaigns click on Add Auto Campaign In the Campaign Details section enter the name, description, and campaign schedule details   Under Message Content enter the popup details. In our case, we have chosen to upload an image banner that when clicked will open http://mycompany.com in the user’s default browser   Under Recipient Profile Filter select License Type and then choose Evaluation   Under Product Usage Filter select Days Since Installation and enter minimum 21 days and maximum 25 days   Click the Save button to create your campaign The next time a user that matches these criteria opens your application or the applications syncs with the server, the following popup window will be displayed   To create the second campaign, simply repeat the same steps but provide a new image and specify the range for installed days between 26 and 30 days instead. Example 2 – Display a form to download a free whitepaper You have published a new whitepaper on how customers can benefit from some advanced features in your software. For this reason, you want to send it out to all users who have run your software more than 10 times and have spent at least 50 hours of usage. To be able to download the whitepaper, you have a form available online which users need to fill in to access the download. Let’s create a campaign to display this form to all users who match the above criteria: From your Usage Intelligence Dashboard left navigation menu click on ReachOut Under Auto ReachOut Campaigns click on the Add Auto Campaign button In the Campaign Details section enter the name, description, and campaign schedule details   Under Message Content enter the popup details. In this example, we have chosen to show the URL to the download form   Under Product Usage Filter choose Lifetime Runtime Minutes and enter minimum 3000 minutes and Lifetime Number of Sessions minimum 10 days   Click the Save button to create your campaign The next time a user that matches the criteria opens your application or the application syncs with the server, the following popup window will be displayed   Example 3 – Notifying customers that their software version has reached the end of support Your company has decided that as of April 30, it will no longer provide support for version 1.0 of its software product. However, the Version Distribution reports provided by Usage Intelligence show that you still have a number of customers using this version and you’d like to let them know. You decide to push out a message to these customers using the notification system implemented in your application, which retrieves messages from ReachOut and displays them in a balloon notification. Create the campaign as follows: From your Usage Intelligence Dashboard left navigation menu click on ReachOut Under Manual ReachOut Campaigns click on the Add Manual Campaign button In the Campaign Details section enter the name, description, and campaign schedule details   Under Message Content select Plain Text and enter the text you would like to push out to your application   Under Recipient Profile Filter choose Product Version and select 1.0 from the available versions   Click the Save button to create your campaign The next time your application checks for new messages, if the version installed matches then the following message will be displayed to the user   The following is the C# code used in the application to display the notification: string message = ""; int msgCount; int msgType; //rui is your RUISDK instance RUIResult result = rui.CheckForReachOut(out message, out msgCount, out msgType); if (msgCount > 0) { NotifyIcon notifyIcon = new NotifyIcon(); notifyIcon.Visible = true; notifyIcon.BalloonTipTitle = "MyApp Message"; notifyIcon.BalloonTipText = message; notifyIcon.Icon = SystemIcons.Application; notifyIcon.ShowBalloonTip(60 * 1000); } Trying ReachOut in a Test environment Now that you’ve read about the benefits of in-app messaging and seen how easy it is to create a campaign, feel free to give it a try. If you’d like to see ReachOut in action in a test environment without sending out public messages to your users, we suggest you create a specific test version/build number and create a test campaign by filtering for that specific product version/build. This way only users running your test version/build will receive the ReachOut message. If you don’t have a Usage Intelligence account yet, you may sign up for a free trial and try ReachOut for free. ... View more