如何使用 TIMSDK 的自定义字段？

前言介绍

为了方便不同用户的定制化及业务需求，IMSDK 目前提供了五个维度的自定义字段

"用户资料自定义字段"，"好友自定义字段"，"群成员维度自定义字段"，"群维度自定义字段" 均已键值对 Key-Value 形式存储并使用。扩展相应的字段 Key，为相应的字段 Key 设置值 Value，这便是 IMSDK 字段的使用方式

"消息自定义字段" 有些不一样，请翻至对应的章节详阅

控制台添加自定义字段

1）进入控制台打开 "应用配置"

2）切换至 "功能配置" 页

3）将会看到 "用户资料自定义字段"，"好友自定义字段"，"群成员维度自定义字段"，"群维度自定义字段"

4）点击 " 新增自定义字段" 配置 "字段名称 Key" 和 "读写权限"

注意事项

字段名只能由字母、数字、下划线（_）组成，不能以数字开头，且长度不能超过16个字符，一旦添加成功后，便不可修改及删除

读写权限可再次编辑

用户资料自定义字段

相关 API

代码语言：javascript复制

modifySelfProfile()
-> 创建 HashMap，Key 为基础字段或自定义字段，Value 为需要设置的内容；

getSelfProfile()
getUsersProfile()
-> 接口返回 TIMUserProfile，通过成员方法 getCustomInfo() 获取自定义字段的键值对；

querySelfProfile()
queryUserProfile()
-> 接口返回 TIMUserProfile，通过成员方法 getCustomInfo() 获取自定义字段的键值对；

示例代码

写自定义字段：

代码语言：javascript复制

HashMap<String, Object> profileMap = new HashMap<>();
profileMap.put(TIMUserProfile.TIM_PROFILE_TYPE_KEY_NICK, "我的昵称");
profileMap.put(TIMUserProfile.TIM_PROFILE_TYPE_KEY_CUSTOM_PREFIX   "test", "--我的自定义字段信息--");
TIMFriendshipManager.getInstance().modifySelfProfile(profileMap, new TIMCallBack() {
    @Override
    public void onError(int code, String desc) {
        Log.e(tag, "modifySelfProfile failed: "   code   " desc: "   desc);
    }
    @Override
    public void onSuccess() {
        Log.i(tag, "modifySelfProfile success");
    }
});

读自定义字段：

代码语言：javascript复制

TIMFriendshipManager.getInstance().getSelfProfile(new TIMValueCallBack(){
    @Override
    public void onError(int code, String desc){
Log.e(tag, "getSelfProfile failed: "   code   " desc: "   desc);
    }
    @Override
    public void onSuccess(TIMUserProfile result){
        Log.i(tag, "getSelfProfile succ");
        Map<String, byte[]> customInfo = result.getCustomInfo();
    }
});

//获取本地保存的自己的资料
TIMUserProfile selfProfile = TIMFriendshipManager.getInstance().querySelfProfile();
Map<String, byte[]> customInfo = selfProfile.getCustomInfo();

好友自定义字段

相关 API

代码语言：javascript复制

modifyFriend()
-> 创建 HashMap，Key 为基础字段或自定义字段，Value 为需要设置的内容；

getFriendList()
-> 接口返回 TIMFriend，通过成员方法 getCustomInfo() 获取自定义字段的键值对；

queryFriend()
queryFriendList()
-> 接口返回 TIMFriend，通过成员方法 getCustomInfo() 获取自定义字段的键值对；

适用场景

添加好友成功后，可以对好友进行备注，标记好友来源等字段可供使用，某些特殊场景下需要用到自定义字段，例如：星标好友，好友亲密度等一些场景

示例代码

写自定义字段：

代码语言：javascript复制

HashMap<String, Object> friendInfo = new HashMap<>();
friendInfo.put(TIMFriend.TIM_FRIEND_PROFILE_TYPE_KEY_REMARK, "remark_test");
friendInfo.put(TIMFriend.TIM_FRIEND_PROFILE_TYPE_KEY_CUSTOM_PREFIX   "test", "--我的自定义字段信息--");
TIMFriendshipManager.getInstance().modifyFriend(identifier, friendInfo, new TIMCallBack() {
            @Override
            public void onError(int i, String s) {
                Log.e(tag, "modifyFriend failed: "   code   " desc: "   desc);
            }
            @Override
            public void onSuccess() {
                Log.i(tag, "modifyFriend success");
            }
        });

读自定义字段：

代码语言：javascript复制

TIMFriendshipManager.getInstance().getFriendList(new TIMValueCallBack>() {
        @Override
        public void onError(int code, String desc) {
               Log.e(tag, "getFriendList failed: "   code   " desc: "   desc);
        }
        @Override
        public void onSuccess(List result) {
               Log.i(tag, "getFriendList success");
               for (int i = 0; i < result.size();   i){
                    Map<String, byte[]> customInfo = result.get(i).getCustomInfo();
                    //TODO
               }
        }
});
        
//获取本地保存的好友列表
TIMFriend friend = TIMFriendshipManager.getInstance().queryFriend(“test01”);
Map<String, byte[]> customInfo = friend.getCustomInfo();

群成员维度自定义字段

相关 API

代码语言：javascript复制

(Android)modifyMemberInfo()
(iOS)modifyGroupMemberInfoSetCustomInfo()
-> 创建 Map，Key 为基础字段或自定义字段，Value 为需要设置的内容；

getGroupMembers()
getGroupMembersInfo()
-> 接口返回 TIMGroupMemberInfo，通过成员方法 getCustomInfo() 获取自定义字段的键值对；

