聊天室属性管理(KV)
聊天室属性(KV)管理接口用于在指定聊天室中设置自定义属性。
在语音直播聊天室场景中,可利用此功能记录聊天室中各麦位的属性;或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。
功能局限
提示
- 聊天室销毁后,聊天室中的自定义属性同时销毁。
- 每个聊天室中,最多允许设置 100 个属性信息,以
Key-Value
的方式进行存储。 - 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室,每秒钟操作
Key-Value
频率保持在 100 次及以下(一秒内单次操作 100 个 KV 等同于操作 100 次)。
开通服务
使用聊天室属性(KV)接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。
如果配置了服务端回调 URL,融云服务端会将应用下的聊天室属性变化(设置,删除,全部删除等操作)同步到指定的回调地址。详见服务端文档聊天室属性同步(KV)。
添加聊天室 KV
方法
addChatRoomEntry(targetId: string, key: string, value: string, deleteWhenLeft: boolean, overwrite: boolean): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
key | string | 聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符 |
value | string | 聊天室属性对应的值,最大长度 4096 个字符 |
deleteWhenLeft | boolean | 用户掉线或退出时,是否自动删除该 Key、Value 值 |
overwrite | boolean | 如果当前 key 存在,是否进行覆盖 |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表最终操作结果,状态码详细信息 |
代码示例
engine.addChatRoomEntry(
targetId,
key,
value,
deleteWhenLeft,
overwrite
)
.then((code: number) => {});
回调方法
- setOnChatRoomEntryAddedListener
setOnChatRoomEntryAddedListener(listener?: (code: number, targetId: string, key: string) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
key | string | 聊天室属性名称 |
代码示例
engine. (
(
code,
targetId,
key
) => {}
);
添加多个聊天室 KV
方法
addChatRoomEntries(targetId: string, entries: Map<string, string>, deleteWhenLeft: boolean, overwrite: boolean): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
entries | Map<string, string> | 聊天室属性,键值对 |
deleteWhenLeft | boolean | 用户掉线或退出时,是否自动删除该 Key、Value 值 |
overwrite | boolean | 如果当前 key 存在,是否进行覆盖 |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表最终操作结果,状态码详细信息 |
代码示例
engine.addChatRoomEntries(
targetId,
entries,
deleteWhenLeft,
overwrite
)
.then((code: number) => {});
回调方法
- setOnChatRoomEntriesAddedListener
setOnChatRoomEntriesAddedListener(listener?: (code: number, targetId: string, entries: Map<string, string>, errorEntries: Map<string, number>) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
entries | Map<string, string> | 聊天室属性 |
errorEntries | Map<string, number> | 发生错误的属性 |
代码示例
engine.setOnChatRoomEntriesAddedListener(
(
code: number,
targetId: string,
entries: Map<string, string>,
errorEntries: Map<string, number>
) => {}
);
加载聊天室 KV
方法
loadChatRoomEntry(targetId: string, key: string): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
key | string | 聊天室属性键值 |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表 最终操作结果,状态码详细信息 |
代码示例
engine.loadChatRoomEntry(
targetId,
key
)
.then((code: number) => {});
回调方法
- setOnChatRoomEntryLoadedListener
setOnChatRoomEntryLoadedListener(listener?: (code: number, targetId: string, entry: Map<string, string>) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
entries | Map<string, string> | 聊天室属性 |
代码示例
engine.setOnChatRoomEntryLoadedListener(
(
code,
targetId,
entry: Map<string, string>
) => {}
);
加载某个聊天室所有 KV
方法
loadAllChatRoomEntries(targetId: string): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表最终操作结果,状态码详细信息 |
代码示例
engine.loadAllChatRoomEntries(targetId);
.then((code: number) => {});
回调方法
- setOnAllChatRoomEntriesLoadedListener
setOnAllChatRoomEntriesLoadedListener(listener?: (code: number, targetId: string, entries: Map<string, string>) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
entries | Map<string, string> | 聊天室属性 |
代码示例
main.engine?.setOnAllChatRoomEntriesLoadedListener(
(
code: number,
targetId: string,
entries: Map<string, string>
) => {}
);
移除聊天室 KV
方法
removeChatRoomEntry(targetId: string, key: string, force: boolean): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
key | string | 要移除的聊天室属性名称 |
force | string | 是否强制删除 |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表最终操作结果,状态码详 细信息 |
示例代码
engine.removeChatRoomEntry(
targetId,
key,
force
)
.then((code: number) => {});
回调方法
- setOnChatRoomEntryRemovedListener
setOnChatRoomEntryRemovedListener(listener?: (code: number, targetId: string, key: string) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
key | string | 移除的聊天室属性键值 |
代码示例
engine.setOnChatRoomEntryRemovedListener(
(
code: number,
targetId: string,
key: string
) => {}
);
移除聊天室多个 KV
方法
removeChatRoomEntries(targetId: string, keys: Array<string>, force: boolean): Promise<number>;
参数说明
参数 | 类型 | 说明 |
---|---|---|
targetId | string | 聊天室 ID |
keys | Array<string> | 要删除的聊天室属性集合 |
force | boolean | 是否强制删除 |
返回值
返回值 | 描述 |
---|---|
Promise<number> | 当次接口操作状态码,并不代表最终操作结果,状态码详细信息 |
代码示例
engine.removeChatRoomEntries(
targetId,
keys,
force
);
.then((code: number) => {});
回调方法
- setOnChatRoomEntriesRemovedListener
setOnChatRoomEntriesRemovedListener(listener?: (code: number, targetId: string, keys: Array<string>) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
code | number | 接口回调的状态码,0 代表成功,非 0 代表出现异常 |
targetId | string | 聊天室 ID |
keys | Array<string> | 移除的聊天室属性键值集合 |
代码示例
engine.setOnChatRoomEntriesRemovedListener(
(
code: number,
targetId: string,
keys: Array<string>
) => {}
);
聊天室时 KV 同步完成的回调
刚加入聊天室时 KV 同步完成的回调
方法
setOnChatRoomEntriesSyncedListener(listener?: (roomId: string) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
roomId | string | 聊天室 ID |
代码示例
engine.setOnChatRoomEntriesSyncedListener(
(
roomId: string
) => {}
);
聊天室 KV 变化的回调
如果刚进入聊天室时存在 KV,会通过此回调将所有 KV 返回,再次回调时为其他人设置或者修改 KV
方法
setOnChatRoomEntriesChangedListener(listener?: (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => void): void;
参数说明
参数 | 类型 | 说明 |
---|---|---|
operationType | RCIMIWChatRoomEntriesOperationType | KV 变化的操作类型 |
roomId | string | 聊天室 ID |
entries | Map | 发生变化的 KV 集合 |
代码示例
engine.setOnChatRoomEntriesChangedListener(
(
operationType: RCIMIWChatRoomEntriesOperationType
roomId: string,
entries: Map<string, string>
) => {}
);