Contacts and profiles

The BBM Social Platform provides read and write access to a user’s contacts and BBM profile. Your app can access the personal message, display name, status, status message, and display picture. For more information, see User profiles.

Your app can also update the profile box. A profile box is an area for your app that appears on the Apps tab in the user's BBM profile. It contains the banner and items for your app. You can use a profile box to broadcast achievements and provide updates. For more information, see Profile boxes.

Your app can also invite a user to download another app through the BBM Social Platform. For more information, see Invite to download.

Apps that are installed in the work perimeter can't access the BBM Social Platform APIs. To connect to BBM, your app must be installed in the personal perimeter.

Prerequisites

APIs for using the BBM Social Platform are included in the bbplatformbbm and bbmsp libraries. To use these classes, set the BlackBerry Messenger (bbm_connect) permission in your bar-descriptor.xml file.

Not applicable

Add the BBM (libbbplatformbbm) library to your project.

Add the BBM Social Platform (libbbmsp) library to your project.

Generate a UUID

Each app must define its own Universally Unique Identifier (UUID) so that it can uniquely identify itself. A UUID, also known as a Globally Unique Identifier (GUID), is a unique, 128-bit, 36-character identifier. You can generate one for your app by using a UUID/GUID generator. Your app must provide a UUID when it registers with the BBM Social Platform to access the BBM APIs. The UUID string must conform to the Microsoft 8-4-4-4-12 format (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx). Valid characters consist of hexadecimal values in the ranges 0 to 9 and a to f.

The UUID is also used to identify your app (along with the vendor name and the app name) in the preproduction test environment, before the app is made available in BlackBerry World. If the app is installed from BlackBerry World, the UUID is not used to identify it. You should use the same UUID when testing future releases of the same app. If the UUID changes across versions, different versions of the same app can't communicate with each other in the preproduction environment.

Registration

Connecting to the BBM Social Platform starts with registering your app. The BBM Social Platform APIs are not available for use until the app is registered. When your app is successfully registered with the BBM Social Platform and has access to the APIs, it listens for bbmsp events, determines the event category and type, retrieves any applicable payload data, and processes them.

Not applicable

To connect your app for the first time, create a Context object, passing in the UUID you created, and then call requestRegisterApplication().

#include <bb/platform/bbm/ApplicationPermissions>
#include <bb/platform/bbm/Context>
#include <bb/platform/bbm/RegistrationState>

using namespace bb::cascades;
using namespace bb::platform::bbm;
using namespace bb::system;

// Attempt to register the application with the following UUID.
// You can generate one here: http://www.guidgenerator.com/

const QString m_uuid ( QLatin1String ( "<fill in your UUID>" ));

m_context = new Context(QUuid(m_uuid));
m_context -> requestRegisterApplication();

if ( m_context.isAccessAllowed ()) {
    // Access is allowed, the application is registered.
    return ;
}

Successful registration is indicated when the value of RegistrationState is equal to Allowed and isAccessAllowed() returns true.

To learn more, download the BBM registration sample app from GitHub.

If you are using C, to connect your app for the first time, call bbmsp_register() passing in the UUID you created.

#include <bps/bps.h>
#include <bbmsp/bbmsp.h>

if ( bbmsp_register ( UUID )) {
    // Registration started. The user will see a dialog box
    // informing them that your app is connecting to BBM.
    progress = BBM_PROGRESS_PENDING ;
    return ;
}

Successful registration is indicated when the registration status code is BBMSP_ACCESS_ALLOWED and bbmsp_is_access_allowed() returns true. On start-up your app might receive one of the _CHANGED_ events, indicating that a value has been either initialized or changed.

To learn more, download the sample registration app from the Core Native Community on GitHub.

Best practices

Register your app with the BBM Social Platform when users open your app for the first time. Users are more likely to expect setup activities the first time that they open an app.

Provide nondisruptive reminders when your app is not BBM connected. If users tap a dimmed item (for example, in menus or on buttons on the screen), display a toast to notify that the app isn't connected to BBM and explain how they can connect to BBM.

Invite to download

Your app can invite BBM contacts to download your app from BlackBerry World. A user who is running your app can send an invitation to their contacts through a BBM chat session. The invitation includes a message provided by the app and the user sending the invitation. The chat session also contains buttons for the recipient to accept or decline the invitation. If the recipient accepts the invitation, BlackBerry World opens to show your app.

Not applicable

