Collecting Custom Data with Event Tracking

Yes

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 section of the Usage Intelligence SDK Download Links and API Documentation page.

We will demonstrate the steps to collect the settings as a list delimited by the “|” character.

To collect custom events 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 Logging a Custom Event.

Build your solution, run the application and execute the relevant events.
Close the application.
Open the Usage Intelligence Dashboard, select Product from the Administration menu, and open the Event Tracking Management tab. If you have Auto-Approve enabled, tracking will already be enabled for ‘Settings – Application Preferences’, otherwise select it.

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.

NOTE: 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.

NOTE: By default, numeric values collected with TrackEventNumeric() are not included as custom events but can be enabled per product. Contact Revenera 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 Support Contacts 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.

Collecting Custom Data with Event Tracking