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 HTML pop-up messages (handled entirely by the Revulytics Usage Intelligence library and requires absolutely NO coding.) Currently this is only available on Windows and Mac OS X.
  • Manually retrieving the message (plain text or URL) through code by using the RUISDK.CheckForReachOut or RUISDK.CheckForReachOutOfType functions.

Automated Message Retrieval

The RUI V5 SDK provides a default, automated ReachOutTM handler that works on Windows and Mac OS X. Developers can override this handler by implementing the ReachOutTM handler interface with their own code and providing this handler to the RUISDK.SetReachOutHandler function after the creation of the RUISDK object. In brief, the RUIReachOutHandler class has three abstract methods that must be implemented:

  • abstract public void Handle(String width, String height, Int32 position, String message) - responsible for handling (displaying) 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.
  • abstract public int GetReadyForNext() - called by the RUI SDK to see if the handler is ready for the next ReachOut message. A zero value indicates not ready, non-zero indicates ready.

  • abstract public void Close() - called by RUI SDK when stopping or shutting down the SDK.


RUIResult RUISDK.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 (RUISDK). Setting a handler to NULL effectively removes the current handler, if any, without setting a new handler.

RUISDK.SetReachOutHandler can be called more than once.

RUISDK.SetReachOutHandler 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.
* sdkInternalErrorFatal                  Irrecoverable internal fatal error.  No further API calls should be made.
* sdkSuspended                           The RUI Server has instructed a temporary back-off.
* sdkPermantelyDisabled                  The RUI Server has instructed a permanent disable.
* sdkOptedOut                            Instance has been instructed by the application to opt-out.
* sdkAlreadyStarted                      SDK has already been successfully started.
* sdkAlreadyStopped                      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 RUISDK.CheckForReachOut and RUISDK.CheckForReachOutOfType is that RUISDK.CheckForReachOut takes an ‘empty’ messageType parameter and fills it with the type of message that is sent by the server. In the case of RUISDK.CheckForReachOutOfType, 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 RUISDK.CheckForReachOut (out String message, out Int32 messageCount, out Int32 messageType)

Explicitly checks for manual ReachOutTM messages on the RUI Server. RUISDK.CheckForReachOut will check for any manual ReachOutTM message type, whereas RUISDK.CheckForReachOutOfType will check for ReachOutTM messages of a specified type.

RUISDK.CheckForReachOut can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.CheckForReachOut is a synchronous function, returning when all functionality is completed.

Parameters:

message (out 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 (out Int32) - Receives the message count (including returned message).

messageType (out Int32) - Receives the type of returned message. Can be either ‘text’ or ‘url’ from the ref:RUIMessageType enum.

Return Type:

RUIResult enum value with the following possible values:

* 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.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI 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.
* timeThresholdNotReached                The API call frequency threshold (set by the RUI Server) has not been reached.
* networkConnectionError                 Not able to reach the RUI Server.
* networkServerError                     Error while communicating with the RUI Server.
* networkResponseInvalid                 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
bool registerDefaultReachOut = true;
String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";
RUISDK mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);
// Other initialization.....

string message = "";
Int32 msgType;
Int32 msgCount = 0;

while (mySDK.CheckForReachOut(out message, out msgCount, out msgType) == RUIResult.ok &&
       msgCount > 0) {
    if (msgType == (Int32)RUIMessageType.text) {
        MessageBox.Show("TEXT Message" + message);
    } else if (msgType == (Int32)RUIMessageType.url){
        MessageBox.Show("URL Message" + message);
    }
}

RUIResult RUISDK.CheckForReachOutOfType (String message, out Int32 messageCount, Int32 messageTypeExpected)

Explicitly checks for manual ReachOutTMmessages on the RUI Server. RUISDK.CheckForReachOutOfType will check for manual ReachOutTMmessages of the specified type, whereas RUISDK.CheckForReachOut will check for manual ReachOutTMmessages of any type.

RUISDK.CheckForReachOutOfType can be called between RUISDK.StartSDK and RUISDK.StopSDK, and can be called zero or more times.

RUISDK.CheckForReachOutOfType is a synchronous function, returning when all functionality is completed.

Parameters:

message (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 (out Int32) - Receives the message count (including returned message).

messageTypeExpected (Int32) - 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.
* 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.  StopSDK and RUISDK destructor are possible.
* suspended                              Instance has been instructed by RUI Server to back-off.  Will return to Running once back-off cleared.
* permanentlyDisabled                    Instance has been instructed by RUI 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.
* invalidMessageType                     The messageType is not an allowable value.
* timeThresholdNotReached                The API call frequency threshold (set by the RUI Server) has not been reached.
* networkConnectionError                 Not able to reach the RUI Server.
* networkServerError                     Error while communicating with the RUI Server.
* networkResponseInvalid                 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.

bool registerDefaultReachOut = true;
String ruiSDKDLLPath = "<path to Revulytics Usage Intelligence SDK .NET library>";
RUISDK mySDK = new RUISDK(registerDefaultReachOut, ruiSDKDLLPath);
// Other initialization.....

String message = "";
Int32 msgCount = 0

while (mySDK.CheckForReachOutOfType(out message, out msgCount, (Int32)RUIMessageType.text) == RUIResult.ok &&
       msgCount > 0) {
    MessageBox.Show(message);
}