To invite a user's contacts to download your app, create an instance of the MessageService object and call sendDownloadInvitation(). The user is 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();

To learn more, you can download the BBM Invite to Download sample app from GitHub.

Coming soon

Best practices

Make sure that users are the ones who initiate requests to engage other users. Your app should not initiate requests on a user's behalf. For example, users should initiate requests to send a file, download an app, or invite others to join games, forums, or chats.

Allow users to enter their own text or provide default text in the message or invitation. If you provide default text, don't include ads or spam. Users might be annoyed if they have to delete unnecessary text.

If users send a file, voice note, or image, send only what the user intends to send. Avoid sending ads or spam along with the file, voice note, or image.

Include a contextual link in messages where possible. For example, if a user sends a picture of a landmark, you can include a link to a map that shows where it is located. Otherwise, link to the main screen of the app.

User profiles

Screen showing the BBM Profile Update confirmation dialog box.You can update the user's BBM profile by using the UserProfile API or the set functions in the bbmsp_userprofile API. When you invoke the API, a dialog box appears prompting the user to accept or reject the change.

The following code samples show you how to read from and write to a user's BBM profile.

You can read a user's BBM profile.

Not applicable

Here's how to retrieve a user's profile details and then expose them to QML so they can be read from and written to. Begin by creating a UserProfile object (m_userProfile) by calling UserProfile() and passing in the BBM context object (m_context). The m_context object is an instance of the Context class and provides access to BBM Social Platform functionality. For more information, see Registration.

The user's existing profile data can then be accessed in profile.qml by invoking the C++ UserProfile functions (for example, personalMessage()):

// Retrieve the user profile 
m_userProfile = new bb::platform::bbm::UserProfile(m_context, this);

// Create the qml document and set the 
// profile editor as a context property
QmlDocument *qml = 
    QmlDocument::create("asset:///profile.qml").parent(this);
qml->setContextProperty("_profile", this);

// Retrieve root object for the UI and display it
AbstractPane *root = qml->createRootObject<AbstractPane>();
Application::instance()->setScene(root);

To learn more, you can download the BBM profile sample app from GitHub.

To access the user profile, you need to include the following classes in your app's header file:

#include "bbmsp/bbmsp_userprofile.h"
#include <bbmsp/bbmsp_presence.h>

You can read a user's BBM profile by retrieving the display name. Begin by creating and initializing an empty profile object (m_profile), and then populating it with the user's BBM profile data.

  // Initializes a pointer to the profile object
  bbmsp_profile_t *m_profile = 0;

// Creates the new, empty profile object
  bbmsp_profile_create(&m_profile);

// Populates the object with the user's profile data
  bbmsp_get_user_profile(m_profile);

Next, define a function called read_profile_display_name() and pass in the user's profile data. Because you don't know the length of the user's display name, create an array (displayName) using the maximum allowed length to hold the string. Then call bbmsp_profile_get_display_name() and pass in the profile object, the array, and the array size. If the display name field is not empty, the string is returned in displayName and you print it out. Otherwise, print an error message.

void read_profile_display_name(bbmsp_profile_t *m_profile)
{
    // Creates an array to hold the display name
    char displayName[BBMSP_PROFILE_DISPLAY_NAME_MAX];
    
    // Retrieves the display name,
    // prompts the user to accept/reject,
    // and displays a message accordingly
    if(BBMSP_FAILURE == bbmsp_profile_get_display_name(m_profile, 
        displayName,BBMSP_PROFILE_DISPLAY_NAME_MAX))
    {
      displayName[0] = 0;
      fprintf(stdout, "Error: Failed to get Display Name.\n");
    }
    fprintf(stdout, "BBMSP display name=%s\n", displayName);
}

To learn more, you can download the BBM profile sample app from the Core Native Community on GitHub.

You can write to a user's BBM profile.

Not applicable

Screen showing the updated personal message.As shown in the BBM profile sample app, to update the personal message, you can create a ProfileEditor object for a profile (m_profileEditor).

ProfileEditor is a class (defined in the sample app) that you use to save the updated profile values. You pass in the user profile (m_userProfile).

m_profileEditor = new ProfileEditor(m_userProfile, this);

Saving the personal message in the app invokes profileEditor::savePersonalMessage(). The savePersonalMessage() function invokes requestUpdatePersonalMessage(), which displays a dialog box that prompts the user to accept or reject the change. If the user accepts the change, the new value is written to the profile.

