Logging a Normal Event with a String Field

The RUISDK.TrackEventText function logs a normal event with the supplied data, including a custom string field.

The RUISDK.TrackEventText function can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

The RUISDK.TrackEventText function can be called while a New Registration is being performed (RUISDK.CreateConfig, RUISDK.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 RUISDK.TrackEventText function is an asynchronous function, returning immediately with further functionality executed on separate thread(s).

RUISDK.TrackEventText

RUIResult RUISDK.TrackEventText (String eventCategory, String eventName, String customValue, String sessionID = “”)

Parameters

The RUISDK.TrackEventText function has the following parameters.

RUISDK.TrackEventText Parameters

Parameter

Description

eventCategory (String)

The name of the category of this event. This parameter is optional (set to string.Empty or null 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.

customValue (String)

A text custom value related to this particular event. Trimmed to a maximum length determined by the Server. Current default maximum is 4096 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 RUISDK.StartSession.

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

Returns

The RUISDK.TrackEventText function returns a RUIResult enum value with the following possible values.

RUISDK.TrackEventText Returns

Return

Description

ok

Function successful.

sdkInternalErrorFatal

Irrecoverable internal fatal error. No further API calls should be made.

sdkAborted

A required New Registration has failed, and hence the SDK is aborted. RUISDK.StopSDK and RUISDK destructor are possible.

suspended

Instance has been instructed by Server to back-off. Will return to Running once back-off cleared.

permanentlyDisabled

Instance has been instructed by Server to disable. This is permanent, irrecoverable state.

sdkOptedOut

Instance has been instructed by the application to opt-out.

configNotCreated

Configuration has not been successfully created.

sdkNotStarted

SDK has not been successfully started.

sdkAlreadyStopped

SDK has already been successfully stopped.

invalidSessionIDExpectedEmpty

The sessionID is expected to be empty, and it was not.

invalidSessionIDExpectedNonEmpty

The sessionID is expected to be non-empty, and it was not.

invalidSessionIDTooShort

The sessionID violates its allowable minimum length.

invalidSessionIDTooLong

The sessionID violates its allowable maximum length.

invalidSessionIDAlreadyActive

The sessionID is already currently in use.

invalidParameterExpectedNonEmpty

Some API parameter is expected to be non-empty, and is not.