跳到主要内容

好友管理

本文档旨在指导开发者如何使用融云即时通讯 HarmonyOS IMLib SDK 实现添加好友、删除好友、查看好友列表、管理好友等功能。

提示

此功能从 25.12.0 版本开始支持。

开通服务​

信息托管服务已默认开通，您可以直接使用此功能。

好友事件监听​

为了及时接收好友添加删除、好友申请状态、好友全部清理、好友信息变更多端回调变更通知，您需要在应用调用 IMLib SDK 的初始化之后，且在调用 IMLib SDK 的连接之前，设置订阅好友事件监听器 FriendEventListener。

您可以调用 addFriendEventListener 设置好友事件监听器，如果不想再接收好友事件，调用 removeFriendEventListener 即可。

提示

信息托管服务中，好友操作产生的 SDK 通知回调也是一种状态通知行为，不管应用中是否实现 SDK 的事件监听，服务端都会对 SDK 进行状态同步，确保本地最新的好友关系状态，所以会计入消息的分发、下行数据统计中。

示例代码​

TypeScript
let listener: FriendEventListener = {
  onFriendAdd: (userId: string, name: string, portraitUri: string, directionType: number, operationTime: number) => {
    // 好友添加回调
  },
  onFriendDelete: (userIds: Array<string>, directionType: number, operationTime: number) => {
    // 好友删除回调
  },
  onFriendApplicationStatusChanged: (userId: string, applicationType: number, applicationStatus: number, directionType: number, operationTime: number, extra: string | null) => {
    // 好友申请状态变更回调
  },
  onFriendCleared: (operationTime: number) => {
    // 好友清空回调
  },
  onFriendInfoChangedSync: (userId: string, remark: string | null, extProfile: Map<string, string> | null, operationTime: number) => {
    // 好友信息变更多端回调事件
  },
};
IMEngine.getInstance().addFriendEventListener(listener).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 设置好友添加监听完成
  } else {
    // 设置好友添加监听失败
  }
});

好友在线状态与资料变更​

IMLib SDK 会自动处理好友之间的在线状态和用户资料变更。 如果您需要接收变更事件通知，您可以在 SDK 初始化之后，建立连接之前调用 addSubscribeEventListener 设置变更事件监听器。

订阅事件的变更，需要根据 SubscribeType 订阅类型来处理对应的业务：

  • SubscribeTypeFriendOnlineStatus(3) 时代表好友在线状态；
  • SubscribeTypeFriendUserProfile(4) 代表好友资料。
提示

您需要通过开发者后台开启"客户端好友资料变更通知"和"客户端好友在线状态变更通知"功能后，才能使用此功能，实时接收好友之间的在线状态和用户资料变更通知，通知行为也会计入单聊消息的分发、下行数据统计。

示例代码​

TypeScript
let listener: SubscribeEventListener = {
  onEventChange : (events: Array<SubscribeInfoEvent>) => {
    // 订阅事件变化
  },
  onSubscriptionSyncCompleted : (type: SubscribeType) => {
    // 订阅同步完成
  },
  onSubscriptionChangedOnOtherDevices : (events: Array<SubscribeEvent>) => {
    // 订阅在其他设备上发生变化
  }
}
IMEngine.getInstance().addSubscribeEventListener(listener);

好友操作​

添加好友​

您可以通过调用 addFriend 接口根据用户 userId 将指定用户添加为好友，添加时可通过设置 extra 将好友申请的附加信息同步给被添加的用户。

用户 userId 的获取可以使用融云提供的用户搜索功能。

提示

一个用户最多可以添加 3000 个好友。

示例代码​

TypeScript
// 添加的好友用户 ID
let userId: string = "userId";
// 添加双向好友
let directionType: FriendDirectionType = FriendDirectionType.FriendDirectionTypeBoth;
// 发送好友请求时的附加信息，长度不超过 128 个字符
let extra: string = "请求添加好友";
IMEngine.getInstance().addFriend(userId, directionType, extra).then((result: IAsyncResult<number>) => {
  if (result.code === EngineError.Success) {
    // 添加好友请求成功
  } else {
    // 添加好友请求失败
  }
});

设置加好友权限​

您可以使用 setFriendAddPermission 设置当前用户的加好友权限，未设置时以 AppKey 默认的加好友权限为准。

加好友权限说明​

  • AppKey 默认用户信息权限为 需要用户同意添加好友。
  • 用户的权限设置将覆盖 AppKey 的权限设置，若用户未设定自己的权限，此时将采用 AppKey 的权限设置。

加好友权限 FriendAddPermission 枚举介绍​

枚举值枚举说明
FriendAddPermissionFree任何人直接添加好友
FriendAddPermissionNeedVerify需要用户同意添加好友
FriendAddPermissionNoOneAllowed不允许任何人添加好友

示例代码​

