Developer Zone

ReachOut™ direct-to-desktop messaging service

From the on-line customer area you can create ReachOut™ 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 ReachOut™ campaign you can choose between 2 message delivery options.

  • Automated HTML popup messages (which is handled entirely by the Usage Intelligence library and requires absolutely NO coding.
  • Manually retrieving the message (plain text or URL) through code by using the checkMessageReturningMessage or checkMessageForType methods.

Manual Message Retrieval

When you want full control on when and where in your application to display a ReachOut™ message to your users, you can define ReachOut™ 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 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 checkMessageReturningMessage and checkMessageForType is that checkMessageReturningMessage uses an ‘empty’ messageType parameter and fills it with the type of message that is sent by the server, while in the case of checkMessageForType, 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:

* TBC_MESSAGETYPE_ALL  (0)
* TBC_MESSAGETYPE_TEXT (1)
* TBC_MESSAGETYPE_URL  (2)

(TBCRESULT) checkMessageReturningMessage: (NSMutableString*)message messageType: (int*)messageType

This function requests a manual ReachOut™ 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:

message (NSMutableString*) - A string pointer that will be filled-in by the SDK with the message
that is sent by the server.
messageType (int*) - This value is filled by the SDK and contains the type of message that is received (can
be either TextMessageType or URLMessageType from the ref:MessageType integer constant).

Return Type:

Integer constant. If 0 or greater, it contains the number of messages remaining on the server. Otherwise, it may contain one of the following values:

* TBC_FUNCTION_NOT_AVAIL ( -1)
* TBC_CONN_ERROR         ( -2)
* TBC_AUTH_FAILURE       ( -3)
* TBC_SERVER_ERROR       ( -4)
* TBC_NOT_STARTED        ( -7)
* TBC_INVALID_PARAMETER  ( -9)
* TBC_APP_STOPPED        (-14)
* TBC_INTERNAL_ERROR     (-99)

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.
TBCTrackerbirdOBJC* tbcInstance; // = ...; //Creation and initialization shown in other snippets.

int messageType = 0;
NSMutableString* message = [[NSMutableString alloc] init];
int messageRet = [tbcInstance checkMessageReturningMessage:message messageType:&messageType];
if (messageRet > 0) {
    NSLog(@"This is your message:----%@", message);
} else {
    NSLog(@"No messages");
}
//  [message release];   //Either release or use ARC.

(TBCRESULT) checkMessageForType: (int)messageType returningMessage: (NSMutableString*)message

This function requests a manual ReachOut™ 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 integer values described below.

Parameters:

messageType (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 following:

* TBC_MESSAGETYPE_ALL  (0)
* TBC_MESSAGETYPE_TEXT (1)
* TBC_MESSAGETYPE_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.

Return Type:

If 0 or greater, it contains the number of messages of the requested type remaining on the server. Otherwise, it can contain one of the following values:

* TBC_FUNCTION_NOT_AVAIL ( -1)
* TBC_CONN_ERROR         ( -2)
* TBC_AUTH_FAILURE       ( -3)
* TBC_SERVER_ERROR       ( -4)
* TBC_NOT_STARTED        ( -7)
* TBC_INVALID_PARAMETER  ( -9)
* TBC_APP_STOPPED        (-14)
* TBC_INTERNAL_ERROR     (-99)

Code Example:

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

TBCTrackerbirdOBJC* tbcInstance; // = ...; //Creation and initialization shown in other snippets.

int messageTypeExpected = TBC_MESSAGETYPE_TEXT;
NSMutableString* message = [[NSMutableString alloc] init];
int messageRet = [tbcInstance checkMessageForType:messageTypeExpected returningMessage:message];
if (messageRet > 0) {
    NSLog(@"This is your message:----%@", message);
} else {
    NSLog(@"No messages");
}
//  [message release];   //Either release or use ARC.