IM 即时通讯
Android
开发指南

Android SDK API

更新时间: 2024/02/20 15:40:38

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

SDK API 概述

点击查看 API 概述

接口类型

NIM Android SDK (以下简称 SDK)提供两种接口类,供开发者使用:

类型
说明
主动发起请求 接口名均以 Service 结尾,例如 AuthService
作为观察者监听事件和变化 接口名均以 ServiceObserver 结尾,例如 AuthServiceObserver。个别太长的类名则直接以 Observer 结尾,例如 SystemMessageObserver
  • SDK 接口调用必须在主进程中进行,请在主进程中调用 SDK 的 XXXService 提供的方法,在主进程中注册 XXXServiceObserver 的观察者(有事件变更,会回调给主进程的主线程)。
  • 如果您的模块运行在非主进程,请自行实现主进程与非主进程的通信(AIDL/Messenger/ContentProvider/BroadcastReceiver等 IPC 渠道)将主进程回调或监听返回的数据传递给非主进程。

返回值类型

SDK 提供三种接口返回值:

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

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


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

异步接口回调函数 说明
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 调用方式。其他插件自动生成的调用入口类为:NIMChatRoomSDKNIMLuceneSDK。例如采用 NIMSDK.getAuthService().login() 替换NIMClient.getService(AuthService.class).login()

SDK API 参考

点此进入:Android SDK API 参考

SDK 核心 API

以下仅列出 SDK 的部分核心 API,如需查阅其他 SDK API 信息,请参考下文的SDK 核心类/接口类或者直接进入Android SDK API 参考查询 API 名称。

初始化与登录

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 将同时在线的其他设备端踢下线

消息(单聊与群聊)

API说明
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 的组合调用示例,可参见收发提示消息
sendMessageReceipt 发送单聊(P2P)消息的已读回执
deleteMsgSelf 单向删除多条消息
updateIMMessage 更新消息。目前只能更新本地扩展字段 LocalExtension
updateIMMessageStatus 更新消息记录的状态。可更新:
  • 消息状态 IMMessage#getStatus() 不为 null 时更新
  • 附件状态 IMMessage#getAttachStatus() 不为 null 时更新
  • 附件内容 IMMessage#getAttachment() 不为 null 时更新
revokeMessage 撤回消息,并设置相应的第三方推送配置(包括IOS平台的推送)与未读数变化

历史消息

API说明
clearServerHistory 清空服务端的单聊历史消息
deleteRangeHistory 根据时间范围删除本地历史消息
searchMessageHistory 从本地消息数据库搜索消息历史
queryMessageListByUuid 通过 uuid 批量获取历史消息
pullMessageHistoryEx 从服务器拉取消息历史记录
searchRoamingMsg 云端聊天记录关键词查询
queryLastMessage 查询同指定用户的最近一条消息

消息扩展

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

会话列表

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

离线推送与消息提醒

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

群组

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

超大群

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

聊天室

API说明
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。

用户资料

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

好友关系

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

SDK 核心类/接口类

以下仅列出 SDK 的核心类和接口类,如需查阅其他类或接口类的信息,请进入Android SDK API 参考搜索与查阅。

初始化与登录相关

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

消息(单聊 & 群聊)与会话相关

类/接口说明
MessageBuilder 云信 IM 消息构造器,提供构建各类型消息的接口
MsgService 云信消息服务接口类,提供消息发送、消息查询、历史消息、消息扩展功能、获取未读数、已读回执、会话列表等相关接口
MsgServiceObserve 云信 IM 消息服务观察者接口类,提供消息、会话等的监听接口
AudioRecorder 高清语音录制工具类,提供语音录制相关接口
AudioPlayer 和AudioRecorder对应音频播放器,提供语音播放相关接口
NosService 网易云存储服务(NOS)接口类,提供云存储相关接口
SystemMessageService 云信 IM 系统通知接口类,提供系统通知查询和管理接口
SystemMessageObserver 云信 IM 系统通知观察者接口类,提供系统通知相关监听接口
LuceneService 全文检索接口类,提供会话检索相关接口

第三方离线推送相关

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

群组相关

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

超大群相关

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

聊天室相关

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

圈组相关

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

用户资料相关

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

好友关系相关

类/接口说明
FriendService 好友关系服务接口类,提供好友管理、好友关系、黑名单、消息提醒等相关接口
FriendServiceObserve 好友关系、黑名单变更等的监听接口
此文档是否对你有帮助?
有帮助
去反馈
  • SDK API 概述
  • 接口类型
  • 返回值类型
  • SDK API 调用框架
  • SDK API 参考
  • SDK 核心 API
  • 初始化与登录
  • 消息(单聊与群聊)
  • 历史消息
  • 消息扩展
  • 会话列表
  • 离线推送与消息提醒
  • 群组
  • 超大群
  • 聊天室
  • 圈组
  • 用户资料
  • 好友关系
  • SDK 核心类/接口类
  • 初始化与登录相关
  • 消息(单聊 & 群聊)与会话相关
  • 第三方离线推送相关
  • 群组相关
  • 超大群相关
  • 聊天室相关
  • 圈组相关
  • 用户资料相关
  • 好友关系相关