Developer Zone

ReachOutTM direct-to-desktop messaging service

From the Usage Intelligence dashboard, you can create ReachOutTM messaging campaigns that are used to deliver messages or surveys directly to the desktop of users who are running your software. You may choose a specific target audience for your message by defining a set of delivery filters so that each message will be delivered only to those users who match the specified criteria (such as geographical region, edition, version, build, language, OS, license status, runtime duration, days since install, etc.)

When building a ReachOutTM campaign you can choose between two message delivery options.

Automated Message Retrieval

The RUI V5 SDK provides a default, automated ReachOutTM handler that works on Windows and Mac OS X. The Java SDK does not have a default ReachOutTM handler. Developers can override this handler by implementing the ReachOutTM handler interface with their own code and providing this handler to the the setReachOutHandler(RUIReachOutHandler) 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:

  • public void handle(String width, String height, int position, String message) - responsible for handling the display of the ReachOut message. Parameters :

    • 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 RUI 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 RUI SDK on stop or shutdown.


RUIResult setReachOutHandler(RUIReachOutHandler handler)

This function sets a custom ReachOutTM handler. Any previously registered handler, including the default graphical ReachOutTM handler that may have been registered (SDKImpl(boolean)). Setting a handler to NULL effectively removes the current handler, if any, without setting a new handler.

setReachOutHandler(RUIReachOutHandler) can be called more than once.

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

Parameters:

handler (RUIReachOUtHandler) - An instance implementing the RUIReachOutHandler interface.

Return Type:

RUIResult enum value with the following possible values:

* 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 RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI Server has instructed a temporary back-off.
* SDK_OPTED_OUT                Instance has been instructed by the application to opt-out.
* SDK_ALREADY_STARTED          SDK has already been successfully started.
* SDK_ALREADY_STOPPED          SDK has already been successfully stopped.

Manual Message Retrieval

When you want full control on when and where in your application to display a ReachOutTM message to your users, you can define ReachOutTM messages of the type plain text or URL. Then from within your application you can call one of the below functions to check with the Revulytics Usage Intelligence server whether there are any pending messages (of this type) waiting to be delivered.

You may choose to display plain text messages anywhere in your application such as in a status bar or information box. For the URL type messages you can either open the URL in a browser or else render it in some HTML previewer embedded within your application.

The difference between checkForReachOut(MutableObject, MutableInt, MutableObject) and checkForReachOutOfType(MutableObject, MutableInt, MutableObject) is that checkForReachOut(MutableObject, MutableInt, MutableObject) takes an ‘empty’ messageType parameter and fills it with the type of message that is sent by the server. In the case of checkForReachOutOfType(MutableObject, MutableInt, MutableObject), the message type is specified by the developer and the server would then only send messages of that type.

The message type (plain text or URL) can be one of the types from the following RUIMessageType enum:

* ANY  (0)
* TEXT (1)
* URL  (2)

RUIResult checkForReachOut(MutableObject<String> message, MutableInt messageCount, MutableObject<RUIMessageType> messageType)

Explicitly checks for manual ReachOutTM messages on the RUI Server. checkForReachOut(MutableObject, MutableInt, MutableObject) will check for any manual ReachOutTM message type, whereas checkForReachOutOfType(MutableObject, MutableInt, MutableObject) will check for ReachOutTM messages of a specified type. NOTE: MultableInt and MutableObject are from org.apache.commons.lang.mutable

checkForReachOut(MutableObject, MutableInt, MutableObject) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

checkForReachOut(MutableObject, MutableInt, MutableObject) is a synchronous function, returning when all functionality is completed.

Parameters:

message (MutableObject<String>) - A string of maximum length 256 that will be filled-in by the SDK with the message
that is sent by the server.

messageCount (MutableInt) - Receives the message count (including returned message).

messageType (MutableObject<RUIMessageType>) - Receives the type of returned message. Can be either RUIMessageType.TEXT or RUIMessageType.URL.

Return Type:

