BlackBerry® Messenger (BBM™) is more than just chat! With the release of the BBM Social Platform, we have released a comprehensive set of tools to easily add the power of BBM to your app. This blog post is one in a series focusing on how to easily add social networking features to your app – and there’s no better time to use this knowledge to update your app so that it’s ready for submission to the 2011 BlackBerry® Developer Challenge (particularly the Most Addictive social app using the BBM Social Platform category).

People love to share their accomplishments with their peers. You can design your app to incorporate levels of recognition for various accomplishments by use of some sort of award (e.g. badge, statement, icon, trophy, et cetera). Incorporating awards in your app can be a great way to enable users to promote your app to their peers.

Awards generally consist of an icon and a text string and should convey why they were awarded. The BBM Social Platform easily enables achievement sharing as can be seen in the screenshot below, where you can specify the icon and text for the achievement. The platform then automatically groups them under your application’s custom profile box.

If achievements are not a good fit for your application, there are plenty of situations where users have content that they want to share with their friends that may be more suitable in their profile box as opposed to their status message. This could include their current location as a user travels, the current song a user is listening to, or the current book a user is reading. Other use cases include apps that leverage other platform services; for example, apps that are using BlackBerry Push Service may want to post updates for things like a win from a favorite sports team or an alert for extreme weather conditions. Apps that are using Payment Service for in-app purchase may want to allow the user to share items they bought which may encourage other users to purchase the same items. Alternatively, the achievements themselves, may not necessarily be application achievements but rather personal achievements, such as achieving a fitness or weight loss goal, a career goal, or even a financial goal. The possibilities are endless – and I’m sure you can find a way to leverage this feature in your application!

As a developer, all you need to do is pass an optional (but highly recommended) icon and a string to the platform and, provided that the user has given your app permission to post, the profile box will appear under your app for that user. The profile box is visible to all BBM users whether they have the app or not. Any user who clicks the box without having the app installed will be prompted to download it, expanding your user base through viral distribution. Users who already have the app installed will be prompted to launch it, increasing user engagement.

In the screenshot above, you can see that Nicole has a profile box entitled “Always Happy!” letting everyone know that the application (in this case the BBM SDK Demo) has seen fit to award her with this achievement. The code to accomplish this is seen below in Java® and BlackBerry® WebWorks™.

Java

UserProfile userProfile = platformContext.getUserProfile();
UserProfileBox profileBox = userProfile.getProfileBox();
if (profileBox.isAccessible()) // Ensure that we have permission to access the box
{
	// Each icon used by your application must have a unique ID
int iconId = 1;
EncodedImage icon = EncodedImage.getEncodedImageResource("smiley.png");
profileBox.registerIcon(iconId, icon);
profileBox.addItem(iconId, “Always Happy!");
// A third parameter, cookie (String), can be added to give your app context when launched via the BBMPlatformContextListener listener.
}

BlackBerry WebWorks

To access the tools and get information about other features of the BBM Social Platform, visit our BlackBerry Messenger Developer site. To access the complete sample app demonstrating the code shown here, check out the Knowledge Base article “BBM Social Platform – Drawing Users in with the Profile Box”.

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);
};

With the BlackBerry® Messenger (BBM™) v6.0 client now officially launched, we’re excited to announce that the BlackBerry® Partners Fund’s 2011 BlackBerry® Developers Challenge has just opened submissions for the ‘Most Addictive Social App Using the BBM Social Platform’ competition*! You can now test the apps you’ve been creating with the BlackBerry® Messenger SDK against the gold release of the BBM v6.0 client and submit them to the competition. If you haven’t created an app yet that integrates BBM features, you still have time to get to work. Submissions for the BBM competition close September 23rd and we’ve compiled a list of resources to help you get started:

Three-part webcast series: ‘Integrating with the BBM Social Platform, One Step at a Time’

• Step 1: Viral Distribution and the BBM Contact List
• Step 2: User Profile and Custom Profile Box
• Step 3: BBM Chat and Embedding Chat within your App

Blog posts:

• BBM Social Platform – Help Your App Go Viral!

Tools and Resources:

• Visit the BlackBerry Messenger Social platform landing page to download the latest BBM™ SDK and documentation. You can find the BBM v6.0 gold client in the BlackBerry App World™ storefront.
• Twitterview with Research In Motion® (RIM®) development experts on @BlackBerryDev – Tuesday August 2nd at 2:30pm EDT. Bring your BBM questions!

