Revulytics Blog

Collecting Custom Data with Event Tracking

February 9, 2016

Subscribe

There are instances when knowing the number of times that an event occurred is not enough, but you would like to collect further information which 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

Revulytics Usage Intelligence gives you the ability to collect such information in the form of Custom Events, where you can collect free text data 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 check for updates frequency)

Software Application Preferences - Revulyitcs

 

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.

  1. Open the class where you will be collecting the data from
  2. At the top of the file make sure you have the using RUISDK_<x_x_x>;  directive
  3. 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.
  4. Build your solution, run the application and execute the relevant events
  5. Close the application
  6. From the Revulytics Product Dashboard go to the Administration page and under Product Settings click on Tracked Events Whitelist Management. If you have Auto-whitelist enabled, Basic tracking will already be selected 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.

Tracking an event in Basic Mode will be sufficient for the event to be included in the Feature & Event Tracking reports as well as to be able to download the data for this event in CSV format.

* 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 Revulytics Usage Intelligence Dashboard Home page.

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 Revulytics Usage Intelligence Dashboard by going to Feature & Event Tracking > Basic Event Tracking. 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”.

Revulytics Feature Event Usage Report

Exporting the RAW Data

The custom data included with the events can be viewed and downloaded from the Revulytics Usage Intelligence Dashboard by going to Feature & Event Tracking > Custom Event Tracking.

Custom Software Event Tracking - Revulytics

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 meta data, including product details, operating system and architecture details, licensing info and custom properties. This is particularly useful when you’re initially including custom events in your product, so you can browse the latest incoming data for testing purposes.

Custom Event Tracking Recent

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 which contain the custom event data.

Custom Event Tracking Archives - Revulytics

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 meta data 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, geo location etc.

The meta data also includes a Client ID which represents the user installation that generated the event. This is a Revulytics 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.

Custom Event Tracking Archive - Software Usage Analytics

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 a Revulytics account yet, you may sign up for a freeware account at https://www.revulytics.com/usage-intelligence-try-for-free . Using a freeware account you can collect data from 400 unique active installations and evaluate feature & event tracking with up to 300 unique events.

Get Started 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. Start making data-driven decisions.

Post written by Arielle Bonnici

Software Developer & Technical Writer