====== 用户属性 ======

更新时间：2021-12-31

新版文档见：[[ccim:ios:userprofile|用户属性]]。
===== 产品介绍 =====

用户属性指的是用户的信息，包括：昵称、头像、年龄、手机号等。 
用户属性为可选服务，如果不希望敏感信息存储在环信服务器，用户可以自行维护。

使用用户属性功能可以获得以下能力：
  * 标准的用户属性的读写能力，包括：昵称、头像url、邮箱、电话、性别、签名、生日；
  * 自定义用户属性的读写能力，提供自定义扩展，可以通过JSON字符串添加多个属性。



===== 集成概述 =====
SDK提供了用户属性托管服务，可供用户保存头像、昵称等常用字段以及一个扩展字段。如果用户不希望环信获取您的用户属性信息，则需用户自行维护相关数据。

用户属性管理模块可使用以下方式从SDK获取如下

<code>
[[EMClient sharedClient] userInfoManager];
</code>

环信可以管理的用户属性信息如下：
<code>
@interface EMUserInfo : NSObject<NSCopying>
@property (nonatomic,copy) NSString *userId; /*! *\~chinese 用户环信Id *\~english user's id */
@property (nonatomic,copy) NSString *nickName; /*! *\~chinese 用户昵称，建议最大64字节 *\~english user's nickname */
@property (nonatomic,copy) NSString *avatarUrl; /*! *\~chinese 用户头像地址，建议最大256字节 *\~english user's avatar file uri */
@property (nonatomic,copy) NSString *mail; /*! *\~chinese 用户邮箱地址，建议最大64字节 *\~english user's mail  address */

@property (nonatomic,copy) NSString *phone; /*! *\~chinese 用户联系方式，建议最大32字节 *\~english user's phone  number */
@property (nonatomic) NSInteger gender; /*! *\~chinese 用户性别，默认为0 ,1表示男,2表示女,其他为非法 *\~english user's phone  number */
@property (nonatomic,copy) NSString* sign; /*! *\~chinese 用户签名，建议最大256字节 *\~english user's sign info */
@property (nonatomic,copy) NSString* birth; /*! *\~chinese 用户生日，建议最大64字节 *\~english user's birth */
@property (nonatomic,copy) NSString *ext; /*! *\~chinese 扩展字段 *\~english extention info */
@end
</code>

===== 设置用户属性 =====

每一个用户只能设置自己的用户属性，而不能修改别人的。
设置用户属性时，可以设置用户的所有属性，也可以只设置用户的某一项属性

  * 设置用户所有属性
设置用户所有属性的接口如下
<code>
/*!
 *  \~chinese
 *  设置自己的所有用户属性
 *
 *  @param aUserData       要设置的用户属性信息
 *  @param aCompletionBlock     完成回调
 *
 *  \~english
 *  Set all own user info
 *
 *  @param aUserData       The user info data to set
 *  @param aCompletionBlock    The completion callback
 */
- (void)updateOwnUserInfo:(EMUserInfo*)aUserData
                completion:(void (^)(EMUserInfo*aUserInfo,EMError *aError))aCompletionBlock;
</code>

调用过程如下：
<code>
EMUserInfo* userInfo = [[EMUserInfo alloc] init];
userInfo.nickName = @"昵称";
userInfo.avatarUrl = @"http://www.a.com/Image1.png";
userInfo.mail = @"1111@qq.com";
userInfo.phone = @"1234556666";
userInfo.gender = 1;
userInfo.sign = @"我的签名";
userInfo.birth = @"生日";
userInfo.ext = @"ext";
[[[EMClient sharedClient] userInfoManager] updateOwnUserInfo:userInfo completion:^(EMUserInfo* aUserInfo,EMError *aError) {
        }];
</code>

  * 设置用户指定属性
用户可以指定的用户属性类型包括：
<code>
typedef NS_ENUM(NSInteger, EMUserInfoType) {
    EMUserInfoTypeNickName = 0,
    EMUserInfoTypeAvatarURL,
    EMUserInfoTypePhone,
    EMUserInfoTypeMail,
    EMUserInfoTypeGender,
    EMUserInfoTypeSign,
    EMUserInfoTypeBirth,
    EMUserInfoTypeExt = 100,
};
</code>
设置指定用户属性的接口如下：
<code>
/*!
 *  \~chinese
 *  设置自己的指定用户属性
 *
 *  @param aValue       要设置的用户属性信息
 *  @param aType         要设置的用户属性类型
 *  @param aCompletionBlock     完成回调
 *
 *  \~english
 *  Set special own user info
 *
 *  @param aValue       The user info data to set
 *  @param aType         The user info type to set
 *  @param aCompletionBlock    The completion callback
 */
