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.

Sharing content with BBM contacts

Sharing content across different versions of BBM

The BBM platform allows your application to share content with a user's BlackBerry Messenger contacts, even if the contact is not running the same version of BBM. The recipient must have BBM 6.0.1 or later installed on their BlackBerry device to download your application and any content. If the recipient does not have the required version of BBM installed on their BlackBerry device, the BBM platform takes the following action:

BBM version

Action

6.0.0 and earlier

  1. The recipient receives a download invitation to upgrade to BBM 6.0.1 or later.

  2. After upgrading BBM, they receive a download invitation for your application.
  3. After downloading your application, the content is sent when the application registers with the BBM platform at the recipient's end.

6.0.1 without your application installed

  1. The recipient receives a download invitation for your application.
  2. After downloading your application, the content is sent when the application registers with the BBM platform at the recipient's end.

6.0.1 with your application installed and registered

  1. The content is sent to your application.
  2. If your application is not running, a new item notification ( new item notification splat. ) is applied to your application's Home screen icon, and the recipient will receive the message when your application is started up again. For more details, take a look at Notifying a user about a share request when your application is not running.

Share content with a user's BBM contacts

The net.rim.blackberry.api.bbm.platform.service.MessagingService class provides a method that allows your application to share content with a user's BlackBerry Messenger contacts.

To share content, invoke shareContent() on the MessagingService object that is associated with your application and pass in the content that you want to share (for example, a URL), a cookie that is associated with the content, and a title that is displayed in the contact picker UI. By default, shareContent() displays the contact picker with all of the user's BBM contacts. You can use the ignoreList argument to provide a list of contacts that the user can choose to ignore.

// Retrieve the messaging service associated with your application
MessagingService msgService = _platformContext.getMessagingService();

String content = "<content to share>";
String cookie = "<cookie>";

// Provide a list of contacts that the user can choose to ignore
// or pass in null

BBMPlatformContactList igonoreList = new BBMPlatformContactList();
ignoreList.add(pickContact());

msgService.shareContent(content, new BBMPlatformData(cookie), 
                         "Contact Picker Title", ignoreList);


// Create a list of contacts that have your app installed

public BBMPlatformContact pickContact()
{
    UIService uiService = _platformContext.getUIService();
    BBMPlatformContactList bbmPlatformContactList = uiService.showContactPicker(
      "All Contacts", ContactListProvider.BBM_CONTACTS_WITH_APP, false, false);
    BBMPlatformContact platformContact = null;

    if (bbmPlatformContactList != null)
    {
        try
        {
           platformContact = (BBMPlatformContact) 
            bbmPlatformContactList.getAll().nextElement();
        } 
        catch(NoSuchElementException e) 
        {
           // Code that runs if no more elements exist     
        } 
        finally
        {
           return platformContact;    
        }
    } 
    else
    {
        return null;
    }
}

Notifying a user about a share request when your application is not running

You can use the net.rim.blackberry.api.bbm.platform.BBMPlatformContext interface to notify a BlackBerry device user that a request to share content was received while your application was not running. You can configure this behavior when you register your application with the BBM platform by overriding BBMPlatformApplication.getDefaultSettings() and returning SETTING_SHARECONTENT_SPLAT.

public int getDefaultSettings()
{
      return BBMPlatformContext.SETTING_SHARECONTENT_SPLAT;
}

When the BBM platform receives a message from MessagingServiceListener.onShareContentReceived(), a new item indicator ( new item indicator splat. ) is applied to your application's Home screen icon to notify the user that a message is pending. When the user opens your application, the BBM platform passes all queued messages to your application as soon as it registers the MessagingServiceListener with the platform.