RUIResult enum value with the following possible values:

* 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 RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI 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_SUSPENDED                Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED              SDK has not been successfully started.
* TIME_THRESHOLD_NOT_REACHED   The API call frequency threshold (set by the RUI Server) has not been reached.
* NETWORK_CONNECT_ERROR        Not able to reach the RUI Server.
* NETWORK_SERVER_ERROR         Error while communicating with the RUI Server.
* NETWORK_RESPONSE_INVALID     Message format error while communicating with the RUI Server.

Code Example:

Get all of the messages on the server, check if it is a text or URL message and display the appropriate message box.

// Create instance
boolean registerDefaultReachOut = false;  // No default ReachOut
RUISDK mySDK = new SDKImpl(registerDefaultReachOut);
// Other initialization including application specific ReachOut handler

MutableObject<String> message = new MutableObject<>("");
MutableObject<RUIMessageType> msgType = new MutableObject<>(RUIMessageType.ANY);
MutableInt msgCount = new MutableInt(0);

while (mySDK.checkForReachOut(message, msgCount, msgType) == RUIResult.OK &&
       msgCount > 0) {
                MutableObject<RUIMessageType> textMsg = new MutableObject<>(RUIMessageType.TEXT);
                MutableObject<RUIMessageTYpe> urlMsg = new MutableObject<>(RUIMessageType.URL);
    if (msgType.equals(testMsg)) {
        //  code to display Text message
    } else if (msgType.equals(urlMsg)){
        // code to display URL
    }
}

RUIResult checkForReachOutOfType(MutableObject<String> message, MutableInt messageCount, MutableObject<RUIMessageType> messageTypeExpected)

Explicitly checks for manual ReachOutTMmessages on the RUI Server. checkForReachOutOfType(MutableObject, MutableInt, MutableObject) will check for manual ReachOutTMmessages of the specified type, whereas checkForReachOut(MutableObject, MutableInt, MutableObject) will check for manual ReachOutTMmessages of any type. NOTE: MultableInt and MutableObject are from org.apache.commons.lang.mutable

checkForReachOutOfType(MutableObject, MutableInt, MutableObject) can be called between startSDK() and stopSDK(int), and can be called zero or more times.

checkForReachOutOfType(MutableObject, MutableInt, MutableObject) is a synchronous function, returning when all functionality is completed.

Parameters:

message (MutableObject<String>) - A string of maximum length 256 that will be filled-in by the SDK with the message
that is sent by the server.

messageCount (MutableInt) - Receives the message count (including returned message).

messageTypeExpected (MutableObject<RUIMessageType>) - This value is filled by the developer and should contain the type of
message that is being requested. This must be one of the RUIMessageType enum values.

Return Type:

RUIResult enum value with the following possible values:

* 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 RUI Server has instructed a permanent disable.
* SDK_SUSPENDED                The RUI 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_SUSPENDED                Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* SDK_NOT_STARTED              SDK has not been successfully started.
* INVALID_MESSAGE_TYPE         The messageType is not an allowable value.
* TIME_THRESHOLD_NOT_REACHED   The API call frequency threshold (set by the RUI Server) has not been reached.
* NETWORK_CONNECT_ERROR        Not able to reach the RUI Server.
* NETWORK_SERVER_ERROR         Error while communicating with the RUI Server.
* NETWORK_RESPONSE_INVALID     Message format error while communicating with the RUI Server.

Code Example:

Get all text messages from the server and display them inside of a message box.

boolean registerDefaultReachOut = false;  // Java SDK has no default handler
RUISDK mySDK = new SDKImpl(registerDefaultReachOut);
// Other initialization.....

MutableObject<String> = new MutableObject<>("");
MultableInt msgCount = new MutableInt(0);
MutableObject<RUIMessageType> msgType = new MutableObject<>(RUIMessageType.TEXT);

while (mySDK.checkForReachOutOfType(message, msgCount, msgType) == RUIResult.OK &&
       msgCount > 0) {
    // code to display TEXT message
}