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

You may also keep a numeric value, a text value, or a collection of name/value pairs every time an event is reported. This can be used, for example in the case of trackEventCategory:eventName:withNumeric:sessionID:, 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 trackEventCategory:eventName:withNumeric:sessionID:, trackEventCategory:eventName:withText:sessionID:, and trackEventCategory:eventName:withNameValuePairs:sessionID: 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.

(RUIRESULTOBJC) trackEventCategory: (NSString*)eventCategory eventName: (NSString*)eventName sessionID: (NSString*)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 thanspace characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

trackEventCategory:eventName:sessionID: can be called between startSDK and stopSDK:, and can be called zero or more times.

trackEventCategory:eventName:sessionID: can be called while a New Registration is being performed (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, 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.

trackEventCategory:eventName:sessionID: is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (NSString*) - The name of the category of this event. This parameter is optional (send NULL if not required.).

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

sessionID (NSString*) - 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 null.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* RUI_SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED                               A required New Registration has failed, and hence the SDK is aborted.  StopSDK and DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED                           SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY         The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.

(RUIRESULTOBJC) trackEventCategory: (NSString*)eventCategory eventName: (NSString*)eventName withNumeric: (NSNumber*)customValue sessionID: (NSString*)sessionID

Logs a normal event with the supplied data, including a custom numeric 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 thanspace characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

trackEventCategory:eventName:withNumeric:sessionID: can be called between startSDK and stopSDK:, and can be called zero or more times.

trackEventCategory:eventName:withNumeric:sessionID: can be called while a New Registration is being performed (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, 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.

trackEventCategory:eventName:withNumeric:sessionID: is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (NSString*) - The name of the category of this event. This parameter is optional (send null if not required).

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

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

sessionID (NSString*) - 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 null.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* RUI_SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED                               A required New Registration has failed, and hence the SDK is aborted.  StopSDK and DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED                           SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY         The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.

(RUIRESULTOBJC) trackEventCategory: (NSString*)eventCategory eventName: (NSString*)eventName withText: (NSString*)customValue sessionID: (NSString*)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 thanspace characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

trackEventCategory:eventName:withText:sessionID: can be called between startSDK and stopSDK:, and can be called zero or more times.

trackEventCategory:eventName:withText:sessionID: can be called while a New Registration is being performed (i.e. createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, 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.

trackEventCategory:eventName:withText:sessionID: is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (NSString*) - The name of the category of this event. This parameter is optional (send null if not required).

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

customValue (NSString*) - A string custom value related to this particular event. Server defined maximum is 4096 UTF-8 characters.


sessionID (NSString*) - 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 null.

Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* RUI_SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED                               A required New Registration has failed, and hence the SDK is aborted.  StopSDK and DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED                           SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY         The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.

(RUIRESULTOBJC) trackEventCategory: (NSString*)eventCategory eventName: (NSString*)eventName withNameValuePairs: (NSArray*)customValue sessionID: (NSString*)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 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 thanspace characters (' ') are removed.
* Conditioning: Trimmed to a maximum of 128 UTF-8 characters.
* Validation: eventCategory can be empty; eventName cannot be empty.

trackEventCategory:eventName:withNameValuePairs:sesionID: can be called between startSDK and stopSDK:, and can be called zero or more times.

trackEventCategory:eventName:withNameValuePairs:sesionID: can be called while a New Registration is being performed (createConfig:productID:appName:serverURL:protocol:aesKeyHex:multiSessionEnabled:reachOutOnAutoSync:, 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.

trackEventCategory:eventName:withNameValuePairs:sesionID: is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

Parameters:

eventCategory (NSString*) - The name of the category of this event. This parameter is optional (send null if not required).

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

customValue (NSArray*) - A NSArray custom of name/value pairs to this particular event. Server defined maximum length for name and value is 128 UTF-8 characters each. A convenience type is available for name/value pairs

@interface RUINameValuePairOBJC : NSObject <NSCopying>
@property(nonatomic, copy) NSString* className;
@property(nonatomic, copy) NSString* methodName;
@property(nonatomic, copy) NSString* exceptionMessage;
@property(nonatomic, copy) NSString* stackTrace;
-(id)init;
-(id)initWithClassName:(NSString*)className methodName:(NSString*)methodName exceptionMessage:(NSString*)exceptionMessage stackTrace:(NSString*)stackTrace;
-(id)copyWithZone:(NSZone*)zone;
-(void)dealloc;
@end
sessionID (NSString*) - 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 null.

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


Return Type:

Integer constant value with the following possible values:

* RUI_OK                                        Synchronous functionalitysuccessful
* RUI_SDK_INTERNAL_ERROR_FATAL                  Irrecoverable internal fatal error.  No further API calls should be made.
* RUI_SDK_ABORTED                               A required New Registration has failed, and hence the SDK is aborted.  StopSDK and DestroySDK are possible.
* RUI_SDK_SUSPENDED                             The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED                  The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT                             Instance has been instructed by the application to opt-out.
* RUI_CONFIG_NOT_CREATED                        Configuration has not been successfully created.
* RUI_SDK_NOT_STARTED                           SDK has not been successfully started.
* RUI_SDK_ALREADY_STOPPED                       SDK has already been successfully stopped.
* RUI_INVALID_SESSION_ID_EXPECTED_EMPTY         The sessionID is expected to be empty, and it was not.
* RUI_INVALID_SESSION_ID_EXPECTED_NON_EMPTY     The sessionID is expected to be non-empty, and it was not.
* RUI_INVALID_SESSION_ID_TOO_SHORT              The sessionID violates its allowable minimum length.
* RUI_INVALID_SESSION_ID_TOO_LONG               The sessionID violates its allowable maximum length.
* RUI_INVALID_SESSION_ID_NOT_ACTIVE             The sessionID is not currently in use.
* RUI_INVALID_PARAMETER_EXPECTED_NON_NULL       Some API parameter is expected to be non-NULL, and is not.
* RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY      Some API parameter is expected to be non-empty, and is not.
* RUI_INVALID_PARAMETER_EXPECTED_NO_WHITESPACE  Some API parameter is expected to be free of whitespace, and is not.