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

功能介绍

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

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

前提条件

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

• 已集成 SDK。
• 已在云信控制台创建应用，获取 App Key。
• 已注册云信 IM 账号，获取 accid 和 token。

实现初始化

步骤1：引入头文件

在项目文件中引入头文件。

#import <NIMSDK/NIMSDK.h>

步骤2（可选）：配置初始化可选项

您可按需对初始化的可选项进行配置。可选项主要分为NIMSDKConfig中的参数、SDK 根目录和NIMServerSetting中的配置项。这些可选项如果不配置，将使用默认配置。

NIMSDKConfig 配置

NIMSDKConfig 是一个单例，推荐在调用初始化接口前配置。NIMSDKConfig提供了自动下载消息附件、NSFileProtectionKey、撤回消息是否计入未读、是否多端同步未读数、HTTPS 支持、自动登录最大重试次数、本地 log 存活期等重要 SDK 初始化配置项，您可按需进行配置。

点击查看 NIMSDKConfig 部分重要配置参数

参数	类型	说明
fetchAttachmentAutomaticallyAfterReceiving	BOOL	是否在收到消息（群消息和点对点消息）后自动下载附件 默认为 YES，即 SDK 会在第一次收到图片或视频消息时，主动获取图片的缩略图和视频的第一帧封面 若设置为 NO，SDK 将不再主动获取，您需要根据应用的业务逻辑手动调用fetchMessageAttachment:error:方法获取附件
fetchAttachmentAutomaticallyAfterReceivingInChatroom	BOOL	是否在收到消息（聊天室消息）后自动下载附件。默认为 NO，即 SDK 不会在第一次收到图片或视频消息时，去主动下载聊天室消息的附件
enableDataProtection	BOOL	是否开启 Data Protection，默认为 NO，即不开启
fileProtectionNone	BOOL	是否设置云信文件的保护等级（NSFileProtectionKey）为 NSFileProtectionNone（文件没有设置任何保护，随时可以读写） 默认为 NO，即不设置，此时保护等级为 NSFileProtectionCompleteUntilFirstUserAuthentication 设置为 YES，则保护等级为 NSFileProtectionNone 只有在上层应用开启了 Data Protection 时才起效
shouldConsiderRevokedMessageUnreadCount	BOOL	是否需要将被撤回的消息计入未读数，默认为 NO，即不计入 若设置成 YES，将被撤回的消息计入未读数，那么如果被撤回的消息本地还未读，当消息发生撤回时，对应会话的未读计数将减 1，与最近会话未读数保持一致
shouldSyncUnreadCount	BOOL	是否需要多端同步未读数，默认为 NO，即不同步 若设置为 YES，那么同个账号的多端（PC 和 移动端等）将同步未读数
shouldCountTeamNotification	BOOL	是否需要将群通知计入未读数，默认为 NO，即不计入 若设置为 YES，那么收到的群通知也会计入未读数
enabledHttpsForInfo	BOOL	针对用户信息是否开启 HTTPS 支持，默认为 YES，即开启 默认情况下，用户头像、群头像、聊天室用户头像等信息都托管在云信服务器，SDK 会针对这些用户信息自动开启 HTTPS 支持 若用户头像、群头像、聊天室用户头像等信息都托管在用户自己的服务器上，那么需要设置为 NO，避免 SDK 自动将您的 HTTP URL 自动转换为 HTTPS URL
enabledHttpsForMessage	BOOL	针对消息内容是否开启 HTTPS 支持，默认为 YES，即开启 默认情况下，多媒体消息附件，包括图片、视频、音频信息都默认托管在云信服务器，SDK 会针对这些消息内容自动开启 HTTPS 支持 若图片消息，视频消息，音频消息等信息都托管在用户自己的服务器上（强烈不建议），那么需要设置为 NO，避免 SDK 自动将您的 HTTP URL 自动转换为 HTTPS URL 该配置项只影响接收到的消息 URL 格式转换。即使设置为 NO，通过 SDK 发出去的消息 URL 仍是 HTTPS 的，只有接收到的消息 URL 格式为 HTTP
maxAutoLoginRetryTimes	NSInteger	自动登录重试次数 默认情况下，自动登录将无限重试 若设置成大于 0 的值（X）后，在没有登录成功前，自动登录将重试最多 X 次，如果登录失败，则报错 NIMLocalErrorCodeAutoLoginRetryLimit
maximumLogDays	NSInteger	本地 log 存活期，默认为 7 天，即超过 7 天的 log 将被清除只能设置大于等于 2 的值
animatedImageThumbnailEnabled	BOOL	是否支持动图缩略，默认为 NO，即不支持 默认为 NO，即默认情况下，从服务器获取原图缩略图时，如果原图为动图，云信将返回原图第一帧的缩略图 若设置为 YES，开启动图缩略后，云信将返回缩略图后的动图 该配置项只影响从服务器获取的缩略图，不影响本地生成的缩略图
thumbnailSize	NSInteger	消息缩略图的尺寸，该值为最长边的大小，默认为 350 像素下载的缩略图最长边不会超过该值
teamReceiptEnabled	BOOL	是否开启群消息已读回执功能，默认为 NO，即不开启 若开启群消息已读回执功能，那么用户在群组中发送消息，其他群成员收到消息会发送已读回执给发送者 只有开启群消息已读回执功能，群消息回执相关接口才会生效 使用群消息已读回执功能，需将群成员控制在 200 人以内
customTag	NSString	客户端自定义信息，用于多端登录时同步该信息
fileQuickTransferEnabled	BOOL	是否开启本地文件快传功能，默认为 YES，即开启 默认情况下，SDK 会在本地网络直接传输文件，而不需要通过互联网上传到服务器再下载到另一台设备，从而实现更快的传输速度 若设置为 NO，关闭本地文件快传，则会使用传统的上传下载方式进行文件传输
exceptionOptimizationEnabled	BOOL	是否开启异常错误上报功能，默认 NO，即不上报 建议用户开启异常错误上报，方便云信根据上报信息，分析 SDK 发生的错误，并进行优化
asyncLoadRecentSessionEnabled	BOOL	是否开启异步读取最近会话功能，默认 NO，即不异步读取 若设置为 YES，开启异步读取最近会话，那么 allRecentSessions 会优先返回一部分最近会话，等到全部读取完成时，通过回调通知用户刷新 UI若用户的最近会话较多，那么 SDK 在初始化读取数据时，可能会影响启动速度。该场景下用户可以将该配置项设为 YES
sessionDatabaseBackupEnabled	BOOL	是否备份会话数据库，默认 NO，即不备份 若开启备份，当数据库文件损坏时，SDK 会恢复备份的数据库文件，并重置漫游时间戳
maxUploadLogSize	unsigned long long	上传的日志文件大小 默认情况下，不限制日志文件的大小 设置成大于 0 的值（X）后，上传的日志文件大小不能超过 X （单位为 byte），超过则无法上传
shouldSyncStickTopSessionInfos	BOOL	是否同步置顶会话记录，默认 NO，即不同步
customClientType	NSInteger	自定义的客户端类型，默认为 0。若需要自定义，需要设置大于 0 的值该配置项配合自定义多端登录策略使用
cdnTrackInterval	NSTimeInterval	CDN 信息上报的回调间隔，默认 30s 上报一次。若设置为 0s，即表示不上报该配置项需要在触发 CDN 拉流前设置，在触发拉流后再设置将不会生效
chatroomMessageReceiveMinInterval	NSTimeInterval	聊天室消息接收回调的最小时间间隔，默认有效区间：50 毫秒 ~ 500 毫秒，如果低于或高于边界值，采用边界值。若不设置，则采用默认有效区间
fcsEnable	BOOL	是否开启融合云存储，默认 YES，即开启 若设置为 NO，无论服务端侧的融合云存储功能是否开启，都不启用融合云存储
fcsAuthType	NSInteger	融合云存储的鉴权类型，即下载文件时的鉴权类型。默认不鉴权，可设置如下值： 1：refer 鉴权 2：基于时间的 token 鉴权 3：基于 URL 的 token 鉴权 4：custom 鉴权 如果设置为 refer 鉴权，还需设置下文的 fcsUa 和 facRefer
fcsUa	NSString	融合云存储的 UserAgent，选择 refer 鉴权（fcsAuthType=1）时需要配置
fcsRefer	NSString	融合云存储的参照位置，选择 refer 鉴权（fcsAuthType=1）时需要配置
isSingleTable	BOOL	是否使用 SingleTable 数据库设计模式，默认 YES 适用于小型应用程序或者只有少量实体之间有简单关系的情况。该模式可以简化数据查询和维护，但在处理大量数据或者复杂关系时可能会变得笨重和难以维护
growDeviceEnabled	BOOL	是否开启设备指纹功能，默认 YES，开启设备指纹功能
logDesensitizationConfig	NIMLogDesensitizationConfig	设置日志脱敏的配置项，包括是否脱下载地址等
fixMsgStatusByBlackList	BOOL	消息状态是否结合黑名单列表判断，默认 NO，即不结合，消息状态的判断与是否在黑名单无关 若设置为 YES，那么消息状态与是否在黑名单有关。判断逻辑如下： 同步接收到的消息，如果发送者在黑名单列表中，那么消息状态为 Failed，即接收不到该消息 查询到的云端历史消息，如果发送者在黑名单列表中，那么消息状态为 Failed，即查询不到该消息
reportIgnoredMessage	BOOL	是否上报被过滤的消息，默认 NO，即不上报被过滤的消息

