Buddy List Integration

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 the existing relationships for a logged in user is the first step.

1. Providing an Existing Buddy List

Userplane’s setBuddyList callback function allows you to establish a preset Buddy List for the local user, via Javascript. 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.

Argument Description Required
buddyListArray An array of buddy users

// example of javascript array
[ {displayName:"Patrick", userId:1,group:"Friends"} ]
Yes

Below is an explanation of all the parameters that can/should be provided as a part of a buddy.

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. No, if you don’t provide it a localized “friends” group will be used in the language you select.

Example

onReady = function() {
var buddyList = [ {displayName:"Patrick", userId:1} ];
up.api.setBuddyList( buddyList );
}
up.event.addCallback( up.api.events.READY, onReady );

Confused about callbacks?

2. Capturing when a user becomes a friend within Userplane

Depending on your implementation there may be the possibility for users to promote a user’s relationship from simply talking to actually calling them a “friend”. This “friending” action occurs within the experience and you may or may not want to capture this event on your side and establish them as a friend within your system. The callback mechanism for this is available as a part of the Userplane Callback API and you can implement it to capture this data.

Callback Flow

setFriendStatus( domainID, userID, friendUserID, friend, callID )

Sets whether userID wants friendUserID added or removed from their friend list.

Arguments Value
function setFriendStatus
domainID The identifier for the domain the user is on.
userID The identifier for the user who performed the action.
friendUserID The user to add (or remove).
friend A true or false value that specifies whether the friend user is to be added or removed from their friend list.
callID A unique identifier for this XML call.
xmlData A FORM variable that contains the archive data (example shown below).
Returns nothing

3. Integrating Custom Buddy Additions or Removals

Buddy Lists are automatically updated within Userplane as users accept invites from one another, or, remove one another as buddies. However, if your site has the ability for users to befriend or unfriend one another outside of Userplane functionality, the seamless experience with Userplane is preserved by employing addBuddy and removeBuddy callback functions. These functions ensure that user relationships are updated in your user database when they emerge from Userplane-based events, or vice versa, are updated in Userplane when relationships emerge from your site’s native functionality. The ultimate outcome is that users see (or don’t see) each other in their Buddy List regardless of whether they befriended (or unfriended) one another from within Userplane.

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. If not provided, a localized “friends” group will be used in the language you select.
requestSubscription Boolean set to true to request a subscription between two users Yes

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.addBuddy( 1, "Patrick", 1, true );

     // remove a buddy
     up.api.removeBuddy( 2 );

}
up.event.addCallback( up.api.events.READY, onReady );