BlackBerry Java to BlackBerry 10 Cascades Porting Series – Part 12: BBM

Java Development

BlackBerry Java Porting Guide for BBM

Most features of the BlackBerry Messenger Social Platform on BlackBerry Java are also available on BlackBerry 10. The following chart summarizes the feature sets:

TITLE_IMAGE

The features supported on both BlackBerry OS 5-7 and BlackBerry 10 are cross compatible as well, meaning a BlackBerry 10 user could send an invite to download request to a BlackBerry OS 5-7 user and it can work. As a developer, you’re application doesn’t need to be aware of the version of the remote user. The important factor for this to function is that both applications must use the same product and SKU in BlackBerry World. Let’s take a look at these features individually and see how they can be applied to BlackBerry 10.

Registration

Registration is the first step in connecting to the BBM Social Platform on both BlackBerry OS 5-7 and BlackBerry 10. It involves the application registering itself with the BlackBerry hosted BBM infrastructure. Keep in mind that like most features on a BlackBerry, the user can approve or deny this connection, allowing them to regulate which applications they allow to use the BBM SP. The application is also informed during this process whether or not the connection was a success. If it did fail, the application is given the reason why. Possible reasons include lack of network coverage, registration blocked by the user, or BBM Client not configured. Once this step is complete, the more interesting APIs of the BBM SP are available to your application. A sample called BBMRegistration is available on the BlackBerry Github site, which demonstrates BBM SP registration.

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. The chat session also contains buttons for the user to accept or decline the invitation. If they accept the invitation, BlackBerry App World is opened to show your application. This feature is ideal for multi-user applications or games, allowing the user to easily invite their contacts to participate.

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

Invite to download is one of the easiest features to implement. After you’ve registered, you can do this with just 2 lines of code. The first line instantiates the MessageService object and the second kicks off the invite to download process. The user would then be prompted to select the BBM contacts they want to send the invitation to.

m_messageService = new bb::platform::bbm::MessageService(
				m_context, this);
m_messageService->sendDownloadInvitation();

We have a complete sample for this feature as well, called BBMInviteToDownload.

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. The screenshot above shows the confirmation prompt that appears when an application attempts to update a user’s personal message. The screenshot is taken from BlackBerry 10, but a similar prompt also exists for BlackBerry OS 5-7.

Profile updates are visible from the devices of my contacts. They can see a list of recent updates made to my profile and provide yet another opportunity for viral growth. If an update to my 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. Note the “from BBM SDK Demo” tag beside the red arrow. Users can click on that tag to download the application from BlackBerry App World. This requires the sender to have installed the application from App World, so that tag won’t take you to App World if you side loaded your application for testing.

,p>Let’s take a look at how to update the personal message and status. The first step is to get an instance of the user’s BBM profile.

m_userProfile = new bb::platform::bbm::UserProfile(m_context, this);

With that, we can update the user’s BBM personal message or status. Here’s how we can do both with just 3 lines of code.

QString personalMessageString = "Best app ever!";

m_userProfile->requestUpdatePersonalMessage(personalMessageString);

m_userProfile->requestUpdateStatus(false, statusMessageString);

The boolean false being passed into requestUpdateStatus is the flag to set the free/busy indicator shown beside their BBM status. If we had updated their status to something like “Don’t bug me I’m busy playing Slingshot 5000” we’d likely set that to true.

For a complete sample application that performs various profile updates, refer to out bbmprofile sample.

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 user’s contacts can also use this to download the application from App World.

To start this process, grab an instance of ProfileBox.

m_profileBox = new bb::platform::bbm::ProfileBox(m_context, this);

If you wish to use a custom image in your ProfileBoxItem the image must be registered first. Refer to the BBMQtProfileBoxSample for some sample code on how to do that. If not, you can just populate the ProfileBoxItem with some text like this:

QString m_text = "Hello";

m_profileBox->requestAddItem(m_text, QString("cookie"));

Download the bbmprofilebox sample to try this out.

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. An application could pick up on changes to individual contacts to trigger some event. For example if someone gets a new high score a game, they may broadcast it to the user’s BBM contacts by changing their BBM personal message. An application could listen for this update and use it to trigger an in-game challenge to beat their friend’s new high score.

You could also use this to trigger in game connections. A user could enter a game and indicate they want to play against their friends. The game could update the user’s BBM status to something like “Mark wants to play Slingshot 5000 with someone”. By listening to BBM status updates, Mark’s contacts who, are also in game could be prompted to join for some head to head action.

Step one is to get an instance of the ContactService.

m_ContactService = new 
bb::platform::bbm::ContactService(m_context, this);

Once we have that we can retrieve the BBM contacts that also have the same application installed. The sample code below prints out the display name of all contacts retrieved to the BlackBerry Native SDK console.

if (m_ContactService->contactCount() > 0)
{
	foreach (const Contact &contact, m_ContactService->contacts())
	{
		qDebug() << contact.displayName();
	}
}

To listen for updates to a user’s contact list and/or the contacts themselves, we can connect a slot to the contactListUpdated and/or contactUpdated signals. Here’s an example of connecting them to handleUpdateContactList and handleUpdateContact slots.

QObject::connect(m_ContactService, SIGNAL(contactListUpdated()), this, SLOT(handleUpdatedContactList()));

QObject::connect(m_ContactService, SIGNAL(contactUpdated(const QString)), this, SLOT(handleUpdatedContact()));

The handlers would take care of updated any in application resources that reference the users BBM Contacts.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus