ReachOutTM direct-to-desktop messaging service

From the on-line customer area 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.
  • Manually retrieving the message (plain text or URL) through code by using the tbMessageCheck() or tbMessageCheckWithMessageType() functions.

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 tbMessageCheck() and tbMessageCheckWithMessageType() is that tbMessageCheck() takes an ‘empty’ messageType parameter and fills it with the type of message that is sent by the server. In the case of tbMessageCheckWithMessageType(), 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:
  • TB_MESSAGETYPE_ALL (0)
  • TB_MESSAGETYPE_TEXT (1)
  • TB_MESSAGETYPE_URL (2)

TBRESULT tbMessageCheck(TBINSTANCE *tbInstance, char *&message, int *messageType)

This function requests a manual ReachOutTM message from the server. This can be either a plain text message or a URL, depending on what messages are waiting on the server.

Parameters:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

message (char*&) - An out parameter that is allocated by the
Revulytics Usage Intelligence SDK and returned to the calling application. This memory must be freed by calling function tbFree() when the application no longer needs the string. Memory is ALWAYS allocated regardless of the return code so the application must ALWAYS call tbFree().
messageType (int*) - This value is filled by the SDK and contains the type of message that is received (can
be either TB_MESSAGETYPE_TEXT or TB_MESSAGETYPE_URL)
Returns:If 0 no message is available on the server. Memory for message is allocated but value is empty. If >0 this is the message count (including this message) of messages on the server (so the remaining messages are this value minus one). If <0, it indicates an error and will be one of the return status constants below:
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_CONN_ERROR (-2)
* TB_AUTH_FAILURE (-3)
* TB_SERVER_ERROR (-4)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

Code Example:

//Linux/Mac OS X example
        TBINSTANCE* tbInstance; //...; //Creation and initialization shown in other snippets.

int message_type;
char* message;
int messageRet = tbMessageCheck(tbInstance, message, &message_type);
if(messageRet > 0){
    printf("This is your message:----%s\n", message);
} else {
    printf("No messages\n");
}
tbFree(message);

TBRESULT tbMessageCheckWithMessageType(TBINSTANCE *tbInstance, char *&message, int 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:

tbInstance (TBINSTANCE*) - The Revulytics Usage Intelligence SDK instance returned in call to tbCreateInstance()

message (char*&) - An out parameter that is allocated by the
Revulytics Usage Intelligence SDK and returned to the calling application. This memory must be freed by calling function tbFree() when the application no longer needs the string. Memory is ALWAYS allocated regardless of the return code so the application must ALWAYS call tbFree.
messageTypeExpected (int) - This value is filled by the developer and should contain the type of
message that is being requested. This must be one of the message types described above.
Returns:If 0 no message is available on the server. Memory for message is allocated but value is empty. If >0 this is the message count (including this message) of messages on the server (so the remaining messages are this value minus one). If <0, it indicates an error and will be one of the return status constants below:
* TB_FUNCTION_NOT_AVAIL (-1)
* TB_CONN_ERROR (-2)
* TB_AUTH_FAILURE (-3)
* TB_SERVER_ERROR (-4)
* TB_APP_CONFIG_NOT_LOADED (-7)
* TB_INVALID_PARAMETER (-9)
* TB_APP_STOPPED (-14)
* TB_INTERNAL_ERROR (-99)

Code Example:

//Linux/Mac OS X example
        TBINSTANCE* tbInstance; //...; //Creation and initialization shown in other snippets.

int message_type_expected = TB_MESSAGETYPE_TEXT;
char* message;
int messageRet = tbMessageCheckWithMessageType(tbInstnace, message, message_type_expected);
if(messageRet > 0){
    printf("This is your message:----%s\n", message);
} else {
    printf("No messages\n");
}
tbFree(message);

void tbFree(void *arg)

This function frees memory that was allocated by the Revulytics Usage Intelligence SDK and returned to the application. Memory allocation occurs in tbMessageCheck(), tbMessageCheckWithMessageType(), tbKeyCheck(), and tbKeyChanged().

NOTE: This function should not be used for general memory management. It should only be called for pointers to memory allocated by the Revulytics Usage Intelligence SDK.

Failing to call tbFree for memory allocated by the Revulytics Usage Intelligence SDK will result in memory leaks.

Parameters:

arg (void*) - A pointer to memory allocated by the Revulytics Usage Intelligence SDK.