Automated Message Retrieval

The Usage Intelligence V5 SDK provides a default, automated ReachOut handler that works on Windows and macOS. The Java SDK does not have a default ReachOut handler. Developers can override this handler by implementing the ReachOut handler functions with their own code and providing this handler to the setReachOutHandler() function after the creation of the RUISDK object. See the RUIReachOutHandler interface class for more details. In brief, the RUIReachOutHandler interface contains three methods that must be implemented:

Functions Required to Support Custom ReachOut

Function

Description

public void handle(String width, String height, int position, String message)

Responsible for handling the display of the ReachOut message. The parameters are:

width—Width of the window as configured in the ReachOut campaign. Value will be suffixed by P for pixels or % for percentage.
height—Height of the window as configured in the ReachOut campaign. Value will be suffixed by P for pixels or % for percentage.
position—Position where the window should be displayed (1 = top-left, 2 = top-center, 3 = top-right, 4 = middle-left, 5 = middle-center, 6 = middle right, 7 = bottom-left, 8 = bottom-center, 9 = bottom-right).
message—URL to display.

public boolean readyForNext()

Called by the SDK to determine if the handler is ready for the next ReachOut Message. A false return means not ready; true means ready.

public void close()

Called by the SDK on stop or shutdown.

The setReachOutHandler() function sets a custom ReachOut handler. Any previously registered handler, including the default graphical ReachOut handler that may have been registered (SDKImpl()). If handler is NULL, then all parameters are considered to be NULL. Setting a handler to NULL effectively removes the current handler, if any, without setting a new handler.

setReachOutHandler() can be called more than once.

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

setReachOutHandler()

RUIResult setReachOutHandler(RUIReachOutHandler handler)

Parameters

The setReachOutHandler() function has the following parameters.

setReachOutHandler() Parameters

Parameter

Description

handler (RUIReachOUtHandler)

An instance implementing the RUIReachOutHandler interface.

Returns

The setReachOutHandler() function returns a RUIResult enum value with the following possible values

setReachOutHandler() Returns

Parameter

Description

OK

Function 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.

SDK_ALREADY_STARTED

The SDK has already been successfully started.

SDK_ALREADY_STOPPED

SDK has already been successfully stopped.