用户信息自动管理
用户信息自动管理
功能说明
环信即时通讯 IM HarmonyOS SDK 提供用户信息自动管理功能。开启该功能后,SDK 可自动维护用户信息的同步与本地缓存更新,帮助开发者减少手动拉取、存储和更新用户信息的工作量。
该功能适用于会话列表、消息列表、群聊页面等需要展示用户昵称、头像、好友备注、群成员名片的场景。
本文提及的用户信息指用于业务展示的用户相关信息,包括 用户属性、好友备注 和 群成员名片。
技术原理
用户信息自动管理功能由 ChatOptions#setEnableUserInfo(true) 控制。开启后,SDK 会在登录成功时自动同步当前登录用户的用户属性,并在发送消息时附带发送方用户属性的更新时间。对于群聊消息,还会额外附带发送方在当前群中的群成员名片更新时间。
好友备注从接收方的本地好友数据中读取,不随消息发送,也不通过上述更新时间比较机制同步。详见 通过消息获取发送方信息。
接收方收到消息后,SDK 会根据消息中携带的更新时间,按需同步用户属性和群成员名片、更新本地缓存,并通过事件通知业务层刷新 UI。具体处理流程如下:
- 用户登录成功后,SDK 自动从服务端获取当前登录用户的信息,并写入本地缓存。
- 当用户更新自身信息后,后续发送的消息会携带对应信息的更新时间。
- 接收方收到消息后,SDK 会解析消息中携带的发送方用户属性更新时间;群聊消息还会携带发送方群成员名片的更新时间。
- SDK 会将消息中的更新时间与本地缓存中的对应时间戳进行比较。
- 如果本地缺少对应数据,或消息中的更新时间晚于本地缓存,SDK 会自动 从服务端拉取最新用户属性 或 群成员名片。
- 拉取成功后,SDK 会自动更新本地缓存。
- 本地缓存更新完成后,SDK 会通过事件通知上层应用,业务层可据此刷新 UI。
该功能的核心是:SDK 自动完成用户信息获取、更新检测、本地缓存更新和变更通知。
本地缓存更新流程如下:

