Sorry about the red box, but we really need you to update your browser. Read this excellent article if you're wondering why we are no longer supporting this browser version. Go to Browse Happy for browser suggestions and how to update.

Managing your app's BBM settings

Retrieving version information about your app and the BBM SDK

The net.rim.blackberry.api.bbm.platform.profile.UserProfile class provides methods that allow your application to query the version of your application and the version of the BlackBerry Messenger SDK that is installed on a user's BlackBerry device. You can also query net.rim.blackberry.api.bbm.platform.profile.BBMPlatformContact to obtain the same information about the user's contacts. You can use this information to determine whether your application is compatible between users.

To retrieve the version of your application that is installed on a user's BlackBerry device, invoke getAppVersion() on the userProfile object that represents the user's BBM profile.

String myTpaVersion = myUserProfile.getAppVersion();

To retrieve the version of your application that is installed by a user's contact, invoke getAppVersion() on a BBMPlatformContact object that represents the contact's BBM profile.

String tpaVersion = contact.getAppVersion();

// Use the application version information to determine the compatibility
// of your application between users. 

if (myTpaVersion > tpaVersion)
{
     Dialog.alert("Unable to start game. Contact requires a newer version
      of the application.");
)

To retrieve the version of the BlackBerry Messenger SDK that is installed on a user's BlackBerry device, invoke getBBMSDKVersion() on the userProfile object that represents the user's BBM profile.

int myBbmSdkVersion = userProfile.getBBMSDKVersion();

To retrieve the version of the BlackBerry Messenger SDK that is installed by a user's contact, invoke getBBMSDKVersion() on a BBMPlatformContact object that represents the contact's BBM profile.

int bbmSdkVersion = contact.getBBMSDKVersion();

// Use the SDK version information to determine BBM platform compatibility
// between BlackBerry devices
    
if (myBbmSdkVersion > bbmSdkVersion)
{
    Dialog.alert ("Unable to share content. Contact requires a newer
     version of the BlackBerry Messenger SDK");
}

Retrieving application menu items from a BlackBerry device

The net.rim.blackberry.api.bbm.platform.ui.MenuItemManager class provides methods that allow your application to retrieve the menu items that your application has added to a user's BlackBerry device. The net.rim.blackberry.api.bbm.platform.ui.InvitationMenuItem class encapsulates a menu item's information, for example, ID, order, label, and message.

To retrieve individual menu items, invoke MenuItemManager.getMenuItem() and pass in the menu item ID. If no menu item exists, the method returns null. To retrieve all menu items, invoke MenuItemManager.getMenuItems(), which returns an array of InvitationMenuItem[] items.

// Retrieve all menu items

InvitationMenuItem[] menuItems = _menuItemMgr.getMenuItems();

// Display the menu items

myScreen.add(new LabelField("The existing menu items are:"));

for(int i = 0; i < menuItems.length; i++)
{
    myScreen.add(new LabelField(menuItems[i].getId() + ": " + menuItems[i].getLabel()));
}

if (menuItems.length = 0)
{
    myScreen.add(new LabelField("There are no menu items to display."));
}    

Retrieving the profile box settings for your app

The net.rim.blackberry.api.bbm.platform.SettingsManager class allows your application to obtain a user's setting for the profile box for your application. For example, you can determine whether your application's profile box is enabled or disabled.

To obtain the status of the profile box for your application, you must first obtain your application's SettingsManager object by invoking getSettingsManager() on your application's BBMPlatformContext object.

To determine the status of the profile box setting, invoke SettingsManager.getSetting() and specify SETTING_PROFILE_BOX as the field to return.

If the profile box for your application is disabled, you can prompt the user to enable your application's profile box by invoking requestAppSettings() on your application's BBMPlatformContext object.

private static void alertIfNotShowingProfile()
{
    // Obtain the value of the profile box setting

    final SettingsManager settingsMgr = context.getSettingsManager();
    final int profileBoxSetting = settingsMgr.getSetting
     (SettingsManager.SETTING_PROFILE_BOX);

    // If the setting is disabled, ask the user to change the setting

    if(profileBoxSetting == SettingsManager.VALUE_DISABLED)
    {
        if(Dialog.D_OK == Dialog.ask(Dialog.D_OK_CANCEL,
         "Would you like this application to appear in your profile?"))
        {
            // If the user agrees, prompt the user to go to the options screen

            context.requestAppSettings();
        }
    }
}

Retrieving the public connections setting for your app

The net.rim.blackberry.api.bbm.platform.SettingsManager class provides a constant, SETTING_ALWAYS_ALLOW_PUBLIC_CONN, that allows your app to determine whether a user has chosen to be prompted before they make or join a public connection.

To retrieve this setting, you must first obtain your application's SettingsManager object by invoking getSettingsManager() on your application's BBMPlatformContext object.

To determine the status of the public connections setting, invoke SettingsManager.getSetting() and specify SETTING_ALWAYS_ALLOW_PUBLIC_CONN as the field to return.

int value = SettingsManager.getSetting(SettingsManager.SETTING_ALWAYS_ALLOW_PUBLIC_CONN);

if(value == SettingsManager.VALUE_ENABLED)
{
    // User will not be prompted
}
else if(value == SettingsManager.VALUE_PROMPT)
{
    // User will be prompted
}

Prompting the user to change the BBM settings for your app

The net.rim.blackberry.api.bbm.platform.BBMPlatformContext interface provides a method, requestAppSettings(), that allows your application to bring its BBM options screen to the foreground so that the user can adjust the settings for the application. This is useful when the application requires certain settings, such as a connection to BBM or to display a profile box in the user’s BBM profile.

// Prompt the user to enable the profile box setting

private static void alertIfNotShowingProfile() 
{
    // Retrieve the settings manager associated with the application
    final SettingsManager settings = context.getSettingsManager();
    
    // Retrieve the profile box setting
    final int profileBoxSetting = 
     settings.getSetting(SettingsManager.SETTING_PROFILE_BOX);

    // If the profile box setting is disabled, ask the user to change the setting
    if(profileBoxSetting == SettingsManager.VALUE_DISABLED) 
    {
        if(Dialog.D_OK == Dialog.ask(Dialog.D_OK_CANCEL, "You have not enabled this
           application to appear in your profile. Would you like to enable it?")) 
        {
            // If the user agrees, bring up the BBM options screen
            try  
            {
                context.requestAppSettings();
            } 
            catch(ControlledAccessException e) 
            {
                // Code that runs when the BBM platform access status is not
                // ACCESS_ALLOWED or is ACCESS_BLOCKED_BY_USER
            }
        }
    }
}

Obtaining information about how your app is invoked from within BBM

You can use BBMPlatformContextListener.appInvoked() to capture how your app was invoked from within BlackBerry Messenger and to gather related data, such as the current user, contact, PPID, and profile box items. You can use this information to learn how the BBM features that are integrated into your app are being used. For example, you might want to change the behavior of your app so that it opens in the context in which it is typically invoked, such as when displaying an achievement list in a user's profile box. It can also help you to determine the importance of these features to your app.

The following table shows the contextual information that BBMPlatformContextListener.appInvoked(reason, param, user) can capture with each reason constant:

Reason constant

App is invoked when the current user clicks

Param

User

INVOKE_PROFILE_BOX_ITEM

A user's profile box item for the application

The UserProfileBoxItem that was clicked

The user whose profile box item was clicked (might be the current user)

INVOKE_PROFILE_BOX

A user's profile box header for the application

null

The user whose profile box was clicked (might be the current user)

INVOKE_PERSONAL_MESSAGE

The app's personal message link in a contact's profile

The personal message string (excluding the link to the app)

The contact whose personal message link was clicked

INVOKE_CHAT_MESSAGE

The link to the app in a contact's chat message

null

The contact whose chat message link was clicked

Let's take a look at a few scenarios

public appInvoked(final int reason, final Object param, final Presence user)
{
    /* Scenario 1: The current user clicks a contact’s profile box header 
     * for the app. */

        if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX)
        {
            int ppid = getPPID(user);

            /* Add code to capture all the items in the current user's profile box
             * for the app, for example, activities and achievements) /*
        }

    /* Scenario 2: The current user clicks a contact’s profile box item for the app.
     * The app can capture whose profile box was clicked, and the associated profile
     * box item. */

        if(reason == BBMPlatformContext.INVOKE_PROFILE_BOX_ITEM)
        {
            Int ppid = getPPID(user);
            UserProfileBoxItem item = (UserProfileBoxItem) param;

            // display the profile box item, for example, a game score

            int score = Integer.parseInt(item.getCookie());
        }

    /* Scenario 3: The current user clicks a contact’s personal message link
     * in a contact's profile. The app can capture whose personal message 
     * was clicked and the personal message (minus the app link).*/

        if(reason == BBMPlatformContext.INVOKE_PERSONAL_MESSAGE)

        {
            int ppid = getPPID(user);
            String personalMessage = (String) param;
        }

    /* Scenario 4: The current user clicks a contact’s chat message link
     * in a contact's chat message. The app can capture whose chat message 
     * link was clicked.*/

        if(reason == BBMPlatformContext.INVOKE_CHAT_MESSAGE)
        {
            int ppid = getPPID(user);

            //  Add code to start an activity with the contact
        }
}

// A generic function to obtain a user's unique ID

public static int getPPID (Presence user)
{
    if (user instanceof UserProfile)
    {   // returns the current user's PPID
        return ((UserProfile) user).getPPID();
    }
    else if(user instanceof BBMPlatformContact)
    {   // returns the contact's PPID
    return ((BBMPlatformContact) user).getPPID();
    }
}