用户属性

更新时间：2022-02-28

用户属性指实时消息互动用户的信息，如用户昵称、头像、邮箱、电话、性别、签名和生日等。

例如，在招聘场景下，利用用户属性功能可存储性别、邮箱、用户类型（面试者）、职位类型（Web 研发）等。查看用户信息时，可直接查询服务器存储的用户属性信息。

本文介绍如何通过管理用户属性设置、更新、存储并获取实时消息用户的相关信息。

注意

为保证用户信息安全，环信即时通讯 IM 仅支持用户本人或 app 管理员设置用户属性。

环信即时通讯 IM Web SDK 提供 connection 类，支持获取、设置及修改用户属性信息，其中包含如下方法：

• updateOwnUserInfo 设置用户属性；
• fetchUserInfoById 获取用户属性。

设置用户属性前，请确保满足以下条件：

• 完成 SDK 初始化，详见 快速开始。
• 了解环信即时通讯 IM 的使用限制，详见 使用限制。

本节展示如何在项目中设置及获取用户属性。

实现过程中注意单个用户的所有属性最大不超过 2 KB，单个 app 的所有用户属性数据最大不超过 10 GB。

参考如下示例代码，在你的项目中为指定用户设置所有属性或者仅设置某一项属性。

//设置用户所有属性。
let options = {
    nickname: '昵称',
    avatarurl: 'http://avatarurl',
    mail: '123@qq.com',
    phone: '16888888888',
    gender: 'female',
    birth: '2000-01-01',
    sign: 'a sign',
    ext: JSON.stringify({
          nationality: 'China',
          merit: 'Hello, world！'
        })
}
WebIM.conn.updateOwnUserInfo(options).then((res) => {
    console.log(res)
})

//以修改用户头像为例，设置指定用户属性。
WebIM.conn.updateOwnUserInfo('nickname', '昵称').then((res) => {
    console.log(res)
})

SDK 端上的用户属性使用以下字段：

参考以下示例代码，获取用户的所有属性或其中一项或多项，如只获取昵称或头像。

/**
 * 获取用户的所有属性。
 * @param {String|Array} users 用户 ID，可以传单个或者多个，一次调用用户 ID 数量不能超过 100。
   */
   let users = 'user1' || ['user1', 'user2']
   WebIM.conn.fetchUserInfoById(users).then((res) => {
   console.log(res)
   })
   

/**
 * 获取指定的用户属性。
 * @param {String|Array} users 用户 ID，可以传单个或者多个，一次调用的用户 ID 数量不能超过 100。
 * @param {String|Array} properties 查询用户属性。
   */
   WebIM.conn.fetchUserInfoById('userId', 'nickname').then((res) => {
   console.log(res)
   })

// 同时查询多个用户属性。
WebIM.conn.fetchUserInfoById(['user1', 'user2'], ['nickname', 'avatarurl']).then((res) => {
    console.log(res)
})

如果你的应用场景中涉及用户头像管理，还可以参考如下步骤进行操作：

1.开通第三方文件存储服务。详情可以参考文件存储服务商的文档。

2.将头像文件上传到上述第三方文件存储服务。

3.完成头像上传后，你会获取一个 URL 地址。将该 URL 地址设置为用户属性的头像 URL 字段。

4.显示头像时，调用 fetchUserInfoById 获取头像 URL ，并在本地 UI 中渲染头像。

如果你的场景中涉及名片消息，你也可以使用自定义属性功能，并参考如下示例代码实现：

// 设置自定义消息的 `event` 为 `userCard`，并在 `ext` 中添加展示名片所需的用户 ID 、昵称和头像等字段。
// 生成本地消息 ID。
let id = conn.getUniqueId();                 
// 创建自定义消息。
let msg = new WebIM.message('custom', id);  
// 创建自定义事件。
let customEvent = "userCard";             
let customExts = {
  nickname: '昵称',
  avatarurl: 'http://avatarurl',
  mail: '123@qq.com',
  phone: '16888888888',
  gender: 'female',
  birth: '2000-01-01',
  sign: 'a sign',
};                         
// 消息内容，key/value 需为 string 类型。
msg.set({
  // 消息接收方（用户 ID）。
  to: 'username',                          
  customEvent,
  customExts,
  ext: {},
  chatType: 'singleChat', 
  success: function (id, serverMsgId) {},
  fail: function(e){}
});
WebIM.conn.send(msg.body);

如果需要在名片中展示更丰富的信息，可以在 ext 中添加更多字段。

可参考示例项目 中 src/components/contact/ 下 UserInfoModal 组件。