本文提供初始化 NIM SDK 的详细说明。

功能介绍

在使用云信 IM 的各项功能之前，必须先对 NIM SDK 进行初始化。一般情况下，在应用的生命周期内，仅需进行一次初始化。

初始化时，可配置第三方离线推送服务、会话已读多端同步、群消息已读和融合存储等重要功能。

前提条件

开始 NIM SDK 的初始化前，请确保：

• 已集成 SDK。
• 已在云信控制台创建应用，获取 App Key 和 App Secret。
  • App Key 需要在调用初始化的方法时，通过 SDKOptions 传入（具体见下文）。
  • App Secret 可在初始化完成后，用于实现动态 Token 登录。
• 已注册云信 IM 账号，获取 IM 账号和 token。

实现方法

本节介绍如何实现 NIM SDK 的初始化。

步骤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 支持在应用代码的任意位置初始化。

调用 NIMClient#initV2 方法进行初始化。

• 参数说明

public static void initV2(Context context, SDKOptions options)

参数	类型	说明
context	Context	应用上下文
options	SDKOptions	SDK 的配置信息，如 App Key、第三方离线推送配置、是否开启会话已读多端同步等。 其中 App Key 如果已在集成 SDK 时在AndroidManifest.xml传入，则此处不需要再传入，否则必须传入， 如果两处都设置了，取此处的值。 更多重要配置参数说明，可点击下方的 SDKOptions 的部分重要配置参数查看。如果你的应用主要服务于海外用户，且数据需要写入海外数据中心，请先在云信控制台选择服务区域为海外，并配置私有化服务器地址中的 LBS 和 link 域名相关信息，具体参见配置 LBS 和 link 域名。

SDKOptions 的部分重要配置参数

参数	说明
disableV2Login	是否在开启 V10 API 后，禁用 V10 的登录 API，仍使用 V9 的登录 API 登录 IM。 默认 false，即开启 V10 API 后使用 V10 的登录 API 登录 IM。 设置为 true，则开启V10 API 后仍需要使用 V9 的登录 API 登录 IM。V9 和 V10 版本的登录 API 无法同时使用，只能选择其一。
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，不开启

以上仅展示初始化重要参数，如需查看其他参数请参见 SDKOptions。

• 示例代码

java// 激活V10 API后，可以根据该字段选项选择是否禁用V10 API登录，默认false，即使用V10 API登录
// sdkOptions.disableV2Login = true;
...
// 按需设置其它 SDKOptions 设置项

NIMClient.initV2(context, sdkOptions);

后续步骤

完成初始化后，可登录 IM。

相关参考

离线推送初始化配置

如果您的应用需要实现离线推送，需在初始化时完成推送证书信息等配置。详情请参见实现离线推送。

实现应用的隐私合规

建议您参考 IM 应用隐私合规中介绍的最佳实践，实现应用隐私合规。

配置 SDK 数据缓存目录

点击查看如何在初始化时配置SDK 数据缓存目录

当用户收到富媒体消息后，SDK 默认会下载相关的文件，同时 SDK 还会记录一些关键的日志文件，因此 SDK 需要一个数据缓存目录（下文简称为“该目录”）。

• 该目录可以在 SDK 初始化时通过 SDKOptions#sdkStorageRootPath 进行设置。

  上述应用扩展存储缓存目录的文件会随着应用卸载而被删除，也可以由用户手动在设置界面里面清除。

  
  

• 如果不设置，则该目录默认为/{外卡根目录}/{应用包名}/nim/，其中外卡根目录可通过 Environment.getExternalStorageDirectory().getPath() 获取。

• 如果您的应用需要清除缓存功能，可扫描该目录下的文件，按照规则清理即可。

SDK 初始化完成后，可通过 NIMClient#getSdkStorageDirPath 获取该目录。

该目录中包含：

子目录	内容
log	SDK 日志文件：如nim_sdk.log，一般不超过 8 MB。
image	图片消息中的原图
audio	语音消息中的音频
video	视频消息中的原视频
thumb	图片/视频消息中的缩略图
file	文件消息中的文件

查询 SDK 版本号

可调用 NIMClient#getSDKVersion 方法获取当前使用的 SDK 的版本号。