BBM Platform

Provides access to the BBM Social Platform.

Required BBM Version

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

Authorization

Applications must first obtain access to the platform by calling 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+

View Supported Platform Table

APIOS 5.0OS 6.0OS 7.0PlayBookRipple
register Y Y Y   
requestUserPermission Y Y Y   
environment Y Y Y   
onaccesschanged Y Y Y   
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 IDOS 5.0OS 6.0OS 7.0PlayBookRipple
<feature id="blackberry.bbm.platform" /> Y Y Y   

Permission Elements (PlayBook Only)
This API does not require a <permission> element to be declared in the configuration document of your BlackBerry WebWorks Application.

API Summary




Properties

register


static void register(options : Object)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Registers for access to BBM Platform.

The application must assign a callback to onaccesschanged before registering. During registration, a dialog will be shown to guide the user through the registration process. The application should wait until 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 then 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.



Parameter Type Description
options Object Options.

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

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

Code Example(s)

<script type="text/javascript">

// Create callback invoked when access changes
blackberry.bbm.platform.onaccesschanged = function(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>

requestUserPermission


static void requestUserPermission(onComplete : Function, connected : Boolean)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Shows a dialog prompting the user to connect this 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 then the application should call register to complete connecting this application to BBM.



Parameter Type Description
onComplete Function Called when the user has finished connecting this application to BBM.
connected Boolean true if the user connected the application to BBM; false otherwise.

Code Example(s)

<script type="text/javascript">

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

</script>

onaccesschanged


static void onaccesschanged(accessible : Boolean, status : String)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Called when the access status changes.

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



Parameter Type Description
accessible Boolean true if access is allowed; false otherwise.
status String 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).
  • "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 register in 30 minutes, or the next time the application starts.
  • "nonuiapp": Access is blocked because 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.

onappinvoked


static void onappinvoked(reason : String, param : blackberry.bbm.platform.self.profilebox.ProfileBoxItem)

Supported Platform(s)

 - BlackBerry OS 5.0+

Description

Called in certain cases when the application is invoked from within BBM. At the moment this event is only triggered by profile box items.

This callback should be assigned before the call to register. If the application is not yet running then it will be launched. This callback will only be invoked once access to the platform is allowed.

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

ProfileBoxItem Invocations

The user can launch the application via profile box items (see blackberry.bbm.platform.self.profilebox). This callback will be invoked with the reason "profilebox" and a blackberry.bbm.platform.self.profilebox.ProfileBoxItem param -- the profile box item which was clicked.



Parameter Type Description
reason String The reason that the application was invoked. If "profilebox" then param is a blackberry.bbm.platform.self.profilebox.ProfileBoxItem.
param blackberry.bbm.platform.self.profilebox.ProfileBoxItem The parameter associated with reason.

Code Example(s)

<script type="text/javascript">

// Trigger an action in the application when a profile box item is selected
blackberry.bbm.platform.onappinvoked = function(reason, param) {
    if(reason == "profilebox") {
        var boxItem = param;
        // Take action based on profile box item...
    }
};

</script>

Properties:


Property Type Description Supported Platform(s)
environment Static
String
readonly
The application environment.
  • "appworld": The application exists in App World.
  • "test": The application does not exist in App World.

 - BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Sun Dec 30 2012 13:31:19 GMT-0500 (EST)