Logging a Custom Event

The trackEventCategory:eventName:withNameValuePairs:sessionID: function logs a normal event with the supplied data, including an array of custom name/value pairs.

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

The trackEventCategory:eventName:withNameValuePairs:sessionID: function can be called while a New Registration is being performed (createConfig, 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.

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

trackEventCategory:eventName:withNameValuePairs:sessionID:

(RUIRESULTOBJC) trackEventCategory: (NSString*)eventCategory eventName: (NSString*)eventName withNameValuePairs: (NSArray*)customValue sessionID: (NSString*)sessionID

Parameters

The trackEventCategory:eventName:withNameValuePairs:sessionID: function has the following parameters.

trackEventCategory:eventName:withNameValuePairs:sessionID: Parameters

Parameter

Description

eventCategory (NSString*)

The name of the category that this event forms part of. This parameter is optional (send empty string if not required).

Unlike V4 of the Usage Intelligence 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.

eventName (NSString*)

The name of the event to be tracked.

Unlike V4 of the Usage Intelligence 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.

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 (multiSessionEnabled = true), this should contain the unique ID that refers to the user session in which the event occurred. It must be a current valid value used in startSession:.

If the application supports only a single session (multiSessionEnabled = false), then this value should be empty.

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

Returns

The trackEventCategory:eventName:withNameValuePairs:sessionID: function returns one of the return status constants below.

trackEventCategory:eventName:withNameValuePairs:sessionID: Returns

Return

Description

RUI_OK

Synchronous functionality successful.

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 Objective-C instance release are possible.

RUI_SDK_SUSPENDED

The Server has instructed a temporary back-off.

RUI_SDK_PERMANENTLY_DISABLED

The 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

Parameter validation: The sessionID is not currently in use.

RUI_INVALID_PARAMETER_EXPECTED_NON_EMPTY

Parameter validation: 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 white space, and is not.