本文介绍安卓项目初始化网易云信即时通讯（NetEase IM）SDK （以下简称 NIM SDK）的详细说明。

功能介绍

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

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

SDK 的初始化方法必须在 主进程 中调用，在非主进程中初始化无效。SDK 的 xxxService 接口（如 SystemMessageService）和 xxxServiceObserver 接口（如 AuthServiceObserver）提供的方法也必须在 主进程 中调用。

前提条件

开始 NIM SDK 的初始化前，请确保您已经完成了以下操作：

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

第一步：初始化 SDK

NIM SDK 提供了两种初始化方式，您可按需选择。

方式	说明
在 onCreate 中初始化	在您应用的 Application#onCreate 中调用初始化方法，属于常规初始化方式。
在任意位置初始化	在应用代码的任意位置进行初始化，该方式有如下优点： 耗时较少 更适配 弱 IM 场景 适用于需要用户 授权隐私信息采集 的业务场景

方式一：在 onCreate 中

在应用的 Application#onCreate 中，调用 NIMClient#init 方法进行初始化。

参数	类型	说明
context	Context	应用上下文。
info	LoginInfo	登录用户的信息，如账号 ID（即accid）和 token。如果提供，可用于后续的自动登录。如果当前用户尚未手动登录成功过，传入 null。
options	SDKOptions	SDK 的配置信息，如 App Key、第三方离线推送配置、是否开启会话已读多端同步等。 其中 App Key 如果已在 集成 SDK 时在 AndroidManifest.xml 传入，则此处不需要再传入，否则必须传入，如果两处都设置了，取此处的值。 更多重要配置参数说明，可单击下方的 SDKOptions 的部分重要配置参数 查看。如果您的应用主要服务于海外用户，且数据需要写入海外数据中心，请先在 网易云信控制台 上 选择服务区域 为海外，并配置私有化服务器地址中的 LBS 和 link 域名相关信息，具体参考 配置 LBS 和 Link 域名。

单击展开查看 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;
    }
}

方式二：在任意位置

v5.0.0 版本开始支持在应用代码的任意位置初始化 SDK，该初始化方式一般 不再需要做进程判断。相较于方式一，该方式有如下优点：

• 耗时更少

• 更适配 弱 IM 场景

• 适用于需要用户授权隐私信息采集的业务场景。

  弱 IM 场景 指应用仅需在其部分业务中使用 IM 能力（不需要在应用启动时就做 IM 自动登录），且并不需要保证消息、通知和数据的实时性的场景。

在任意位置初始化 SDK，涉及以下两个方法的调用:

方法	说明	使用方式
NIMClient#config	在 Application#onCreate 中配置 SDK（仅仅是配置，不影响性能），具体可配置的参数同 方式 1 的 NIMClient#init	此处以隐私合规场景的 初始化最佳实践 为例
NIMClient#initSDK	在 UI 进程主线程上按需初始化 SDK，请 不要 放在 Application#onCreate 中，支持： 配置SDKOptions#asyncInitSDK 实现 SDK 的异步初始化 将SDKOptions#reducedIM 设置为 true 实现延迟加载 push 进程服务（注：非弱 IM 场景慎用）。 调用该方法前必须先在 Application#onCreate 中调用 NIMClient#config。

第二步：监听初始化状态

如果初始化方式为异步初始化，调用 observeMainProcessInitCompleteResult 方法注册观察者，监听主进程初始化状态。注册后，如果主进程完成初始化，Observer 的 onEvent 回调函数会被立即调用一次，告知观察者当前状态。

示例代码：

JavaNIMClient.getService(SdkLifecycleObserver.class).observeMainProcessInitCompleteResult(new Observer<Boolean>() {
    @Override
    public void onEvent(Boolean aBoolean) {
            if (aBoolean != null && aBoolean) {
                // ...
            }
    }
}, true);

下一步

完成初始化后，可 登录 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 的版本号。