初始化

大约 6 分钟

初始化

初始化是使用 SDK 的必要步骤。请在调用其他 SDK API 前完成初始化，并在应用生命周期内避免重复初始化。

如果进行了多次初始化操作，只有第一次初始化以及相关的参数生效。

提示

Android 应在应用主进程中初始化 SDK。

前提条件

你已拥有有效的环信即时通讯 IM 开发者账号和 App Key。关于创建应用并获取 App Key，详见环信控制台相关文档。

初始化 SDK

使用 ChatOptions.withAppKey 创建初始化配置，然后调用 ChatClient.getInstance.init 初始化 SDK：

final ChatOptions options = ChatOptions.withAppKey(appKey);
await ChatClient.getInstance.init(options);

配置 iOS 生命周期回调

Flutter SDK 4.13.0 及以上版本支持通过 ExtSettings.kDisableIosEnterBackground 控制 Flutter iOS 插件是否自动向 iOS 原生 SDK 转发应用进入后台和返回前台的生命周期事件：

未设置该参数或设置为 false：插件监听 iOS 生命周期通知，并分别调用原生 SDK 的 applicationDidEnterBackground 和 applicationWillEnterForeground。
设置为 true：插件不注册上述生命周期通知，也不会自动调用这两个原生 SDK 方法。

如需关闭 Flutter iOS 插件的自动转发，可进行如下配置：

final ChatOptions options = ChatOptions.withAppKey(
  appKey,
  extSettings: <String, dynamic>{
    ExtSettings.kDisableIosEnterBackground: true,
  },
);

await ChatClient.getInstance.init(options);

常用初始化配置

下表列出了 ChatOptions.withAppKey 的部分常用参数。全部参数请参见 ChatOptions API 参考open in new window。

参数	类型	默认值	描述
`appKey`	`String`	无	在环信控制台创建应用后获得的 App Key，必须传入。
`autoLogin`	`bool`	`true`	是否开启自动登录。开启后，用户首次成功登录且未主动退出时，SDK 可在后续启动时自动登录。
`acceptInvitationAlways`	`bool`	`false`	是否自动接受好友邀请： - `true`：自动接受好友邀请。 - `false`：不自动接收好友邀请。
`autoAcceptGroupInvitation`	`bool`	`false`	是否自动接受群组邀请： - `true`：自动接受加群申请； - `false`: 不自动接受加群申请。
`requireAck`	`bool`	`true`	是否要求消息已读回执。
`requireDeliveryAck`	`bool`	`false`	是否要求消息送达回执。
`deleteMessagesAsExitGroup`	`bool`	`true`	离开群组时是否删除该群组的本地消息： -（默认）`true`: 退出群组时删除群组消息。 - `false`: 退出群组时不删除群组消息。
`deleteMessagesAsExitChatRoom`	`bool`	`true`	离开聊天室时是否删除该聊天室的本地消息： -（默认）`true`：删除。 - `false`：保留。
`isChatRoomOwnerLeaveAllowed`	`bool`	`true`	是否允许聊天室所有者离开聊天室： - （默认） `true`：允许。即使聊天室所有者离开，该所有者仍具有聊天室的所有权限，只不过不再接收任何消息。 - `false`：不允许。
`enableUserInfo`	`bool`	`false`	是否开启用户信息自动管理功能。
`enableAutoSyncContacts`	`bool`	`false`	是否在登录后自动从服务器同步联系人列表。
`enableEmptyConversation`	设置从本地数据库加载会话时是否包含空会话，必须在初始化 SDK 前设置。 - `true`：包含空会话。 -（默认）`false`：不包含空会话。
`autoLoadConversations`	设置初始化时是否自动将本地数据库中的全部会话加载到内存。该功能自 Flutter SDK 4.25.0 起支持，必须在初始化 SDK 前设置。 -（默认）`true`：自动加载全部会话。 - `false`：不自动加载全部会话，可通过 `fetchConversationsFromDB` 按页加载。
`enableChatroomConversation`	设置获取本地会话列表时是否包含聊天室会话。该配置不控制聊天室会话的创建或存储，也不影响聊天室消息的正常收发。自 Flutter SDK 4.25.0 起支持。 - `true`：本地会话列表中包含聊天室会话。 -（默认）`false`：本地会话列表中不包含聊天室会话。必须在初始化 SDK 前设置。
`apnsCertName`	`String?`	`null`	APNs 推送证书名称，仅对 iOS 生效。必须在 SDK 初始化时设置，运行期间不可修改。自 Flutter SDK 4.25.0 起支持。
`pushKitCertName`	`String?`	`null`	PushKit 推送证书名称，用于 iOS VoIP 推送，仅对 iOS 生效。必须在 SDK 初始化时设置，运行期间不可修改。自 Flutter SDK 4.25.0 起支持。

