Instant Messaging
iOS
Getting Started
Product Introduction
Overview
Features
Limits
Feature overview
Account Integration and Login
Basic Message Features
Group Chat
Chat Room
Chat Room Tags
Multi-device Login
Statistics Monitoring
Development Integration
Message Sending
Message Receiving
Recent Chats
Server Sessions
User Profile
User Relationship
Online Status Subscription
System Notification
APNs
Team Chat
Superteam
Chat Room
Anti-spam
Chat Extension
Miscellaneous Features
Reference Documents
Configuration Instruction for PushKit
Push Configuration for Apple iOS
API References
iOS API Reference
Status Codes

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 NIMUserto 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
email NSString Email
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

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
Was this topic helpful?
Yes
No
  • Get a user profile
  • Get a user profile locally
  • Update the user profile
  • Get a user profile on the cloud
  • Update a user profile
  • Avatar resource processing
  • The callback of user profile changes
  • User search