Developer Zone

Feature / Event Tracking

Through event tracking, Trackerbird allows you 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. Futher 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 which features 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 expierence.

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.

eventTrack(category, eventName[, sessionID=None][, allowExtendedNames = False])

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 None.

Note on Event Naming Conventions: Whatever event and category names you use as parameters will be visible in the 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 analytics reports.

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

Parameters:
  • category (str/unicode) – The name of the category that this event forms part of. This parameter is optional (send None if not required).
  • eventName (str/unicode) – The name of the event to be tracked.
  • sessionID (str) – 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 not be used.
  • 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 Trackerbird default UI and are only meant to be used via the Trackerbird API.
Return type:

One of the return status codes below.

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* APP_CONFIG_NOT_LOADED (-7)
* INVALID_PARAMETER (-9)

eventTrackNum(category, eventName, customValue[, sessionID=None][, allowExtendedNames = False])

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 None.

Note on Event Naming Conventions: Whatever event and category names you use as parameters will be visible in the 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 analytics reports.

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

Parameters:
  • category (str/unicode) – The name of the category that this event forms part of. This parameter is optional (send None if not required).
  • eventName (str/unicode) – The name of the event to be tracked.
  • customValue (float) – A numeric custom value related to this particular event.
  • sessionID (str) – 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 not be used.
  • 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 Trackerbird default UI and are only meant to be used via the Trackerbird API.
Return type:

One of the return status codes below.

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* APP_CONFIG_NOT_LOADED (-7)
* INVALID_PARAMETER (-9)

eventTrackTxt(category, eventName, customValue, sessionID=None[, allowExtendedNames = False])

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 None.

Note on Event Naming Conventions: Whatever event and category names you use as parameters will be visible in the 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 analytics reports.

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

Parameters:
  • category (str/unicode) – The name of the category that this event forms part of. This parameter is optional (send None if not required).
  • eventName (str/unicode) – The name of the event to be tracked.
  • customValue (str/unicode) – A custom text value related to this particular event.
  • sessionID (str) – 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 not be used.
  • 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 Trackerbird default UI and are only meant to be used via the Trackerbird API.
Return type:

One of the return status codes below.

* OK (1)
* FUNCTION_NOT_AVAIL (-1)
* APP_CONFIG_NOT_LOADED (-7)
* INVALID_PARAMETER (-9)