Android
初始化
更新时间： 2024/03/14 16:36:33
本文提供初始化 NIM SDK 的详细说明。
功能介绍
在使用云信 IM 的各项功能之前，必须先对 NIM SDK 进行初始化。一般情况下，在应用的生命周期内，仅需进行一次初始化。
初始化时，可配置第三方离线推送服务、会话已读多端同步、群消息已读和融合存储等重要功能。
前提条件
开始 NIM SDK 的初始化前，请确保：
- 已集成 SDK。
- 已在云信控制台创建应用，获取 App Key 和 App Secret。
- App Key 需要在调用初始化的方法时，通过 SDKOptions 传入（具体见下文）。
- App Secret 可在初始化完成后，用于实现动态Token登录。
- 已注册云信 IM 账号，获取 accid 和 token。
实现方法
本节介绍如何实现 NIM SDK 的初始化。
SDK 的初始化方法必须在主进程中调用，在非主进程中初始化无效。SDK 的 xxxService 接口（如 SystemMessageService）和 xxxServiceObserver 接口（如 AuthServiceObserver）提供的方法也必须在主进程中调用。
步骤1：监听初始化状态
调用 observeMainProcessInitCompleteResult 方法注册观察者，监听主进程初始化状态。注册后，如果主进程完成初始化，Observer的onEvent回调函数会被立即调用一次，告知观察者当前状态。
示例代码：
javaNIMClient.getService(SdkLifecycleObserver.class).observeMainProcessInitCompleteResult(new Observer<Boolean>() {
@Override
public void onEvent(Boolean aBoolean) {
if (aBoolean != null && aBoolean) {
// ...
}
}
}, true);
步骤2：初始化 SDK
NIM SDK 提供了两种初始化方式，您可按需选择。
| 方式 | 说明 |
|---|---|
| 在 onCreate 中初始化 | 在您应用的Application#onCreate 中调用初始化方法，属于常规初始化方式 |
| 在任意位置初始化 | 在应用代码的任意位置进行初始化，该方式有如下优点：
|
方式1：在 onCreate 中初始化
在应用的 Application#onCreate 中，调用 NIMClient#init 方法进行初始化。
参数 |
类型 |
说明 |
|---|---|---|
context |
Context | 应用上下文 |
info |
LoginInfo |
登录用户的信息，如account(即accid)和token。如果提供，可用于后续的自动登录。如果当前用户尚未手动登录成功过，传入 null |
options |
SDKOptions |
SDK 的配置信息，如 App Key、第三方离线推送配置、是否开启会话已读多端同步等。 其中 App Key 如果已在集成 SDK 时在 AndroidManifest.xml传入，则此处不需要再传入，否则必须传入， 如果两处都设置了，取此处的值。更多重要配置参数说明，可点击下方的SDKOptions 的部分重要配置参数查看。 |
SDKOptions 的部分重要配置参数
参数 |
说明 |
|---|---|
| appKey | 设置云信SDK的appKey。appKey还可以在AndroidManifest文件中，通过meta-data的方式设置。 |
| statusBarNotificationConfig | 云信封装的消息提醒配置 |
| userInfoProvider | 用户信息提供者，目前主要用于通知栏显示用户昵称和头像 |
| messageNotifierCustomization | 通知栏提醒文案定制 |
| sdkStorageRootPath | 外置存储根目录,用于存放多媒体消息，日志等文件 如果使用data/user/0/的子目录，在没有存储权限的情况下会导致部分文件操作失败，可以使用data/data/或者/sdcard/Android/data/包名/的子目录 |
| preloadAttach | 是否需要 SDK 自动预加载多媒体消息的附件 |
| recentContactContentSource | 最近会话的内容来源，默认为 MessageTypeTipPreferred（即优先使用与该联系人的最后一条消息的消息类型Tip字段，若为空，则使用与该联系人的最后一条消息的消息内容）具体类型请参见 RecentContactContentSource |
| thumbnailSize | 消息缩略图的尺寸 |
| sessionReadAck | 是否开启会话已读多端同步 |
| improveSDKProcessPriority | 是否提高SDK进程优先级（默认提高，可以降低SDK核心进程被系统回收的概率） |
| serverConfig | 配置私有化的服务器地址 |
| preLoadServers | 预加载服务，默认true，不建议设置为false，预加载连接可以优化登陆流程 |
| teamNotificationMessageMarkUnread | 群通知消息是否计入未读数，默认不计入未读 |
| useXLog | 是否使用性能更好的 SDK 日志模式。默认 false，即使用普通日志模式。 |
| animatedImageThumbnailEnabled | 开启对动图缩略图的支持，默认为 false，截取第一帧 |
| asyncInitSDK | 是否异步初始化SDK，默认为 false。开启可降低 Application#onCreate 中 SDK 初始化函数的同步响应时间 |
| reducedIM | 是否是弱IM场景，默认为 false。如果您的APP 仅在部分场景按需使用 IM 能力(不需要在应用启动时就做自动登录)，并不需要保证消息通知、数据的实时性，那么这里可以填 true。弱 IM 场景下，push 进程采用懒启动策略(延迟到用户登录阶段)，启动后其生命周期将跟随 UI 进程，降低弱 IM 场景的APP的后台功耗开销。 |
| checkManifestConfig | 是否在 SDK 初始化时检查清单文件配置是否完全，默认为 false，建议开发者在调试阶段打开，上线时关掉 |
| mixPushConfig | 配置第三方离线推送的 appid、appkey、证书 |
| enableBackOffReconnectStrategy | 是否使用随机退避重连策略，默认true，强烈建议打开。如需关闭，请咨询云信技术支持。 |
| enableLBSOptimize | 是否启用网络连接优化策略，默认开启。 |
| enableTeamMsgAck | 是否启用群消息已读功能，默认关闭 |
| shouldConsiderRevokedMessageUnreadCount | 撤回消息时未读数减一 |
| mNosTokenSceneConfig | nos token 场景配置 |
| loginCustomTag | 登录时的自定义字段 ， 登陆成功后会同步给其他端 ，获取可参考 AuthServiceObserver#observeOtherClients() |
| disableAwake | 禁止后台进程唤醒ui进程 |
| fetchServerTimeInterval | 获取服务器时间连续请求间隔时间, 最小1000ms， 默认2000ms |
| customPushContentType | 离线推送不显示详情时，要显示的文案对应的类型名称 |
| notifyStickTopSession | 置顶会话是否同步 |
| enableForegroundService | 启动NimService失败时，是否尝试以前台服务方式启动 |
| cdnRequestDataInterval | Cdn信息上报的回调间隔 |
| rollbackSQLCipher | 是否回滚SQLCipher加密的数据库 |
| coreProcessStartTimeout | core进程启动的超时时间（单位：毫秒） |
| clearTimeTagAtBeginning | 是否重置同步时间戳，启动时重置，只重置一次（不建议开启，如需开启请联系技术支持） |
| enableDatabaseBackup | 是否开启数据库备份功能 |
| captureDeviceInfoConfig | 设备信息获取配置 null代表都可以获取 不获取设备信息可能影响功能，使用请联系技术支持 |
| secondTimeoutForSendMessage | 发消息的第二超时时间，非常规功能，开启请联系技术支持 |
| enableRecentContactsTimeIndex | 是否开启最近联系人会话时间索引,默认不开启，开启最近联系人会话时间索引后会明显减少查询最近联系人会话耗时，但是同时也会增加最新联系人会话写入操作耗时。 |
| notificationChannelProvider | 可配置通知要走的通道，如果不配置，根据响铃振动等配置走对应默认通道 |
| enableFcs | 是否支持aws s3存储，默认开启 |
| fcsDownloadAuthStrategy | aws s3存储下载鉴权策略，如需开启，请咨询云信技术支持 |
| enabledQChatMessageCache | 是否开启圈组消息缓存支持，默认不开启 |
| syncConfig | 同步配置，可设置是否在初始化时同步群成员以及超大群成员，默认为 true，同步 |
| qchatAutoSubscribe | 是否开启圈组自动订阅，默认为 false，不开启 |
- 每个进程都会创建自己的 Application 然后调用
onCreate方法。如果您有自己的逻辑需要写在Application#onCreate（或者 Application 的其他方法）中，一定要注意判断进程，不能把业务逻辑写入 core 进程。理论上，core 进程的Application#onCreate（或者 Application 的其他方法）只能做与 NIM SDK 相关的工作。 - 建议在
Application#onCreate中添加进程判断，IM 进程启动的时候不去初始化第三方库。
示例代码：
javapublic class NimApplication extends Application {
public void onCreate() {
// ... your codes
// SDK初始化（启动后台服务，若已经存在用户登录信息， SDK 将进行自动登录）。不能对初始化语句添加进程判断逻辑。
NIMClient.init(this, loginInfo(), options());
// ... your codes
// 使用 `NIMUtil` 类可以进行主进程判断。
// boolean mainProcess = NIMUtil.isMainProcess(context)
if (NIMUtil.isMainProcess(this)) {
// 注意：以下操作必须在主进程中进行
// 1、UI相关初始化操作
// 2、相关Service调用
}
}
// 如果提供，将同时进行自动登录。如果当前还没有登录用户，请传入null。详见自动登录章节。
private LoginInfo loginInfo() {
return null;
}
// 设置初始化配置参数，如果返回值为 null，则全部使用默认参数。
private SDKOptions options() {
SDKOptions options = new SDKOptions();
...
// 配置是否需要预下载附件缩略图，默认为 true
options.preloadAttach = true;
...
return options;
}
}
方式2：在任意位置初始化
v5.0.0 版本开始支持在应用代码的任意位置初始化 SDK，该初始化方式一般不再需要做进程判断。
相较于方式1，该方式有如下优点：
- 耗时更少
- 更适配弱 IM 场景
- 适用于需要用户授权隐私信息采集的业务场景。
弱 IM 场景指应用仅需在其部分业务中使用 IM 能力（不需要在应用启动时就做 IM 自动登录），且并不需要保证消息、通知和数据的实时性的场景。
在任意位置初始化 SDK，涉及以下两个方法的调用:
方法 |
说明 | 使用姿势 |
|---|---|---|
NIMClient#config |
在 Application#onCreate 中配置 SDK（仅仅是配置，不影响性能），具体可配置的参数同方式1 的NIMClient#init |
此处以隐私合规场景的初始化最佳实践为例 |
NIMClient#initSDK |
在 UI 进程主线程上按需初始化 SDK，请不要放在 Application#onCreate 中，支持：
Application#onCreate中调用NIMClient#config。 |
后续步骤
完成初始化后，可登录 IM。
相关参考
离线推送初始化配置
如果您的应用需要实现离线推送，需在初始化时完成推送证书信息等配置。详情请参见实现离线推送。
NIMClient
NIMClient类，提供了初始化 SDK 和获取各个服务能力的方法，同时也提供获取当前状态等的方法。
常见问题
如何实现应用的隐私合规？
建议您参考IM 应用隐私合规中介绍的最佳实践，实现应用隐私合规。
如何进行初始化配置，以便实现 IM 的自动登录？
调用 NIM SDK 的初始化方法时（如调用NIMClient#init方法），传入上次登录的LoginInfo对象，即可实现自动登录。更多详情，参见自动登录最佳实践。
如何配置 SDK 数据缓存目录？
点击查看如何在初始化时配置SDK 数据缓存目录
当用户收到多媒体消息后，SDK 默认会下载相关的文件，同时 SDK 还会记录一些关键的日志文件，因此 SDK 需要一个数据缓存目录（下文简称为“该目录”）。
-
该目录可以在 SDK 初始化时通过
SDKOptions#sdkStorageRootPath进行设置。自 v4.4.0 版本起，如果您将该目录配置在
Context#getExternalCacheDir和Context#getExternalFilesDir等应用扩展存储缓存目录下（即/sdcard/Android/data/{package}），SDK 内部将不再检查写权限。上述应用扩展存储缓存目录的文件会随着应用卸载而被删除，也可以由用户手动在设置界面里面清除。
-
如果不设置，则该目录默认为
/{外卡根目录}/{应用包名}/nim/，其中外卡根目录可通过Environment.getExternalStorageDirectory().getPath()获取。 -
如果您的应用需要清除缓存功能，可扫描该目录下的文件，按照规则清理即可。
SDK 初始化完成后，可通过 NIMClient#getSdkStorageDirPath 获取该目录。
该目录中包含：
| 子目录 | 内容 |
|---|---|
log |
SDK 日志文件：如nim_sdk.log，一般不超过 8 MB。 |
image |
图片消息中的原图 |
audio |
语音消息中的音频 |
video |
视频消息中的原视频 |
thumb |
图片/视频消息中的缩略图 |
file |
文件消息中的文件 |
如何查询 SDK 版本号？
可调用NIMClient#getSDKVersion方法获取当前使用的 SDK 的版本号。