Feature / Event Tracking

Through event tracking, Revulytics Usage Intelligence allows you to keep track of how your clients are interacting with the various features within your application, potentially identifying how often every single feature is being used by various user groups. Apart from monitoring feature usage, you can also keep track of how often an event happens - such as how often an auto save has been made on average for every hour your application was running. Further to that, you may also keep a numeric value every time an event is reported. This can be used for example to keep the length of time it took to save a file, or the file size that was saved, etc. These events can be recorded using the function tbEventTrack().

Once event-related data has been collected, you will be able to identify trends of the features that are most used during evaluation and whether this trend changes once users switch to a freeware or purchased license or once they update to a different version/product build. You will also be able to compare whether any UI tweaks in a particular version or build number had any effect on exposing a particular feature or whether changes in the actual functionality make a feature more or less popular with users. This tool provides excellent insight for A/B testing whereas you can compare the outcome from different builds to improve the end user experience.

Note: Event Tracking should NOT be used to track the occurrence of exceptions since there is another specific API call for this purpose. If you need to track exceptions, refer to Exception Tracking.


TBRESULT tbEventTrack(TBINSTANCE *tbInstance, const wchar_t *category, const wchar_t *eventName, const wchar_t *sessionID, bool allowExtendedNames)

This function is used to track events in which no custom value needs to be recorded. Instead, only the fact that the event has happened is recorded by this function.

Optionally, events can be organised into categories. In order to do this, the category name should be passed in the category parameter. This category name then shows up in the reports, making the data more readable and easier to work with. If category names are not desired, this parameter should be set to NULL.

Note on Event Naming Conventions: The event and category names you use as parameters will be visible in the Revulytics Usage Intelligence Analytics reports. Therefore we recommend you use a meaningful and structured naming convention to make it easier for you to identify the events in the Revulytics Usage Intelligence Analytics reports.

Naming restrictions: Event and category names are limited to 40 characters each (not including terminating NULL). The total combined length of the category and event name should not exceed 50 characters (not including the terminating NULL). Longer names will be truncated.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

category (wchar_t*) - The name of the category that this event forms part of. This parameter is optional (send NULL if not required).

eventName (wchar_t*) - The name of the event to be tracked.

sessionID (wchar_t*) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session in which the event occurred. If the application supports only a single session, then this value should be NULL.
allowExtendedNames (bool) - Allow event names and categories that exceed the default naming restrictions. The maximum is set to 256
characters for both event name and categories if this is set to TRUE. Note that such long names are not supported in the Revulytics Usage Intelligence default UI and are only meant to be used via the Revulytics Usage Intelligence API.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbEventTrackNum(TBINSTANCE *tbInstance, const wchar_t *category, const wchar_t *eventName, double customValue, const wchar_t *sessionID, bool allowExtendedNames)

This function is used to track events in which a numeric custom value needs to be recorded. This value is then used in the event tracking report to produce averages. This is normally used to record the time it takes for a process to finish, or some other numeric value that can be used to calculate a specific trend.

Optionally, events can be organised into categories. In order to do this, the category name should be passed in the category parameter. This category name then shows up in the reports, making the data more readable and easier to work with. If category names are not desired, this parameter should be set to NULL.

Note on Event Naming Conventions: The event and category names you use as parameters will be visible in the Revulytics Usage Intelligence Analytics reports. Therefore we recommend you use a meaningful and structured naming convention to make it easier for you to identify the events in the Revulytics Usage Intelligence Analytics reports.

Naming restrictions: Event and category names are limited to 40 characters each (not including terminating NULL). The total combined length of the category and event name should not exceed 50 characters (not including the terminating NULL). Longer names will be truncated.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

category (wchar_t*) - The name of the category that this event forms part of. This parameter is optional (send NULL if not required).

eventName (wchar_t*) - The name of the event to be tracked.

customValue (double) - A numeric custom value related to this particular event.

sessionID (wchar_t*) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session in which the event occurred. If the application supports only a single session, then this value should be NULL.
allowExtendedNames (bool) - Allow event names and categories that exceed the default naming restrictions. The maximum is set to 256
characters (not including terminating NULL) for both event name and categories if this is set to TRUE. Note that such long names are not supported in the Revulytics Usage Intelligence default UI and are only meant to be used via the Revulytics Usage Intelligence API.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

TBRESULT tbEventTrackTxt(TBINSTANCE *tbInstance, const wchar_t *category, const wchar_t *eventName, const wchar_t *customValue, const wchar_t *sessionID, bool allowExtendedNames)

This function is used to track events in which a text value needs to be recorded. This type of event is used to record textual data collected from the application or the user. It may be used to provide functionality such as asking the user for comments or even recording the brand name of the GPU on the user’s machine.

Optionally, events can be organised into categories. In order to do this, the category name should be passed in the category parameter. This category name then shows up in the reports, making the data more readable and easier to work with. If category names are not desired, this parameter should be set to NULL.

Note on Event Naming Conventions: The event and category names you use as parameters will be visible in the Revulytics Usage Intelligence Analytics reports. Therefore we recommend you use a meaningful and structured naming convention to make it easier for you to identify the events in the Revulytics Usage Intelligence Analytics reports.

Naming restrictions: Event and category names are limited to 40 characters each (not including terminating NULL). The total combined length of the category and event name should not exceed 50 characters (not including the terminating NULL). Longer names will be truncated.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

category (wchar_t*) - The name of the category that this event forms part of. This parameter is optional (send NULL if not required).

eventName (wchar_t*) - The name of the event to be tracked.

customValue (wchar_t*) - A custom text value related to this particular event.

sessionID (wchar_t*) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session in which the event occurred. If the application supports only a single session, then this value should be NULL.
allowExtendedNames (bool) - Allow event names and categories that exceed the default naming restrictions. The maximum is set to 256
characters (not including the terminating NULL) for both event name and categories if this is set to TRUE. Note that such long names are not supported in the Revulytics Usage Intelligence default UI and are only meant to be used via the Revulytics Usage Intelligence API.
Returns:One of the return status constants below.
* TB_OK (1)
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)