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.
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+
API | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
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 ID | OS 5.0 | OS 6.0 | OS 7.0 | PlayBook | Ripple |
---|---|---|---|---|---|
<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
Functions
Events
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.
|
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.
|
- BlackBerry OS 5.0+
|