群组信息
要在 Global IM UIKit UI 上展示群组的头像(非群成员的头像)、群名称等,需要应用层(App)主动向 Global IM UIKit SDK 提供群组信息(Group
)。
Global IM UIKit 使用 UserInfoConfig
类统一管理以下数据。App 需要使用 UserInfoConfig
向 Global IM UIKit 提供数据,用于在 UI 上展示。
- 用户信息:包含昵称、头像
- 群组信息:包含群组名称、群组头像
- 群成员用户信息:仅支持群用户昵称
用户信息、群组信息、群成员用户信息必须由应用开发者主动从 App 服务端获取,并提供给 SDK。融云不提供 App 用户与群组信息托管服务。融云服务端的用户昵称及头像仅用于推送服务。
本文仅描述了应用层(App)如何为 Global IM UIKit SDK 提供群组信息(Group
),以实现在 Global IM UIKit UI 上展示群组的头像(非群成员的头像)、群名称等功能。
Group group = new Group(groupId, groupName, groupPortrait);
// 5.3.0 及之后,新增 String 类型的 extra 字段
Group group = new Group(groupId, groupName, groupPortrait, extra);
刷新群组信息
如果 App 本地持有群组信息数据,可直接刷新本地缓存和数据库中存储的群组信息(群组名称与群组头像)。刷新后,Global IM UIKit UI 会展示最新的群组信息 Group
。
刷新群组信息必须在 Global IM UIKit 已成功 建立 IM 连接后操作,否则无法刷新本地数据。可能适用场景如下:
- App 首次启动,并成功建立 IM 连接以后,可以将自身业务所需的用户信息批量提供给 SDK,由 SDK 写入缓存与本地数据库,供后续使用。
- 在 IM 建立连接后,如果群组名称、头像等信息变动,由 App 服务端通知客户端(例如使用消息),客户端调用接口刷新群组信息。
Group group = new Group(groupId, groupName, groupPortrait);
ConfigCenter.getUserInfoConfig().refreshGroupInfoCache(group);
如果 App 本地不持有数据,推荐在 Global IM UIKit 需要展示数据时动态提供群组信息。
动态提供群组信息
从 Global IM UIKit 5.X 版本开始,SDK 设计了「群组信息提供者」UserDataProvider.GroupInfoProvider
接口类。如果 Global IM UIKit 无法从 UserInfoConfig
中获取群组名称与群组头像,将触发 GroupInfoProvider
的 getGroupInfo
回调方法。App 应在该回调中提供 SDK 所需要的群组名称与群组头像。
获取群组信息数据后,SDK 会自动设置、刷新群组的名称和头像,以及实现相关 UI 展示。
public interface GroupInfoProvider {
/**
* 获取群组信息。
*
* @param groupId 群组 ID.
* @return 群组信息。
*/
Group getGroupInfo(String groupId);
}
步骤 1:设置群组信息提供者
在 Global IM UIKit 中,您可以使用 UserInfoConfig
的 setGroupInfoProvider
方法设置群组信息提供者。必须在 SDK 初始化之后,建立 IM 连接之前设置。建议在应用生命周期内设置。
// 允许 SDK 在本地持久化存储群组信息
boolean isCacheGroupInfo = true;
ConfigCenter.getUserInfoConfig().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider() {
@Override
public Group getGroupInfo(String groupId) {
...// 此处需要 App 提供群组信息。
}
}, isCacheGroupInfo);
参数 | 类型 | 说明 |
---|---|---|
groupProvider | UserDataProvider.GroupInfoProvider | 群组信息提供者接口 |
isCacheGroupInfo | boolean | 是否持久化存储群组信息到 SDK 的本地数据库。true 表示存储。false 表示不存储。 |
建议设置
isCacheGroupInfo
为true
,即在本地持久化存储群组信息。
在 App 的生命周期中,如果 SDK 获取过群组的信息,便会在内存中缓存该信息。允许持久化存储后,SDK 优先从本地数据库中获取群组信息,App 下次启动时数据仍然可用。SDK 在处理对应信息时默认行为如下:
- 当 SDK 需要在 UI 上显示群组信息时,首先从内存中查询已获取的数据。
- 如果 SDK 可从缓存或本地数据库中查询到所需信息,将直接将数据返回 UI 层并刷新 UI。
- 如果 SDK 未能从缓存或本地数据库查询到所需信息,则将触发
UserDataProvider.GroupInfoProvider
的回调方法,并尝试从应用层获取信息。收到应用层提供的相应信息后,SDK 将刷新 UI。
步骤 2:提供群组信息给 SDK
在需要展示群组信息时(例如会话列表页面、会话页面),Global IM UIKit 会为根据群组 ID 逐个调用 UserInfoConfig
的 getGroupInfo
方法获取群组信息。如果 SDK 无法在缓存或本地数据库中查询到所需群组信息,将触发 UserDataProvider.GroupInfoProvider
的回调方法,要求 App 提供群 组信息数据。
请在 UserDataProvider.GroupInfoProvider
的 getGroupInfo
回调触发时,向 SDK 提供群组信息数据。
-
异步获取群组信息,再手动刷新: App 可以使用该方式避免耗时操作影响 UI。
-
App 需要在
getGroupInfo
方法中直接返回null
,同时,App 应在该方法中触发自行获取groupId
的群组信息的逻辑。注意,该步骤会将groupId
的用户信息临时置为空。ConfigCenter.getUserInfoConfig().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider {
@Override
public Group getGroupInfo(String groupId) {
...// 在需要展示群组信息时(例如会话列表页面、会话页面),Global IM UIKit 首先会根据群组 ID 逐个调用 getGroupInfo
// 此处由 App 自行完成异步请求群组信息的逻辑。后续通过 refreshGroupInfoCache 提供给 SDK。
return null;
}
}, true); -
App 成功获取
groupId
的群组信息数据后,再调用UserInfoConfig
的refreshGroupInfoCache
方法,手动刷新groupId
的群组信息。SDK 收到该群组的信息后会刷新 UI。详见刷新群组信息。Group group = new Group(groupId, groupName, groupPortrait);
ConfigCenter.getUserInfoConfig().refreshGroupInfoCache(group);
-
-
同步返回群组信息:App 也可以直接返回
groupId
的群组信息。SDK 在收到该群组的信息后会刷新 UI。ConfigCenter.getUserInfoConfig().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider() {
@Override
public Group getGroupInfo(String groupId) {
Group group = new Group(groupId, groupName, groupPortrait);
return userInfo;
}
}, true);