We look forward to seeing your creative ideas come to life through your apps! Submit your app to the ‘Most Addictive Social App Using the BBM Social Platform’ competition today and be among the first to be considered for an incentive prize package (see the terms and conditions). For more information on this year’s BlackBerry Developer Challenge, see http://www.blackberry.com/developers/challenge.

*No purchase necessary. Submission deadline: 11:59PM EST on September 23, 2011. See Terms and Conditions for complete details and restrictions. Void where prohibited.

The release of the BlackBerry® Messenger (BBM™) Social Platform opens a gigantic world of possibilities to application developers. While some are obvious, such as allowing your users to chat with each other, others may be a little more subtle. This post is the first in a series that will talk about how to easily add social features to your application using the BBM Social Platform. And there’s no better time to update your app! The 2011 BlackBerry Developer Challenge is on, and submissions for the Most Addictive social app using the BBM™ Social Platform category will open later this summer.

One of the greatest benefits of the BBM Social Platform is enabling application developers to access the enormous social graph of their users. Friends often place a much greater level of trust in each other’s suggestions when compared to anonymous reviews and advertisements. With the BBM Social Platform, leveraging this ability to help expand your reach and increase your user base is so simple that I will demonstrate it here.

While you may or may not want to add social features to your app, there is one feature that every app should definitely implement: the “Invite to Download” feature. This feature is so easy to implement – and can have such a great effect on app reach and downloads – that there is really no reason not to take advantage. The idea is simple: The developer adds a button or menu item to their app that allows the user to invite a friend from BBM to download the application. The user, finding the app to be of great utility or enjoyment, decides that this app needs to be shared and selects the “Invite to download” option. Once selected, the user is presented with a list of users from their BBM list. After selecting a user, the rest is out of their hands (and yours), and the platform dutifully goes off and presents the invited user with a message stating that their friend would like them to download an application. Most importantly, it provides a link that will take the user directly to the app in BlackBerry App World™ for a quick and easy download.

What the inviter sees:

What the invitee sees:

All you need to do to enable this feature is to call the following code in Java® or BlackBerry® WebWorks™:

Java
MessagingService messagingService = platformContext.getMessagingService();
messagingService.sendDownloadInvitation();

BlackBerry WebWorks
var result = blackberry.bbm.platform.io.inviteToDownload(onComplete);

The first line for the Java code is just a call to the platform to obtain a reference to the Messaging Service, and isn’t necessary in the BlacKBerry WebWorks implementation. The sendDownloadInvitation() and inviteToDownload() methods are where the magic happens. The platform will automatically show the user a Contact Picker UI field populated with their BBM contacts who do not already have the app installed. The user can select a contact or cancel if they change their mind, either way, control is returned to your app as soon as the user makes a selection. This method should always be called as a response to a specific user request to invite their contacts to download your application.

Be sure to check out the KB article How to – Invite contacts to download your application using the BBM Social Platform for Java and WebWorks for more information, and register for our upcoming three-part Webcast series “Integrating with the BBM Social Platform, One Step at a Time”, where we will cover Download Invitations and more. We’ll follow up this blog post’s corresponding webcast with two more webcasts covering user profiles and embedded chat using the BBM Social Platform. See the details below for more information and register today!

Integrating with the BBM Social Platform, One Step at a Time
Step 1: Viral Distribution and the BBM Contact List
Date: Tuesday, July 19, 2011
Time: 2:00 PM EST / 11:00 AM PST
Register at: http://webcast.streamlogics.com/audience/index.asp?eventid=98450433

Integrating with the BBM Social Platform, One Step at a Time
Step 2: User Profile and Custom Profile Box
Date: Thursday, July 21, 2011
Time: 2:00 PM EST / 11:00 AM PST
Register at: http://webcast.streamlogics.com/audience/index.asp?eventid=69648378

Integrating with the BBM Social Platform, One Step at a Time
Step 3: BBM Chat and Embedding Chat within your App
Date: Tuesday, July 26, 2011
Time: 2:00 PM EST / 11:00 AM PST
Register at: http://webcast.streamlogics.com/audience/index.asp?eventid=87217347

We are proud to announce that the BlackBerry® Messenger (BBM™) Social Platform SDK 1.0 for BlackBerry® WebWorks™ is ready for its first public beta! Now’s the time to experiment with the beta and start thinking about the possibilities of BBM integration in your BlackBerry WebWorks application.

