Developer Zone

Feature / Event Tracking

Through event tracking, Revulytics Usage Intelligence 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. This is accomplished through RUISDK.TrackEvent .

You may also keep a numeric value, text value, or group of name-value pairs every time an event is reported. This can be used, for example in the case of RUISDK.TrackEventNumeric, to keep track of 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 functions RUISDK.TrackEventNumeric, RUISDK.TrackEventText, and RUISDK.TrackEventCustom respectively.

Once event-related data has been collected, you will be able to identify trends of what 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 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.

RUIResult RUISDK.TrackEvent (String eventCategory, String eventName, String sessionID = “”)

Logs a normal event with the supplied data. The usage requirements of the sessionID parameter are the following:

* multiSessionEnabled = false - sessionID must be empty.
* multiSessionEnabled = true  - sessionID must be a current valid value used in StartSession.

NOTE: Unlike V4 of the RUI SDK, there is no concept of extended names (for eventCategory and eventName). The content of eventCategory and eventName is conditioned and validated (after conditioning) with the following rules:

* Conditioning: All leading white space is removed.
* Conditioning: All trailing white space is removed.
* Conditioning: All internal white spaces other than space characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

RUISDK.TrackEvent can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.TrackEvent can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.StartSDK). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

RUISDK.TrackEvent is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (String) - The name of the category of this event. This parameter is optional (set to string.Empty or null if not required).

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

sessionID (String) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session where the event occurred. If the application supports only a single session, then this value should be empty.

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Synchronous functionality successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedEmpty          The sessionID is expected to be empty, and it was not.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              The sessionID is not currently in use.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.

RUIResult RUISDK.TrackEventNumeric (String eventCategory, String eventName, Double customValue, String sessionID = “”)

Logs a normal event with the supplied data, including a custom numeric value. The usage requirements of the sessionID parameter are the following:

* multiSessionEnabled = false - sessionID must be empty.
* multiSessionEnabled = true  - sessionID must be a current valid value used in :csharp:meth:`RUISDK.StartSession`.

NOTE: Unlike V4 of the RUI SDK, there is no concept of extended names (for eventCategory and eventName). The content of eventCategory and eventName is conditioned and validated (after conditioning) with the following rules:

* Conditioning: All leading white space is removed.
* Conditioning: All trailing white space is removed.
* Conditioning: All internal white spaces other than space characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

RUISDK.TrackEventNumeric can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.TrackEventNumeric can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.StartSDK). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

RUISDK.TrackEventNumeric is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (String) - The name of the category of this event. This parameter is optional (set to string.Empty or null if not required).

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

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

sessionID (String) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session where the event occurred. If the application supports only a single session, then this value should be empty.

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Synchronous functionality successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedEmpty          The sessionID is expected to be empty, and it was not.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              The sessionID is not currently in use.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.

RUIResult RUISDK.TrackEventText (String eventCategory, String eventName, String customValue, String sessionID = “”)

Logs a normal event with the supplied data, including a custom string field. The usage requirements of the sessionID parameter are the following:

* multiSessionEnabled = false - sessionID must be empty.
* multiSessionEnabled = true  - sessionID must be a current valid value used in StartSession.

NOTE: Unlike V4 of the RUI SDK, there is no concept of extended names (for eventCategory and eventName). The content of eventCategory and eventName is conditioned and validated (after conditioning) with the following rules:

  • Conditioning: All leading white space is removed.
  • Conditioning: All trailing white space is removed.
  • Conditioning: All internal white spaces other than space characters (‘ ‘) are removed.
  • Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
  • Validation: eventCategory can be empty; eventName cannot be empty.

RUISDK.TrackEventText can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.TrackEventText can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.StartSDK). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

RUISDK.TrackEventText is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (String) - The name of the category of this event. This parameter is optional (set to string.Empty or null if not required).

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

customValue (String) - A text custom value related to this particular event. Trimmed to a maximum length determined by the RUI Server. Current default maximum is 4096 UTF-8 characters.

sessionID (String) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session where the event occurred. If the application supports only a single session, then this value should be empty.

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Synchronous functionality successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedEmpty          The sessionID is expected to be empty, and it was not.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              The sessionID is not currently in use.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.

RUIResult RUISDK.TrackEventCustom (String eventCategory, String eventName, List<RUINameValuePair> customValues, String sessionID = “”)

Logs a normal event with the supplied data, including an array of custom name/value pairs. The usage requirements of the sessionID parameter are the following:

* multiSessionEnabled = false - sessionID must be empty.
* multiSessionEnabled = true  - sessionID must be a current valid value used in :csharp:meth:`RUISDK.StartSession`.

NOTE: Unlike V4 of the RUI SDK, there is no concept of extended names (for eventCategory and eventName). The content of eventCategory and eventName is conditioned and validated (after conditioning) with the following rules:

* Conditioning: All leading white space is removed.
* Conditioning: All trailing white space is removed.
* Conditioning: All internal white spaces other than space characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

RUISDK.TrackEventCustom can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.TrackEventCustom can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.StartSDK). However, the event data is not written to the log file until the New Registration completes, and if the New Registration fails, the data will be lost.

RUISDK.TrackEventCustom is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

NOTE: Custom data will be logged in the format (Key1,Value1)&&(Key2,Value2)…&&(KeyN,ValueN)

Parameters:

eventCategory (String) - The name of the category of this event. This parameter is optional (set to string.Empty or null if not required).

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

customValues (List<RUINameValuePair) - A List of name/value String pairs related to this particular event. The RUINameValuePair class has two members:

public String name;   // Custom data associated with the event.  A given name and/or value can be
                      // empty.  A given name cannot contain white space.  All names and values are trimmed to a maximum
                      // length configured on the RUI Server. Both names and values have a default maximum of 128 UTF-8 characters.
public String value;  //  Custom text data associated with the event, cannot be empty.  Trimmed to a maximum length determined by the RUI Server. Both names and values have a default maximum of 128 UTF-8 characters.
sessionID (String) - If multiple user sessions are supported within the application, this should contain the unique
ID that refers to the user session where the event occurred. If the application supports only a single session, then this value should be empty.

Return Type:

RUIResult enum value with the following possible values:

* ok                                     Synchronous functionality successful.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkAborted                             A required New Registration has failed, and hence the SDK is aborted.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI Server to disable.  This is permanent, irrecoverable state.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* configNotCreated                       Configuration has not been successfully created.
* sdkNotStarted                          SDK has not been successfully started.
* sdkAlreadyStopped                      SDK has already been successfully stopped.
* invalidSessionIDExpectedEmpty          The sessionID is expected to be empty, and it was not.
* invalidSessionIDExpectedNonEmpty       The sessionID is expected to be non-empty, and it was not.
* invalidSessionIDTooShort               The sessionID violates its allowable minimum length.
* invalidSessionIDTooLong                The sessionID violates its allowable maximum length.
* invalidSessionIDNotActive              The sessionID is not currently in use.
* invalidParameterExpectedNonEmpty       Some API parameter is expected to be non-empty, and is not.