Overview
Providing a seamless integration is likely a priority when integrating a third party feature like Userplane. Buddy List integration is where that experience begins. Providing Userplane with a list of existing relationships for the local user is the first step.
Providing an Existing Buddy List
Userplane’s setBuddyList Javascript API function allows you to programmatically set a Buddy List for the local user. Buddy Lists can contain up to 1,000 buddies, but it should be noted that Buddy Lists having a high buddy count ( greater than 200 ) will take longer to load for the user. Due to this performance impact, setBuddyList should only be called under certain circumstances. By default, Userplane calls this function once per hour, or per session, as defined by the Simple-SSO token signature, which includes a timestamp.
setBuddyList( buddyListArray )
Set the Buddy List for the local user.| Argument | Description | Required |
|---|---|---|
| buddyListArray | An array of buddy users | Yes |
Below is an explanation of the properties that should be provided for the buddyListArray.
| Property | Description | Required |
|---|---|---|
| displayName | The displayName of the end user in your roster. | Yes |
| userID | The userId of the end user in your roster. | Yes |
| group | The name of the roster group the user belongs in. | Optional. If not provided, defaults to “Friends”. |
Example
onReady = function() {
var buddyListArray = [ {displayName:"Patrick", userId:"user01", group:"group01"} ];
up.api.buddyList.setBuddyList( buddyListArray );
}
up.api.addEventListener( up.api.events.READY, onReady );
Confused about callbacks?
Pushing Buddy Relationships
If your site has the ability for users to befriend or unfriend one another outside of Userplane functionality, a seamless experience with Userplane is preserved by employing our addBuddy and removeBuddy Javascript API methods. These methods ensure that user relationships that emerge from your site’s native functionality are pushed to the Userplane experience.
up.api.buddyList.addbuddy ( userId, displayName, groupId, requestSubscription )
Adds a buddy to a user’s Buddy List| Property | Description | Required |
|---|---|---|
| userID | The userId of the end user in your roster. | Yes |
| displayName | The displayName of the end user in your roster. | Yes |
| groupId | The ID of the roster group the user belongs in. | Optional. If not provided, defaults to “Friends”. |
| requestSubscription | Boolean set to true to request a subscription between two users | Yes |
up.api.buddyList.removeBuddy ( userId )
Removes a buddy from a user’s Buddy List| Property | Description | Required |
|---|---|---|
| userID | The userId of the end user in your roster. | Yes |
Examples
onReady = function() {
// add a new buddy
up.api.buddyList.addBuddy( "user01", "Patrick", "group01", true );
// remove a buddy
up.api.buddyList.removeBuddy( "user02" );
}
up.event.addCallback( up.api.events.READY, onReady );