Since this beta version enables on-device testing, developers now have the opportunity to perfect the BBM workflow in their applications ahead of the release.

This beta release is designed to give developers the ability to accomplish the following:

• access and update fields in the user’s profile such as status, avatar and personal message
• create their own custom areas within the user’s profile for promoting recent application activity or storing trophies and achievements
• initiate BBM chats with friends
• initiate file transfers
• the ability to share applications virally with friends in their contact list
• initiate application-to-application background communication through BBM for sending and receiving application instructions, such as moves in a game or any other application state changes

For BlackBerry WebWorks app developers, initiating application-to-application background communication through BBM is particularly relevant. The major difference between the Java® and BlackBerry WebWorks versions of the BBM Social Platform is that Java developers are able to leverage the pre-existing BBM chat fields, adding those Java UI components directly in their applications to support in-app chat. For a BlackBerry WebWorks developer, if you’re enabling BBM chat within the context of your application, you’ll want to leverage the app-to-app background communication functionality for the sending and receiving of messages between two BBM users, then render that chat using the HTML and CSS you define.

To get started, download the beta version of the BBM Social Platform for BlackBerry WebWorks from BlackBerry Developer Zone. Next, compile and sign your app with this new build. For on device testing with this release of the BBM Social Platform SDK, you will need to upgrade to the latest BlackBerry Messenger 6.0 beta available on BlackBerry® Beta Zone.

New to BlackBerry® Beta Zone? No problem – just follow the steps in the blog post announcing support for on-device testing!

To get started with the BBM Social Platform SDK 1.0 for BlackBerry WebWorks and review all the supported features, be sure to check out BlackBerry® Developer Zone’s BBM Social Platform page, and as always, stay tuned to the BlackBerry Developer Blog for more updates on the platform. Don’t forget to read about the release of BBM Social Platform SDK 1.0 for BlackBerry Java!

We look forward to hearing about your experiences using the platform!

After months of development and testing, we’re proud to announce the latest edition of the BlackBerry® Messenger (BBM™) Social Platform SDK 1.0 for Java®! We’d like to thank our dedicated development community for all your hard work and diligent bug reporting, which truly helped to shape the platform.

Now that this release of the SDK has been launched, you can start submitting your applications to the BlackBerry App World™ storefront. Remember, apps using the new BBM Social Platform need the user to have BBM 6 installed, which is currently still in beta. As such, apps received by July 8th, 2011 will be reviewed and, if approved, available for sale when the BBM v6.0.0 app itself is released!

We’ve seen a few changes and refinements to the platform since the last beta refresh and here’s what you can expect to see:

• Added the ability for an application to receive invitations from other users who are not on their contact list.
• Contact picker UI changed to improve selection of multiple contacts and multi-user chat.
• Added the ability to send a “join” invite to a user who does not have the app installed. They will see a download invite and after installing the app will receive a join invite.
• Added a new API to determine whether the app is running on the test platform or production platform.

To get started, download the newest version of the BBM Social Platform SDK 1.0 for Java from BlackBerry® Developer Zone. Next, compile and sign your app with this new build. For on device testing with this release of the BBM Social Platform SDK, you will need to upgrade to the latest BlackBerry Messenger 6.0 beta available on BlackBerry® Beta Zone.

New to BlackBerry® Beta Zone? No problem – just follow the steps in the blog post announcing support for on-device testing!

To get started with the BBM Social Platform and review all the supported features, be sure to check out BlackBerry Developer Zone’s BBM Social Platform page, and as always, stay tuned to the BlackBerry Developer Blog for more updates on the platform. Don’t forget to check out the BBM Social Platform SDK 1.0 for BlackBerry® WebWorks™ (Beta)!

