跳到主要内容

群组信息

要在 IMKit UI 上展示群组的头像（非群成员的头像）、群名称等，需要应用层（App）主动向 IMKit SDK 提供群组信息（Group）。

IMKit 使用 RongUserInfoManager 类统一管理以下数据。App 需要使用 RongUserInfoManager 向 IMKit 提供数据，用于在 UI 上展示。

  • 用户信息：包含昵称、头像
  • 群组信息：包含群组名称、群组头像
  • 群成员用户信息：仅支持群用户昵称
提示

用户信息、群组信息、群成员用户信息必须由应用开发者主动从 App 服务端获取，并提供给 SDK。融云不提供 App 用户与群组信息托管服务。融云服务端的用户昵称及头像仅用于推送服务。

本文仅描述了应用层（App）如何为 IMKit SDK 提供群组信息（Group），以实现在 IMKit UI 上展示群组的头像（非群成员的头像）、群名称等功能。

Group group = new Group(groupId, groupName, groupPortrait);
// 5.3.0 及之后，新增 String 类型的 extra 字段
Group group = new Group(groupId, groupName, groupPortrait, extra);

刷新群组信息​

如果 App 本地持有群组信息数据，可直接刷新本地缓存和数据库中存储的群组信息（群组名称与群组头像）。刷新后，IMKit UI 会展示最新的群组信息 Group。

刷新群组信息必须在 IMKit 已成功建立 IM 连接后操作，否则无法刷新本地数据。可能适用场景如下：

  • App 首次启动，并成功建立 IM 连接以后，可以将自身业务所需的用户信息批量提供给 SDK，由 SDK 写入缓存与本地数据库，供后续使用。
  • 在 IM 建立连接后，如果群组名称、头像等信息变动，由 App 服务端通知客户端（例如使用消息），客户端调用接口刷新群组信息。
Group group = new Group(groupId, groupName, groupPortrait);
RongUserInfoManager.getInstance().refreshGroupInfoCache(group);

如果 App 本地不持有数据，推荐在 IMKit 需要展示数据时动态提供群组信息。

动态提供群组信息​

从 IMKit 5.X 版本开始，SDK 设计了「群组信息提供者」UserDataProvider.GroupInfoProvider 接口类。如果 IMKit 无法从 RongUserInfoManager 中获取群组名称与群组头像，将触发 GroupInfoProvider 的 getGroupInfo 回调方法。App 应在该回调中提供 SDK 所需要的群组名称与群组头像。

获取群组信息数据后，SDK 会自动设置、刷新群组的名称和头像，以及实现相关 UI 展示。

public interface GroupInfoProvider {
  /**
         * 获取群组信息。
         *
         * @param groupId 群组 ID.
         * @return 群组信息。
         */
  Group getGroupInfo(String groupId);
}

步骤 1：设置群组信息提供者​

在 IMKit 中，您可以使用 RongUserInfoManager 的 setGroupInfoProvider 方法设置群组信息提供者。必须在 SDK 初始化之后，建立 IM 连接之前设置。建议在应用生命周期内设置。

// 允许 SDK 在本地持久化存储群组信息
boolean isCacheGroupInfo = true;

RongUserInfoManager.getInstance().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider() {
    @Override
    public Group getGroupInfo(String groupId) {
    ...// 此处需要 App 提供群组信息。
    }
}, isCacheGroupInfo);
参数类型说明
groupProviderUserDataProvider.GroupInfoProvider群组信息提供者接口
isCacheGroupInfoboolean是否持久化存储群组信息到 SDK 的本地数据库。true 表示存储。false 表示不存储。
提示

建议设置 isCacheGroupInfo 为 true，即在本地持久化存储群组信息。

在 App 的生命周期中，如果 SDK 获取过群组的信息，便会在内存中缓存该信息。允许持久化存储后，SDK 优先从本地数据库中获取群组信息，App 下次启动时数据仍然可用。SDK 在处理对应信息时默认行为如下：

  1. 当 SDK 需要在 UI 上显示群组信息时，首先从内存中查询已获取的数据。
  2. 如果 SDK 可从缓存或本地数据库中查询到所需信息，将直接将数据返回 UI 层并刷新 UI。
  3. 如果 SDK 未能从缓存或本地数据库查询到所需信息，则将触发 UserDataProvider.GroupInfoProvider 的回调方法，并尝试从应用层获取信息。收到应用层提供的相应信息后，SDK 将刷新 UI。

步骤 2：提供群组信息给 SDK​

在需要展示群组信息时（例如会话列表页面、会话页面），IMKit 会为根据群组 ID 逐个调用 RongUserInfoManager 的 getGroupInfo 方法获取群组信息。如果 SDK 无法在缓存或本地数据库中查询到所需群组信息，将触发 UserDataProvider.GroupInfoProvider 的回调方法，要求 App 提供群组信息数据。

请在 UserDataProvider.GroupInfoProvider 的 getGroupInfo 回调触发时，向 SDK 提供群组信息数据。

  • 异步获取群组信息，再手动刷新： App 可以使用该方式避免耗时操作影响 UI。

    1. App 需要在 getGroupInfo 方法中直接返回 null，同时，App 应在该方法中触发自行获取 groupId 的群组信息的逻辑。注意，该步骤会将 groupId 的用户信息临时置为空。

      RongUserInfoManager.getInstance().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider {
          @Override
          public Group getGroupInfo(String groupId) {
              ...// 在需要展示群组信息时（例如会话列表页面、会话页面），IMKit 首先会根据群组 ID 逐个调用 getGroupInfo
              // 此处由 App 自行完成异步请求群组信息的逻辑。后续通过 refreshGroupInfoCache 提供给 SDK。
              return null;
          }

      }, true);

    2. App 成功获取 groupId 的群组信息数据后，再调用 RongUserInfoManager 的 refreshGroupInfoCache 方法，手动刷新 groupId 的群组信息。SDK 收到该群组的信息后会刷新 UI。详见刷新群组信息。

      Group group = new Group(groupId, groupName, groupPortrait);
      RongUserInfoManager.getInstance().refreshGroupInfoCache(group);

  • 同步返回群组信息：App 也可以直接返回 groupId 的群组信息。SDK 在收到该群组的信息后会刷新 UI。

    RongUserInfoManager.getInstance().setGroupInfoProvider(new UserDataProvider.GroupInfoProvider() {
        @Override
        public Group getGroupInfo(String groupId) {
            Group group = new Group(groupId, groupName, groupPortrait);
            return userInfo;
        }
    }, true);

获取群组信息​

App 可以主动调用 RongUserInfoManager 的 getGroupInfo 方法获取群组信息。SDK 的行为如下：

  1. 首先尝试从本地缓存获取应用层提供的数据。如果在设置群组信息提供者时，已授权 SDK 在本地数据库中存储群组信息（即 isCacheGroupInfo 为 true），SDK 还会尝试从本地数据库中获取群组信息。
  2. 如果本地没有相关信息的数据，SDK 会触发 UserInfoProvider 的 getGroupInfo 回调方法。如果您的 App 应用层已在该回调中提供数据，则 SDK 可成功获取群组信息 Group。
Group group = RongUserInfoManager.getInstance().getGroupInfo(groupId);