Logging a Normal Event with a String Field
You may keep a numeric value, a text value, or a collection of name/value string pairs every time an event is reported. This can be used, for example in the case of ruiTrackEventNumeric(), 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 ruiTrackEventNumeric(), ruiTrackEventText(), and ruiTrackEventCustom() respectively.
The ruiTrackEventText() function logs a normal event with the supplied data, including a custom string field.
The ruiTrackEventText() function can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.
The ruiTrackEventText() function can be called while a New Registration is being performed (ruiCreateConfig(), ruiStartSDK()). 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 ruiTrackEventText() function is an asynchronous function, returning immediately with further functionality executed on separate thread(s).
RUIRESULT ruiTrackEventText(RUIINSTANCE* ruiInstance, const char* eventCategory, const char* eventName, const char* customValue, const char* sessionID)
Parameters
The ruiTrackEventText() function has the following parameters.
Parameter |
Description |
|||||||||||||||
ruiInstance (RUIINSTANCE*) |
Pointer to the Usage Intelligence instance created via ruiCreateInstance(). |
|||||||||||||||
eventCategory (const char*) |
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:
|
|||||||||||||||
eventName (const char*) |
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:
|
|||||||||||||||
customValue (const char*) |
Custom text data associated with the event, cannot be empty. Trimmed to a maximum length determined by the Server. Current default maximum is 4096 UTF-8 characters. |
|||||||||||||||
sessionID (const char*) |
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 ruiTrackEventText() function returns one of the return status constants below.
Return |
Description |
RUI_OK |
|
RUI_INVALID_SDK_OBJECT |
SDK Instance parameter is NULL or invalid. |
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. ruiStopSDK() and ruiDestroyInstance() 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. |