Flutter

初始化

更新时间: 2024/09/02 14:42:39

集成 NIM Flutter SDK 之后,需要将其初始化,创建 SDK 实例。

前提条件

开始初始化前,请确保:

初始化 SDK

将 SDK 集成到客户端后,调用initialize方法初始化 SDK。

示例代码如下:

dart
final NIMSDKOptions options;
if (Platform.isAndroid) {
  options = NIMAndroidSDKOptions(
    appKey: 'appkey',
    /// 其他 通用/Android 配置
  );
} else if (Platform.isIOS) {
  options = NIMIOSSDKOptions(
    appKey: 'appkey',
    /// 其他通用配置/iOS 配置
  );
} else if (KisWeb) {
    options = NIMSDKOptions(
      appKey: 'appKey',
      /// 其他基础通用配置参数    
    )
}
NimCore.instance.initialize(options)
    .then((result){
        if (result.isSuccess) {
            /// 初始化成功
        } else {
            /// 初始化失败
        }
    });

相关参考

海外数据中心配置

初始化 SDK 时,通过 NIMServerConfig 配置私有化的服务器地址中的 LBS 和 link 域名相关信息,详情请参见配置Link域名和LBS域名

如果你的应用主要服务于海外用户,且数据需要写入海外数据中心,请先在云信控制台选择服务区域为海外,并在初始化 SDK 时通过 NIMServerConfig 配置私有化的服务器地址中的 LBS 和 link 域名相关信息,详情请参见配置 Link 域名和 LBS 域名

目前仅 Android 和 iOS 平台支持的该配置。

初始化配置参数

您可通过 NIMSDKOptions 结构体配置初始化参数。NIMSDKOptions下还包含多个子结构体,用于不同平台的特有配置。

  • NIMSDKOptions 为基础配置类型,包含跨平台通用参数
  • NIMAndroidSDKOptions 在通用参数的基础上添加了 Android 平台独有的参数
  • NIMIOSSDKOptions 在通用参数的基础上添加了 iOS 平台独有的参数
  • NIMWINDOWSSDKOptions 在通用参数的基础上添加了 Windows 平台独有的参数
  • NIMMACOSSDKOptions在通用参数的基础上添加了 macOS 平台独有的参数

Web 使用通用参数即可。

通用参数

NIMSDKOptions 的参数说明如下:

