User Information

This document describes how to set user, group, and group member information, including nicknames and avatars. It covers the following topics:

• Setting the nickname and avatar of the currently logged-in user.
• Providing user, group, group member, and group member list information to the SDK through various information provider protocols for setting and display.
• How to persistently store user information, group information, and group member information.

Enabling Persistent Storage

Global IM UIKit supports persistently storing user information, group information, and group member information in a local database. It does not support persistent storage of group member list information.

When you need to persistently store user information, group information, or group member information locally, set the enableUserInfoPersistence property of the RCIMKitClient class to YES. The information will be cached in both memory and the database, and the cache will remain valid the next time the app is launched.

Set the persistent storage property after initialization but before connecting.

@property (nonatomic, assign) BOOL enableUserInfoPersistence;

The default value is NO. Information is only cached in memory and will be cleared when the app lifecycle ends. The app will retrieve the information again through the corresponding information provider protocol the next time it is launched.

Understanding Information Provider Protocols

Global IM UIKit has designed and provided the following information provider protocols for retrieving information from the application layer. Developers need to implement these protocols to provide the correct data.

The application layer is only responsible for providing the data source. Once the SDK retrieves the data, it will automatically set and refresh user avatars and nicknames, as well as related UI displays.

• User Information Provider: RCIMKitUserInfoDataSource, used to retrieve user information for non-local logged-in users, such as nicknames and avatars.
• Group Information Provider: RCIMKitGroupInfoDataSource, used to retrieve group nicknames and avatars.
• Group Member Information Provider: RCIMKitGroupUserInfoDataSource, used to retrieve group member nicknames (group cards) within a group.
• Group Member List Information Provider: RCIMKitGroupMemberDataSource, used to retrieve group member lists.

It is recommended to implement the above protocols in AppDelegate or other singletons.

During the app lifecycle, if the SDK has retrieved user or group information, it will cache this information in memory. As long as the SDK can retrieve the required information from the cache, it will not trigger the callback to retrieve that information again.

When handling user and group information, the SDK’s default behavior is as follows:

1. When the SDK needs to display user or group information in the UI, it first queries the data already retrieved from memory.
2. If the SDK can retrieve the required information from the cache or local database, it will directly return the data to the UI layer and refresh the UI. This process will not trigger the callback method to retrieve information from the application layer.
3. If the SDK cannot retrieve the required information from the cache or local database, it will trigger the corresponding information provider interface callback method and attempt to retrieve the information from the application layer. After receiving the corresponding information from the application layer, the SDK will refresh the UI.

Setting the Information of the Currently Logged-in User

After establishing a connection with the RC server, developers should set the user information of the currently logged-in user to ensure that the SDK can properly display the local user’s avatar in the interface.

Property Description

If the user ID in the provided user information does not match the currently logged-in user ID, the SDK will ignore it.

@property (nonatomic, strong) RCUserInfo *currentUserInfo;

Code Example

Set this after successfully establishing a connection with the RC server. You can set it in the connection success callback.

RCUserInfo *currentUserInfo = [[RCUserInfo alloc] initWithUserId:userId name:userNickName portrait:userPortraitUri];
[RCIMKitClient shared].currentUserInfo = currentUserInfo;

Setting User Information for Other Users

The User Information Provider (RCIMKitUserInfoDataSource protocol) is used to retrieve user information for non-local logged-in users, such as nicknames and avatars.

Delegate Callback

The SDK retrieves user information from the application layer through the delegate.

Setting the Delegate

Set the delegate after SDK initialization but before connecting to the RC server.

[RCIMKitClient shared].userInfoDataSource = self;

Delegate Method

@protocol RCIMKitUserInfoDataSource <NSObject>

/// SDK callback to retrieve user information from the app
///
/// - Parameter userId:      User ID
/// - Parameter completion:  Block to execute after retrieving user information [userInfo: The user information corresponding to the user ID]
///
/// The SDK retrieves user information through this method for display. Please return the user information corresponding to the user ID in the completion block.
/// After setting the User Information Provider, the SDK will call this method when it needs to display user information, requesting user information for display.
- (void)getUserInfoWithUserId:(NSString *)userId completion:(void(^)(RCUserInfo *userInfo))completion;

