跳到主要内容

聊天室属性管理（KV）

从 1.1.0 版本开始，SDK 提供了聊天室属性（KV）管理接口，用于在指定聊天室中设置自定义属性。

在语音直播聊天室场景中，可利用此功能记录聊天室中各麦位的属性；或在狼人杀等卡牌类游戏场景中记录用户的角色和牌局状态等。

开通服务​

使用聊天室属性（KV）接口要求开通聊天室属性自定义设置服务。您可以前往控制台的免费基础功能页面开启服务。

聊天室业务还提供服务端回调功能，支持由融云服务端将应用下的全部聊天室属性变化（设置，删除，全部删除等操作）同步到您指定的地址，方便 App 业务服务端了解聊天室属性变化。详见服务端文档聊天室属性同步（KV）。

功能局限​

提示
  • 聊天室销毁后，聊天室中的自定义属性同时销毁。
  • 每个聊天室中，最多允许设置 100 个属性信息，以 Key-Value 的方式进行存储。
  • 客户端 SDK 未针对聊天室属性 KV 的操作频率进行限制。建议每个聊天室，每秒钟操作 Key-Value 频率保持在 100 次及以下（一秒内单次操作 100 个 KV 等同于操作 100 次）。

监听聊天室属性变化​

SDK 在聊天室业务中提供了 ChatroomKVStatusListener，用于监听聊天室属性（KV）变化。

/**
 * IMLib 聊天室 KV 状态变化监听器
 * @version 1.1.0
 */
interface ChatroomKVStatusListener {
  /**
   * IMLib 刚加入聊天室时 KV 同步完成的回调。加入聊天室成功后，SDK 默认从服务端同步 KV 列表，同步完成后触发。
   * 
   * @param roomId 聊天室 ID
   */
  onChatroomKVSync(roomId: string): void;

  /**
   * IMLib 聊天室 KV 变化的回调。聊天室 KV 更新时。如果刚进入聊天室时存在 KV，会通过此回调将所有 KV 返回，再次回调时为其他人设置或者修改 KV 的增量数据。
   * 
   * @param roomId 聊天室 ID
   * @param entries 发生变化的 KV，返回 KV 变化的增量数据。加入某个聊天室后第一次回调会返回全量 KV。
   */
  onChatroomKVUpdate(roomId: string, entries: Map<string, string>): void;

  /**
   * IMLib 聊天室 KV 被删除的回调。KV 被删除时触发。
   * 
   * @param roomId 聊天室 ID
   * @param entries 被删除的 KV
   */
  onChatroomKVRemove(roomId: string, entries: Map<string, string>): void;
}

设置聊天室 KV 监听器​

使用 setChatroomKVStatusListener 方法，添加聊天室 KV 监听器 setChatroomKVStatusListener。

let listener: ChatroomKVStatusListener = {

  onChatroomKVSync: (roomId: string): void => {
    hilog.info(0x0000, 'IM-App', 'onChatroomKVSync roomId:%{public}s', roomId);
  },

  onChatroomKVUpdate: (roomId: string, entries: Map<string, string>): void => {
    let json = JSON.stringify(Array.from(entries));
    hilog.info(0x0000, 'IM-App', 'onChatroomKVUpdate roomId:%{public}s entries:%{public}s', roomId, json);
  },

  onChatroomKVRemove: (roomId: string, entries: Map<string, string>): void => {
    let json = JSON.stringify(Array.from(entries));
    hilog.info(0x0000, 'IM-App', 'onChatroomKVRemove roomId:%{public}s entries:%{public}s', roomId, json);
  }

}

IMEngine.getInstance().setChatroomKVStatusListener(listener);

获取指定一批属性​

通过属性的 Key 获取指定聊天室中的一批属性 KV。

let roomId = "聊天室 ID";

let list = new List<string>();
list.add("key1");
list.add("key2");

IMEngine.getInstance().getChatroomEntries(roomId, list).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取 KV 失败
    return;
  }
  if (!result.data) {
    // KV 为空
    return;
  }
  // KV map
  let kvMap = result.data as Map<string,string>;
  
});
参数类型说明
roomIdstring聊天室 ID
liststring 集合聊天室属性名称列表 ,Key 支持大小写英文字母、数字、部分特殊符号 + = - _ 的组合方式，最大长度 128 个字符

获取所有属性​

获取指定聊天室中所有属性 KV 对。

let roomId = "聊天室 ID";

IMEngine.getInstance().getAllChatroomEntries(roomId).then(result => {
  if (EngineError.Success !== result.code) {
    // 获取 KV 失败
    return;
  }
  if (!result.data) {
    // KV 为空
    return;
  }
  // KV map
  let kvMap = result.data as Map<string,string>;
});
参数类型说明
roomIdstring聊天室 ID

批量设置属性​

批量设置聊天室属性。通过 overWrite 参数可控制是否强制覆盖他人设置的属性。

let roomId = "聊天室 ID";

let map = new Map<string, string>();
map.set("key1","value1");
map.set("key2","value2");

let autoDelete = true;
let overWrite = true;

IMEngine.getInstance().setChatroomEntries(roomId, map, autoDelete, overWrite).then(result => {
  if (EngineError.Success !== result.code) {
    // 设置 KV 失败
    return;
  }
  if (!result.data) {
    // 所有 KV 都设置成功
    return;
  }
  // 设置失败的 key 和对应的失败错误码，视情况决定是否重新设置失败的 KV 
  let errorMap = result.data as Map<string, EngineError>;
});

参数类型说明
roomIdstring聊天室 ID
mapMapmap size 最大限制为10，超过限制返回错误码 ChatroomKvLimit (23429)。
autoDeleteboolean用户掉线或退出时，是否自动删除该 Key、Value 值。
overWriteboolean是否强制覆盖

批量删除属性​

从指定单个聊天室中批量删除属性。单次最多删除 10 个属性。通过 isForce 参数可控制是否强制删除他人设置的属性。

let roomId = "聊天室 ID";

let list = new List<string>();
list.add("key1");
list.add("key2");

let isForce = true;

IMEngine.getInstance().deleteChatroomEntries(roomId, list, isForce).then(result => {
  if (EngineError.Success !== result.code) {
    // 删除 KV 失败
    return;
  }
  if (!result.data) {
    // 删除 KV 成功
    return;
  }
  // 删除失败的 K 和对应的错误，视情况决定是否重新删除失败的 KV 
  let errorMap = result.data as Map<string,EngineError>;
  
});
参数类型必填说明
roomIdString是聊天室 ID
liststring 集合是聊天室属性名称集合，集合 size 最大限制 10
isForceboolean是是否强制覆盖
最后于 更新