参数 类型 必填 说明
appKey String 设置SDK 的 appKey
sdkRootDir String 外置存储根目录,用于存放多媒体消息和日志等文件
enablePreloadMessageAttachment bool 是否需要 SDK 自动预加载多媒体消息的附件
shouldSyncUnreadCount bool 是否开启会话已读多端同步
shouldTeamNotificationMessageMarkUnread bool 群通知消息是否计入未读数,默认不计入未读
enableAnimatedImageThumbnail bool 开启动图缩略图,默认为 false,如开启则截取动图的第一帧作为缩略图
enableTeamMessageReadReceipt bool 是否启用群消息已读功能,默认关闭
shouldConsiderRevokedMessageUnreadCount bool 撤回消息时未读数是否减一
nosSceneConfig Map<NIMNosScene, int> 设置网易对象存储服务(Netease Object Storage,NOS)的存储场景,从而指定 IM 相关资源(如多媒体消息的附件)在 NOS 上的过期时间
loginCustomTag String 登录时的自定义字段,登陆成功后会同步给其他端。其他端通过监听多端登录事件流(AuthService#onlineClients)获取该字段
shouldSyncStickTopSessionInfos bool 置顶会话是否同步
cdnTrackInterval int CDN 信息上报的回调间隔
enableDatabaseBackup bool 是否开启数据库备份功能
enableReportLogAutomatically bool 是否开启 IM 日志自动上报,默认关闭
autoLoginInfo NIMLoginInfo 自动登录账号信息(Windows 和 macOS 暂不支持)

Android 平台独有参数

NIMAndroidSDKOptions的参数说明如下:

参数 类型 必填 说明
notificationConfig NIMStatusBarNotificationConfig 消息通知栏配置
improveSDKProcessPriority bool 是否提高 SDK 进程优先级(默认提高,可降低 SDK 核心进程被系统回收的概率)
preLoadServers bool 预加载服务,默认 true,不建议设置为 false,预加载连接可以优化登陆流程
reducedIM bool 是否是弱 IM 场景,默认为 false。如果您的应用仅在部分场景按需使用 IM 能力(不需要在应用启动时就做自动登录),并不需要保证消息通知、数据的实时性,那么这里可以填 true。弱 IM 场景下,push 进程采用懒启动策略(延迟到用户登录阶段),启动后其生命周期将跟随 UI 进程,降低弱 IM 场景的应用后台功耗开销。
checkManifestConfig bool 是否在 SDK 初始化时检查清单文件配置是否完全,默认为 false,建议在调试阶段打开,上线时关掉
mixPushConfig NIMMixPushConfig 配置第三方推送的appidappkey和证书
disableAwake bool 是否禁止后台进程唤醒 UI 进程
fetchServerTimeInterval int 获取服务器时间的连续请求的间隔时间, 最小 1000ms, 默认 2000ms
customPushContentType String 离线推送不显示详情时,要显示的文案对应的自定义类型名称。不显示推送详情相关配置说明请参见推送文案
databaseEncryptKey String 数据库加密秘钥,用于消息数据库加密。
如果不设置,数据库处于明文状态; 设置后,数据库会加密保存数据,之前明文保存的历史数据会被转为加密保存; 一旦开启过加密功能后,不支持退回明文保存状态
thumbnailSize int 消息缩略图的尺寸。该值为最长边的大小,下载的缩略图最长边不会超过该值。默认值 350 px
enableFcs bool 是否开启融合存储。融合存储为海外用户提供了新的存储方式。开启融合存储后,SDK 在应用收到文件消息会自动启用 CDN 加速选择最快的节点进行存储,将文件消息存储到 AWS 服务器或网易对象存储(NetEase Object Storage, NOS)服务器上。默认 true
注意:虽然融合存储默认开启,但需要开通该功能后才能生效。如有需要,请通过云信官网首页提供的微信等联系方式咨询商务经理开通该功能
enabledQChatMessageCache bool 开启圈组的消息缓存,默认不开启

iOS 平台独有参数

NIMIOSSDKOptions的参数说明如下:

参数 类型 必填 说明
apnsCername String 在云信控制台配置的 APNs 推送证书名
pkCername String 在云信控制台配置的 PushKit 推送证书名
disableTraceroute bool 设置禁用 NIM Flutter SDK 的 traceroute 能力,默认为 NO。SDK 会在请求失败时,进行 traceroute ,探测网路中各节点,以判断在哪个节点失去连接
maxUploadLogSize int 日志上传大小上限,默认 0,不限制,单位(byte)
enableFetchAttachmentAutomaticallyAfterReceivingInChatroom bool 是否在收到聊天室消息后自动下载附件,默认为 NO
enableFileProtectionNone bool 是否使用 NSFileProtectionNone 作为云信文件的 NSProtectionKey,默认为 NO。只有在应用上层开启了 Data Protection 时才生效
enabledHttpsForInfo bool 针对用户信息开启 HTTPS 协议支持,默认为 YES。在默认情况下,用户头像、群头像和聊天室用户头像等信息都默认托管在云信服务端上,所以 SDK 会针对它们自动开启 HTTPS 支持。如果您需要将这些信息都托管在自己的服务器上,需要将该参数设置为 NO,避免 SDK 自动将您的 HTTP URL 自动转换为 HTTPS URL。
enabledHttpsForMessage bool 针对消息内容开启 HTTPS 协议支持,默认为 YES。在默认情况下,消息(包括附带的图片、视频和音频数据)都默认托管在云信服务端,所以 SDK 会针对它们自动开启 HTTPS 支持。如果您需要将这些数据都托管在自己的服务器上,需要将该参数为 NO (强烈不建议),避免 SDK 自动将您的 HTTP URL 自动转换为 HTTPS URL。 需要注意的是,即使设置了这个参数,通过 SDK 发出去的消息 URL 仍是 HTTPS 的,设置这个参数只影响接收到的消息的 URL 格式转换
maxAutoLoginRetryTimes int 自动登录重试次数,默认为 0。即默认情况下,自动登录将无限重试。设置成大于 0 的值后,在没有登录成功前,自动登录将重试最多 maxAutoLoginRetryTimes
maximumLogDays int 本地日志的有效期,默认为 7 天。即超过 7 天的本地日志将被清除。只能设置大于等于 2 的值
disableReconnectInBackgroundState bool 是否禁止后台重连,默认为 NO。即默认情况下,当程序退到后台断开连接后,如果应用仍能运行,SDK 将继续执行自动重连机制。设置为 YES 后在后台将不自动重连,重连将被推迟到前台进行。只有特殊用户场景才需要此设置,无明确原因请勿设置。
enableTeamReceipt bool 是否开启群消息已读回执功能,默认为 NO
enableFileQuickTransfer bool 是否开启文件快传本地开关,默认 YES。
enableAsyncLoadRecentSession bool 是否开启异步读取最近会话,默认 NO。对于最近会话比较多的用户,初始读取数据库时,可能影响到启动速度,这些用户可以选择开启该选项,querySessionList 会优先返回一部分最近会话,等到全部读取完成时,通过回调通知用户刷新 UI。
enabledQChatMessageCache bool 开启圈组的消息缓存,默认不开启

Windows 平台独有参数

NIMWINDOWSSDKOptions的参数说明如下:

参数 类型 必填 说明
databaseEncryptKey String 数据库秘钥,目前只支持最多 32 个字符的加密密钥。建议使用 32 个字符
preloadImageQuality int 预下载图片质量,选填,范围 0-100
preloadImageResize String 预下载图片基于长宽做内缩略,选填,例如图片宽 100 高 50,则赋值为 100x50,中间为小写字母 x
preloadImageNameTemplate String 预下载图片命名规则,以{filename}为 token 进行替换
maxAutoLoginRetryTimes int 自动登录失败的最大重试次数,如需设置,建议设置大于 3 次。默认填 0
enabledHttps bool 是否启用 HTTPS 协议,默认为 true
shouldVchatMissMessageMarkUnread bool 语音消息未接通时,该语音消息是否计入未读数,默认为 false
enableClientAntispam bool 是否开启客户端反垃圾进行内容审核,默认为 false。如需开启请先联系商务经理开通该功能
needUpdateLbsBeforeRelogin bool 重新登录前是否先刷新 LBS,适用于切换网络的场景

macOS 平台独有参数

NIMMACOSSDKOptions的参数说明如下:

参数 类型 必填 说明
databaseEncryptKey String 数据库秘钥,目前只支持最多 32 个字符的加密密钥。建议使用 32 个字符
preloadImageQuality int 预下载图片质量,选填,范围 0-100
preloadImageResize String 预下载图片基于长宽做内缩略,选填,例如图片宽 100 高 50,则赋值为 100x50,中间为小写字母 x
preloadImageNameTemplate String 预下载图片命名规则,以{filename}为 token 进行替换
maxAutoLoginRetryTimes int 自动登录失败的最大重试次数,如需设置,建议设置大于 3 次。默认填 0
enabledHttps bool 是否启用 HTTPS 协议,默认为 true
shouldVchatMissMessageMarkUnread bool 语音消息未接通时,该语音消息是否计入未读数,默认为 false
enableClientAntispam bool 是否开启客户端反垃圾进行内容审核,默认为 false。如需开启请先联系商务经理开通该功能
needUpdateLbsBeforeRelogin bool 重新登录前是否先刷新 LBS,适用于切换网络的场景
pushCertName String 在云信控制台配置的推送证书名称
pushToken String 需要接收推送的设备的 token
enableAppNap bool 是否启用 macOS 下的 App Nap 功能,默认为 false
此文档是否对你有帮助?
有帮助
去反馈
  • 前提条件
  • 初始化 SDK
  • 相关参考
  • 海外数据中心配置
  • 初始化配置参数
  • 通用参数
  • Android 平台独有参数
  • iOS 平台独有参数
  • Windows 平台独有参数
  • macOS 平台独有参数