@end

Code Example

The following code example is from the TestDemo project (GitHub · Gitee).

- (void)getUserInfoWithUserId:(NSString *)userId completion:(void(^)(RCUserInfo *userInfo))completion {
    // Developers call their own server interface to asynchronously request user information based on the userID
    [RCDUserInfoManager getUserInfoFromServer:userId
                                     complete:^(RCUserInfo *userInfo) {
        // Return the retrieved user information to the SDK through the completion callback
            return completion(userInfo);
    }];
}

Retrieving User Information

You can call the following method to retrieve user information. The SDK will first attempt to retrieve the data from the local cache. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also attempt to retrieve user information from the local database.

If there is no relevant data locally, the SDK will trigger the corresponding callback method to retrieve data from the application layer.

Call Example

[[RCIMKitClient shared] getCachedUserInfo:@"userId"];

Refreshing User Information

You can use the following method to update the user information cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also update the user information in the local database.

Call Example

RCUserInfo *user = [[RCUserInfo alloc] initWithUserId:@"userId" name:@"userName" portrait:@"http://portrait"];

[[RCIMKitClient shared] refreshUserInfoCache:user];

Clearing User Information

You can use the following method to clear the user information cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also clear the user information in the local database.

Call Example

[[RCIMKitClient shared] clearCachedUserInfo];

Setting Group Information

The Group Information Provider (RCIMKitGroupInfoDataSource protocol) is used to retrieve group nicknames and avatars.

Delegate Callback

The SDK retrieves group information from the application layer through the delegate.

Setting the Delegate

[RCIMKitClient shared].groupInfoDataSource = self;

Delegate Method

@protocol RCIMKitGroupInfoDataSource <NSObject>

/// SDK callback to retrieve group information from the app
///
/// - Parameter groupId:     Group ID
/// - Parameter completion: Block to execute after retrieving group information [groupInfo: The group information corresponding to the group ID]
///
/// The SDK retrieves group information through this method for display. Please return the group information corresponding to the group ID in the completion block.
/// After setting the Group Information Provider, the SDK will call this method when it needs to display group information, requesting group information for display.
- (void)getGroupInfoWithGroupId:(NSString *)groupId completion:(void(^)(RCGroup *groupInfo))completion;

@end

Code Example

The following code example is from the TestDemo project (GitHub · Gitee).

- (void)getGroupInfoWithGroupId:(NSString *)groupId completion:(void(^)(RCGroup *groupInfo))completion {
    // Developers call their own server interface to asynchronously request data based on the groupID
    [RCDGroupManager getGroupInfoFromServer:groupId
                                   complete:^(RCGroup * groupInfo) {
        return completion(groupInfo);
    }];
}

Retrieving Group Information

You can call the following method to retrieve group information. The SDK will first attempt to retrieve the data from the local cache. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also attempt to retrieve group information from the local database.

If there is no relevant data locally, the SDK will trigger the corresponding callback method to retrieve data from the application layer.

Call Example

[[RCIMKitClient shared] getCachedGroupInfo:@"groupId"];

Refreshing Group Information

Construct Group Information (RCGroup) as follows:

RCGroup *group = [[RCGroup alloc] initWithGroupId:@"groupId" groupName:@"groupName" portraitUri:@"http://portraitUri"];
/// 5.4.1 and later versions added an extra field of type NSString
group.extra = @"groupExtra";

You can use the following method to update the group information cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also refresh the group information in the local database.

[[RCIMKitClient shared] refreshGroupInfoCache:group];

Clearing Group Information

You can use the following method to clear the group information cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also clear the group information in the local database.

Call Example

[[RCIMKitClient shared] clearCachedGroupInfo];

Group Member Information

The Group Member Information Provider (RCIMKitGroupUserInfoDataSource protocol) is used to retrieve group member nicknames and avatars. If this protocol is not implemented, the SDK will default to using the User Information protocol.

