使用说明
更新时间: 2024/03/14 16:36:30
接口介绍
IM Android SDK (以下简称 SDK)提供两类接口供开发者使用:
- 一类是主动发起请求,接口名均以
Service
结尾,例如AuthService
- 一类是作为观察者监听事件和变化,接口名均以
ServiceObserver
结尾,例如AuthServiceObserver
。个别太长的类名则直接以Observer
结尾,例如SystemMessageObserver
。
SDK 接口调用必须在主进程中进行,请在主进程中调用 SDK XXXService
提供的方法,在主进程中注册 XXXServiceObserver
的观察者(有事件变更,会回调给主进程的主线程)。如果您的模块运行在非主进程,请自行实现主进程与非主进程的通信(AIDL/Messenger/ContentProvider/BroadcastReceiver等IPC渠道
)将主进程回调或监听返回的数据传递给非主进程。
SDK 提供三种接口返回值:基本数据类型(同步接口),InvocationFuture(异步接口) 和 AbortableFuture(异步接口)。异步接口基本都从主进程发起调用,然后在后台进程执行,最后再将结果返回给主进程。
如果调用 AbortableFuture 异步接口,传输大量数据或者出现耗时很长的情况,可通过 abort
方法中断请求。例如上传下载、登录等。
异步接口可通过 RequestCallback 和 RequestCallbackWrapper 两种方式设置回调函数。
异步接口回调函数 | 说明 |
---|---|
RequestCallback | 需要实现3个接口: 成功 onSuccess, 失败 onFailed, 异常 onException |
RequestCallbackWrapper | 需要实现 onResult。封装了成功,失败和异常的3个接口,在参数上进行区分 |
SDK 4.4.0 API 调用框架增强:
- 支持带 Looper 的非UI线程发起的异步API调用,直接回调到调用者线程。老版本会默认回调到 UI 线程。
- 提供异步强制转成同步的接口:
NIMClient#syncRequest
,允许设置最大同步等待时间,支持非 UI 线程里需要同步调用云信 API的场景。 - 添加自动生成的 NIMSDK类,开发者可以直接采用
NIMSDK#getXXXService
方法获取服务接口,不再需要传递 XXXService.class,简化 API 调用方式。其他插件自动生成的调用入口类为:NIMChatRoomSDK
、NIMLuceneSDK
。例如采用NIMSDK.getAuthService().login()
替换NIMClient.getService(AuthService.class).login()
。
数据缓存目录
当收到多媒体消息后,SDK 默认会下载相关的文件,同时 SDK 还将记录一些关键的日志文件,因此 SDK 需要一个数据缓存目录。
该目录可以在 SDK 初始化时通过 SDKOptions#sdkStorageRootPath
进行设置。
SDK 4.4.0版本起,如果开发者配置在 Context#getExternalCacheDir
及 Context#getExternalFilesDir
等应用扩展存储缓存目录下(即/sdcard/Android/data/{package}
),SDK 内部将不再检查写权限。
上述缓存目录下的文件会随着 App 卸载而被删除,也可以由用户手动在设置界面里面清除。
如果不设置,则默认为/{外卡根目录}/{应用包名}/nim/
,其中外卡根目录可通过 Environment.getExternalStorageDirectory().getPath()
获取。
如果您的 APP 需要清除缓存功能,可扫描该目录下的文件,按照规则清理即可。 在 SDK 初始化完成后可以通过 NimClient#getSdkStorageDirPath
获取 SDK 数据缓存目录。
SDK 数据缓存目录中包含:
子目录 | 内容 |
---|---|
log | SDK 日志文件:如nim_sdk.log,一般不超过 8M。 |
image | 图片消息中的原图 |
audio | 语音消息中的音频 |
video | 视频消息中的原视频 |
thumb | 图片/视频消息中的缩略图 |
file | 文件消息中的文件 |