SDK 根目录配置

除上述NIMSDKConfig的配置参数外，您还可调用NIMSDKConfig的setupSDKDir:方法设置 SDK 的根目录。为了更好的应用体验，SDK 需要对应用数据做本地持久化，如聊天记录、用户信息等。若不设置，数据默认放置于 $Document/NIMSDK 目录下。

• 该方法必须在 NIM SDK 任意一次 sharedSDK 方法的调用之前调用，否则 SDK 根目录配置无法生效。
• 调用该方法设置 SDK 根目录后，SDK 产生的临时文件不会放置在根目录下。

示例代码如下：

objc[[NIMSDKConfig sharedConfig] setupSDKDir:@"your data path"];

NIMServerSetting 配置

通过NIMServerSetting可对云信服务器进行配置，如 CDN 域名下发、是否是专属云、IM 服务器 LBS 域名等。

NIMServerSetting需要开发者自己创建并注入。

• HTTPS 配置

  NIMServerSetting一个主要功能为是否开启 HTTPS 支持（httpsEnabled）。该属性的配置将影响使用 SDK 时上传下载文件的模式。

  • httpsEnabled默认为 YES，服务器将使用 HTTPS 上传/下载文件，所有返回的 URL，也会尝试将 HTTP 转换为 HTTPS。

  • httpsEnabled若设置为 NO，服务器将使用 HTTP 上传，所有返回的 URL 都只使用原 URL，不做任何处理，同时 NIMSDKConfig的enabledHttpsForInfo 和 enabledHttpsForMessage将无效。

  示例代码如下：

  NIMServerSetting *setting    = [[NIMServerSetting alloc] init];
  setting.httpsEnabled = YES;
  [[NIMSDK sharedSDK] setServerSetting:setting];
  ...
  [[NIMSDK sharedSDK] registerWithOption:option];
  

