Developer Zone

ReachOut™ direct-to-desktop messaging service

From the Usage Intelligence dashboard you can create ReachOutTM messaging campaigns which 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 2 message delivery options.

  • Automated HTML popup messages are handled entirely by the Revulytics Usage Intelligence library and require absolutely NO coding.
  • Manually retrieving the message (plain text or URL) through code by using the checkForReachOutReturningMessage or checkForReachOutOfType methods.

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 the setReachOutHandler function after the creation of the RUISDK object. See the ruiSDKOBJC.h file for details on the RUIReachOutHandlerOBJC class.In brief, the RUIReachOutHandlerOBJC class must implement the three following methods:

* -(void)handleWidth:(NSString*)width height:(NSString*)height position:(int32_t)position message:(NSString*)message - Handles displaying ReachOut message.
* -(int32_t)getReadyForNext - Called by the RUI SDK to determine if the handler is ready for the next ReachOut message. Return zero if not ready, non-zero if ready.  
* -(void)close - Called by the RUI SDK when the SDK is stopped or shutdown.

(RUIRESULTOBJC) setReachOutHandler: (id<RUIReachOutHandlerOBJC>)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.

setReachOutHandler can be called more than once.

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

Parameters:

handler (id<RUIReachOutHandlerOBJC>) - An instance implementing the RUIReachOutHandlerOBJC interface.
returns:

One of the result codes below:

* RUI_OK - Function successful
* 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. 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 checkForReachOutReturningMessage and checkForReachOutOfType is that checkForReachOutReturningMessage uses an ‘empty’ messageType parameter and fills it with the type of message that is sent by the server, while in the case of 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 integer values:

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

(RUIRESULTOBJC) checkForReachOutReturningMessage: (NSMutableString*)message messageCount:**(*int32_t**)messageCount **messageType: (int32_t*)messageType

Explicitly checks for manual ReachOutTM messages on the RUI Server. checkForReachOutReturningMessage:messageCount:messageType: will check for any manual ReachOutTM message type, whereas checkForReachOutOfType:ReturningMessage:messageCount: will check for ReachOutTMmessages of a specified type.

checkForReachOutReturningMessage:messageCount:messageType: can be called between startSDK and stopSDK:, and can be called zero or more times.

checkForReachOutReturningMessage:messageCount:messageType: is a synchronous function, returning when all functionality is completed.

Parameters:

message (NSMutableString*) - A string pointer that will be filled-in by the SDK with the message
that is sent by the server.

messageCount (int32_t*) - Receives the message count (including returned message).

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

Return Type:

Integer constant. It may contain one of the following values:

* RUI_OK                                        Function successful
* 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.  StopSDK and DestroySDK 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_INVALID_PARAMETER_EXPECTED_NON_NULL       Some API parameter is expected to be non-NULL, and is not.
* 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:

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

//OS X / ObjC Example.
RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.

int32_t messageType = 0;
int32_t messageCount = 0;

NSMutableString* message = [[NSMutableString alloc] init];

RUIRESULTOBJC rc = [mySDK checkForReachOutReturningMessage:message messageCount:&messageCount messageType:&messageType];

if (rc == RUI_OK && messageCount > 0) {
    NSLog(@"This is your message:----%@", message);
} else {
    NSLog(@"No messages");
}
//  [message release];   //Either release or use ARC.

(RUIRESULTOBJC) checkForReachOutOfType: (int32_t)messageType returningMessage: (NSMutableString*)message messageCount: (int32_t*)messageCount

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 messageType parameter, and can be one of the integer values described below.

Parameters:

messageType (int32_t) - This value is filled by the developer and should contain the type of

message that is being requested. This must be one of the following:

* RUI_MESSAGE_TYPE_ANY  (0)
* RUI_MESSAGE_TYPE_TEXT (1)
* RUI_MESSAGE_TYPE_URL  (2)
message (NSMutableString*) - A string pointer that will be filled-in by the SDK with the message
that is sent by the server. This should be released when the application is done with it.

messageCount (int32_t*) - Receives the message count (including returned message).

Return Type:

Integer constant. It may contain one of the following values:

* RUI_OK                                        Function successful
* 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.  StopSDK and DestroySDK 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_INVALID_MESSAGE_TYPE                      The messageType is not an allowable value.
* RUI_INVALID_PARAMETER_EXPECTED_NON_NULL       Some API parameter is expected to be non-NULL, and is not.
* 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:

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

//OS X / ObjC Example.
RUISDKOBJC* mySDK = [[RUISDKOBJC alloc]initRegisterDefaultGraphicalReachOutHandler:YES]; // = ...; //Creation and initialization shown in other snippets.

int32_t messageTypeExpected = RUI_MESSAGE_TYPE_TEXT;
NSMutableString* message = [[NSMutableString alloc] init];
int32_t messageCount = 0;

RUIRESULTOBJC rc = [mySDK checkMessageForType:messageTypeExpected returningMessage:message messageCount:&messageCount];
if (rc == RUI_OK && messageCount > 0) {
    NSLog(@"This is your message:----%@", message);
} else {
    NSLog(@"No messages");
}
//  [message release];   //Either release or use ARC.