TypeScript
let permission: FriendAddPermission = FriendAddPermission.FriendAddPermissionAllowAll;
IMEngine.getInstance().setFriendAddPermission(permission).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 设置好友添加权限完成
  } else {
    // 设置好友添加权限失败
  }
});

获取加好友权限​

您可以使用 getFriendAddPermission 获取当前用户的加好友权限。

示例代码​

TypeScript
IMEngine.getInstance().getFriendAddPermission().then((result: IAsyncResult<FriendAddPermission>) => {
  if (result.code === EngineError.Success) {
    // 获取加好友权限成功
  } else {
    // 获取加好友权限失败
  }
});

不同的权限设置，会产生以下两种流程​

场景1：添加好友不需要对方同意​

  1. 用户 A 和 B 调用 addFriendEventListener 设置好友事件监听。
  2. 用户 B 通过 setFriendAddPermission 设置加好友权限为：任何人直接添加好友（FriendAddPermissionFree），见 FriendAddPermission。
  3. 用户 A 调用 addFriend 申请添加 B 为好友，result.code === EngineError.Success，表示直接加为好友，同时用户 A 和 B 都会收到好友添加回调 onFriendAdd。

场景2：添加好友需要通过对方同意​

  1. 用户 A 和 B 调用 addFriendEventListener 设置好友事件监听。
  2. 用户 B 通过 setFriendAddPermission 设置加好友权限为：需要用户同意添加好友（FriendAddPermissionNeedVerify），见 FriendAddPermission。
  3. 用户 A 调用 addFriend 申请添加 B 为好友，回调 result.code === EngineError.FriendNeedAccept，表示需要等待用户 B 的同意，同时用户 A 和 B 都会收到好友申请状态回调 onFriendApplicationStatusChanged。
  4. 用户 B 收到 onFriendApplicationStatusChanged 回调，参数 FriendApplicationStatus 为 FriendApplicationStatusUnHandled，可以选择接受或者拒绝：
    • 用户 B 调用 acceptFriendApplication 接受好友请求，双方都会收到 onFriendAdd 回调，说明好友添加成功。
    • 用户 B 调用 refuseFriendApplication 拒绝好友请求，双方都会收到 onFriendApplicationStatusChanged 回调，参数 FriendApplicationStatus 为 FriendApplicationStatusRefused。

解除好友​

您可以使用 deleteFriends 批量解除好友关系。解除好友成功，双方都会收到好友删除回调 onFriendDelete。

接口每次调用最多支持解除 100 个好友。

示例代码​

TypeScript
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let directionType: FriendDirectionType = FriendDirectionType.FriendDirectionTypeBoth;
IMEngine.getInstance().deleteFriends(userIds, directionType).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 删除好友完成
  } else {
    // 删除好友失败
  }
});

检查好友关系​

您可以使用 checkFriends 检查好友关系，目前仅支持双向好友检查。

提示

一次最多检查 20 个用户。

示例代码​

TypeScript
// 好友用户 ID 列表
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
let friendType: FriendDirectionType = FriendDirectionType.FriendDirectionTypeBoth;
IMEngine.getInstance().checkFriends(userIds, friendType).then((result: IAsyncResult<Array<FriendRelationInfo>>) => {
  if (result.code === EngineError.Success) {
    // result.data 为好友关系信息列表
  } else {
    // 检查好友失败
  }
});

好友申请操作​

分页获取好友请求列表​

您可以使用 getFriendApplications 查看所有发送和接收的添加好友请求记录信息。

  • 此接口不支持返回请求总数。
  • 好友请求处理有效期为 7 天，融云服务端最多存储 7 天的请求数据，超过 7 天后需要重新发起请求。
提示

分页拉取说明：

  1. 首次拉取时，PagingQueryOption 的 pageToken 无需设置（不设置、设置null、设置""，效果等同）。
  2. 拉取第二页需要传入首次拉取返回结果 PagingQueryResult 类型中的 pageToken。
    • 如果不为 ""，则可以传入该值再次拉取，直至 pageToken 返回为 ""，表示全部拉取完成。
    • 如果为 ""，表示没有下一页或已拉取完成，无需再次拉取。如传递 ""，将视为拉取首页数据。

示例代码​

TypeScript
let pageToken: string = "";
let count: number = 10;
let order: boolean = false; // true：正序；false：倒序
let pagingOption: PagingQueryOption = new PagingQueryOption(pageToken, count, order);
let requestType: Array<FriendApplicationType> = [FriendApplicationType.FriendApplicationTypeSent, FriendApplicationType.FriendApplicationTypeReceived];
let requestStatus: Array<FriendApplicationStatus> = [FriendApplicationStatus.FriendApplicationStatusUnHandled, FriendApplicationStatus.FriendApplicationStatusAccepted];
IMEngine.getInstance().getFriendApplications(pagingOption, requestType, requestStatus).then((result: IAsyncResult<PagingQueryResult<FriendApplicationInfo>>) => {
  if (result.code === EngineError.Success) {
    // result.data 为好友申请信息列表
  } else {
    // 获取好友申请失败
  }
});

同意加为好友​

在收到添加好友请求后，调用 acceptFriendApplication 接受好友请求。触发成功回调后，好友添加成功，同时双方会触发 onFriendAdd 回调。

同时好友申请列表中的好友请求状态 FriendApplicationStatus 变为已同意（FriendApplicationStatusAccepted）。

示例代码​

TypeScript
let userId: string = "userId";
IMEngine.getInstance().acceptFriendApplication(userId).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 接受好友申请完成
  } else {
    // 接受好友申请失败
  }
});

拒绝加为好友​

在收到添加好友请求后，用户可以拒绝成为好友，调用 refuseFriendApplication 拒绝好友请求。

拒绝成功后，双方会触发 onFriendApplicationStatusChanged 回调，好友请求状态 FriendApplicationStatus 为已拒绝（FriendApplicationStatusRefused）。

示例代码​

TypeScript
let userId: string = "userId";
IMEngine.getInstance().refuseFriendApplication(userId).then((result: IAsyncResult<void>) => {
  if (result.code === EngineError.Success) {
    // 拒绝好友申请完成
  } else {
    // 拒绝好友申请失败
  }
});

好友信息的设置与获取​

获取好友列表​

您可以使用 getFriends 获取当前用户的好友列表。

示例代码​

TypeScript
let directionType: QueryFriendsDirectionType = QueryFriendsDirectionType.QueryFriendsDirectionTypeBoth;
IMEngine.getInstance().getFriends(directionType).then((result: IAsyncResult<Array<FriendInfo>>) => {
  if (result.code === EngineError.Success) {
    // 获取好友完成
  } else {
    // 获取好友失败
  }
});

好友信息设置​

您可以使用 setFriendInfo 设置好友的备注名和扩展信息。

提示
  • 扩展信息的 key 需要通过融云控制台 好友自定义属性 设置后才能使用，否则返回设置失败，最多可设置 10 个扩展信息 key。
  • 好友信息修改成功后，本用户登录的其他终端会收到好友信息变更多端回调 onFriendInfoChangedSync。
  • 默认情况下，设置的资料信息不支持审核。如需审核功能，请在需先按控制台内嵌指南嵌入到管理后台的 IM 服务功能配置页面（page_code: im_service_config）中，进入 安全&审核 > IM 信息托管审核，开启并设置需要审核的内容。

示例代码​

TypeScript
let userId: string = "userId";
let remark: string = "remark";
let extProfile: Map<string, string> = new Map<string, string>();
extProfile.set("key1", "value1");
extProfile.set("key2", "value2");
IMEngine.getInstance().setFriendInfo(userId, remark, extProfile).then((result: IAsyncResult<Array<string>>) => {
  if (result.code === EngineError.Success) {
    // 设置好友信息完成
  } else {
    // 设置好友信息失败
    if (result.data) {
      let errorKeys: Array<string> = result.data; // 失败的 key 数组
    }
  }
});

根据用户 ID 获取好友信息​

您可以使用 getFriendsInfo 根据用户 ID 获取好友信息。

该接口支持批量获取，您可以一次传入多个 userId 获取多个好友信息，最多不超过 100 个。

示例代码​

TypeScript
let userIds = new Array<string>();
userIds.push("userId1");
userIds.push("userId2");
IMEngine.getInstance().getFriendsInfo(userIds).then((result: IAsyncResult<Array<FriendInfo>>) => {
  if (result.code === EngineError.Success) {
    // 获取好友信息完成
  } else {
    // 获取好友信息失败
  }
});

根据好友昵称搜索好友信息​

您可以使用 searchFriendsInfo 根据好友昵称搜索好友信息。

搜索时默认先搜好友备注名 remark，再搜索好友名称 name。只要其中一个字段匹配成功，即返回搜索结果。

示例代码​

TypeScript
let name: string = "name";
IMEngine.getInstance().searchFriendsInfo(name).then((result: IAsyncResult<Array<FriendInfo>>) => {
  if (result.code === EngineError.Success) {
    // result.data 为好友信息列表
  } else {
    // 搜索好友失败
  }
});
AppKey 权限用户权限结果
FriendAddPermissionFree、FriendAddPermissionNeedVerify、FriendAddPermissionNoOneAllowed未设置以 AppKey 权限设置为准
FriendAddPermissionFree、FriendAddPermissionNeedVerify、FriendAddPermissionNoOneAllowed设置为（FriendAddPermissionFree、FriendAddPermissionNeedVerify、FriendAddPermissionNoOneAllowed）以用户权限设置为准