((All the places worldwide where the 32 BlackBerry® Developer Groups are located!)

In what is becoming an annual tradition, I wanted to share some end of year updates and highlight a few of the accomplishments within the BlackBerry developer community in 2010:

• Over 350,000 registered BlackBerry developers! Welcome to more than 150,000 new developers this year alone.
• Thirty-two BlackBerry Developer Groups around the world established themselves and created unique opportunities for developers to learn and network.
• A series of BlackBerry Developer Days were run around the world. (Due to the overwhelming response, we’ll soon be posting a list of 2011 dates, so check back soon!)
• Engaged with you on our social channels. We are now more than 12,000 followers strong on @BlackBerryDev! The Twitter team has enjoyed the opportunity to provide more support, tips and connect directly with you on a daily basis, and they’ll continue to do so in the new year.
• Announced the BlackBerry® PlayBook™ tablet – a new 7” dual core tablet with full support for uncompromised browsing (Flash 10.1 and HTML5) and an exciting set of development platforms. We are also now accepting BlackBerry PlayBook tablet apps in BlackBerry App World™!
• Free BlackBerry PlayBook tablet offer – Click the link for all the details, and see the terms and conditions here.
• Now approving apps for the free BlackBerry PlayBook tablet offer – After announcing the final terms and conditions on December 7, we’ve had over 1,000 vendors register with BlackBerry App World. And now we’re happy to announce that we’ve started approving applications; as soon as the hardware is ready to ship, we’ll send free BlackBerry PlayBook tablets to the vendors with accepted apps (subject, of course, to the full terms and conditions!). Be sure to register for BlackBerry App World and submit your BlackBerry PlayBook tablet apps to qualify!
• Another amazing BlackBerry DEVCON with over 130 sessions and our largest number of attendees ever. Announced the very first BlackBerry DEVCON Asia conference in Bali, Indonesia for January 13-14, 2011.
• The third annual BlackBerry Partners Fund Super App Developer Challenge, showcasing some of the best Super Apps from around the world and distributing over $1.5 million in prizing.
• Kicked off the first official celebration of the BlackBerry Developer recognition program announced at BlackBerry DEVCON 2009, recognizing three great BlackBerry developers from around the world – Bryan Tafel, Peter Strange and Eki Baskoro.
• Announced the BlackBerry® Messenger (BBM™) Social Platform, which will enable applications to take advantage of the unique characteristics of BBM to communicate with friends, family and co-workers. Developers will be able to use a variety of APIs to give their apps read access to BBM contact lists, user profiles and groups.

There was also the launch of numerous developer services, tools and technologies including:

1. BlackBerry App World v2.0, enabling carrier billing and credit card billing in over 70 countries worldwide – including an industry leading webstore that allows purchases to be made directly on the desktop and sideloaded to the device.
2. BlackBerry Advertising Service, enabling new opportunities for developers to generate revenue with their applications.
3. Launched a completely revamped browser on BlackBerry® 6 based on WebKit, with strong support for advanced standards including HTML5 and CSS3.
4. BlackBerry® WebWorks™ SDK, making it easy for web developers to create compelling Super Apps on the BlackBerry platform using HTML5, CSS and JavaScript®. The BlackBerry WebWorks SDK also supports modern web frameworks such as Sencha, PhoneGap, jQuery™ or Dojo™ for both enterprise and consumer-oriented solutions needing advanced web and AJAX functionality.
5. BlackBerry 6, with its new user interface APIs, barcode APIs, and new Super App APIs including integration with Universal Search.
6. BlackBerry Locate service to compliment the BlackBerry® Maps service, allowing developers to easily add context to their applications.
7. BlackBerry Tablet OS SDK for Adobe® AIR® (Windows, Mac and Linux)
8. BlackBerry® Push Service, an essential component of the real-time, always-on experience of BlackBerry smartphones.
9. BlackBerry® Java® Plug-in for Eclipse® and BlackBerry Java Plug-in for Eclipse Tech Preview for Mac OS X, both containing new features that leverage the Eclipse environment and streamline testing with device simulators.
10. BlackBerry Developer Zone Portal, where developers can register and get access to all of the BlackBerry DEVCON 2010 sessions for free!

It has been an incredibly busy and exciting year for the platform and developer relations teams here at Research In Motion® (RIM®). This was a year of making it easier to be a BlackBerry developer – from making it easier to generate revenue through commercial services to removing barriers to getting the tools and leveraging BlackBerry App World. This year also included my first trip to Asia and learning about the growing opportunities for our developer community in that market along with over 180 countries worldwide that sell BlackBerry smartphones.

I am very excited about 2011 and am looking forward to sharing that success with each of you. We will be taking a little time off on the blog until the New Year to celebrate the end of the year and prepare for a stellar 2011. We’ll be back in action the week of January 4th! If you have a chance over the holidays, please post a comment with suggestions or feedback, as we love receiving input from the community.