用户属性

小于 1 分钟

管理用户属性

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

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

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

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

提示

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

技术原理

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

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

前提条件

开始前,请确保满足以下条件:

实现方法

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

实现过程中注意单个用户的所有属性的长度不超过 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 的接口设置删除用户属性,请求中必须传以下字段各客户端才能获取到。

字段类型备注
nicknameString用户昵称。长度在 64 字符内。
avatarurlString用户头像 URL 地址。长度在 256 字符内。
phoneString用户联系方式。长度在 32 字符内。
mailString用户邮箱。长度在 64 字符内。
genderNumber用户性别。
- 1:男;
- 2:女;
- (默认)0:未知;
- 设置为其他值无效。
signString用户签名。长度在 256 字符内。
birthString用户生日。长度在 64 字符内。
extString扩展字段。

获取用户属性

你可以调用 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 中进行用户头像管理,需采取以下步骤:

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

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

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

  1. 将消息类型设置为 custom
  2. 将自定义消息中的 customEvent 设置为 userCard
  3. 在用户属性中查询 nicknamemailavatarurl 的值,然后使用 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 中添加更多字段。

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