聊天室属性管理（KV）
聊天室属性（KV）管理接口用于在指定聊天室中设置自定义属性。
在语音直播聊天室场景中，可利用此功能记录聊天室中各麦位的属性；或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。
功能局限
提示
- 聊天室销毁后，聊天室中的自定义属性同时销毁。
- 每个聊天室中，最多允许设置 100 个属性信息，以
Key-Value的方式进行存储。 - 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室，每秒钟操作
Key-Value频率保持在 100 次及以下（一秒内单次操作 100 个 KV 等同于操作 100 次）。
开通服务
使用聊天室属性（KV）接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。
如果配置了服务端回调 URL，融云服务端会将应用下的聊天室属性变化（设置，删除，全部删除等操作）同步到指定的回调地址。详见服务端文档聊天室属性同步（KV）。
添加聊天室 KV
方法
Future<int> addChatRoomEntry(String targetId, String key, String value, bool deleteWhenLeft, bool overwrite, {IRCIMIWAddChatRoomEntryCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| key | String | 聊天室属性名称，Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符 |
| value | String | 聊天室属性对应的值，最大长度 4096 个字符 |
| deleteWhenLeft | bool | 用户掉线或退出时，是否自动删除该 Key、Value 值 |
| overwrite | bool | 如果当前 key 存在，是否进行覆盖 |
| callback | IRCIMIWAddChatRoomEntryCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
IRCIMIWAddChatRoomEntryCallback? callback = IRCIMIWAddChatRoomEntryCallback(onChatRoomEntryAdded: (int? code) {
//...
});
int? ret = await engine?.addChatRoomEntry(targetId, key, value, deleteWhenLeft, overwrite, callback:callback);
回调方法
- onChatRoomEntryAdded
Function(int? code, String? targetId, String? key)? onChatRoomEntryAdded;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| key | String | 聊天室属性名称 |
代码示例
engine?.onChatRoomEntryAdded = (int? code, String? targetId, String? key) {
//...
};
添加多个聊天室 KV
方法
Future<int> addChatRoomEntries(String targetId, Map entries, bool deleteWhenLeft, bool overwrite, {IRCIMIWAddChatRoomEntriesCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| entries | Ma<String, String> | 聊天室属性 |
| deleteWhenLeft | bool | 用户掉线或退出时，是否自动删除该 Key、Value 值 |
| overwrite | bool | 是否强制覆盖 |
| callback | IRCIMIWAddChatRoomEntriesCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
IRCIMIWAddChatRoomEntriesCallback? callback = IRCIMIWAddChatRoomEntriesCallback(onChatRoomEntriesAdded: (int? code, Map? errors) {
//...
});
int? ret = await engine?.addChatRoomEntries(targetId, entries, deleteWhenLeft, overwrite, callback:callback);
回调方法
- onChatRoomEntriesAdded
Function(int? code, String? targetId, Map? entries, Map? errorEntries)? onChatRoomEntriesAdded;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| entries | Ma<String, String> | 聊天室属性 |
| errorEntries | Ma<String, int> | 发生错误的属性 |
代码示例
engine?.onChatRoomEntriesAdded = (int? code, String? targetId, Map? entries, Map? errorEntries) {
//...
};
加载聊天室 KV
方法
Future<int> getChatRoomEntry(String targetId, String key, {IRCIMIWGetChatRoomEntryCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| key | String | 聊天室属性键值 |
| callback | IRCIMIWGetChatRoomEntryCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
IRCIMIWGetChatRoomEntryCallback? callback = IRCIMIWGetChatRoomEntryCallback(onSuccess: (Map? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getChatRoomEntry(targetId, key, callback:callback);
回调方法
- onChatRoomEntryLoaded
Function(int? code, String? targetId, Map? entry)? onChatRoomEntryLoaded;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| entry | Ma<String, String> | 获取到的属性。 |
代码示例
engine?.onChatRoomEntryLoaded = (int? code, String? targetId, Map? entry) {
//...
};
加载某个聊天室所有 KV
方法
Future<int> getChatRoomAllEntries(String targetId, {IRCIMIWGetChatRoomAllEntriesCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| callback | IRCIMIWGetChatRoomAllEntriesCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
IRCIMIWGetChatRoomAllEntriesCallback? callback = IRCIMIWGetChatRoomAllEntriesCallback(onSuccess: (Map? t) {
//...
}, onError: (int? code) {
//...
});
int? ret = await engine?.getChatRoomAllEntries(targetId, callback:callback);
回调方法
- onChatRoomAllEntriesLoaded
Function(int? code, String? targetId, Map? entries)? onChatRoomAllEntriesLoaded;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| entries | Ma<String, String> | 获取到的属性集合。 |
代码示例
engine?.onChatRoomAllEntriesLoaded = (int? code, String? targetId, Map? entries) {
//...
};
移除聊天室 KV
方法
Future<int> removeChatRoomEntry(String targetId, String key, bool force, {IRCIMIWRemoveChatRoomEntryCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| key | String | 聊天室属性键值 |
| force | bool | 是否强制删除 |
| callback | IRCIMIWRemoveChatRoomEntryCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
示例代码
IRCIMIWRemoveChatRoomEntryCallback? callback = IRCIMIWRemoveChatRoomEntryCallback(onChatRoomEntryRemoved: (int? code) {
//...
});
int? ret = await engine?.removeChatRoomEntry(targetId, key, force, callback:callback);
回调方法
- onChatRoomEntryRemoved
Function(int? code, String? targetId, String? key)? onChatRoomEntryRemoved;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| key | String | 聊天室属性键值 |
代码示例
engine?.onChatRoomEntryRemoved = (int? code, String? targetId, String? key) {
//...
};
移除聊天室多个 KV
方法
Future<int> removeChatRoomEntries(String targetId, List<String> keys, bool force, {IRCIMIWRemoveChatRoomEntriesCallback? callback});
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| targetId | String | 聊天室会话 ID |
| keys | List<String> | 聊天室属性 |
| force | bool | 是否强制覆盖 |
| callback | IRCIMIWRemoveChatRoomEntriesCallback | 事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数，仅触发 callback 回调。 |
返回值
| 返回值 | 描述 |
|---|---|
| Future<int> | 当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调，非 0 代表当前接口调用操作失败，不会触发接口回调，详细错误参考错误码 |
代码示例
IRCIMIWRemoveChatRoomEntriesCallback? callback = IRCIMIWRemoveChatRoomEntriesCallback(onChatRoomEntriesRemoved: (int? code) {
//...
});
int? ret = await engine?.removeChatRoomEntries(targetId, keys, force, callback:callback);
回调方法
- onChatRoomEntriesRemoved
Function(int? code, String? targetId, List<String>? keys)? onChatRoomEntriesRemoved;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| code | int | 接口回调的状态码，0 代表成功，非 0 代表出现异常 |
| targetId | String | 会话 ID |
| keys | List<String> | 聊天室属性键值集合 |
代码示例
engine?.onChatRoomEntriesRemoved = (int? code, String? targetId, List<String>? keys) {
//...
};
聊天室时 KV 同步完成的回调
刚加入聊天室时 KV 同步完成的回调
方法
Function(String? roomId)? onChatRoomEntriesSynced;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| roomId | String | 聊天室 ID |
代码示例
engine?.onChatRoomEntriesSynced = (String? roomId) {
//...
};
聊天室 KV 变化的回调
如果刚进入聊天室时存在 KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV
方法
Function(RCIMIWChatRoomEntriesOperationType? operationType, String? roomId, Map? entries)? onChatRoomEntriesChanged;
参数说明
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| operationType | RCIMIWChatRoomEntriesOperationType | 操作的类型 |
| roomId | String | 聊天室 ID |
| entries | Ma<String, String> | 发送变化的 KV |
代码示例
engine?.onChatRoomEntriesChanged = (RCIMIWChatRoomEntriesOperationType? operationType, String? roomId, Map? entries) {
//...
};