跳到主要内容

聊天室属性管理

聊天室属性(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,
callback: IRCIMIWAddChatRoomEntryCallback
): Promise<number>;

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性名称,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式,最大长度 128 个字符
valuestring聊天室属性对应的值,最大长度 4096 个字符
deleteWhenLeftboolean用户掉线或退出时,是否自动删除该 Key、Value 值
overwriteboolean如果当前 key 存在,是否进行覆盖
callbackIRCIMIWAddChatRoomEntryCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

代码示例

let callback = {
onChatRoomEntryAdded:(res) => {
//...
}};
let code = await engine.addChatRoomEntry(targetId, key, value, deleteWhenLeft, overwrite, callback);

回调方法

  • setOnChatRoomEntryAddedListener
setOnChatRoomEntryAddedListener(listener?: ({code, targetId, key}) => void): void;

参数说明

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

代码示例

engine.setOnChatRoomEntryAddedListener((res) => {
//...
});

添加多个聊天室 KV

方法

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

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
entriesMap<string, string>聊天室属性
deleteWhenLeftboolean用户掉线或退出时,是否自动删除该 Key、Value 值
overwriteboolean是否强制覆盖
callbackIRCIMIWAddChatRoomEntriesCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

代码示例

let callback = {
onChatRoomEntriesAdded:(res) => {
//...
}};
let code = await engine.addChatRoomEntries(targetId, entries, deleteWhenLeft, overwrite, callback);

回调方法

  • setOnChatRoomEntriesAddedListener
setOnChatRoomEntriesAddedListener(listener?: ({code, targetId, entries, errorEntries}) => void): void;

参数说明

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

代码示例

engine.setOnChatRoomEntriesAddedListener((res) => {
//...
});

加载聊天室 KV

方法

getChatRoomEntry(
targetId: string,
key: string,
callback: IRCIMIWGetChatRoomEntryCallback
): Promise<number>;

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性键值
callbackIRCIMIWGetChatRoomEntryCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

代码示例

let callback = {
onSuccess:(res) => {
//...
},
onError:(res) => {
//...
}};
let code = await engine.getChatRoomEntry(targetId, key, callback);

回调方法

  • setOnChatRoomEntryLoadedListener
setOnChatRoomEntryLoadedListener(listener?: ({code, targetId, entry}) => void): void;

参数说明

参数名参数类型描述
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring会话 ID
entryMap<string, string>获取到的属性。

代码示例

engine.setOnChatRoomEntryLoadedListener((res) => {
//...
});

加载某个聊天室所有 KV

方法

getChatRoomAllEntries(
targetId: string,
callback: IRCIMIWGetChatRoomAllEntriesCallback
): Promise<number>;

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
callbackIRCIMIWGetChatRoomAllEntriesCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

代码示例

let callback = {
onSuccess:(res) => {
//...
},
onError:(res) => {
//...
}};
let code = await engine.getChatRoomAllEntries(targetId, callback);

回调方法

  • setOnChatRoomAllEntriesLoadedListener
setOnChatRoomAllEntriesLoadedListener(listener?: ({code, targetId, entries}) => void): void;

参数说明

参数名参数类型描述
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring会话 ID
entriesMap<string, string>获取到的属性集合。

代码示例

engine.setOnChatRoomAllEntriesLoadedListener((res) => {
//...
});

移除聊天室 KV

方法

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

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
keystring聊天室属性键值
forceboolean是否强制删除
callbackIRCIMIWRemoveChatRoomEntryCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

示例代码

let callback = {
onChatRoomEntryRemoved:(res) => {
//...
}};
let code = await engine.removeChatRoomEntry(targetId, key, force, callback);

回调方法

  • setOnChatRoomEntryRemovedListener
setOnChatRoomEntryRemovedListener(listener?: ({code, targetId, key}) => void): void;

参数说明

参数名参数类型描述
codenumber接口回调的状态码,0 代表成功,非 0 代表出现异常
targetIdstring会话 ID
keystring聊天室属性键值

代码示例

engine.setOnChatRoomEntryRemovedListener((res) => {
//...
});

移除聊天室多个 KV

方法

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

参数说明

参数名参数类型描述
targetIdstring聊天室会话 ID
keysArray<string>聊天室属性
forceboolean是否强制覆盖
callbackIRCIMIWRemoveChatRoomEntriesCallback事件回调。SDK 从 5.3.1 版本开始支持 callback 方式回调。从 5.4.0 版本废弃该接口的其他回调方式。如果传入了 callback 参数,仅触发 callback 回调。

返回值

返回值描述
Promise<number>当次接口操作的状态码。0 代表调用成功 具体结果需要实现接口回调,非 0 代表当前接口调用操作失败,不会触发接口回调,详细错误参考状态码文档。

代码示例

let callback = {
onChatRoomEntriesRemoved:(res) => {
//...
}};
let code = await engine.removeChatRoomEntries(targetId, keys, force, callback);

回调方法

  • setOnChatRoomEntriesRemovedListener
setOnChatRoomEntriesRemovedListener(listener?: ({code, targetId, keys}) => void): void;

参数说明

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

代码示例

engine.setOnChatRoomEntriesRemovedListener((res) => {
//...
});

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

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

方法

setOnChatRoomEntriesSyncedListener(listener?: ({roomId}) => void): void;

参数说明

参数名参数类型描述
roomIdstring聊天室 ID

代码示例

engine.setOnChatRoomEntriesSyncedListener((res) => {
//...
});

聊天室 KV 变化的回调

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

方法

setOnChatRoomEntriesChangedListener(listener?: ({operationType, roomId, entries}) => void): void;

参数说明

参数名参数类型描述
operationTypeRCIMIWChatRoomEntriesOperationType操作的类型
roomIdstring聊天室 ID
entriesMap<string, string>发送变化的 KV

代码示例

engine.setOnChatRoomEntriesChangedListener((res) => {
//...
});