• The SDK provides a service of hosting friends.

Initialization parameters

• Not all initialization parameters are listed here. Please refer to Initialize the SDK, and initialization parameters are given in other chapters.

  • Initialization parameters for connection
  • Initialization parameters for multi-device login
  • Initialization parameters for messages
  • Initialization parameters for a team
  • Initialization parameters for user profile
  • Initialization parameters for friendship
  • Initialization parameters for user relationship
  • Initialization parameters for a session
  • Initialization parameters for system notifications
  • Synchronization completed
  • Complete initialization codes

• Please refer to Process system notification for friends related logics.

Sample codes

javascriptvar nim = NIM.getInstance({
    onfriends: onFriends,
    onsyncfriendaction: onSyncFriendAction
});
function onFriends(friends) {
    console.log('receive a list of friends', friends);
    data.friends = nim.mergeFriends(data.friends, friends);
    data.friends = nim.cutFriends(data.friends, friends.invalid);
    refreshFriendsUI();
}
function onSyncFriendAction(obj) {
    console.log(obj);
    switch (obj.type) {
    case 'addFriend':
        console.log('you added a friend at other devices' + obj.account + ', postscript' + obj.ps);
        onAddFriend(obj.friend);
        break;
    case 'applyFriend':
        console.log('you applied to add a friend at other devices' + obj.account + ', postscript' + obj.ps);
        break;
    case 'passFriendApply':
        console.log('you passed a friend application at other devices' + obj.account + ', postscript' + obj.ps);
        onAddFriend(obj.friend);
        break;
    case 'rejectFriendApply':
        console.log('you rejected a friend application at other devices' + obj.account + ', postscript' + obj.ps);
        break;
    case 'deleteFriend':
        console.log('you deleted a friend at other devices' + obj.account);
        onDeleteFriend(obj.account);
        break;
    case 'updateFriend':
        console.log('you updated a friend at other devices', obj.friend);
        onUpdateFriend(obj.friend);
        break;
    }
}
function onAddFriend(friend) {
    data.friends = nim.mergeFriends(data.friends, friend);
    refreshFriendsUI();
}
function onDeleteFriend(account) {
    data.friends = nim.cutFriendsByAccounts(data.friends, account);
    refreshFriendsUI();
}
function onUpdateFriend(friend) {
    data.friends = nim.mergeFriends(data.friends, friend);
    refreshFriendsUI();
}
function refreshFriendsUI() {
    // Refresh The API
}

Parameter description

• onfriends: It is the callback for synchronizing friends list, which will input the Friends list friends.
  • The attribute "invalid" in friends contains a list of deleted friends.
  • It is an increment callback, and nim.mergeFriends and nim.cutFriends can be invoked to merge data.
• onsyncfriendaction: It is the callback for current login user after friends related operations at other devices.
  • Operations include:
    • Add friends
    • Apply for friends
    • Accept friend application
    • Reject friend application
    • Delete friends
    • Update friends
  • The callback will receive a parameter obj of which the field type is operation type. The detailed types are described as below:
    • 'addFriend' is "Add friends". Now, fields of obj include:
      • account is the account that is added friends.
      • friend is the Object of friend that is added friends.
      • ps is postscript.
    • 'applyFriend' is "Apply for friends". Now, fields of obj include the following:
      • account is the account that is applied for friends.
      • ps is postscript.
    • 'passFriendApply' is "Accept friend application". Now, fields of obj include the following:
      • account is the account that is accepted for friend application.
      • friend is the Object of friend that is accepted for friend application.
      • ps is postscript.
    • 'rejectFriendApply' is "Reject friend application". Now, fields of obj include the following:
      • account is the account that is rejected for friend application.
      • ps is postscript.
    • 'deleteFriend' is "Delete friends". Now, fields of obj include the following:
      • account is the account under which friend is deleted
    • 'updateFriend' is "Update friends". Now, fields of obj include:
      • friend is the Object of friend that is updated.
  • You can invoke nim.mergeFriends and nim.cutFriendsByAccounts to merge data.

Object of friend

The object of friend contains fields as below:

• account: Account
• alias: Nickname
• custom: It is the extension field, which can be extended independently by the developer. We recommend packing into JSON character string.
• createTime: It is the time that being friends.
• updateTime: Update time

Add friends

• After being added friends, a certain user will be a friend of current login user without confirmation.
• ps: It is postscript (optional). Developers can also extend the content with JSON character string
• The user will receive a system notification of 'addFriend' type, of which from field is account of the applicant and to field is the account of the acceptor.

