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 ruiCheckForReachOut() or ruiCheckForReachOutOfType() 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 functions with their own code and providing these handler functions to the the ruiSetReachOutHandler() function. See the ruiSDKC.h file for details on the functions required to support custom ReachOutTM. The three functions include:

* void (*RUIReachOutHandler)(void* arg, const char* width, const char* height, int32_t position, const char* message) - handles 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.

* int (*RUIReachOutGetReadyForNext)(void* arg) - to handle getting the status of whether the handler is ready for the next ReachOut message. Returns 0 for not ready, non-zero for ready.
* void (RUI_CALLBACK_LINKAGE *RUIReachOutCloser)(void* arg) - called when the SDK is stopping or shutting down.

RUIRESULT ruiSetReachOutHandler(RUIINSTANCE* ruiInstance, RUIREACHOUTHANDLER handler, RUIREACHOUTCLOSER closer, RUIREACHOUTREADYFORNEXT getReadyForNext, void* arg)

Sets a custom ReachOutTM handler. Any previously registered handler, including the default graphical ReachOutTM handler that may have been registered (ruiCreateInstance()). 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.

ruiSetReachOutHandler() can be called more than once.

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

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

handler (RUIREACHOUTHANDLER) - The function to be called when a ReachOutTM is received from the RUI Server.

closer (RUIREACHOUTCLOSER) - The function to be called when the RUI SDK is shutting down.

getReadyForNext (RUIREACHOUTREADYFORNEXT) - The function to be called when the RUI SDK is checking to see if the handler is ready for a new ReachOutTMmessage.

arg (void*) - Data to be passed to handler function and closer function; provides the client a self-managed handle.

Returns:One of the result codes below:
* 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_SUSPENDED - The RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI Server has instructed a permanent disable.
* RUI_SDK_OPTED_OUT - Instance has been instructed by the application to opt-out.
* RUI_SDK_ALREADY_STARTED - The SDK has already been successfully started.
* RUI_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. From within the application 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 the application such as in a status bar or information box. URL type messages can either be opened in a browser or else rendered it in a HTML previewer embedded within the application.

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

The message type can be one of the following constants:

  • RUI_MESSAGE_TYPE_ANY (0)
  • RUI_MESSAGE_TYPE_TEXT (1)
  • RUI_MESSAGE_TYPE_URL (2)

RUIRESULT ruiCheckForReachOut(RUIINSTANCE* ruiInstance, char** message, int32_t* messageCount, int32_t* messageType)

Explicitly checks for manual ReachOutTM messages on the RUI Server. ruiCheckForReachOut() will check for any manual ReachOutTM message type, whereas ruiCheckForReachOutOfType() will check for ReachOutTM messages of a specified type.

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

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

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

message (char**) - Receives the ReachOutTM string allocated by the RUI SDK; must be freed via ruiFree().

messageCount (int32_t*) - Receives the message count (including returned message). A zero (0) return means no message is available on the server.
If messageCount is greater than zero, it indicates the number of messages remaining on the server. No allocation, no ruiFree().
messageType (int32_t*) - This value is filled by the SDK and contains the type of message that is received (can
be either RUI_MESSAGE_TYPE_TEXT or RUI_MESSAGE_TYPE_URL.)
Returns:One of the result codes below:
* 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 RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI 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_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_TIME_THRESHOLD_NOT_REACHED - The API call frequency threshold (set by the RUI Server) has not been reached.
* RUI_NETWORK_CONNECTION_ERROR - Not able to reach the RUI Server.
* RUI_NETWORK_SERVER_ERROR - Error while communicating with the RUI Server.
* RUI_NETWORK_RESPONSE_INVALID - Message format error while communicating with the RUI Server.

Code Example:

bool useDefaultReachOutHandler = false;
RUIINSTANCE* mySDK = ruiCreateInstance(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.

int32_t message_type;
char* message;
int32_t message_count;

RUIRESULT messageRet = ruiCheckForReachOut(mySDK, &message, &message_count, &message_type);

if(messageRet == RUI_OK && message_count > 0){
    cout << "This is your message:----" <<  message << endl;
} else {
    cout << "No messages" << endl;
}
ruiFree(message);

RUIRESULT ruiCheckForReachOutOfType(RUIINSTANCE* ruiInstance, char** message, int32_t* messageCount, int32_t messageTypeExpected)

This function requests a manual ReachOutTM message from the server while specifying the type of message that is needed. The message type needed is to be sent in the messageTypeExpected parameter, and can be one of the message type constants described above.

Parameters:

ruiInstance (RUIINSTANCE*) - Pointer to the RUI instance created via ruiCreateInstance()

message (char**) - Receives the ReachoutTM string allocated by the RUI SDK; must be freed via ruiFree().

messageCount (int32_t*) - Receives the message count (including returned message). A zero (0) return means no message is available on the server.
If messageCount is greater than zero, it indicates the number of messages remaining on the server.
messageType (int32_t) - This value is provided by the application and dictates the type of message that is expected to be received (can
be either RUI_MESSAGE_TYPE_TEXT or RUI_MESSAGE_TYPE_URL)
Returns:One of the result codes below:
* 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 RUI Server has instructed a temporary back-off.
* RUI_SDK_PERMANENTLY_DISABLED - The RUI 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_ALREADY_STOPPED - SDK has already been successfully stopped.
* RUI_TIME_THRESHOLD_NOT_REACHED - The API call frequency threshold (set by the RUI Server) has not been reached.
* RUI_NETWORK_CONNECTION_ERROR - Not able to reach the RUI Server.
* RUI_NETWORK_SERVER_ERROR - Error while communicating with the RUI Server.
* RUI_NETWORK_RESPONSE_INVALID - Message format error while communicating with the RUI Server.

Code Example:

bool useDefaultReachOutHandler = false;
RUIINSTANCE* mySDK = ruiCreateInstance(useDefaultReachOutHandler); //...; //Creation and initialization shown in other snippets.

int32_t message_type_expected = RUI_MESSAGE_TYPE_TEXT;
char* message;
int32_t message_count;

RUIRESULT messageRet = ruiCheckForReachOutOfType(mySDK, &message, &message_count, message_type_expected);

if(messageRet == RUI_OK && message_count > 0){
    cout << "This is your message:----" <<  message << endl;
} else {
    cout << "No messages" << endl;
}
ruiFree(message);

void ruiFree(void* arg)

Frees the memory allocated by the RUI SDK. The APIs that return allocated memory are: ruiGetSDKVersion(), ruiCheckForReachOut(), ruiCheckForReachOutOfType(), ruiCheckLicenseKey(), and ruiSetLicenseKey().

ruiFree() can be called any time and can be called more than once.

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

Parameters:

arg (void*) - Pointer to allocated memory returned by the RUI SDK in one of the above APIs.