How to Integrate Your Native Application with BBM

How-to

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 look.

In this next blog post, we’ll cover the technical aspects of how you can use the BBM SP within your application. I’m going to assume that you are using the BlackBerry Native SDK to create a Cascades™ application using the Qt style BBM SP APIs. The same functionality is available at the c level in the style of the BlackBerry Platform Services library. If you are already using BPS within your application, you could use it for BBM SP as well, but in general I recommend using the Cascades BBM SP APIs instead because they’re easier to use.

Testing an application 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.

Configure Your Project

The first step is to configure your project in the BlackBerry Native SDK, adding the BBM SP libraries and permissions.

Open bar-descriptor.xml and click on the General tab. Within bar-descriptor.xml click on the Application tab and check off BlackBerry Messenger in the Permissions box.

TITLE_IMAGE

Now it’s time to add the BBM SP library. Right click on your project and choose Configure -> Add Library. Click Next and filter for BBM. Add the libbbplatformbbm library. Follow the steps in the wizard and add the line below to your .pro file.

LIBS += -lbbplatformbbm
LIBS += -lbbsystem

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 sample called BBMRegistration is available on the BlackBerry github site. It demonstrates BBM SP registration, so have a look at it once you’ve finished reading this section for the complete version of the code snippets used here.

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.

// Attempt to register the application with the following UUID.
//Define your own UUID.  You can generate one here: http://www.guidgenerator.com/
m_uuid = QString::fromUtf8("c0fef20e-5f94-4eb1-be1e-e055f2c2391c");

Next, create a new instance of the BBM platform context.

m_context = new bb::platform::bbm::Context(QUuid(m_uuid));

Now connect the registrationStatusUpdate signal with a slot in your application. In this example, I created slot called registrationStatus.

QObject::connect(m_context, SIGNAL(registrationStateUpdated(bb::platform::bbm::RegistrationState::Type)),
  			this, SLOT(registrationStatus(bb::platform::bbm::RegistrationState::Type)));

Now we’re ready to kick off the BBM SP registration process by calling requestRegisterApplication.

m_context->requestRegisterApplication();

Refer to the BBMRegistrationfor implementation details for the registrationsStatus. Once it receives a status of

case bb::platform::bbm::RegistrationState::Allowed:

our application will be ready to use the rest of the BBM SP APIs described below. Also note m_context used above — it’ll be used throughout the rest of the examples.

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 the user sending the invitation. This is one of the easiest features to implement. After you’ve registered, you can do this with just two 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.

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. To see more, have a look at the BBMProfile sample. Let’s learn how to update the user’s personal and status messages in BBM.

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.

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 three 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.

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.

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.

Wrapping It Up

I hope this helped you get started in implementing some features of the BBM Social Platform into your application, or at least convinced you how easy it is to do. I look forward to seeing your innovative uses of the BBM SP. Your application could be the next one featured on the Connected App Showcase.

Come back next week if you are a BlackBerry® WebWorks™ developer — we’ll have a post similar to this one, but demonstrate these features using the BlackBerry WebWorks APIs.

Join the conversation

Show comments Hide comments
+ -
blog comments powered by Disqus