Logging a Custom Event

The trackEventCustom() function logs a normal event with the supplied data, including an array of custom name/value pairs.

The trackEventCustom() function can be called between startSDK() and stopSDK(), and can be called zero or more times.

The trackEventCustom() 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 trackEventCustom() function 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).

trackEventCustom()

RUIResult trackEventCustom(String eventCategory, String eventName, List<RUINameValuePair> customValues)

RUIResult trackEventCustom(String eventCategory, String eventName, List<RUINameValuePair> customValues, String sessionID)

Parameters

The trackEventCustom() function has the following parameters.

trackEventCustom() Parameters

Parameter	Description
eventCategory (String)	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 (String)	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.
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 (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 ruiStartSession. If the application supports only a single session (multiSessionEnabled = false), then this value should be empty.

Returns

The trackEventCustom() function returns one of the return status constants below.

ruiTrackEventCustom() Returns

Return	Description
OK	Synchronous functionality 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 Server has instructed a permanent disable.
SDK_SUSPENDED	The 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_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 non-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.