初始化后设置监听

初始化完成后，可以添加连接事件处理器和消息事件处理器，监听 SDK 连接状态及消息接收事件。每个事件处理器都使用业务自定义的唯一 ID 管理；使用相同 ID 再次添加时，会覆盖此前的处理器。

const String connectionHandlerId = 'connection_handler';
const String messageHandlerId = 'message_handler';

ChatClient.getInstance.addConnectionEventHandler(
  connectionHandlerId,
  ConnectionEventHandler(
    onConnected: () {
      debugPrint('Connected to the IM server.');
    },
    onDisconnected: () {
      debugPrint('Disconnected from the IM server.');
    },
  ),
);

ChatClient.getInstance.chatManager.addEventHandler(
  messageHandlerId,
  ChatEventHandler(
    onMessagesReceived: (List<ChatMessage> messages) {
      debugPrint('Received ${messages.length} message(s).');
    },
  ),
);

不再需要监听时，应使用对应的 ID 移除事件处理器：

ChatClient.getInstance.removeConnectionEventHandler(connectionHandlerId);
ChatClient.getInstance.chatManager.removeEventHandler(messageHandlerId);

设置登录后自动同步好友数据

Flutter SDK 4.22.0 可通过 ChatOptions.withAppKey 的 enableAutoSyncContacts 参数设置登录后是否自动同步好友列表和好友对象。该参数默认为 false；如需开启，必须在初始化 SDK 时设置为 true。好友对象包含用户 ID、备注和添加时间等信息，不代表已获取所有好友的昵称和头像。

同步状态监听、好友列表和好友对象的本地读取方式，详见登录后自动同步好友列表。

开启用户信息自动管理

Flutter SDK 4.22.0 可通过 enableUserInfo 参数设置用户信息自动管理功能。该参数默认为 false，设置为 true 后，原生 SDK 会在登录成功时自动同步 当前登录用户 的属性；其他用户的属性可在接收相关消息和主动从服务端拉取用户属性等场景下更新。它与 enableAutoSyncContacts 相互独立，不会在登录时自动获取所有好友的昵称和头像。

如果两项功能都需要，可在同一次初始化中配置：

final ChatOptions options = ChatOptions.withAppKey(
  'your_app_key',
  enableAutoSyncContacts: true,
  enableUserInfo: true,
);

await ChatClient.getInstance.init(options);

用户属性更新事件、本地读取与主动获取方式，详见用户信息自动管理。

接口列表

API 名称	所属模块/类	说明
`withAppKey`	`ChatOptions`	使用 App Key 创建初始化配置。
`init`	`ChatClient`	初始化 Flutter SDK 单例。
`addConnectionEventHandler`	`ChatClient`	添加连接事件处理器。
`removeConnectionEventHandler`	`ChatClient`	移除连接事件处理器。
`addEventHandler`	`ChatManager`	添加消息事件处理器。
`removeEventHandler`	`ChatManager`	移除消息事件处理器。
`enableAutoSyncContacts`	`ChatOptions`	登录后自动同步好友数据的初始化配置。
`enableUserInfo`	`ChatOptions`	用户属性自动管理的初始化配置。
`apnsCertName`	`ChatOptions`	iOS APNs 推送证书名称的初始化配置。
`pushKitCertName`	`ChatOptions`	iOS PushKit 推送证书名称的初始化配置。
`enableChatroomConversation`	设置获取本地会话列表时是否包含聊天室会话。该配置不控制聊天室会话的创建或存储，也不影响聊天室消息的正常收发。自 Flutter SDK 4.25.0 起支持。
`enableEmptyConversation`	设置从本地数据库加载会话时是否包含空会话，必须在初始化 SDK 前设置。
`autoLoadConversations`	设置初始化时是否自动将本地数据库中的全部会话加载到内存。该功能自 Flutter SDK 4.25.0 起支持，必须在初始化 SDK 前设置。

初始化

# 初始化

# 前提条件

# 初始化 SDK

# 配置 iOS 生命周期回调

# 常用初始化配置

# 初始化后设置监听

# 设置登录后自动同步好友数据

# 开启用户信息自动管理

# 接口列表

初始化