BBM Platform

The BBM Social Platform (BBMSP) provides APIs that allow you to leverage the social features and functionality of BlackBerry Messenger from within your app.

Required BBM Version

BBM Social Platform APIs come with BBM 6.1.0 and later. BBM 6.1.0 is supported on BlackBerry OS 5, 6, and 7.

Authorization

Applications must first obtain access to the platform by calling blackberry.bbm.platform.register.

  • Accessing other namespaces under blackberry.bbm.platform may throw exceptions if not authorized.
  • Authorization may be revoked by the user or server at any time.


Learning Resources:

Download BBM SDK Resources Download the resources required to use the BBM SDK for WebWorks [BlackBerry].
Getting Started Guide Setup the BBM SDK for BlackBerry WebWorks [BlackBerry Developer Resource Center].
Sample Application Guide Get started with the sample application included with the BBM SDK for BlackBerry WebWorks [BlackBerry Developer Resource Center].

Supported Platform(s)

- BlackBerry OS 5.0+
- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.bbm.platform.register           Y 
blackberry.bbm.platform.register Y Y Y       
blackberry.bbm.platform.requestUserPermission Y Y Y       
blackberry.bbm.platform.showBBMAppOptions Y Y Y       
environment Y Y Y       
blackberry.bbm.platform.onaccesschanged Y Y Y       
blackberry.bbm.platform.onaccesschanged           Y 
blackberry.bbm.platform.onappinvoked Y Y Y       

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.bbm.platform" /> Y Y Y     Y 
Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>bbm_connect</rim:permit>
BBM APIs require this permission to be set

Functions

static void blackberry.bbm.platform.register (options : Object)


Registers your app to allow it to access the BBM Social Platform.

The application must assign a callback to blackberry.bbm.platform.onaccesschanged before registering. During registration, a dialog opens and guides the user through the registration process. The application should wait until blackberry.bbm.platform.onaccesschanged is invoked before continuing.

Application in Test Environment

Applications must provide a UUID used to identify the application in the test environment. If the application is in App World, the UUID will not be used. The same UUID should be used for future releases of the same application; otherwise communication between them will not be possible. The UUID must be a randomly generated 36-character UUID. Any UUID generator can be used.


Supported Platforms
 - BlackBerry 10


Parameters
options Options.

uuid: ID used to identify the application in the test environment.

Code Example: 
<script type="text/javascript">

// Create callback invoked when access changes
blackberry.event.addEventListner("onaccesschanged", accessChangedCallback);

function accessChangedCallback(accessible, status) {
    if (status == "unregistered") {
        // App is unregistered, proceed to register
        registerApp();
    } else if (status == "allowed") {
        // Access allowed
    }
    // Listen for other status...
};

function registerApp() {
// Register with the platform
     blackberry.bbm.platform.register({
         uuid: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // Randomly generated UUID
     });
}

</script>

static void blackberry.bbm.platform.register (options : Object)


Registers your app to allow it to access the BBM Social Platform.

The application must assign a callback to blackberry.bbm.platform.onaccesschanged before registering. During registration, a dialog opens and guides the user through the registration process. The application should wait until blackberry.bbm.platform.onaccesschanged is invoked before continuing.

Application in Test Environment

Applications must provide a UUID that will be used to identify the application in the test environment. If the application is in App World, the UUID will not be used. The same UUID should be used for future releases of the same application; otherwise communication between them will not be possible. The UUID must be a randomly generated 36-character UUID. Any UUID generator can be used.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
options Options.

uuid: ID used to identify the application in the test environment.

Throws
IllegalStateException If blackberry.bbm.platform.onaccesschanged is not assigned.
IllegalArgumentException If UUID is not a valid 36-character UUID.

Code Example: 
<script type="text/javascript">

// Create callback invoked when access changes
blackberry.event.addEventListner("onaccesschanged", accessChangedCallback);

function accessChangedCallback(accessible, status) {
    if  (status == "allowed") {
        // Access allowed
    } else if (status == "user") {
        // Access blocked by user
    } else if (status == "rim") {
        // Access blocked by RIM
    }
    // Listen for other status...
};

// Register with the platform
blackberry.bbm.platform.register({
    uuid: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // Randomly generated UUID
});

</script>

static void blackberry.bbm.platform.requestUserPermission (onComplete : Function, connected : Boolean)


Deprecation Notice:

Use blackberry.bbm.platform.showBBMAppOptions

Shows a dialog prompting the user to connect the application to BBM. This will only work if the application is blocked by the user (i.e. access status is "user").

If the user decides to connect, the application should call blackberry.bbm.platform.register to complete connecting the application to BBM.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
onComplete Called when the user has finished connecting the application to BBM.
connected true if the user connected the application to BBM; false otherwise.

Code Example: 
<script type="text/javascript">

// Prompt the user to connect to BBM, and if the user connects, call register()
blackberry.bbm.platform.requestUserPermission(function(allowed) {
    if(allowed) {
        // Register with the platform
        blackberry.bbm.platform.register({
            uuid: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" // Randomly generated UUID
        });
    }
});