Delegate Callback

The SDK retrieves group member information (nicknames, avatars) from the application layer through the delegate.

Setting the Delegate

Set the delegate after SDK initialization but before connecting to the RC server.

[RCIMKitClient shared].groupUserInfoDataSource = self;

Delegate Method

@protocol RCIMKitGroupUserInfoDataSource <NSObject>

/// SDK callback to retrieve group card information from the app
///
/// - Parameter userId:      User ID
/// - Parameter groupId:     Group ID
/// - Parameter completion:  Block to execute after retrieving group card information [userInfo: The group card information corresponding to the user ID in the group]
///
/// If you use the group card feature, the SDK needs to retrieve and display the group card information for users in the group through the Group Card Information Provider you implemented.
- (void)getUserInfoWithUserId:(NSString *)userId
                      inGroup:(NSString *)groupId
                   completion:(void(^)(RCUserInfo *userInfo))completion;

@end

Code Example

The following code example is from the TestDemo project (GitHub · Gitee).

- (void)getUserInfoWithUserId:(NSString *)userId
                      inGroup:(NSString *)groupId
                   completion:(void(^)(RCUserInfo *userInfo))completion {
    [RCDGroupManager getGroupMemberDetailInfoFromServer:userId
                                                groupId:groupId
                                               complete:^(RCUserInfo *memberInfo) {
        return completion(memberInfo);
    }];
}

Retrieving Group Member Information

You can call the following method to retrieve group member information (nicknames, avatars). The SDK will first attempt to retrieve the data from the local cache. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also attempt to retrieve group member information from the local database.

If there is no relevant data locally, the SDK will trigger the corresponding callback method to retrieve data from the application layer.

Call Example

[[RCIMKitClient shared] getCachedGroupUserInfo:@"userId" withGroupId:@"groupId"];

Refreshing Group Member Information

You can use the following method to update the group member information (nicknames, avatars) cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIM.h), the SDK will also update the group member information in the local database.

Call Example

RCUserInfo *user = [[RCUserInfo alloc] initWithUserId:@"userId" name:@"userName" portrait:@"http://portrait"];

[[RCIMKitClient shared] refreshCachedGroupUserInfo:user withGroupId:@"groupId"];

Clearing Group Member Information

You can use the following method to clear the group member information (nicknames, avatars) cached locally by the SDK. If persistent storage is enabled (i.e., enableUserInfoPersistence is set to YES in RCIMKitClient.h), the SDK will also clear the group member information in the local database.

Call Example

[[RCIMKitClient shared] clearCachedGroupUserInfo];

Setting Group Member List Information

When using features like @ in group chat pages, the SDK requires the application layer to provide the group member list.

Note: The SDK does not cache group member list information.

Delegate Callback

Setting the Delegate

Set the delegate after SDK initialization but before connecting to the RC server.

[RCIMKitClient shared].groupMemberDataSource = self;

Delegate Method

@protocol RCIMKitGroupMemberDataSource <NSObject>
@optional

/// SDK callback to retrieve the current group member list from the app (requires implementation of the User Information Provider RCIMKitUserInfoDataSource)
///
/// - Parameter groupId:     Group ID
/// - Parameter resultBlock: Block to execute after successful retrieval [userIdList: Group member ID list]
///
/// The SDK retrieves the group member list through this method. Please return the group member ID list corresponding to the group ID in the resultBlock.
/// After setting the Group Member List Provider, the SDK will call this method when it needs to retrieve the group member list, requesting the group member list for display.
- (void)getAllMembersOfGroup:(NSString *)groupId result:(void(^)(NSArray<NSString *> *userIdList))resultBlock;

@end

Code Example

The following code example is from the TestDemo project (GitHub · Gitee).

- (void)getAllMembersOfGroup:(NSString *)groupId result:(void (^)(NSArray<NSString *> *))resultBlock {
    [RCDGroupManager getGroupMembersFromServer:groupId
                                      complete:^(NSArray<NSString *> *_Nonnull memberIdList) {
                                              return resultBlock(memberIdList);
                                      }];
}