• 海外数据中心配置

  如果你的应用主要服务于海外用户，且数据需要写入海外数据中心，请先在云信控制台选择服务区域为海外，并配置私有化服务器地址中的 LBS 和 link 域名相关信息，具体参见配置 LBS 和 Link 域名。

NIMQChatConfig 配置

通过NIMServerSetting可配置圈组初始化实例，如圈组消息缓存、自动订阅功能。

• 圈组消息缓存

  NIMQChatConfig一个主要功能为是否开启圈组消息缓存（enabledMessageCache）。若需要缓存圈组消息，那么需要在使用圈组消息功能前设置该配置项。

  • enabledMessageCache 默认为 NO，服务器将不缓存圈组消息。

  • enabledMessageCache 若设置为 YES，那么 SDK 可以为 100 个频道缓存消息，每个频道最多缓存 20 条。如果超出，则按消息的创建时间去除最晚的。

  示例代码如下：

  [NIMQChatConfig sharedConfig].enabledMessageCache = YES;
  

• 圈组自动订阅

  可通过配置 autoSubscribe 来选择圈组的订阅模式。

  • autoSubscribe 默认为 NO，即不开启自动订阅，使用手动订阅模式。当用户登录到圈组服务器后，需要先订阅相关服务器或频道，才能收到相关频道和服务器的消息、事件和系统通知，退出时手动取消订阅。

  • autoSubscribe 若设置为 YES，即使用自动订阅模式。当用户登录到圈组服务器后，无需手动订阅服务器或频道，进入服务器或频道时即可收到消息、事件和系统通知，退出时则自动取消订阅。

  示例代码如下：

  [NIMQChatConfig sharedConfig].autoSubscribe=YES;
  

步骤3：调用初始化接口

调用 registerWithOption: 方法初始化 SDK，推荐在应用程序启动时初始化。调用该方法可配置NIMSDKOption的参数。

NIMSDKOption参数说明：

参数	类型	是否必传	说明
appKey	NSString	是	云信控制台获取到的 App Key
apnsCername	NSString	否	APNs 推送证书名，如不需要实现离线推送可不配置
pkCername	NSString	否	PushKit 推送证书名，如不需要实现离线推送可不配置

• NIMSDKOption提供类方法optionWithAppKey:来返回实例。
• App Key 作为应用的唯一标识，使用相同 App Key 、不同 Bundle Id 的应用，消息仍可以互通。

示例代码：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    ...
    // 推荐在程序启动的时候初始化 NIM SDK    
    NSString *appKey        = @"your app key";
    NIMSDKOption *option    = [NIMSDKOption optionWithAppKey:appKey];
    option.apnsCername      = @"your APNs cer name";
    option.pkCername        = @"your pushkit cer name";
    [[NIMSDK sharedSDK] registerWithOption:option];
    ...
}

后续步骤

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

相关参考

离线推送初始化配置

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

相关辅助方法

在NIMSDK类中，提供了辅助开发的方法。

方法	说明
sdkVersion	获取当前 NIM SDK 的版本号
appKey	获取当前注册的 App Key
currentLogFilepath	获取 SDK 当前的 log 路径