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:

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.


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.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:
<script type="text/javascript">

// Invite to BBM by PIN
var onComplete = function() {
    // Continue...
}
var users = blackberry.bbm.platform.users;
var invitations = [
        { pin:"2100000A", name:"John Doe" },
        { pin:"2100000B", name:"Jane Doe" }
];
blackberry.bbm.platform.users.inviteToBBM(onComplete, invitations);

</script>

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:
<script type="text/javascript">

// Invite to BBM from a specific connection
blackberry.bbm.platform.users.inviteToBBMFromConnections(function () {
    // Continue...
}, connection);

</script>
<script type="text/javascript">

// Invite to BBM from all open connections in the application
blackberry.bbm.platform.users.inviteToBBMFromConnections(function () {
    // Continue...
});

</script>

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:
blackberry.bbm.platform.users.inviteToDownload(function(result) {
    if(result == "limitreached") {
        // Download invitation limit reached
    } else {
        // User is finished inviting
    }
});

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:
blackberry.bbm.platform.users.inviteToDownload();

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:
<script type="text/javascript">

blackberry.bbm.platform.users.pickUsers( {
    title : "Who would you like to chat with?",
    type : "contactswithapp"
}, function(users) {
    if (users.length == 0) {
        // No users picked
    } else {
        // One or more users picked
    }
});

</script>

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:
<script type="text/javascript">

var onFailure = function(reason) {
    var message = getFileFailureString(reason);
    if(message) {
        alert(message);
    }
};    
blackberry.bbm.platform.users.sendFile("file:///SDCard/smiley.jpg", "Check out this file.", onFailure);

function getFileFailureString(reason) {
    if(reason == "filenotfound") {
        return "The file does not exist.";
    } else if(reason == "filetoolarge") {
        return "The file is too large.";
    } else if(reason == "fileforwardlocked") {
        return "The file is DRM protected.";
    } else if(reason == "filebadtype") {
        return "The user is unable to receive files of this type.";
    } else if(reason == "fileempty") {
        return "The file is empty and cannot be sent.";
    } else if(reason == "usercanceled") {
        return "You canceled the file transfer.";
    } else if(reason == "noncontact") {
        return "You may only send files to your BBM contacts.";
    }
};

</script>

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.
After a recipient has both BBM 6.1.0 and the application installed, and the application registers with the BBM Social Platform, the content is sent to the application.

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:
<script type="text/javascript">

// Share content
blackberry.bbm.platform.users.shareContent("A spoon full of sugar", "Mary's Recipe", function() {
				// User finished sharing...
}, { title: "Choose Recipe Recipients" });

</script>
<script type="text/javascript">

// Enable adding the notification symbol to the app's icon when shared content is received
blackberry.bbm.platform.register({
    uuid: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // Randomly generated UUID
    
    shareContentSplat: true
});

</script>

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:
<script type="text/javascript">

// Start chat with Contact Picker dialog
blackberry.bbm.platform.users.startBBMChat(function() {
    // Continue with application...
}, "Did you see the game?");

</script>

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:
<script type="text/javascript">

blackberry.bbm.platform.users.onupdate = function(user, event) {
    // Handle events for the current user
    if(user.handle == blackberry.platform.self.handle) {
        if (event == "displaypicture") {
            var displayPicImg = document.getElementById("myPicture"); // Must have img element with id="myPicture"
            displayPicImg.src = user.displayPicture;
        }
        // Handle other events for the current user...
    }
    // Handle events for other users...
};

</script>

Properties

static readonly blackberry.bbm.platform.users.BBMPlatformUser[] contactsWithApp


Contacts who have the application installed.


Supported Platforms
 - BlackBerry OS 5.0+

Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:11 GMT-0500 (EST)