How to Integrate Your BlackBerry WebWorks Application with BBM

Welcome to part 3 of my series of blog posts discussing the BlackBerry® Messenger (BBM™) Social Platform. My previous blog post, Integrate with BBM and Watch Your Application Go Viral, covered the features of the BlackBerry Messenger Social Platform (BBM SP) and how you can use them to promote your application. If you haven’t read it yet, I recommend giving it a read. Part 2, How to Integrate Your Native Application with BBM, covered use of the BBM SP in a native application.

Now I’m here to talk about how you can integrate your BlackBerry® WebWorks™ application with the BBM SP. Most of what will be covered is available to both BlackBerry® OS 5-7 and BlackBerry® 10 applications. However, at the time of writing some of the BBM SP APIs discussed here are available only for BlackBerry OS 5-7 applications — I’ve noted where this is the case. We are planning on adding these to the BlackBerry 10 WebWorks SDK as well.

Testing a BBM SP application for BlackBerry 10 currently requires a real device. We’re working on adding BBM SP support in the BlackBerry 10 simulator and this should be available before the end of 2012. Support for testing BlackBerry OS 5-7 applications that use BBM SP is supported in many BlackBerry smartphone simulators we have available today, so ensure you download one that lists support for BBM.

Configure Your Project

The BlackBerry 10 WebWorks SDK includes everything you need to get started. If you have a BlackBerry OS 5-7 application, you’ll need to download the BBM SDK v1.1 for BlackBerry WebWorks in addition to the regular BlackBerry WebWorks SDK for Smartphones. Instructions for connecting these two SDK for targeting BlackBerry OS 5-7 can be found in Getting Started: BlackBerry WebWorks Development for Smartphones and the BBM Social Platform.

In order for your application to access to the BBM SP APIs, you’ll need to request the appropriate permissions in your application’s config.xml file. There are two elements you’ll need to add: bbm_connect for rim:permissions and blackberry.bbm.platform for feature. Here is what it looks like:

<rim:permissions>
	<rim:permit>bbm_connect</rim:permit>
</rim:permissions>
<feature id="blackberry.bbm.platform" />

Register with the BBM Social Platform

Registration is the first step in connecting to the BBM Social Platform, which involves an application registering itself with the RIM-hosted BBM infrastructure. A BBM sample is available on the BlackBerry github site that demonstrates BBM SP registration along with the invite to download feature. Have a look at it once you’ve finished reading this section for the complete version of the code snippets used here.

When using BlackBerry WebWorks, the first thing to do is to register for the onaccesschanged event. If you try to register before registering for this, an IllegalStateException is thrown. Here is how you can register for this event:

blackberry.event.addEventListener("onaccesschanged", function (accessible, status) {
	if (status === 'allowed') {
		/* Access allowed. */
	} 
});

This code sample only catches the allowed status. Your application would need to handle disallowed status that could be caused by the user being out of coverage or if the user disallowed access to BBM. The BBM sample demonstrates how to catch the other statuses.

Each application must define its own Universally Unique Identifier (UUID) so that it can uniquely identify itself. This UUID is used to register with the BBM SP servers during testing and development. Applications in the BlackBerry App World™ storefront are assigned their own UUID automatically. You can generate a UUID using various web sites, such as the one here. In BlackBerry WebWorks, the UUID is stored in the options parameter used in registration.

options = {
	uuid: "33490f91-ad95-4ba9-82c4-33f6ad69fbbc"
};

Now we’re ready for the final step in the registration process, which is to call the register method using the options parameter we defined above. This will trigger the onaccesschanged event.

blackberry.bbm.platform.register(options);

Invite to Download

The invite to download feature allows users of your application to invite their BBM contacts to download your application from BlackBerry App World. The recipient receives the invitation through a BBM Chat session, which includes a message provided by the application and user sending the invitation. This is one of the easiest features to implement. After you’ve registered, you can do this with just one method call.

blackberry.bbm.platform.users.inviteToDownload();

Note that for this to work between BlackBerry 10 and BlackBerry OS 5-7 users, the SKU in BlackBerry App World for the two releases of the application (BAR and COD) must be the same.

Profile Integration

BBM SP allows for both read and write access to the user’s BBM profile. This allows your application access to their profile message, status text, availability and avatar image. Here are a few examples of how to use these APIs:

This first code sample shows how to access the image the user has set for their BBM profile.

blackberry.bbm.platform.self.getDisplayPicture(function (image) {
    // do something with the image here
});
Now let’s look at how your application could update the user’s BBM profile picture.
blackberry.bbm.platform.self.setDisplayPicture("local:///smiley.jpg", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});

If an update to a personal message was made from an application other than the BBM Client, a tag is shown under the update stating the name of the application that performed the update. Users can click on that tag to download the application from BlackBerry App World. This requires the sender to have installed the application from BlackBerry App World, so that tag won’t take you to BlackBerry App World if you side loaded your application for testing. Let’s take a look at how to update the personal message and status.

blackberry.bbm.platform.self.setStatus("busy", "Getting a new high score", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});
blackberry.bbm.platform.self. setPersonalMessage ("I’m loving this app!", function (accepted) {
    if(accepted) {
        // User allowed the change
    } else {
        // User denied the change
    }
});

Profile Boxes

Profile Boxes provide yet another way for an application to promote itself to a user’s BBM contacts. They appear within the Apps area of a user’s profile and are ideal for sharing what a user is doing within an application. Every application that is connected to BBM SP appears in the list. Applications can create profile box items that appear under their application header. You can supply a custom image and string, which is used to create the profile box item.

The ability to add a profile box item using BlackBerry WebWorks is not yet supported on BlackBerry 10, but you can do it on BlackBerry OS 5-7. There are C and C++ APIs for populating the profile box on BlackBerry 10, so you could accomplish this by building a custom BlackBerry WebWorks extension.

When creating a profile box item, use of the image is optional. If you don’t wish to include an image, you can omit it from the options variable.

var options = {text:"No one’s ever beat me at solitare!", icon:"local:///cardshark.jpg", cookie:"unbeatable"};
blackberry.bbm.platform.self.profilebox.addItem(options);

Contacts

An application can retrieve a list of BBM Contacts who have the same application installed. This list can be used as selection criteria for connecting for a multi-user experience. Events are also fired for changes to this contact list, allowing your application to keep track of both the addition and deletion of contacts in the contact list itself and/or changes to individual contacts.

Currently, working with BBM contacts is not supported using BlackBerry WebWorks for BlackBerry 10, but there are APIs for WebWorks for BlackBerry OS 5-7 as well as C and C++ APIs for BlackBerry 10. Further support for this in BlackBerry WebWorks for BlackBerry 10 is planned for a December release. Watch the BlackBerry WebWorks roadmap for updates.

Wrapping It Up

That wraps up my intro post for getting started with the BlackBerry Messenger Social Platform using BlackBerry WebWorks. Now it’s up to you to make use of these APIs in your next hit application, which could be featured on the Connected App Showcase.