javascriptnim.addFriend({
    account: 'account',
    ps: 'ps',
    done: addFriendDone
});
function addFriendDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('directly add friends' + (!error?'succeeded':'failed’));
    if (!error) {
        onAddFriend(obj.friend);
    }
}

Apply to add friends

• After being applied for friends, a certain user will receive a system notification of'applyFriend' type, of which from field is account of the applicant and to field is the account of the acceptor. After receiving friend application, the user can accept or reject the application.
  • If the current login user accepts friend application, the applicant will receive a system notification of 'passFriendApply' type, of which from field is account of the acceptor and to field is account of the applicant.
  • If the user selects to reject friend application, the applicant will receive a System notification of 'rejectFriendApply' type. For such system notification, the field from is account of rejecter and the field to is account of applicant.
• ps: It is postscript (optional). Developers can also extend the content with JSON character string.

javascriptnim.applyFriend({
    account: 'account',
    ps: 'ps',
    done: applyFriendDone
});
function applyFriendDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('apply for friends' + (!error?'succeeded':'failed’));
}

Accept a request of adding friends

• After being applied for friends, a certain user will receive a system notification of'applyFriend' type, of which from field is account of the applicant and to field is the account of the acceptor. After receiving friend application, the user can accept or reject the application.
  • If the current login user accepts friend application, the applicant will receive a system notification of 'passFriendApply' type, of which from field is account of the acceptor and to field is account of the applicant.
  • If the user selects to reject friend application, the applicant will receive a System notification of 'rejectFriendApply' type. For such system notification, the field from is account of rejecter and the field to is account of applicant.
• ps: It is postscript (optional). Developers can also extend the content with JSON character string.

javascript// assumed sysMsg is system notification by calling back `onsysmsg`
nim.passFriendApply({
    idServer: sysMsg.idServer,
    account: 'account',
    ps: 'ps',
    done: passFriendApplyDone
});
function passFriendApplyDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('pass friend application' + (!error?'succeeded':'failed’));
    if (!error) {
        onAddFriend(obj.friend);
    }
}

Reject a request of adding friends

• After being applied for friends, a certain user will receive a system notification of'applyFriend' type, of which from field is account of the applicant and to field is the account of the acceptor. After receiving friend application, the user can accept or reject the application.
  • If the current login user accepts friend application, the applicant will receive a system notification of 'passFriendApply' type, of which from field is account of the acceptor and to field is account of the applicant.
  • If the user selects to reject friend application, the applicant will receive a System notification of 'rejectFriendApply' type. For such system notification, the field from is account of rejecter and the field to is account of applicant.
• ps: It is postscript (optional). Developers can also extend the content with JSON character string

javascript// assumed sysMsg is system notification by calling back `onsysmsg`
nim.rejectFriendApply({
    idServer: sysMsg.idServer,
    account: 'account',
    ps: 'ps',
    done: rejectFriendApplyDone
});
function rejectFriendApplyDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('reject friend application' + (!error?'succeeded':'failed'));
}

Delete friends

• After the current login user Delete friends, the deleted friends will receive a system notification of 'deleteFriend' type, of which field from is account of the user who deletes friends and field to is account of the deleted user.
• Parameter description
  • account is the account that is to delete friends.
  • The parameter delAlias means whether friend remarks will be deleted when a user deletes the friend. The falsemeans that the friend is not deleted by default.

javascriptnim.deleteFriend({
    account: 'account',
    delAlias: true,
    done: deleteFriendDone
});
function deleteFriendDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('delete friends' + (!error?'succeeded':'failed’));
    if (!error) {
        onDeleteFriend(obj.account);
    }
}

Update friends

• The developer can update friend remarks with this API.
• The developer can also extend the content with JSON extension field.

javascriptnim.updateFriend({
    account: 'account',
    alias: 'alias',
    custom: 'custom',
    done: updateFriendDone
});
function updateFriendDone(error, obj) {
    console.log(error);
    console.log(obj);
    console.log('update friends' + (!error?'succeeded':'failed'));
    if (!error) {
        onUpdateFriend(obj);
    }
}

Get a list of friends

• If developers set syncFriends to false in "Initializing SDK", then they cannot get onfriends callback, but can call this API to get the friends list.

javascriptnim.getFriends({
    done: getFriendsDone
});
function getFriendsDone(error, friends) {
    console.log('get friends list' + (!error?'succeeded':'failed'), error, friends);
    if (!error) {
        onFriends(friends);
    }
}