跳到主要内容

聊天室属性管理(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>;

参数说明

参数类型说明
targetIdstring聊天室 ID
keystring聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符
valuestring聊天室属性对应的值,最大长度 4096 个字符
deleteWhenLeftboolean用户掉线或退出时,是否自动删除该 Key、Value 值
overwriteboolean如果当前 key 存在,是否进行覆盖

返回值

返回值描述
Promise<number>当次接口操作状态码,并不代表最终操作结果,状态码详细信息

代码示例

engine.addChatRoomEntry(
targetId,
key,
value,
deleteWhenLeft,
overwrite
)
.then((code: number) => {});

回调方法

  • setOnChatRoomEntryAddedListener
setOnChatRoomEntryAddedListener(listener?: (code: number, targetId: string, key: string) => void): void;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
keystring聊天室属性名称

代码示例

engine. (
(
code,
targetId,
key
) => {}
);

添加多个聊天室 KV

方法

addChatRoomEntries(targetId: string, entries: Map<string, string>, deleteWhenLeft: boolean, overwrite: boolean): Promise<number>;

参数说明

参数类型说明
targetIdstring聊天室 ID
entriesMap<string, string>聊天室属性,键值对
deleteWhenLeftboolean用户掉线或退出时,是否自动删除该 Key、Value 值
overwriteboolean如果当前 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;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
entriesMap<string, string>聊天室属性
errorEntriesMap<string, number>发生错误的属性

代码示例

engine.setOnChatRoomEntriesAddedListener(
(
code: number,
targetId: string,
entries: Map<string, string>,
errorEntries: Map<string, number>
) => {}
);

加载聊天室 KV

方法

loadChatRoomEntry(targetId: string, key: string): Promise<number>;

参数说明

参数类型说明
targetIdstring聊天室 ID
keystring聊天室属性键值

返回值

返回值描述
Promise<number>当次接口操作状态码,并不代表最终操作结果,状态码详细信息

代码示例

engine.loadChatRoomEntry(
targetId,
key
)
.then((code: number) => {});

回调方法

  • setOnChatRoomEntryLoadedListener
setOnChatRoomEntryLoadedListener(listener?: (code: number, targetId: string, entry: Map<string, string>) => void): void;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
entriesMap<string, string>聊天室属性

代码示例

engine.setOnChatRoomEntryLoadedListener(
(
code,
targetId,
entry: Map<string, string>
) => {}
);

加载某个聊天室所有 KV

方法

loadAllChatRoomEntries(targetId: string): Promise<number>;

参数说明

参数类型说明
targetIdstring聊天室 ID

返回值

返回值描述
Promise<number>当次接口操作状态码,并不代表最终操作结果,状态码详细信息

代码示例

engine.loadAllChatRoomEntries(targetId);
.then((code: number) => {});

回调方法

  • setOnAllChatRoomEntriesLoadedListener
setOnAllChatRoomEntriesLoadedListener(listener?: (code: number, targetId: string, entries: Map<string, string>) => void): void;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
entriesMap<string, string>聊天室属性

代码示例

main.engine?.setOnAllChatRoomEntriesLoadedListener(
(
code: number,
targetId: string,
entries: Map<string, string>
) => {}
);

移除聊天室 KV

方法

removeChatRoomEntry(targetId: string, key: string, force: boolean): Promise<number>;

参数说明

参数类型说明
targetIdstring聊天室 ID
keystring要移除的聊天室属性名称
forcestring是否强制删除

返回值

返回值描述
Promise<number>当次接口操作状态码,并不代表最终操作结果,状态码详细信息

示例代码

engine.removeChatRoomEntry(
targetId,
key,
force
)
.then((code: number) => {});

回调方法

  • setOnChatRoomEntryRemovedListener
setOnChatRoomEntryRemovedListener(listener?: (code: number, targetId: string, key: string) => void): void;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
keystring移除的聊天室属性键值

代码示例

engine.setOnChatRoomEntryRemovedListener(
(
code: number,
targetId: string,
key: string
) => {}
);

移除聊天室多个 KV

方法

removeChatRoomEntries(targetId: string, keys: Array<string>, force: boolean): Promise<number>;

参数说明

参数类型说明
targetIdstring聊天室 ID
keysArray<string>要删除的聊天室属性集合
forceboolean是否强制删除

返回值

返回值描述
Promise<number>当次接口操作状态码,并不代表最终操作结果,状态码详细信息

代码示例

engine.removeChatRoomEntries(
targetId,
keys,
force
);
.then((code: number) => {});

回调方法

  • setOnChatRoomEntriesRemovedListener
setOnChatRoomEntriesRemovedListener(listener?: (code: number, targetId: string, keys: Array<string>) => void): void;

参数说明

参数类型说明
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring聊天室 ID
keysArray<string>移除的聊天室属性键值集合

代码示例

engine.setOnChatRoomEntriesRemovedListener(
(
code: number,
targetId: string,
keys: Array<string>
) => {}
);

聊天室时 KV 同步完成的回调

刚加入聊天室时 KV 同步完成的回调

方法

setOnChatRoomEntriesSyncedListener(listener?: (roomId: string) => void): void;

参数说明

参数类型说明
roomIdstring聊天室 ID

代码示例

engine.setOnChatRoomEntriesSyncedListener(
(
roomId: string
) => {}
);

聊天室 KV 变化的回调

如果刚进入聊天室时存在 KV,会通过此回调将所有 KV 返回,再次回调时为其他人设置或者修改 KV

方法

setOnChatRoomEntriesChangedListener(listener?: (operationType: RCIMIWChatRoomEntriesOperationType, roomId: string, entries: Map<string, string>) => void): void;

参数说明

参数类型说明
operationTypeRCIMIWChatRoomEntriesOperationTypeKV 变化的操作类型
roomIdstring聊天室 ID
entriesMap发生变化的 KV 集合

代码示例

engine.setOnChatRoomEntriesChangedListener(
(
operationType: RCIMIWChatRoomEntriesOperationType
roomId: string,
entries: Map<string, string>
) => {}
);