Other Users
Provides access to and interaction with other users. For the current user, see blackberry.bbm.platform.self.
Picking Users
The application can display a Contact Picker to the user with blackberry.bbm.platform.users.pickUsers.
This is generally part of a larger use case. For example, pickUsers()
might be used
so that the current user can select players to remove from a connection.
The Contact Picker will be displayed for all methods in this namespace. The Contact Picker can be avoided in blackberry.bbm.platform.users.sendFile and blackberry.bbm.platform.users.startBBMChat by providing a blackberry.bbm.platform.users.BBMPlatformUser in the method call.
File transfer, invite to download, start a BBM chat, and share content
The current user can send files, invite others to download the application, start a chat in BBM, and share content using the following methods:
- blackberry.bbm.platform.users.sendFile
- blackberry.bbm.platform.users.inviteToDownload
- blackberry.bbm.platform.users.startBBMChat
- blackberry.bbm.platform.users.shareContent
Inviting users to BBM contact list
Inviting users to the current user's contact list is supported. You can invite anonymous users by PIN using blackberry.bbm.platform.users.inviteToBBM. Alternatively you can invite users from open connection(s) using blackberry.bbm.platform.users.inviteToBBMFromConnections.
BBM social graph
Applications can obtain access to the user's social graph. contactsWithApp is a complete list of the current user's BBM contacts who have the application installed.
Applications can listen for changes in the social graph by assigning a callback to blackberry.bbm.platform.users.onupdate. Events are fired for both the current user and their contacts who have the application installed. You can listen for user profile property changes, such as display name and display picture, and also when a user installs/uninstalls your application.
Supported Platform(s)
- BlackBerry OS 5.0+ |
- BlackBerry 10 |
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 | BB5.0 | BB6.0 | BB7.0 | PB1.0 | PB2.0 | BB10 | Ripple |
---|---|---|---|---|---|---|---|
<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
Events
Functions
static
void
blackberry.bbm.platform.users.inviteToBBM
(onComplete : Function, invitations : Object[])
Allows the user to invite users to their BBM contact list. A dialog appears, allowing the user to select users to invite. Users already in the current user's contact list are not shown in the dialog.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
onComplete | Invoked when the user has finished selecting contacts to invite. |
invitations | The pin-name pairs of the users to invite to the BBM Social Platform. |
Throws | |
---|---|
IllegalArgumentException |
If PIN is invalid for any invitation.
|
IllegalArgumentException |
If name is null or empty for any invitation.
|
IllegalArgumentException |
If invitations.length > 24 .
|
Code Example:
|
static
void
blackberry.bbm.platform.users.inviteToBBMFromConnections
(onComplete : Function, [connection : blackberry.bbm.platform.io.Connection])
Allows the user to invite users to their BBM contact list. A dialog appears, allowing the user to select users to invite. Users already in the current user's contact list are not shown in the dialog.
Users from connection
(who are not in the user's contact list) will be shown
in the dialog.
If connection
is not provided, users from all connections that the application
has open (who are not in the user's contact list) are shown in the dialog.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
onComplete | Invoked when the user has finished selecting contacts to invite. |
connection | The connection to invite users from. |
Code Example:
|
|
static
void
blackberry.bbm.platform.users.inviteToDownload
(onComplete: function(result : String))
Allows the user to invite contacts to download the application. A Contact Picker dialog appears, allowing the user to select contacts to invite.
Only contacts who do not have the application installed can be invited to download it.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
onComplete |
Invoked when the user is finished inviting contacts to download the application.
result: "limitreached" if the download invitation limit has been reached;undefined otherwise. A
maximum of 10 download invitations per minute is allowed.
|
Code Example:
|
static
void
blackberry.bbm.platform.users.inviteToDownload
()
Allows the user to invite contacts to download the application. An invitation card appears, allowing the user to select contacts to invite.
Only contacts who do not have the application installed can be invited to download.
Supported Platforms | |
---|---|
- BlackBerry 10 |
Code Example:
|
static
void
blackberry.bbm.platform.users.pickUsers
(options : Object, onComplete: function(users : blackberry.bbm.platform.users.BBMPlatformUser[]))
Shows Contact Picker dialog which allows the user to select users.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
options |
Object containing Contact Picker options.
title: Title of the Contact Picker dialog. type: Type of users to include in the dialog. May be "contactswithapp". users: Users shown in the dialog. multiSelect: true to allow the user to select
multiple users; false to allow only 1.
showSelectAll: true to show the Select All option;
false otherwise. Ignored if options.multiSelect == false .
|
onComplete |
Function called when user is finished.
users: The picked users. users.length == 0 if no users were selected.
|
Code Example:
|
static
void
blackberry.bbm.platform.users.sendFile
(fileURI : String, comment : String, onFailure: function(reason : String), [contact : blackberry.bbm.platform.users.BBMPlatformUser])
Sends a file to a contact. The user will be prompted to edit the comment and choose to send or cancel the file transfer.
If contact
is not provided, the Contact Picker dialog appears,
allowing the user to pick someone in their contact list to send the file to. Otherwise,
the Contact Picker dialog is not shown.
Files can be sent to any contact.
If the contact cannot receive the specific file type, the file will not be sent.
The application is notified of any errors that occur through the onFailure(reason)
callback. The reasons are:
"filenotfound"
: The file transfer failed because the file does not exist."filetoolarge"
: The file transfer failed because the file size exceeds the limit permitted by the BBM Social Platform."fileempty"
: The file transfer failed because the file is empty."fileforwardlocked"
: The file transfer failed because the file is forward-locked."filebadtype"
: The file transfer failed because the recipient is not permitted to receive files of the file type."usercanceled"
: The file transfer failed because the current user canceled the file transfer."noncontact"
: The file transfer failed because the recipient is not one of the user's BBM contacts.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
fileURI | The fully qualified path of the file to send. |
comment | The default comment on the file. The user may edit this comment before sending. |
onFailure |
Invoked if the file transfer fails.
reason: The reason why the transfer failed. |
contact | The recipient of the file. The recipient must be in the current user's contact list. |
Code Example:
|
static
void
blackberry.bbm.platform.users.shareContent
(content : String, description : String, onComplete : Function, [options : Object])
Shares content with a one or more contacts. A Contact Picker dialog appears, allowing the user to select contacts to send the content to.
The content does not appear in BBM; the recipient's application receives the content. The application does not need to be running in order to receive shared content. Once the application is launched and registered with the BBM Social Platform, the callback blackberry.bbm.platform.users.onsharecontent is invoked for the application to handle the content.
Users who do not have BBM 6.1.0 or the application installed
Recipients do not need to have BBM 6.1.0 (or later) or the application installed:
- Recipients who do not have BBM 6.1.0 will be prompted to download the latest version of BBM.
- Recipients who do not have the application installed will receive an invitation to download the application from App World.
Adding the new notification symbol to your app's icon when shared content is received
To notify users about new content, you can enable your app's icon to show the new notification
symbol when shared content is received. To enable the notification symbol, add the property
shareContentSplat: true
to the options object passed into blackberry.bbm.platform.register.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
content | The content to be shared. |
description | A short description of the content. |
onComplete | Invoked when the user has finished selecting content recipients. |
options |
Object containing options for sharing content.
title: Title of the Contact Picker dialog. If not provided, the default title is used. users: Users shown in the dialog. If not provided, all contacts are shown in the dialog. |
Throws | |
---|---|
Exception |
if description is null or greater than 128 characters.
|
Exception |
if content is greater than 61440 characters.
|
Code Example:
|
|
static
void
blackberry.bbm.platform.users.startBBMChat
(onComplete : Function, message : String, [users : blackberry.bbm.platform.users.BBMPlatformUser[]])
Starts a chat within BBM, bringing the chat screen to the foreground and entering a message in the reply field.
If users
is provided, the chat screen is opened immediately; otherwise a Contact
Picker dialog is displayed instead.
Chats can be started with any contact.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
onComplete | Invoked when the chat has been started or canceled. |
message | The initial message in the reply field of the chat screen. |
users | The users to chat with. Must not contain blackberry.bbm.platform.self. |
Code Example:
|
Events
static
void
blackberry.bbm.platform.users.onsharecontent
(sender : blackberry.bbm.platform.users.BBMPlatformUser, content : String, description : String, timestamp : Date)
Invoked when the recipient receives shared content. If the application is not running when content is received, this will be invoked after the application starts and is registers with the BBM Social Platform.
This callback must be assigned before the call to blackberry.bbm.platform.register.
See blackberry.bbm.platform.users.shareContent
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
sender | The user who shared the content. |
content | The content data. |
description | The content description. |
timestamp | Time stamp when the content was received. |
static
void
blackberry.bbm.platform.users.onupdate
(user : blackberry.bbm.platform.users.BBMPlatformUser, event : String)
Invoked when a user's information is updated. Assign a function to receive user updates.
User updates can be captured such as profile information and application installation changes. Updates can be received from the current user, contacts who have the application, and non-contacts who have joined in an application connection with the current user.
"displayname"
: Display name update."displaypicture"
: Display picture update."personalmessage"
: Personal message update."status"
: Status and/or status message update."install"
: User installed or unblocked an application."uninstall"
: User uninstalled or blocked an application."invited"
: The current user received an invitation to join the application in BBM. This only applies to the current user.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |
Parameters | |
---|---|
user | The user whose information was updated. |
event | The type of update. |
Code Example:
|
Properties
static
readonly
blackberry.bbm.platform.users.BBMPlatformUser[]
contactsWithApp
Contacts who have the application installed.
Supported Platforms | |
---|---|
- BlackBerry OS 5.0+ |