- (void)updateOwnUserInfo:(NSString*)aValue
                 withType:(EMUserInfoType)aType
               completion:(void (^)(EMUserInfo*aUserInfo,EMError *aError))aCompletionBlock;
</code>
调用过程如（以昵称为例）：
<code>
[[[EMClient sharedClient] userInfoManager] updateOwnUserInfo:@"新的昵称" withType:EMUserInfoTypeNickName completion:^(EMUserInfo* aUserInfo,EMError *aError) {
        }];
</code>

===== 获取用户属性 =====
获取用户属性时，可以获取用户的所有属性，也可以获取用户的指定属性，如只获取昵称、头像等

  * 获取用户所有属性
获取用户所有属性的接口如下：
<code>
/*!
 *  \~chinese
 *  根据用户ID获取用户属性
 *
 *  @param aUserIds  要获取用户属性的的用户ID
 *  @param aCompletionBlock     完成回调
 *
 *  \~english
 *  Get user info by id
 *
 *  @param aUserIds       The users's id to get user info
 *  @param aCompletionBlock    The completion callback
 */
- (void)fetchUserInfoById:(NSArray<NSString*>*)aUserIds
                completion:(void (^)(NSDictionary*aUserDatas,EMError *aError))aCompletionBlock;
</code>
调用过程如下
<code>
[[[EMClient sharedClient] userInfoManager] fetchUserInfoById:[weakself.userIds copy] completion:^(NSDictionary *aUserDatas, EMError *aError) {
    if(!aError) {
        
    }
}];
</code>

  * 获取用户的指定用户属性
获取指定用户属性的接口如下：
<code>
/*!
 *  \~chinese
 *  根据用户ID获取用户指定属性
 *
 *  @param aUserIds  要获取用户属性的的用户ID
 *  @param aType         要获取哪些类型的用户属性
 *  @param aCompletionBlock     完成回调
 *
 *  \~english
 *  Get user special info by id
 *
 *  @param aUserIds       The users's id to get user info
 *  @param aType              The user info type to get
 *  @param aCompletionBlock    The completion callback
 */
- (void)fetchUserInfoById:(NSArray<NSString*>*)aUserIds
                      type:(NSArray<NSNumber*>*)aType
                completion:(void (^)(NSDictionary*aUserDatas,EMError *aError))aCompletionBlock
</code>

调用过程如下：
<code>
[[[EMClient sharedClient] userInfoManager] fetchUserInfoById:[weakself.userIds copy] type:@[[NSNumber numberWithInt:EMUserInfoTypeNickName],[NSNumber numberWithInt:EMUserInfoTypeAvatarURL]] completion:^(NSDictionary *aUserDatas, EMError *aError) {
    if(!aError && aUserDatas.count > 0) {
        // 这里存储下用户属性
    }
}];
</code>

===== 用户头像管理 =====

环信用户属性托管服务不负责管理用户头像文件，只存储头像文件的远程url地址，用户需要使用阿里云、腾讯云等第三方文件托管服务存储头像文件。当用户设置头像时，需要先将头像文件上传到第三方文件托管服务器，然后将上传后得到的url地址传入用户属性的头像url字段，设置用户属性。显示头像时，先从SDK获取用户属性，得到头像url字段，然后在UI层显示远程头像图片

===== 名片消息 =====

SDK 中没有名片类型的消息，Demo中名片消息的收发使用已有的自定义消息类型，通过指定自定义消息的event为"userCard",并在ext中添加展示名片所需要的环信id、昵称和头像，来展示用户名片。

名片消息发送过程如下：
<code>
EMCustomMessageBody* body = [[EMCustomMessageBody alloc] initWithEvent:@"userCard" ext:@{@"uid":aUid ,@"nickname":aNickName,@"avatar":aUrl}];
[self.chatController sendMessageWithBody:body ext:nil];
</code>
用户如果需要在名片中展示更丰富的信息，可以在ext中增加更多字段。

展示部分参见Demo中的**EMUserCardMsgView**类