用户属性

小于 1 分钟

管理用户属性

环信即时通讯 IM 自 V3.5.1 开始支持管理用户属性功能。

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

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

本文介绍如何管理用户属性，包括设置、更新、存储并获取用户的相关信息。

提示

用户属性存储在环信服务器。如果你有安全方面的顾虑，环信建议你自行管理用户属性。
为保证信息安全，app 用户只能修改自己的用户属性。只有 app 管理员可以修改其他用户的用户属性。

技术原理

环信即时通讯 IM Web SDK 支持你通过调用 API 实现如下功能：

设置或修改用户属性。
获取指定用户的用户属性。

前提条件

开始前，请确保满足以下条件：

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

实现方法

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

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

设置当前用户的属性

当前用户设置自己的所有属性或者仅设置一项指定属性。

参考如下示例代码，设置所有用户属性：

let option = {
  nickname: "The nickname",
  avatarurl: "https://avatarurl",
  mail: "123@qq.com",
  phone: "16888888888",
  gender: "female",
  birth: "2000-01-01",
  sign: "a sign",
  ext: JSON.stringify({
    nationality: "China",
    merit: "Hello, world！",
  }),
};
conn.updateUserInfo(option).then((res) => {
  console.log(res);
});

参考如下示例代码，设置指定用户属性，例如昵称：

conn.updateUserInfo("nickname", "Your nickname").then((res) => {
  console.log(res);
});

若调用 RESTful 的接口设置或删除用户属性，请求中必须传以下字段各客户端才能获取到。

字段	类型	备注
`nickname`	String	用户昵称。长度在 64 字符内。
`avatarurl`	String	用户头像 URL 地址。长度在 256 字符内。
`phone`	String	用户联系方式。长度在 32 字符内。
`mail`	String	用户邮箱。长度在 64 字符内。
`gender`	Number	用户性别。 - `1`：男； - `2`：女； - （默认）`0`：未知； - 设置为其他值无效。
`sign`	String	用户签名。长度在 256 字符内。
`birth`	String	用户生日。长度在 64 字符内。
`ext`	String	扩展字段。

获取用户属性

你可以调用 fetchUserInfoById 方法查询指定用户的用户属性。每次调用最多可获取 100 个用户的用户属性。

参考以下示例代码获取指定用户的所有属性：

/**
 * @param {String|Array} users 用户 ID。可设置一个用户 ID，也可通过数组形式设置多个。
 */
let users = "user1" || ["user1", "user2"];
conn.fetchUserInfoById(users).then((res) => {
  console.log(res);
});

参考以下示例代码获取用户的指定属性。

/**
 * @param {String|Array} users 用户 ID。可设置一个用户 ID，也可通过数组形式设置多个。
 * @param {String|Array} properties 查询的用户属性。
 */
conn.fetchUserInfoById("userId", "nickname").then((res) => {
  console.log(res);
});

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

更多功能

管理用户头像

环信 IM SDK 仅支持存储头像文件的 URL 地址，不存储头像文件本身。要管理用户头像，你需要使用第三方文件存储服务。

在 app 中进行用户头像管理，需采取以下步骤：

开通第三方文件存储服务。详情可以参考文件存储服务商的文档。
将头像文件上传到第三方文件存储服务。文件上传成功后，你将获得头像文件的 URL 地址。
将用户属性中的 avatarurl 参数设置为头像文件的 URL 地址。
要显示头像，调用 fetchUserInfoById 获取头像文件的 URL，然后在本地 UI 渲染图像。

通过使用用户属性创建和发送名片消息

名片消息是自定义消息，包括指定用户的用户 ID、昵称、头像、电子邮件地址和电话号码。要创建和发送名片，请参考以下步骤：

将消息类型设置为 custom。
将自定义消息中的 customEvent 设置为 userCard。
在用户属性中查询 nickname、mail 和 avatarurl 的值，然后使用 customExts 将其设置为自定义消息的扩展信息。

参考以下示例代码创建和发送名片消息：

// 将自定义事件类型设置为 `userCard`。
let customEvent = "userCard";
// 通过 `customExts` 将这些属性设置为自定义消息的扩展信息。
let customExts = {
  nickname: "昵称",
  avatarurl: "https://avatarurl",
  mail: "123@qq.com",
  phone: "16888888888",
  gender: "female",
  birth: "2000-01-01",
  sign: "a sign",
};
let option = {
  // 设置消息类型。
  type: "custom",
  // 设置消息接收方。
  to: "username",
  // 设置消息事件。
  customEvent,
  // 设置消息内容。
  customExts,
  chatType: "singleChat",
};
// 创建自定义消息。
let msg = WebIM.message.create(option);
conn
  .send(msg)
  .then((res) => {
    console.log("Success");
  })
  .catch((e) => {
    console.log("Fail");
  });

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

可参考 Demo 中 src/components/contact/ 下 UserInfoModal 组件。

用户属性

# 管理用户属性

# 技术原理

# 前提条件

# 实现方法

# 设置当前用户的属性

# 获取用户属性

# 更多功能

# 管理用户头像

# 通过使用用户属性创建和发送名片消息