void ProfileEditor::savePersonalMessage
    (const QString &personalMessage)
{
    if (!m_userProfile) // Check that the pointer is still valid
        return;
    // Ask the user if it's OK to update their personal message.
    m_userProfile->requestUpdatePersonalMessage(personalMessage);
}

To learn more, you can download the BBM profile sample app from GitHub.

Screen showing the updated user profile.Because BBM doesn't allow you to change a user's display name, the following code sample demonstrates how to write to a user's BBM profile by changing their personal message. You can see the updated personal message in the image to the right.

First, you define a function, write_profile_personal_message(). Then create an array (message) that contains the new message and pass it in to bbmsp_set_user_profile_personal_message(). The function displays a dialog box that shows the new personal message and prompts the user to accept or reject the change.

If the user accepts the change, bbmsp_set_user_profile_personal_message() writes the new message to the user's profile. Otherwise you print a failure message.

void write_profile_personal_message()
{
  // Creates an array with the new personal message
  char message[46] = 
    "Updated by the BBMSP bps User Profile sample!";
  
  // Sets the personal message, 
  // prompts the user to accept/reject,
  // and displays a message accordingly
  if (BBMSP_FAILURE == bbmsp_set_user_profile_personal_message(message))
  {
    fprintf(stdout, "Failed to update personal message.\n");
  } else
  {
    fprintf(stdout, "Updated BBM SP personal message to:%s.\n",
                      message);
  }
}

To learn more, you can download the BBM profile sample app from the Core Native Community on GitHub.

Best practices

Always ask permission before updating a personal message or status in a user's BBM profile. Don't prompt users to update their display picture because they can't see the picture before it is updated.

If users allow your app to update their personal message, use the personal message field to describe a quality that is attributed to the user (for example, "I am a fan of Word Mole"). To describe a current activity, create a personalized status for the user (for example, "I am playing Word Mole").

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 the BBM Social Platform 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 BlackBerry World.

A profile box is an area for your app that appears on the Apps tab in the user's BBM profile. It contains the banner and items for your app. A profile box consists of the following:

  • Profile box header: the banner inside the profile box that contains the name of the app and its icon
  • Profile box icon: the image in the profile box header
  • Profile box item: the text and the image for each profile box item (for example, a badge and message)

A profile box contains a list of items, each composed of text and an optional icon, and can contain a maximum of three items. As new items are added, older items are removed automatically. Users can control whether an app's profile box appears in their profile through the global settings for the app, and an app can make changes only if users enable this option.

Not applicable

Your app can access the profile box by using the ProfileBox and ProfileBoxItem APIs. You can check whether the profile box should appear in a user's profile by calling permissionValue().

To learn more, you can download the BBM profile box app from GitHub.

Your app can access the profile box by using the bbmsp_user_profile_box API. You can check whether a profile box should appear in a user's profile by calling bbmsp_can_show_profile_box().

The profile box can be viewed by the current user and their contacts. It can be modified by the current user and the app that owns it, but the current user can remove items only. A user can invoke your app from its profile box in theirs or a contact's BBM profile. The app is brought to the foreground, or launched if it's not already running. Contacts who do not have the app installed are taken to the app's page in BlackBerry World, if that version of the app is available on BlackBerry World.

Best practices

Include only new accomplishments or specific activities that are meaningful milestones in a profile box. For example, include notifications such as "Kevin has achieved level 4." Do not use the profile box to promote a feature or a new version of your application.

Provide a short description for each update in the profile box. For example, you could use "Catharina has posted a new playlist. Take a look." If possible, allow users to click a description to get more information. For example, users could click a description to see a playlist. If a link can't open a specific location in the application, link to the main screen of the application.

Include a unique and meaningful icon for the activity or event in the profile box. For example, use a trophy icon to mark noteworthy accomplishments in a game. Avoid shrinking a large picture and using it as an icon. If you don't create icons for each activity or event, then your application icon appears instead.

Create icons that are 119 x 119 pixels. Test the icons on each screen to make sure that the icons, when scaled, still convey the intended meaning.

Contacts

Best practices

Provide filter options for contacts, if possible and if meaningful to the task. For example, in a game, allow users to filter the contacts by skill level such as beginner, intermediate, and expert. This approach makes it easier for users to find relevant contacts, especially if they have a lot of BBM contacts.

Allow users to filter contacts by the contact categories that they create in BBM.

Last modified: 2015-07-24



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus