User Profile
Update time: 2021/12/06 15:03:22
NIMUserManager
provides users profile management. The following API is valid only when you select CommsEase to host your user profiles. Developers should maintain their user profiles if they do not want CommsEase to access their user profiles.
In NIMUserManager
, use NIMUser
to encapsulate user profiles. The attribute of user profileis NIMUserInfo
. The specific information field is defined by NIMUserInfoUpdateTag
. NIMUserInfoUpdateTag
has multiple common information fields (with format check function) and an extension field NIMUserInfoUpdateTagEx
for developers to extend.
NIMUser prototype
@interface NIMUser : NSObject
/**
* User ID
*/
@property (nullable,nonatomic,copy) NSString *userId;
/**
* Remark name. The maximum length is 128 characters.
*/
@property (nullable,nonatomic,copy) NSString *alias;
/**
* Extension field
*/
@property (nullable,nonatomic,copy) NSString *ext;
/**
* Extension field of server. The field can be updated only from a server and can be read only from the client.
*/
@property (nullable, nonatomic, copy, readonly) NSString *serverExt;
/**
* User profile. It is valid only when users host information to CommsEase.
* Except your "user profile", SDK cannot ensure real-time updates for other user profiles.
* Update time for user profile: 1. Invoke The API (void)fetchUserInfos:completion: to refresh users
* 2. A message from the user is received.
* 3. The program starts again, and now information of friends will be synchronized.
*/
@property (nullable,nonatomic,strong,readonly) NIMUserInfo *userInfo;
@end
Property List
Parameter | Type | Description |
---|---|---|
userId | NSString | User ID |
alias | NSString | Remark name. The maximum length is 128 characters. |
ext | NSString | Extension field |
serverExt | NSString | Server extension field. The field can be updated only from the server and can be read only from the client. |
userInfo | NIMUserInfo | User profile. It is valid only when users host profiles to CommsEase. instead of one's user profile, no warranties are made for the real-time update to other user profiles |
NIMUserInfo Prototype
@interface NIMUserInfo : NSObject
/**
* User nickname
*/
@property (nullable,nonatomic,copy,readonly) NSString *nickName;
/**
* profile pictures of users
*/
@property (nullable,nonatomic,copy,readonly) NSString *avatarUrl;
/**
* Thumbnails of user photo profiles
* @discussion - It only applies to useing CommsEase upload server for uploading resources. Otherwise, it is invalid.
*/
@property (nullable,nonatomic,copy,readonly) NSString *thumbAvatarUrl;
/**
* User signature
*/
@property (nullable,nonatomic,copy,readonly) NSString *sign;
/**
* Gender
*/
@property (nonatomic,assign,readonly) NIMUserGender gender;
/**
* Email
*/
@property (nullable,nonatomic,copy,readonly) NSString *email;
/**
* Birthday
*/
@property (nullable,nonatomic,copy,readonly) NSString *birth;
/**
* Telephone number
*/
@property (nullable,nonatomic,copy,readonly) NSString *mobile;
/**
* Custom extension field of a user
*/
@property (nullable,nonatomic,copy,readonly) NSString *ext;
@end
Property List
Parameter | Type | Description |
---|---|---|
nickName | NSString | User nickname |
avatarUrl | NSString | Photo profiles |
thumbAvatarUrl | NSString | Thumbnails of user photo profiles, which only applies to resources uploaded with upload services of CommsEase provides) |
sign | NSString | User signature |
gender | NSString | Gender |
NSString | ||
birth | NSString | Birthday |
mobile | NSString | Mobile |
ext | NSString | User custom extension field |
Get a user profile
Get a user profile locally
@protocol NIMUserManager <NSObject>
/**
* Locally get a user profile
*
* @param userId - User ID
*
* @return NIMUser
*
* @discussion - The API is only valid when the user profile is hosted by CommsEase and the data can be locally cached.
* instead of your "user profile", SDK cannot ensure real-time updates for other user profiles.
* Time of updating information of other users: 1. Invoke The API (void)fetchUserInfos:completion: to refresh users
* 2. A message from the user is received.
* 3. The program starts again, and now information of some friends will be synchronized.
*/
- (nullable NIMUser *)userInfo:(NSString *)userId;
@end
Example
NIMUser *user = [[NIMSDK sharedSDK].userManager userInfo:@"userId"];
Update the user profile
instead of one's local user profile, no warranties are made for the real-time update to other user profiles. Other user profiles update occasion:
-
Actively fetch and refresh a user profile by calling the method
- (void)fetchUserInfos:completion:
. -
Receive messages from other users. In case of any change in the information of the message sender, SDK will make updates and call them back with
- (void)onUserInfoChanged:(NIMUser *)user
. -
After login, the SDK will automatically update friends' user profile by syncing data.
Get a user profile on the cloud
@protocol NIMUserManager <NSObject>
/**
* Get the user profile in batches from the CommsEase server
*
* @param users - A list of user IDs
* @param completion - The callback of a user profile
*
* @discussion - Only when the user profile is hosted by CommsEase, The API will be valid. Invoking The API will not trigger the callback of -(void)onUserInfoChanged:.
* The API will locally cache acquired user profiles. Frequent calls will result in overloaded caches in a local database. For example, request data of each user in a chat room will result in excessive caches and lower the performance.
* You can acquire up to 150 user profiles by calling The API.
*/
- (void)fetchUserInfos:(NSArray<NSString *> *)users
completion:(nullable NIMUserInfoBlock)completion;
@end
with The API, user profiles may be fetched from the server in batches. To ensure user experience and lower flow cost, we recommend avoiding calling The API frequently. For the pages under which the real-time performance requirement is not high, we recommend calling The API of reading the local cache.
Update a user profile
Users may update some fields of their information by calling the modification API.
Prototype:
@protocol NIMUserManager <NSObject>
/**
* Update your "user profile"
*
* @param values - Key value pair of user profileto be updated
* @param completion - A callback for updating results
*
* @discussion - Multiple attributes (e.g. nickname, avatar) can be updated with The API for once. The input key value pair is {@(NIMUserInfoUpdateTag) : NSString}.
* The invalid data will be filtered. Some fields have update restrictions. For details, refer to NIMUserInfoUpdateTag related description.
*/
- (void)updateMyUserInfo:(NSDictionary<NSNumber *,NSString *> *)values
completion:(nullable NIMUserBlock)completion;
@end
Users may only edit their information. The API may edit multiple attributes once. The data key-value pair is {@(NIMUserInfoUpdateTag) : NSString}
, such as nickname, profile picture, etc. Invalid data will be filtered. The modification format check function is supported for some fields. Specific limits are:
Attribute name | Specific field | Type limit | Format check |
---|---|---|---|
User nickname | NIMUserInfoUpdateTagNick |
NSString |
None |
Display pictures | NIMUserInfoUpdateTagAvatar |
NSString |
None |
User signature | NIMUserInfoUpdateTagSign |
NSString |
None |
Gender | NIMUserInfoUpdateTagGender |
NIMUserGender |
Only support specified enum |
User email | NIMUserInfoUpdateTagEmail |
NSString |
Only support legal email |
User birthday | NIMUserInfoUpdateTagBirth |
NSString |
yyyy-MM-dd |
User's mobile | NIMUserInfoUpdateTagMobile |
NSString |
Legal mobile, such as 13588888888, +(86)-13055555555 |
Extension field | NIMUserInfoUpdateTagExt |
NSString |
None |
Avatar resource processing
To update the avatar, it is required to upload the avatar image to the cloud, and transmit URL to SDK. CommsEase provides file resource upload and download services.
File resource upload:
@protocol NIMResourceManager <NSObject>
/**
* Upload a file
* @param filepath - Upload file path
* @param scene - Scene type
* @param progress - Progress Block
* @param completion - A callback for results
*
* @discussion - Multiple attributes (e.g. nickname, avatar) can be updated with The API for once. The input key value pair is {@(NIMUserInfoUpdateTag) : NSString}.
* The invalid data will be filtered. Some fields have update restrictions. For details, refer to NIMUserInfoUpdateTag related description.
*/
- (void)upload:(NSString *)filepath
scene:(nonnull NSString *)scene
progress:(nullable NIMHttpProgressBlock)progress
completion:(nullable NIMUploadCompleteBlock)completion;
@end
Details of scene
are given in the file resource scene.
List of main methods for the protocol NIMResourceManager
:
@protocol NIMResourceManager <NSObject>
/**
* Download a file
*/
- (void)download:(NSString *)urlString
filepath:(NSString *)filepath
progress:(nullable NIMHttpProgressBlock)progress
completion:(nullable NIMDownloadCompleteBlock)completion;
/**
* Cancel upload/download task
*/
- (void)cancelTask:(NSString *)filepath;
/**
* ordinaryize URL address
*/
- (NSString *)ordinaryizeURLString:(NSString *)urlString;
/**
* Adjust URL of input nos image into thumbnail URL
*/
- (NSString *)imageThumbnailURL:(NSString *)urlString;
/**
* Adjust URL of input nos video into thumbnail URL
*/
- (NSString *)videoThumbnailURL:(NSString *)urlString;
@end
The callback of user profile changes
The successful modification to user profile will trigger callback:
@protocol NIMUserManagerDelegate <NSObject>
/**
* User information is updated (online)
*/
- (void)onUserInfoChanged:(NIMUser *)user;
@end
User search
Prototype:
@protocol NIMUserManager <NSObject>
/**
* Find members
*
* @param option - Query conditions
* @param completion - A callback for completion
*/
- (void)searchUserWithOption:(NIMUserSearchOption *)option
completion:(nullable NIMUserInfoBlock)completion;
Parameter list:
Parameter | Type | Description |
---|---|---|
option | NIMUserSearchOption | Search options |
completion | NIMUserInfoBlock | Callback completion |
NIMUserSearchOption Prototype:
@interface NIMUserSearchOption : NSObject
/**
* Search scope of searched text (Default value: NIMUserSearchRangeOptionFriends)
*/
@property (nonatomic, assign) NIMUserSearchRangeOption searchRange;
/**
* Matching area of searched text (Default value: NIMUserSearchContentOptionAll)
*/
@property (nonatomic, assign) NIMUserSearchContentOption searchContentOption;
/**
* Ignore capital and small letter (Default value: YES)
*/
@property (nonatomic, assign) BOOL ignoreingCase;
/**
* Search text
*/
@property (nullable,nonatomic,copy) NSString *searchContent;
Parameter list:
Parameter | Type | Description |
---|---|---|
searchRange | NIMUserSearchRangeOption | Content search range |
searchContentOption | NIMUserSearchContentOption | Search the content matching area |
ignoreingCase | BOOL | Ignore case |
searchContent | NSString | Search content |