前提条件
开始接入前,请确保满足以下条件:
开启用户信息自动管理
该功能默认关闭。在 SDK 初始化前,创建 ChatOptions 并调用 setEnableUserInfo(true) 开启:
const options = new ChatOptions({ appKey: 'your-org#your-app' });
options.setEnableUserInfo(true);
ChatClient.getInstance().init(context, options);
提示
必须在调用 ChatClient#init(context, options) 初始化 SDK 前开启该功能。SDK 初始化完成后再修改配置,不会应用于本次已创建的 SDK 实例。
调用 ChatOptions#setEnableUserInfo(true) 开启用户信息自动管理功能后,SDK 的相关行为如下:
发送消息时,会携带用户属性和群成员名片的更新时间,并根据本地缓存为消息生成
ChatSenderInfo。接收消息时,SDK 会根据消息中携带的更新时间,按需自动同步发送方最新的用户属性和群成员名片,并更新本地缓存。
可通过
ChatMessage#getSenderInfo()获取 SDK 组装的发送方信息,包括用户 ID,以及当前可用的昵称、头像、群成员名片和好友备注。具体内容取决于消息对象及本地缓存,不能保证所有字段均有值。好友备注从接收方的本地好友信息中读取,不随消息发送。调用
ChatManager#fetchGroupMessageReadReceipts(messageId, pageSize, startReceiptId)时,SDK 会为GroupReadReceipt#getFrom()返回的成员信息补充当前可用的昵称、头像和群成员名片(未获取到的字段可能为空)。关闭该功能时,SDK 不会自动补充这些信息。GroupManager#fetchGroupMemberDetails(groupId, pageSize, cursor)返回的GroupMember中会补充当前可用的用户昵称(nickname)和头像(avatarUrl);关闭时不补充。群成员名片(namecard)由服务端返回,不受该开关的影响。登录成功后,SDK 会自动从服务器同步当前登录用户的属性。
不受该开关的影响的功能:
手动调用
UserInfoManager#fetchUserInfoById(userId, attribute)时,仍会按更新时间将拉取结果写入本地缓存。该行为不受此开关影响。UserInfoManager#getUserInfoById(userId)可读取并返回本地已缓存的用户信息。该接口不会主动从服务器获取数据,能否获取到数据取决于本地是否存在缓存,不受该开关的影响。
监听用户属性更新
SDK 提供 UserInfoListener,用于监听用户属性更新事件,主要包括:
UserInfoListener#onSelfUserInfoUpdate:当前登录用户的属性同步或更新并写入本地缓存后触发该事件。UserInfoListener#onUserInfoUpdate:其他用户属性更新并写入本地缓存后触发,包括以下场景:- 收到其他用户的消息,消息中发送方的用户昵称、头像有变更。若实现这种场景下的用户属性更新事件,需要将 SDK 升级至 1.13.0 及以上版本,并开启用户信息自动管理。
- 主动 从服务端获取用户属性。
- 主动 从服务端获取群成员信息。
建议在 SDK 初始化成功后、登录前完成监听注册,以免遗漏登录后的初始同步事件,并及时处理消息触发或主动拉取产生的更新。 关于其他场景下用户属性变更通知机制,详见 监听用户属性变更。
提示
如需接收好友的用户属性变更通知,或订阅非好友用户的属性变更通知,你需要先联系环信商务开通相应功能。详见 监听用户属性变更 和 订阅非好友用户的属性变更。
添加监听:
const listener: UserInfoListener = {
onSelfUserInfoUpdate: (userInfo: UserInfo) => {
ChatLog.d(
`当前用户信息更新: userId=${userInfo.userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
);
},
onUserInfoUpdate: (userInfoList: Array<UserInfo>) => {
userInfoList.forEach((userInfo: UserInfo) => {
ChatLog.d(
`用户信息更新: userId=${userInfo.userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
);
});
}
};
ChatClient.getInstance().userInfoManager()?.addListener(listener);
移除监听:
ChatClient.getInstance().userInfoManager()?.removeListener(listener);
通过消息获取发送方信息
开启用户信息自动管理后,发送消息时,SDK 会自动携带发送方用户属性的更新时间;发送群聊消息时,还会携带发送方在当前群中的群成员名片更新时间。应用无需手动将这些信息或完整用户属性添加到消息扩展中。当接收方收到该消息,且本地缺少发送方用户属性,或消息中携带的更新时间晚于本地缓存时,SDK 会从服务端拉取该用户属性,并触发 UserInfoListener#onUserInfoUpdate 事件。
接收方收到该消息后,可以通过 ChatMessage#getSenderInfo() 获取当前可用的发送方信息,包括昵称、头像、备注和群成员名片。如果接收方已为该发送方设置好友备注,还可通过 senderInfo.remark 获取该备注。好友备注属于接收方的私有好友数据,由接收方 SDK 从本地好友信息中读取,不会由消息发送方随消息发送,也不会传递给对方。
ChatMessage#getSenderInfo() 可能返回 undefined;获取到 ChatSenderInfo 后可读取以下字符串属性。
| 属性 | 类型 | 说明 |
|---|---|---|
userId | string | 消息发送方的用户 ID。 |
nickname | string | 发送方的昵称。 |
avatarUrl | string | 发送方的头像 URL。 |
remark | string | 当前用户为发送方设置的私有好友备注,不会随消息发送给对方。 |
namecard | string | 发送方在当前群组中的群成员名片。 |
function handleReceivedMessages(messages: Array<ChatMessage>): void {
messages.forEach((message: ChatMessage) => {
const senderInfo: ChatSenderInfo | undefined = message.getSenderInfo();
if (senderInfo) {
console.info(
`发送方信息: userId=${senderInfo.userId}, nickname=${senderInfo.nickname}, ` +
`avatarUrl=${senderInfo.avatarUrl}, remark=${senderInfo.remark}, namecard=${senderInfo.namecard}`
);
}
});
}
提示
ChatMessage#getSenderInfo() 返回的是当前本地可用的发送方信息;消息中没有可用的发送方信息时返回 undefined。如果消息触发了用户信息更新,最新数据会在 SDK 完成本地缓存更新后,通过 UserInfoListener 的相关事件通知业务层。
从本地缓存读取用户属性
你可以调用 UserInfoManager#getUserInfoById 从 SDK 本地数据库缓存读取一个或多个用户的属性。该方法接受单个用户 ID 或用户 ID 数组,异步返回以用户 ID 为键、UserInfo 为值的 Map,不会发起网络请求。传入空字符串或空数组时,Promise 会被拒绝,并返回 ChatError.USER_ILLEGAL_ARGUMENT。
const userInfoMap: Map<string, UserInfo> = await ChatClient.getInstance()
.userInfoManager()!
.getUserInfoById(['userId1', 'userId2']);
userInfoMap.forEach((userInfo: UserInfo, userId: string) => {
console.info(
`本地用户属性: userId=${userId}, nickname=${userInfo.nickname}, avatarUrl=${userInfo.avatarUrl}`
);
});
如需同步读取单个用户的本地属性,可以调用 UserInfoManager#getUserInfoWithUserId。用户 ID 为空、本地缓存中不存在该用户信息或读取失败时,返回 undefined:
const userInfo: UserInfo | undefined = ChatClient.getInstance()
.userInfoManager()
?.getUserInfoWithUserId('userId1');
提示
以上接口仅读取本地缓存,不会发起网络请求。如需主动从服务端获取最新用户属性,请调用 UserInfoManager#fetchUserInfoById。详见 管理用户属性。
注意事项
ChatOptions#setEnableUserInfo(true)必须在 SDK 初始化前调用,默认值为false。- 建议在 SDK 初始化成功后、登录前注册
UserInfoListener,以便及时处理登录同步及后续缓存更新事件。 ChatMessage#getSenderInfo()返回当前本地可用的发送方信息,不保证一定是刚收到消息时的最终最新值;未开启用户信息自动管理或没有发送方信息时,返回undefined。- 当本地缺少对应数据,或消息中的更新时间晚于本地缓存时,SDK 会自动从服务端拉取最新数据并更新本地缓存。
UserInfoManager#getUserInfoById和getUserInfoWithUserId仅查询本地缓存,不会主动从服务端拉取最新数据。- 未开启用户信息自动管理时,通过
fetchUserInfoById获取的数据不会写入本地缓存,getUserInfoById和getUserInfoWithUserId无法从本地读取这些数据。
常见问题
何时开启用户信息自动管理?
必须在调用 ChatClient#init(context, options) 初始化 SDK 前调用 ChatOptions#setEnableUserInfo(true)。SDK 初始化完成后再设置,不会应用于本次已创建的 SDK 实例。
功能开启后,SDK 会自动执行哪些操作?
开启用户信息自动管理功能 后,SDK 会在登录成功后自动同步当前登录用户信息;在发送消息时自动附带发送方信息及更新时间;在接收消息后自动比较消息中的更新时间与本地缓存;在本地缺少数据或检测到数据更新时自动从服务端拉取最新信息并更新本地缓存,同时通过 UserInfoListener 通知业务层。
ChatMessage#getSenderInfo() 一定最新?
不一定。ChatMessage#getSenderInfo() 返回的是当前本地可用的发送方信息。如果消息触发了用户信息更新,SDK 会先从服务端拉取最新数据并更新本地缓存,随后通过 UserInfoListener 通知业务层刷新界面。
为何建议尽早注册监听?
开启用户信息自动管理功能 后,SDK 可能在登录后的初始同步以及消息触发的用户信息更新场景中通知业务层。建议在 SDK 初始化成功后、登录前注册 UserInfoListener,以免遗漏登录后的初始同步事件。
本地读取和服务端获取有何区别?
UserInfoManager#getUserInfoById 和 getUserInfoWithUserId 仅查询本地缓存,不会发起网络请求,适用于本地展示场景。如果业务需要获取最新的用户属性,应调用 UserInfoManager#fetchUserInfoById 主动从服务端获取。
功能开启后需自己维护缓存吗?
通常不需要。开启 ChatOptions#setEnableUserInfo(true) 后,SDK 会负责用户信息的自动同步、更新时间比较、本地缓存更新和事件通知。业务层通常只需读取本地缓存,并在相关事件中刷新界面。
相关功能
管理群成员名片
启用用户信息自动管理后,SDK 也支持群成员名片的自动同步与更新。你可以进一步实现群成员名片的设置、查询和变更监听。详见 管理群成员名片。
用户属性与用户信息
- 用户信息:指用于业务展示的用户相关信息,包括 用户属性、好友备注 和 群成员名片。
- 用户属性:指用户可设置和管理的资料字段,例如,用户昵称、头像、邮箱、电话号码等。你可通过相关接口对这些字段进行设置、更新和查询。详见 管理用户属性。例如,你可以通过
UserInfoManager#updateUserInfo设置当前登录用户的昵称、头像等资料。若已开启用户信息自动管理功能(调用ChatOptions#setEnableUserInfo(true)),更新后的信息会在后续发送消息时自动参与同步。
通过消息同步的发送方信息
开启用户信息自动管理后,消息会携带发送方用户属性的更新时间;群聊消息还会携带群成员名片的更新时间。SDK 根据这些时间戳更新本地缓存,业务可通过 ChatMessage#getSenderInfo() 获取当前本地可用的昵称、头像、好友备注和群成员名片。其中,好友备注来自接收方的本地好友数据,不会随消息发送。
