Integrate with BBM and Watch Your Application Go Viral
How to Integrate Your Native Application with BBM
How to Integrate Your BlackBerry WebWorks Application with BBM

Now let’s take a look at how you can use the invocation framework to invoke BlackBerry Messenger and bring cards from BBM into your application. In case the term card is new to you, let me explain. Think of cards as a screen of another application that is shown within your application and acts like a screen in your own app. A card becomes part of the flow that makes up BlackBerry® 10, allowing for a seamless user experience that prevents the user from having to switch applications.

The code samples used in this blog post are in QML, but keep in mind that you can use these invocation features from C++, BlackBerry® WebWorks™ and Adobe® AIR®.

Below is a screenshot of the actions available that you could use in the menu of your application to invoke BBM. The “BBM Invocation” text you see below represents your application screen (it actually says BBM Invocation Sample). Each BBM card is going to be displayed on top of it. At any time the user can peek back to see your applications screen or close the card completely, returning to your application screen.

Let’s take a look at each of these cards individually, see how they’re invoked and what they look like once invoked.

Start a BBM Chat

InvokeActionItem {
    title: "Start BBM Chat"
    query {
        invokeActionId: "bb.action.BBMCHAT"
        uri: "pin:2100000a"
    }
}

The code above shows how to initiate a BBM chat. The chat window will flow into your application as a card. In the example above, a single PIN is used. If you omit the URI parameter, the user will be prompted to choose a contact from their BBM contact list to include in the chat session. If a chat session already exists with the contact, it will be shown with previous messages populated.

Set BBM Avatar Image

InvokeActionItem {
    title: "Set BBM Avatar Pic"
    query {
        invokeTargetId: "sys.bbm.imagehandler"
        invokeActionId: "bb.action.SET"
        uri: "file:///path/to/the/file.png"
    }
}

You can prompt the user to change their BBM avatar image to one specified by your application. This triggers a card that previews the image and allows the user to crop or zoom. Once the user is happy with their selection, they click Save to update their BBM Avatar.

Invite to BlackBerry Messenger

InvokeActionItem {
    title: "Invite to BBM"
    query {
        invokeActionId: "bb.action.INVITEBBM"
        uri: "pin:2100000A"
    }
}

If you know the BlackBerry PIN for contacts who are not yet BlackBerry Messenger users, you can invite them to BBM by using the BlackBerry.action.INVITEBBM invoke action as shown above. The user can then write a personalized message to their contact before sending the message.

Share Text over BBM

InvokeActionItem {
    title: "Share Text Over BBM"
    query {
        mimeType: "text/plain"
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        data: "This is some text to share."
    }
}

Sharing text over BBM enables your application to start a chat session and populates the message entry field with the text specified in the data section. Just like starting a BBM chat session above, if a previous chat session exists, the message history will be shown.

Share Image over BBM

InvokeActionItem {
    title: "Share Image Over BBM"
    query {
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        uri: "file:///path/to/image/file.png"
    }
}

Sharing an image over BBM works almost the same way as sharing text, except you specify a URI that points to an image file. It brings up a chat card with a message composed and ready to send with the image attached.

Wrapping It Up

For simplicity, the QML code samples above are using hard coded data and URI values. However, in a real application you’d want to use dynamic values based on variables within your application. You can do this using the onTriggered method. Here is an example of its use:

InvokeActionItem {
    title: "Share Text Over BBM"
    query {
        mimeType: "text/plain"
        invokeTargetId: "sys.bbm.sharehandler"
        invokeActionId: "bb.action.SHARE"
        data: "This is some text to share."
    }
    onTriggered: {
        data = "Some new text"
    }
}

When invoked, the sample above would populate the chat session with “Some new text”. In a real application you’d change the “Some new text” string to point to a variable or control in your application.

That concludes the list of BBM cards currently available for BlackBerry 10. As you can see, by using just a few lines of code you can integrate some powerful features like BBM Chat into your application. Invoke away!

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