DEVELOPERS BLOG

Messaging Out of the Box

BBM Enterprise SDK is now BlackBerry Spark Communications Platform. Learn more, and download it for free at BlackBerry.com/Spark.

The BlackBerry Spark Communications Platform provides a powerful, real-time, and secure messaging framework that can be used for much more than simple peer-to-peer text messaging. Message payloads are fully customizable, allowing an application to share all manner of information amongst groups of users.

Customizable Message Payloads

Each chat message in Spark protocol carries a specific “tag” which can be used to filter messages. Furthermore, the message itself can carry any arbitrary JSON payload, allowing one to communicate all manner of data or meta-data that can be serialized to JSON, in a chat. The data can include anything, such as including base64 encoded binary data, up to a maximum of 70 KB for the message in its entirety (this includes other message properties, the “thumb” for file transfers, etc)

Example: Sharing Location Data

In the Location Sharing example, we take advantage of Spark’s customizable message payload capability to share real-time location updates between chat participants. A custom tag “Location” is defined to identify these application specific data types, and messages are sent with a JSON payload that includes the user’s current location. The application then parses incoming messages, and renders the participant’s location data points on a map.

Send Location Updates to a Chat

To send a location update to a chat, we create a JSON serializable dictionary containing our location data and any other pertinent information. This information is then sent, as a message, to the appropriate chat.

//Construct a dictionary that can be serialize to JSON
NSDictionary *locationData = @{ @"latitude", latitude,
                                @"longitude", longitude }
                                @"userInfo", info }
BBMChatMessageSendMessage *msg = [[BBMChatMessageSendMessage alloc] initWithChatId:chatId tag:@"LocationUpdate"];
//The rawData property can be any dictionary that can serialize to JSON up to a maximum
//size of approximately 70Kb
msg.rawData = locationData;
[[BBMServiceLayer sharedInstance] sendCoreMessage:msg];

Extract Location Updates from a Chat

To handle incoming location specific updates, we create a filtered list of chat messages with the “Location” tag which will be updated automatically for us as new messages arrive.

BBMChatMessageCriteria *locationCriteria = [[BBMChatMessageCriteria alloc] init];
chatMessageCriteria.tag = @"LocationUpdate";
chatMessageCriteria.chatId = chatId; //Where the chatId is the chat we wish to extract the location messages from
NSArray *locationUpdates = [dataModel chatMessageWithCriteria:locationCriteria].observableArray;
for(BBMChatMessage *message in locationUpdates) {
    NSDictionary *locationData = message.rawData;
    NSString *latitude = locationData[@"latitude"]
    NSString *longitude = locationData[@"longitude"]
    NSDictionary *userInfo = locationData[@"userInfo"]
    //Render the location
}

Complete Flexibility

Location data is just one example of a custom message type that can be sent in a chat. The possibilities are endless:

  • A custom message can be inserted into a chat by the initiator whenever a BBM Enterprise audio or video call ends which can then be used to render a call log.
  • An application can observe the user’s calendar and automatically send upcoming meeting notifications in a chat.
  • An application can implement a custom shared whiteboard by sending vector drawing instructions in the message payload

A Note On Reactive Programming

Spark provides a reactive programming framework to facilitate writing User Interfaces that are responsive to changes in the data model. The ObservableMonitor class provides a powerful way of reacting automatically to changes on “observable” properties. By simply wrapping the code that queries for the custom message in a monitor, we can have that code block execute automatically any time the list of messages changes.

self.chatMonitor = [ObservableMonitor monitorActivedWithName:@"locationMessageMonitor" block:^{
    NSArray *locationUpdates = [dataModel chatMessageWithCriteria:locationCriteria].observableArray;
    //The following code will now be run whenever objects are added to the list. The
    //property "observableArray" will trigger this block to run whenever it changes.
}];

In addition to ObservableMonitor, you can add an explicit listener to any LiveList or LiveMap that will run blocks of code on specific operations on that list or use built-in mechanisms such as KVO.

Next Steps

You can download Spark and try the Location Sharing example mentioned above by visiting the BlackBerry Spark Communications Platform developer portal.

About BBM Enterprise SDK Team