BBM Social Platform – Adding in-app chat to your app

How-to

BBM

Want to allow your app’s users to chat with their contacts without having to leave your app? Add BlackBerry® Messenger (BBM™) Chat! By integrating BBM chat directly into your app, you have the opportunity to create a community of BlackBerry® smartphone users who can get together to socialize and communicate. Adding this social aspect can help increase your app’s reach and maintain its presence, thereby increasing its “stickiness.” (A sticky app is one that users find so useful and engaging that they come back to it over and over again!)

Adding BBM Chat may also increase the discoverability of your app – when people like something, they want to share it with others. Because BlackBerry device users can communicate with any or all of their BBM contacts from within your app, you have a built-in advertising system.

Let’s take a look at a couple of examples:

  • While viewing the latest sports scores in a sports news app, a user starts a BBM chat with fellow fan(s) in his contact list to discuss game highlights.
  • While looking through house listings in a real estate app, a user starts a chat with their real estate agent about a listing that interests them.

You can create a full-screen BBM chat session or embed it into your app’s UI – in the lower half of the screen, for example – allowing users to continue to interact with your app as they chat. Chat messages can be sent from application to application or from application to BBM.

Here are some code samples for Java® and BlackBerry® WebWorks™ to help get you started:

Java

Full screen:

This line of Java code opens a BBM conversation window with the specified message in the ReplyField and opens a Contact Picker UI field populated with the user’s BBM contacts. The user can select one or several contacts to add to the conversation.

platformContext.getUIService().startBBMChat("Let's chat!");

Embedded chat:

The following code sample demonstrates how to create an embedded chat screen.

public class ChatFieldScreen extends MainScreen
{
	private ChatField _chatField; 

	public ChatFieldScreen()
	{
		// Create a field that uses the full height of the manager that contains it.

		Field firstField = null; 

		/* The BottomUpManager allocates space for the bottom fields first, and
		 then allocates the rest of the space to the first field. */

		BottomUpManager bottomUpManager = new BottomUpManager();

		/* Create a chat field that groups messages from the same sender,
		 displays the sender's name, and wraps the messages in bubbles. */

		_chatField = new ChatField(
				MessageListManager.MESSAGE_STYLE_GROUP_MESSAGES_SAME_SENDER |
				MessageListManager.MESSAGE_STYLE_SHOW_SENDER_DISPLAY_NAME,
				MessageListManager.BORDER_STYLE_BUBBLE);

// Add the field that uses the full height of the container, and then the chat                                                                    field.

		bottomUpManager.add (firstField);
		bottomUpManager.add (_chatField);

		add (bottomUpManager);
	}

	// Look for a press of the Enter key, then processes the text in the chat field

	protected boolean keyChar(char key, int status, int time)
	{
        Field fieldWithFocus = getLeafFieldWithFocus();
        ReplyField replyField =  _chatField.getReplyField();

        if (fieldWithFocus == replyField && key == Characters.ENTER)
        	{
            // handle the ENTER key from the embedded chat field
            String msg = replyField.getText().trim();
            	if (msg.length() > 0)
            	{	/* add code to send the message, for example:
            			try {
							sendMessage(msg);
						}
            			catch (DataOverflowException e) {
							 // message cannot be sent
							e.printStackTrace();
					} catch (ContactUnreachableException e) {
							// contact is not reachable
							e.printStackTrace();
							}
				*/
            	}

            replyField.setText(null);  // clear the reply field
            _chatField.toggle();       // hide the reply field
            return true;
        	}
        return super.keyChar(key, status, time);
    }

	/* Create a class to send the message over an existing connection, for example:

private void sendMessage (String msg) throws DataOverflowException, ContactUnreachableException
		{
		BBMPlatformContactList contactList = connection.getContactList();
    		if( connection.getContactList().size() > 0 ) {
       	 	BBMPlatformData data = new BBMPlatformData( msg );
       		connection.sendData( data, contactList );
     		}
		}
	*/
}

BlackBerry WebWorks

HTML chat window elements:

<div id="chatWindow"></div>
<div id="inputArea">
                <textarea id="txtMessage" rows="1"></textarea>
</div>

Styling chat window elements using CSS:

.receive-chatBubble
{
	margin: 4px 20px 0px 4px;
	padding: 0;
	position: relative;
}

#inputArea
{
	border: 1px solid #A5A2A5;
	border-right: 1px solid #A5A2A5;
	background: black;
	background: -webkit-gradient(linear, 0 0, 0 100%, from(#666), to(#1E1B14));
	padding: 5px 3px;
	overflow:auto;
}

Sending an outgoing BBM message via JavaScript:

//Attempt to read the current user's display name from the BBM Client
if ((window.blackberry !== undefined) && (blackberry.bbm.platform !== undefined))
{
	displayName = blackberry.bbm.platform.self.displayName;
}	

//Display the message in the current user's chat window
addMessageToChatWindow(MESSAGE_TYPE_SEND, message, displayName, dt);

if (connType === "session")
{
	conn.broadcast(message);
}
else {
	conn.send(message);
}

Listening for incoming BBM messages via JavaScript:

connection.onBroadcastData = function(user, data)
{
	//Another user in the session has broadcasted a message.
	var displayName = "Unknown", dt = new Date();
	if (user)
	{
		displayName = user.displayName;
	}
	addMessageToChatWindow(MESSAGE_TYPE_RECEIVE, data, displayName, dt);
};

About Brian Z.

Brian joined Research In Motion (RIM) in 2005 working with Independent Software Vendors (ISVs) who specialize in Bluetooth, GPS, multimedia, and gaming. As a senior member of the Developer Relations Team, it's Brian's mandate to not only support the application development efforts for a number of ISVs, but also to act as a voice at RIM for third party application developers. Like RIM, Brian's roots are in the enterprise world, but over the past couple of years he's quickly adapted to the consumer space, and that's where he spends most of his time today.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus