补齐短板-开源IM项目OpenIM关于初始化/登录/好友接口文档介绍

OpenIM文档方面的建设一直远远落后于开发， 也经常被开发者诟病，在接下来一周的时间里，我们重点补齐文档，让开发者更轻松接入。由于app sdk底层都是go来实现，所以本文先写一个模板和框架，在接下来的时间里，会有iOS、Android、Flutter、Uniapp、jssdk同事补充具体的细节，并更新到官网

## 初始化及登录

初始化并登录成功回调，是正常使用OpenIM 服务的前提

| SDK              | 描述                                                         |
| :--------------- | :----------------------------------------------------------- |
| [Login]          | 登录，如果登录成功，必须退出登录才能再次执行登录操作         |
| [Logout]         | 退出登录                                                     |
| [GetLoginStatus] | 获取登录状态， 101：登录成功，   102：登陆中，   103：登录失败，  201：退出登录 |
| [GetLoginUser]   | 获取当前登录用户UserID，此时用户登录状态未知                 |
| [initSDK]        | 初始化 SDK，整个生命周期执行一次，登录相关监听介绍如下：     |

OpenIM和调用方利用监听回调机制，和调用方信息互通，把登录状态通过异步回调方式即时传递给调用方，确保信息及时传达而不阻塞其主线程。

## 监听说明

| 登录相关监听         | 回调描述                                                     |
| :------------------- | :----------------------------------------------------------- |
| [OnConnecting]       | 连接中，在连接后台时（包括重连）回调                         |
| [OnConnectSuccess]   | 连接成功                                                     |
| [OnConnectFailed]    | 连接失败，如果因网络连接失败会重连，其他情况不重连           |
| [OnKickedOffline]    | 被踢下线，可能由于多端登录策略所致，或后台管理员强制其退出登录 |
| [OnUserTokenExpired] | 检测token过期回调                                            |

## 调用流程

OpenIM调用流程分为如下几步：

（1）初始化：在整个生命周期执行一次

（2）设置监听：包括群组监听，好友监听，用户监听，消息及会话监听，这些监听会在其他章节中描述

（3）登录：登录回调成功后再执行其他操作，否则可能出现资源加载未完成的错误

（4）收发消息等操作；

## 好友管理相关接口

OpenIM提供好友关系托管，比如好友申请，同意，以及好友获取等，OpenIM在客户端本地存储好友关系，并结合消息通知机制，按需调用后台接口，确保本地和服务端数据一致。同时利用监听机制，把数据变化通过异步回调传达调用方。OpenIM在收发消息时，默认不检查好友关系，您可以在配置文件中自行修改。OpenIM好友关系是双向关系，A添加B为好友后，则A在B的好友列表中，B也在A的好友列表中，A删除B，仅仅只是删除A的好友列表，而B的好友列表不受影响。同样，黑名单也类似。


| SDK                            | 描述                                                     |
| :----------------------------- | :------------------------------------------------------- |
| [GetDesignatedFriendsInfo]     | 获取指定好友的信息                                       |
| [GetFriendList]                | 获取所有的好友列表                                       |
| [SearchFriends]                | 通过关键词搜索好友                                       |
| [CheckFriend]                  | 检查是否好友关系                                         |
| [AddFriend]                    | 发起添加好友请求                                         |
| [SetFriendRemark]              | 设置好友备注                                             |
| [DeleteFriend]                 | 删除好友（单向删除）                                     |
| [GetRecvFriendApplicationList] | 获取我收到的添加好友申请列表                             |
| [GetSendFriendApplicationList] | 获取我发起的的添加好友申请列表                           |
| [AcceptFriendApplication]      | 同意好友申请                                             |
| [RefuseFriendApplication]      | 拒绝好友申请                                             |
| [SetFriendListener]            | 设置好友、黑名单相关监听，用于UI层实时感知数据变化并刷新 |

## 监听说明

好友监听器的作用：调用方设置好友监听，好友关系的变化会通过OpenIM消息机制实时同步到需要感知的在线用户，包括用户的其他端，调用方根据回调事件做相关的数据处理。

比如用户B在Android端添加用户A为好友，用户A（所有在线的终端）收到B的好友申请，则A调用GetRecvFriendApplicationList获取收到的好友申请列表，刷新界面。同时，用户B在线其他的终端比如PC端也会收到通知，B调用GetSendFriendApplicationList获取发起的好友申请列表，刷新B发出的好友申请列表。

当然也可以利用回调的参数信息，做增量处理，而不用获取全量的好友申请列表。

以用户B申请添加用户A为例

| 好友及黑名单监听              | 描述                                                 |
| :---------------------------- | :--------------------------------------------------- |
| [OnFriendApplicationAdded]    | 好友申请列表增加，主动发起者和被动添加者会收到       |
| [OnFriendApplicationDeleted]  | 好友申请列表删除，主动删除者会收到                   |
| [OnFriendApplicationAccepted] | 好友申请被同意，主动发起者和被动添加者会收到         |
| [OnFriendApplicationRejected] | 好友申请被拒绝，主动发起者和被动添加者会收到         |
| [OnFriendAdded]               | 好友增加，用户好友增加时会收到                       |
| [OnFriendDeleted]             | 好友删除，用户好友减少时会收到                       |
| [OnFriendInfoChanged]         | 好友信息改变，用户好友信息（比如昵称等）改变时会收到 |
| [OnBlackAdded]                | 黑名单增加，用户黑名单增加时会收到                   |
| [OnBlackDeleted]              | 黑名单移除，用户黑名单减少时会收到                   |

## 项目介绍

OpenIM继续领跑开源IM领域，在广大开发者的支持下，目前github star突破9k。在数据泄露、信息外泄、隐私滥用的时代，IM私有化部署需求旺盛。其中，政企协同办公对IM需求猛增，随着信息化技术的迭代升级以及信创产业加速落地和实践，协同办公软件的发展潜力将进一步被释放。“安全可控“逐步成为第一要素。对于社区交友领域，暴露出的隐私安全问题越来越多，私有化部署确保用户数据不泄露。

OpenIM从服务端到客户端SDK开源即时通讯（IM）整体解决方案，可以轻松替代第三方IM云服务，打造具备聊天、社交、办公功能的app。

github地址： https://github.com/OpenIMSDK/Open-IM-Server

开发者中心：https://doc.rentsoft.cn/#/

## OpenIM团队

创始团队来自资深IM技术团队，我们致力于用开源技术创造服务价值，打造轻量级、高可用的IM架构，开发者只需简单调用 SDK，即可在应用内构建多种即时通讯及实时音视频互动场景。OpenIM优势：开源，安全，可靠，低成本。对于信息安全重视的电子政务，企业协同办公，OpenIM都是非常好的选择。

从公司成立之初就将“开源”作为核心战略来推进，开源充分体现了自由、平等、分享的互联网精神。

OpenIM邀请全球技术极客参与技术优化，让开发者轻松集成，让每一个应用都具备IM功能，同时考虑企业的接入成本、服务器资源以及最重要的数据安全性和私密性。