适用场景

群成员信息包含一些基础字段，"角色: 群主，管理员", "群昵称", "加群时间" 等等，某些特殊场景需要用到自定义字段，例如："发言等级：潜水，冒泡，话痨"，群内粉丝数等一些场景

示例代码

写自定义字段：

代码语言：javascript复制

//Android
TIMGroupManager.ModifyMemberInfoParam param = new TIMGroupManager.ModifyMemberInfoParam(groupId, identifier);
Map<String, byte[]> customInfo = new HashMap<>();
try {
    customInfo.put("GroupMember_Test", "--我的自定义字段信息--".getBytes("utf-8"));
    param.setCustomInfo(customInfo);
} catch (UnsupportedEncodingException e) {
    e.printStackTrace();
}
TIMGroupManager.getInstance().modifyMemberInfo(param, new TIMCallBack() {
    @Override
    public void onError(int code, String desc) {
        Log.e(tag, "getFriendList failed: "   code   " desc: "   desc);
    }
    @Override
    public void onSuccess() {
        Log.i(tag, "modifyMemberInfo success");
    }
});

//iOS
[[TIMGroupManager sharedInstance] modifyGroupMemberInfoSetCustomInfo:@"@TGS#xXgroupidXx" user:@"iOS_001" customInfo:customInfo succ:^() {
    NSLog(@"modify group member customInfo succ");
}fail:^(int code, NSString* err) {
    NSLog(@"failed code: %d %@", code, err);
}];

读自定义字段：

代码语言：javascript复制

TIMGroupManager.getInstance().getGroupMembers("@TGS#xXgroupidXx", new TIMValueCallBack>() {
    @Override
    public void onError(int i, String s) {
        Log.e(tag, "getFriendList failed: "   i   " desc: "   s);
    }
    @Override
    public void onSuccess(List timGroupMemberInfos) {
        Log.i(tag, "modifyMemberInfo success");
        for (int i = 0; i < timGroupMemberInfos.size();   i){
            Map<String, byte[]> customInfo = timGroupMemberInfos.get(i).getCustomInfo();
            //TODO
        }
    }
});

群维度自定义字段

相关 API

代码语言：javascript复制

(Android)modifyGroupInfo()
(iOS)modifyGroupCustomInfo()
-> 创建 Map，Key 为基础字段或自定义字段，Value 为需要设置的内容；

getGroupInfo()
queryGroupInfo()
-> 接口返回 TIMGroupDetailInfo，通过成员方法 getCustom() 获取自定义字段的键值对；

适用场景

群组信息包含一些基础字段，"群组ID", "群主", "群头像" 等等，某些特殊场景需要用到自定义字段，例如："工作群，娱乐群等字段"，限制某些人员的群组等一些场景

示例代码

写自定义字段：

代码语言：javascript复制

//Android
TIMGroupManager.ModifyGroupInfoParam param = new TIMGroupManager.ModifyGroupInfoParam(groupId);
Map<String, byte[]> customInfo = new HashMap<>();
try {
    customInfo.put("Group_Test", "--我的自定义字段信息--".getBytes("utf-8"));
    param.setCustomInfo(customInfo);
} catch (UnsupportedEncodingException e) {
    e.printStackTrace();
}
TIMGroupManager.getInstance().modifyGroupInfo(param, new TIMCallBack() {
    @Override
    public void onError(int code, String desc) {
        Log.e(tag, "modifyGroupInfo failed: "   code   " desc: "   desc);
    }
    @Override
    public void onSuccess() {
        Log.i(tag, "modifyGroupInfo success");
    }
});

//iOS
[[TIMGroupManager sharedInstance] modifyGroupCustomInfo:@"@TGS#xXgroupidXx"  customInfo:customInfo succ:^() {
    NSLog(@"modify group customInfo succ");
}fail:^(int code, NSString* err) {
    NSLog(@"failed code: %d %@", code, err);
}];

读自定义字段：

代码语言：javascript复制

        ArrayList groupList = new ArrayList<>();
        groupList.add("@TGS#xXgroupidXx");
        TIMGroupManager.getInstance().getGroupInfo(groupList, new TIMValueCallBack>() {
            @Override
            public void onError(int i, String s) {
                Log.e(tag, "getGroupInfo failed: "   i   " desc: "   s);
            }
            @Override
            public void onSuccess(List timGroupDetailInfo) {
                Log.i(tag, "getGroupInfo success");
                for (int i = 0; i < timGroupDetailInfo.size();   i){
                Map<String, byte[]> customInfo = timGroupDetailInfo.get(i).getCustom();
                //TODO
            }
        });

消息自定义字段

相关 API

代码语言：javascript复制

setCustomInt()
setCustomStr()
-> 设置一个 int 类型或字符串类型来标记消息的自定义字段；

getCustomInt()
getCustomStr()
-> 返回设置的 int 或字符串；

适用场景

消息的自定义字段信息有两种，例如 Int 可以像微信一样标记语音消息是否播放过，0 为未播放，显示红点，1 为播放过了，不显示红点。Str 可以给消息分类，将开发者或用户的一些字段进行设置，再通过字段过滤某些消息

示例代码

代码语言：javascript复制

//写
msg.setCustomInt(1);
msg.setCustomStr("星标消息");
//读
int CustomInt = msg.getCustomInt();
String CustomStr = msg.getCustomStr();

注意事项

消息的自定义字段仅存储于本地，不会同步到 Server，更换终端或删除消息将不会再获取到

即时通信IM

0 人点赞