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 trackEvent(String, String) .

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 trackEventNumeric(String, String, double), 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 trackEventNumeric(String, String, double), trackEventText(String, String, String), and trackEventCustom(String, String, List) 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 trackEvent(String eventCategory, String eventName)
RUIResult 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 - use method without sessionID
* 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.

trackEvent(String, String) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

trackEvent(String, String) can be called while a New Registration is being performed (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), 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.

trackEvent(String, String) 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 (send 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 use method without sessionID.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     Function successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length.
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length.
* INVALID_PARAMETER_EXPECTED_NON_EMPTY   Some API parameter is expected to be non-empty, and is not.
* INVALID_SESSION_ID_NOT_ACTIVE          The sessionID is not currently in use.

RUIResult trackEventNumeric(String eventCategory, String eventName, double customValue)
RUIResult trackEventNumeric(String eventCategory, String eventName, double 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 - Use method without sessionID
* 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.

trackEventNumeric(String, String, double) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

trackEventNumeric(String, String, double) can be called while a New Registration is being performed (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), 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.

trackEventNumeric(String, String, double) 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 (send 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 use method without sessioinID.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     Function successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length.
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length.
* INVALID_PARAMETER_EXPECTED_NON_EMPTY   Some API parameter is expected to be non-empty, and is not.
* INVALID_SESSION_ID_NOT_ACTIVE          The sessionID is not currently in use.

RUIResult trackEventText(String eventCategory, String eventName, String customValue)
RUIResult 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 - Use method without sessionID
* 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.

trackEventText(String, String, String) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

trackEventText(String, String, String) can be called while a New Registration is being performed (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), 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.

trackEventText(String, String, String) 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 (send 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                                     Function successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length.
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length.
* INVALID_PARAMETER_EXPECTED_NON_EMPTY   Some API parameter is expected to be non-empty, and is not.
* INVALID_SESSION_ID_NOT_ACTIVE          The sessionID is not currently in use.

RUIResult trackEventCustom(String eventCategory, String eventName, List<RUINameValuePair> customValues)
RUIResult 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 - Use method call without sessionID
* 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.

trackEventCustom(String, String, List) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

trackEventCustom(String, String, List) can be called while a New Registration is being performed (createConfig(String, String, String, String, RUIProtocol, String, boolean, boolean), 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.

trackEventCustom(String, String, List) 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 (send 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 final 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 final 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 use method without sessionID.

Return Type:

RUIResult enum value with the following possible values:

* OK                                     Function successful.
* SDK_INTERNAL_ERROR_FATAL               Irrecoverable internal fatal error.  No further API calls should be made.
* SDK_ABORTED                            A required New Registration has failed, and hence the SDK is aborted.  stopSDK is possible.
* SDK_PERMANENTLY_DISABLED               The RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                          The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                          Instance has been instructed by the application to opt-out.
* CONFIG_NOT_CREATED                     Configuration has not been successfully created.
* SDK_ALREADY_STOPPED                    SDK has already been successfully stopped.
* SDK_SUSPENDED                          Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED                        SDK has not been successfully started.
* FUNCTION_NOT_AVAIL                     Function is not available.
* INVALID_SESSION_ID_EXPECTED_NON_EMPTY  The sessionID is expected to be empty, and it was not.
* INVALID_SESSION_ID_TOO_SHORT           The sessionID violates its allowable minimum length.
* INVALID_SESSION_ID_TOO_LONG            The sessionID violates its allowable maximum length.
* INVALID_PARAMETER_EXPECTED_NON_EMPTY   Some API parameter is expected to be non-empty, and is not.
* INVALID_SESSION_ID_NOT_ACTIVE          The sessionID is not currently in use.