Starting a Session

The ruiStartSession() function starts an explicit session for event tracking in the SDK. It must be paired with a call to ruiStopSession().

Explicit sessions are allowed only if ruiCreateConfig() was called with multiSessionEnabled = true. When explicit sessions are enabled, a valid sessionID becomes a required parameter to the event tracking APIs, as described in Parameters.

ruiStartSession() can be called between ruiStartSDK() and ruiStopSDK(), and can be called zero or more times.

ruiStartSession() is a synchronous function, returning when all functionality is completed.

ruiStartSession()

RUIRESULT ruiStartSession(RUIINSTANCE* ruiInstance, const char* sessionID)

Parameters

The ruiStartSession() function has the following parameters.

ruiStartSession() Parameters

Parameter	Description
ruiInstance (RUIINSTANCE*)	Pointer to the Usage Intelligence instance created via ruiCreateInstance().
sessionID (const char*)	This parameter should contain a unique ID that refers to the user session that is being started. This same ID should later be used for event tracking. The content of a sessionID 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. • Validation—Cannot be shorter than 10 UTF-8 characters. • Validation—Cannot be longer than 64 UTF-8 characters. The resulting conditioned and validated sessionID must be unique (i.e. not already in use). Note:With the above conditioning, two sessionIDs that differ only by white space or after the 64th character, will not be unique. A sessionID should not be re-used for different sessions.

Returns

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

ruiStartSession() Returns

Return	Description
RUI_OK	Function successful.
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_FUNCTION_NOT_AVAIL	Function is not available.
RUI_SDK_ALREADY_STOPPED	SDK has already been successfully stopped.
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_ALREADY_ACTIVE	The sessionID is already currently in use.