</script>

static void blackberry.bbm.platform.showBBMAppOptions (onComplete : Function)


Brings the BBM options screen for the application to the foreground. This method can only be called if the access status is "allowed" or blocked by "user". Otherwise this method does nothing.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
onComplete Called when the user exits the BBM options screen.

Code Example: 
<script type="text/javascript">

blackberry.bbm.platform.showBBMAppOptions(function() {
    // User exited the BBM options screen
});

</script>

Events

static void blackberry.bbm.platform.onaccesschanged (accessible : Boolean, status : String)


Called when the access status changes.

This callback is mandatory and must be assigned before the call to blackberry.bbm.platform.register.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
accessible true if access is allowed; false otherwise.
status The access status.
  • "allowed": Access is allowed.
  • "user": Access is blocked by the user.
  • "rim": Access is blocked by RIM (the application has most likely violated the terms of use).
  • "itpolicy": Access is blocked by IT Policy.
  • "resetrequired": Access is blocked because a device reset is required to use the BBM Social Platform.
  • "nodata": Access is blocked because the device is out of data coverage. A data connection is required to register the application.
  • "temperror": Access is blocked because of a temporary error. The application should try to call blackberry.bbm.platform.register in 30 minutes, or the next time the application starts.
  • "nonuiapp": Access is blocked because blackberry.bbm.platform.register was called from a non-UI application.

    The application must initially register from a UI application because user interaction is required. The application may register from a background application only after the application has been connected in a UI application at least once.

static void blackberry.bbm.platform.onaccesschanged (accessible : Boolean, status : String)


This event is fired by the system. If you want to listen to the event, you can use the blackberry.event.addEventListener function and remove the listener using the blackberry.event.removeEventListener function.
Registers for access to the BBM Social Platform.

The application must assign a callback by adding an event listener blackberry.bbm.platform.onaccesschanged before registering or attemping to use any BBM related functions.


Supported Platforms
 - BlackBerry 10


Parameters
accessible Flag if the BBM Social Platform access is allowed.
status Status message of current BBMSP access.
  • "allowed": Access is allowed.
  • "unregistered": Access is blocked because the application is currently not registered.
  • "pending": Access is pending and being processed.
  • "user": Access is blocked by the user.
  • "rim": Access is blocked by RIM (the application has most likely violated the terms of use).
  • "nodata": Access is blocked because the device is out of data coverage. A data connection is required to register the application.
  • "unexpectederror": Access is blocked because an unexpected error has occured.
  • "invaliduuid": Access is blocked because an invalid UUID was provided when registering.
  • "temperror": Access is blocked because of a temporary error. The application should try to call blackberry.bbm.platform.register in 30 minutes, or the next time the application starts.

Code Example: 
<script type="text/javascript">

// Create callback invoked when access changes
blackberry.event.addEventListner("onaccesschanged", accessChangedCallback);

function accessChangedCallback(accessible, status) {
    if  (status == "allowed") {
        // Access allowed
    } else if (status == "user") {
        // Access blocked by user
    } else if (status == "rim") {
        // Access blocked by RIM
    }
    // Listen for other status...
    };

</script>

static void blackberry.bbm.platform.onappinvoked (reason : String, param : void, user : blackberry.bbm.platform.users.BBMPlatformUser | blackberry.bbm.platform.self)


Called in certain cases when the application is invoked from within BBM.

The param and user parameters are dictated by the invocation reason.

This callback should be assigned before the call to blackberry.bbm.platform.register. If the application is not running, it will be launched. This callback will only be invoked after access to the BBM Social Platform is allowed.

This callback is optional. Applications are not required to handle this type of event.


Supported Platforms
 - BlackBerry OS 5.0+


Parameters
reason The reason that the application was invoked.
param The parameter associated with reason. May be undefined.
user The user whose personal message/profile box/etc. was clicked. May be undefined.

Code Example: 
<script type="text/javascript">

blackberry.bbm.platform.onappinvoked = function(reason, param, user) {
    // User clicked a user's profile box
    if(reason == "profileboxtitle") {
        // e.g. Show detail for user's whole TPA profile box
        
    // User clicked a user's profile box item
    } else if(reason == "profilebox") {
        // e.g. Show the score and trophy represented by a profile box item
        var item = param;
        var score = item.cookie;
    
    // User clicked a user's personal message TPA link
    } else if(reason == "personalmessage") {
        // e.g. Allow the user to comment on the user's personal message in the user's TPA profile
        var personalMessage = param;
    
    // User clicked a contact's chat message TPA link
    } else if(reason == "chatmessage") {
        // e.g. Start an activity with the contact
        
    } 
}

</script>

Properties

static readonly String environment


The application environment.

  • "appworld": The application exists in App World.
  • "test": The application does not exist in App World.


Supported Platforms
 - BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 18:15:42 GMT-0500 (EST)