SDK API 概述

本文介绍 Android SDK API 的概述性信息，并列出核心 API 与核心类或接口类，方便您查阅 API 信息。

接口类型

NIM Android SDK （以下简称 SDK）提供两种接口类，供开发者使用：

类型	说明
第三方 APP 主动发起请求	接口名均以 `Service` 结尾，例如 `AuthService`
第三方 APP 作为观察者监听事件和变化	接口名均以 `ServiceObserver` 结尾，例如 `AuthServiceObserver`。个别太长的类名则直接以 `Observer` 结尾，例如 `SystemMessageObserver`

注：

SDK 接口调用必须在主进程中进行，请在主进程中调用 SDK 的 XXXService 提供的方法，在主进程中注册 XXXServiceObserver 的观察者（有事件变更，会回调给主进程的主线程）。
如果您的模块运行在非主进程，请自行实现主进程与非主进程的通信（AIDL/Messenger/ContentProvider/BroadcastReceiver等 IPC 渠道）将主进程回调或监听返回的数据传递给非主进程。

返回值类型

SDK 提供三种接口返回值：

基本数据类型（同步接口）
InvocationFuture（异步接口）
AbortableFuture（异步接口）：异步接口基本都从主进程发起调用，然后在后台进程执行，最后再将结果返回给主进程

注：

如果调用 AbortableFuture 异步接口，传输大量数据或者出现耗时很长的情况，可通过 abort 方法中断请求。例如上传下载、登录等。

异步接口可通过 RequestCallback 和 RequestCallbackWrapper 两种方式设置回调函数。

异步接口回调函数	说明
`RequestCallback`	需要实现三个接口：成功 `onSuccess`，失败 `onFailed`，异常 `onException`
`RequestCallbackWrapper`	需要实现 `onResult`。封装了成功、失败和异常三个接口，在参数上进行区分

SDK API 调用框架

自 v4.4.0 起，API 调用框架增强：

支持带 Looper 的非 UI 线程发起的异步 API 调用，直接回调到调用者线程。v4.4.0 之前版本会默认回调到 UI 线程。
提供异步强制转成同步的接口：NIMClient::syncRequest，允许设置最大同步等待时间，支持非 UI 线程里需要同步调用云信 API的场景。
添加自动生成的 NIM SDK 类，您可直接采用 NIMSDK::getXXXService 方法获取服务接口，不再需要传递 XXXService.class，简化 API 调用方式。其他插件自动生成的调用入口类为：NIMChatRoomSDK、NIMLuceneSDK。例如采用 NIMSDK.getAuthService().login() 替换 NIMClient.getService(AuthService.class).login()。

SDK 数据缓存目录结构

当收到多媒体消息后，SDK 会负责下载这些多媒体文件，同时 SDK 还会记录一些关键的日志，因此 SDK 需要一个数据缓存目录。

注：

数据缓存目录可以在 SDK 初始化时通过 SDKOptions::sdkStorageRootPath 进行设置。如果不设置，则默认为“/{外卡根目录}/{app_package_name}/nim/”，其中外卡根目录获取方式为 Environment.getExternalStorageDirectory().getPath()。
如果您的 APP 需要清除缓存功能，可扫描该目录下的文件，按照用户的规则清理即可。
在 SDK 初始化完成后可以通过 NimClient::getSdkStorageDirPath 获取 SDK 数据缓存目录。

log: SDK日志包含一个文件：nim_sdk.log，大小一般不超过 8M。音视频通话的日志包含3个文件：avchat_n.log, nrtc_engine.log, nrtc_net.log。默认路径为：**/{外卡根目录}/{app_package_name}/nim/log/**，如果在 SDKOptions 中配置过 sdkStorageRootPath，那么日志路径为“{sdkStorageRootPath}/log/”。
file: 文件消息文件
image: 图片消息文件
audio：语音消息文件
video：视频消息文件
thumb：图片/视频缩略图文件

SDK 核心类/接口类

初始化与登录相关

类/接口	说明
NIMClient	SDK 核心类，提供初始化 SDK，获取各个服务能力接口，获取当前状态等接口
SdkLifecycleObserver	SDK 生命周期观察者接口类，提供监听主进程初始化状态的接口
MiscService	其他接口类，提供日志文件上传、SDK 本地缓存、获取云信服务端时间等接口
AuthService	用户认证服务接口类，提供用户登录登出业务相关接口
AuthServiceObserver	用户认证服务观察者接口类，提供用户登录登出相关监听接口

消息（单聊 & 群聊）与会话相关

类/接口	说明
MessageBuilder	云信 IM 消息构造器，提供构建各类型消息的接口
MsgService	云信消息服务接口类，提供消息发送、消息查询、历史消息、消息扩展功能、获取未读数、已读回执、会话列表等相关接口
MsgServiceObserve	云信 IM 消息服务观察者接口类，提供接收消息，消息状态变化等的监听接口
AudioRecorder	高清语音录制工具类，提供语音录制相关接口
AudioPlayer	和 AudioRecorder 对应音频播放器，提供语音播放相关接口
NosService	网易云存储服务（NOS）接口类，提供云存储相关接口
SystemMessageService	云信 IM 系统通知接口类，提供系统通知查询和管理接口
SystemMessageObserver	云信 IM 系统通知观察者接口类，提供系统通知相关监听接口
LuceneService	全文检索接口类，提供会话检索相关接口
NosService	网易云存储服务接口类，提供文件上传和下载等接口
NosServiceObserve	网易云存储传输进度监听接口
AVChatManager	语音视频通话接口类，提供语音、视频相关操作等接口
RTSManager	实时会话接口类
RedPacketService	红包接口类，提供获取红包 sdk token 等功能接口

第三方离线推送相关

类/接口	说明
MixPushService	IM 的第三方离线推送服务接口类，提供 IM 的第三方离线推送服务相关配置接口

群组相关

类/接口	说明
TeamService	群组接口类，提供创建群组、添加群成员等群组操作相关接口
TeamServiceObserver	群组观察者接口类，提供监听群组成员变动、群组信息变动等的监听接口

超大群相关

类/接口	说明
SuperTeamService	超大群服务接口类，提供超大群成员管理、超大群消息发送、超大群资料管理等相关接口
SuperTeamServiceObserver	超大群观察者接口类，提供超大群监听接口

聊天室相关

类/接口	说明
ChatRoomService	聊天室服务接口类，提供进出聊天室、发送聊天室消息、聊天室成员管理、聊天室队列服务、聊天室标签等接口
ChatRoomMessageBuilder	聊天室消息构造器，提供构造各类型聊天室消息的接口
ChatRoomServiceObserver	聊天室观察者接口类，提供聊天室监听接口

圈组相关

类/接口	说明
QChatService	圈组接口类，提供圈组登录登出相关接口
QChatServerService	圈组服务器接口类，提供圈组服务器相关接口，如果创建服务器、邀请服务器成员、查询服务器成员等
QChatChannelService	圈组频道接口类，提供圈组频道相关接口，如果创建频道、查询频道、查询频道未读信息等接口
QChatMessageService	圈组消息接口类，提供发送消息、撤回消息、发送消息正在输入事件等接口
QChatServiceObserver	圈组观察者接口类，提供圈组监听接口
QChatPushService	圈组的第三方离线推送服务接口类，提供圈组的第三方离线推送服务相关配置接口
QChatMediaKit	圈组多媒体频道接口类，提供圈组多媒体频道的初始化、连接、修改多媒体频道参数等接口
QChatRTCChannelController	圈组多媒体频道控制器，提供多媒体频道成员管理、摄像头切换、扬声器管理、视频画布设置等接口
QChatRTCChannelListener	圈组多媒体频道事件监听器，提供多媒体频道的监听接口

用户资料相关

类/接口	说明
UserService	用户资料操作相关接口，如更新本人的用户资料、搜索与关键字匹配的用户等
UserInfoProvider	用户信息提供者，由开发者提供用户信息给 SDK

好友关系相关

类/接口	说明
FriendService	好友关系服务接口类，提供好友管理、好友关系、黑名单、消息提醒等相关接口
FriendServiceObserve	好友关系、黑名单变更等的监听接口

事件订阅相关

类/接口	说明
EventSubscribeService	事件订阅服务接口类，提供事件订阅等相关接口
EventSubscribeServiceObserver	事件状态变更等的监听接口

系统设置

类/接口	说明
SettingsService	系统设置接口类，提供多端推送、免打扰配置等相关接口
SettingsServiceObserver	系统设置变更等的监听接口

机器人相关

类/接口	说明
RobotService	机器人操作相关接口类，提供获取机器人、获取机器人信息、判断是否是机器人等功能接口
RobotServiceObserve	机器人数据变更等的监听接口

SDK 核心 API

初始化与登录

类/接口	说明
init	在 Application::onCreate 中初始化 SDK
config	在 Application::onCreate 中进行初始化配置注：调用该方法仅仅是进行初始化配置，调用该方法后还需调用下文的 initSDK 方法进行真正的初始化
initSDK	在 UI 进程主线程上按需进行初始化SDK，支持通过 SDKOptions::asyncInitSDK 配置为同步或异步初始化，并支持通过 SDKOptions::reducedIM 配置为弱 IM 模式，延迟加载push进程服务注：调用该方法前，必须先在 Application::onCreate 中调用上文的 config 方法请不要再 Application::onCreate 中调用该方法
getService	获取各服务接口，例如获取 MsgService
getStatus	获取当前用户的登录状态（在线状态）
getCurrentAccount	获取当前用户的 IM 账号（accid）
updateStrings	当系统语言发生变化时，更新文案配置。配置不能立即生效，所有文案均需要在下次使用时才会生效
getSdkStorageDirPath	获取SDK数据目录路径，需要在初始化 SDK 之后调用
getSDKVersion	运行时获取当前 SDK 版本号
login	登录 IM
logout	登出 IM
kickOtherClient	将同时在线的其他设备端踢下线

消息（单聊与群聊）

类/接口	说明
createTextMessage	构建一条文本消息, 构建后需调用 sendMessage 方法发送
createImageMessage	构建一条图片消息,构建后需调用 sendMessage 方法发送
createAudioMessage	构建一条语音消息, 构建后需调用 sendMessage 方法发送
createVideoMessage	构建一条视频消息, 构建后需调用 sendMessage 方法发送
createFileMessage	构建一条文件消息, 构建后需调用 sendMessage 方法发送
createLocationMessage	构建一条地理位置消息, 构建后需调用 sendMessage 方法发送
createTipMessage	构建一条提示消息, 构建后需调用 sendMessage 方法发送
createCustomMessage	构建一条自定义消息, 构建后需调用 sendMessage 方法发送
createEmptyMessage	构建一条空消息, 仅可设置聊天对象、会话类型和时间点，用于记录查询。构建后需调用 sendMessage 方法发送
createForwardMessage	构建一条转发消息，构建后需调用 sendMessage 方法发送
createForwardMessageListFileDetail	创建多条待合并转发的消息，构建后需调用 sendMessage 方法发送
sendMessage	发送消息，如果需要更新发送进度，请调用MsgServiceObserve::observeMsgStatus
saveMessageToLocalEx	保存消息到本地数据库，但不发送到服务器端。用于应用保存本地提醒一类的消息。与其他 SDK API 的组合调用示例，可参见收发提示消息
deleteMsgSelf	单向删除多条消息
updateIMMessage	更新消息。目前只能更新本地扩展字段 LocalExtension
updateIMMessageStatus	更新消息记录的状态。可更新：消息状态 IMMessage::getStatus() 不为 null 时更新附件状态 IMMessage::getAttachStatus() 不为 null 时更新附件内容 IMMessage::getAttachment() 不为 null 时更新
revokeMessage	撤回消息，并设置相应的第三方推送配置（包括IOS平台的推送）与未读数变化

历史消息

类/接口	说明
clearServerHistory	清空服务端的单聊历史消息
deleteRangeHistory	根据时间范围删除本地历史消息
searchMessageHistory	从本地消息数据库搜索消息历史
queryMessageListByUuid	通过 uuid 批量获取历史消息
pullMessageHistoryEx	从服务器拉取消息历史记录
searchRoamingMsg	云端聊天记录关键词查询
queryThreadTalkHistory	分页查询指定时间段内的云端 Thread 历史消息（单聊、群/超大群）

消息扩展

类/接口	说明
replyMessage	引用一条消息进行回复，形成消息回复树状结构（Thread）
queryThreadTalkHistory	查询 Thread 聊天云端历史（支持单聊、群聊、超大群）
addQuickComment	添加快捷评论，如表情等 reaction
removeQuickComment	移除快捷评论
queryQuickComment	获取快捷评论列表
addCollect	将某条消息添加为收藏
removeCollect	批量移除收藏
addMsgPin	PIN 一条消息
updateMsgPin	更新一条消息的 PIN
removeMsgPin	移除一条消息的 PIN

会话列表

类/接口	说明
queryRecentContacts	查询最近联系人会话列表数据，可按时间逆序或者正序查询指定数量的最新会话列表数据
queryMySession	获取某一个会话
updateRecentAndNotify	更新一条最近联系人会话的属性，并会触发MsgServiceObserve::observeRecentContact(Observer, boolean)的通知。如果仅仅是想更新最近联系人会话但不想收到通知，可调用MsgService::updateRecent(RecentContact)
deleteRecentContact	删除最近联系人记录
createEmptyRecentContact	创建一条空的联系人会话
getTotalUnreadCount	获取未读数总数
queryUnreadMessageList	根据会话ID和会话类型查找未读消息列表
clearUnreadCount	将指定会话类型的未读数清零(标记已读)
queryCollect	从服务的分页查询收藏列表
addStickTopSession	添加一个置顶会话
removeStickTopSession	删除置顶会话
updateStickTopSession	更新一个置顶会话的扩展字段
queryStickTopSessionBlock	获取置顶会话信息的列表

离线推送与消息提醒

类/接口	说明
enable	开启/关闭第三方离线推送服务
setPushNoDisturbConfig	设置推送免打扰时间
setPushShowNoDetail	设置离线推送是否不展示推送文案详情
toggleNotification	通知栏提醒开关控制。该方法只有在 SDKOptions::StatusBarNotificationConfig 配置不为空时调用才有效

群组

类/接口	说明
createTeam	创建一个群组
addMembersEx	添加成员
removeMember	移除单个成员，只有群组创建者有此权限
updateTeam	更新群组资料
dismissTeam	解散群，只有群主有权限
quitTeam	退出群
queryTeam	查询群资料，如果本地没有群组资料，则去服务器查询
queryTeamList	获取自己加入的群列表
queryTeamListById	根据群 ID 列表批量查询群信息
searchTeam	从服务器上查询群资料信息
applyJoinTeam	申请加入群
passApply	同意入群申请
rejectApply	拒绝入群申请
addManagers	添加管理员，仅群主有此权限
removeManagers	移除管理员，仅群主有此权限
transferTeam	转让群
acceptInvite	接受别人的入群邀请
declineInvite	拒绝别人的入群邀请
queryMemberList	获取指定群的成员信息列表
muteTeamMember	禁言或解除禁言
muteAllTeamMember	对整个群禁言或解除禁言，对普通成员生效，只有群主和管理员有权限
queryMutedTeamMembers	查询被禁言群成员列表
sendTeamMessageReceipt	(群消息接收方)标记群组消息已读

超大群

类/接口	说明
addMembers	添加超大群成员
removeMembers	移出超大群的群成员，只有群主有权限
quitTeam	退出超大群
transferTeam	转让超大群
applyJoinTeam	申请加入超大群
passApply	同意入群申请
rejectApply	拒绝入群申请
acceptInvite	接受别人的入群邀请
declineInvite	拒绝别人的入群邀请
addManagers	添加管理员，仅群主有此权限
removeManagers	移除管理员，仅群主有此权限
muteTeamMembers	禁言或解除禁言
muteAllTeamMember	对整个群禁言或解除禁言，对普通成员生效，只有群主和管理员有权限
queryMutedTeamMembers	查询被禁言群成员列表
updateTeam	更新超大群的资料
queryTeamList	获取自己已加入的超大群列表
sendMessage	在超大群里发送消息
revokeMessage	撤回超大群消息
replyMessage	引用一条超大群消息进行回复，形成回复树状结构（Thread）
clearUnreadCount	将指定超大群的未读数清零(标记已读)

聊天室

类/接口	说明
enterChatRoomEx	进入聊天室
getEnterErrorCode	获取进入聊天室失败的错误码
exitChatRoom	退出聊天室
sendMessage	在聊天室内发送消息
pullMessageHistoryEx	获取聊天室历史消息
getMessagesByTags	按标签从云端拉取聊天室消息，每一个标签代表的是某个标签化分组下的聊天室成员
kickMember	将特定成员踢出聊天室
fetchRoomMembers	获取聊天室成员信息
fetchRoomMembersByIds	根据用户的 IM 账号（accid）获取聊天室成员信息
markChatRoomBlackList	将用户添加或移出聊天室黑名单
markChatRoomMutedList	将用户添加到禁言名单或取消禁言
markChatRoomTempMute	设置聊天室成员临时禁言
markNormalMember	将用户设为聊天室普通成员，或取消其普通成员角色
markChatRoomManager	将用户设为聊天室管理员，或取消其聊天室管理员角色
markChatRoomTempMuteByTag	禁言某个标签的用户的发言，只有管理员或创建者能操作
updateMyRoomRole	更新本人在聊天室内的信息
updateRoomInfo	更新聊天室信息
updateQueue	加入或者更新聊天室队列的元素。聊天室队列指聊天室（房间）中由多个元素（key-value 键值对）构成的队列，应用于直播间中的连麦队列场景和礼物队列展示等涉及队列化展示的场景，其中的元素可以是麦位、礼物展示位等
batchUpdateQueue	批量更新聊天室队列的元素
pollQueue	取出聊天室队列的头部元素或者其他指定元素
fetchQueue	排序列出聊天室队列的所有元素
dropQueue	删除聊天室队列

圈组

圈组的 SDK API 数量较多，请前往上文的**圈组核心类/接口类**查阅圈组的 SDK API。

用户资料

类/接口	说明
fetchUserInfo	从服务器获取用户资料
getAllUserInfo	获取本地数据库中所有用户资料
updateUserInfo	更新本人的用户资料
searchUserInfosByKeyword	搜索与关键字匹配的所有用户

好友关系

类/接口	说明
addFriend	添加好友
ackAddFriendRequest	同意/拒绝好友请求
ackAddFriendRequest	同意/拒绝好友请求
deleteFriend	删除好友
getFriendAccounts	获取我的所有好友账号
addToBlackList	将用户添加至黑名单
searchFriendsByKeyword	搜索与关键字匹配的所有好友