SDKsFlutter

按运行环境接入

在 Android 和 iOS Flutter 应用中初始化 OpenIMClientSDK，并处理移动端运行时边界。

运行环境选择

flutter_openim_sdk 面向 Android 和 iOS Flutter 应用。两端使用相同的 Dart manager、model 和 listener，但平台 ID、数据目录、权限、后台生命周期和构建配置不同。

运行环境	`platformID`	主要注意事项
Android	`IMPlatform.android`	网络权限、应用数据目录、后台限制和推送配置。
iOS	`IMPlatform.ios`	网络策略、应用沙盒目录、后台模式和推送配置。

Web、桌面和小程序应使用对应 SDK，不要仅因为 IMPlatform 中存在其他数值就推断此 Flutter 包已经支持相应运行环境。

安装依赖

安装 SDK，并加入用于获取应用文档目录的 path_provider：

flutter pub add flutter_openim_sdk path_provider

该命令会选择当前项目可用的最新兼容版本，并写入 pubspec.yaml。团队项目应提交依赖锁定文件；升级依赖后，需要在 Android 和 iOS 上分别重新验证初始化与连接流程。

初始化 SDK

一个应用进程只应复用 OpenIM.iMManager。先准备可持久化的数据目录，再根据实际系统选择平台枚举，并把连接生命周期 listener 传给 initSDK()。

import 'dart:io';

import 'package:flutter_openim_sdk/flutter_openim_sdk.dart';
import 'package:path_provider/path_provider.dart';

Future<bool> initializeOpenIM({
  required String apiAddr,
  required String wsAddr,
}) async {
  final directory = await getApplicationDocumentsDirectory();
  final platformID = Platform.isIOS
      ? IMPlatform.ios
      : IMPlatform.android;

  final initialized = await OpenIM.iMManager.initSDK(
    platformID: platformID,
    apiAddr: apiAddr,
    wsAddr: wsAddr,
    dataDir: directory.path,
    logLevel: 6,
    isLogStandardOutput: true,
    listener: OnConnectListener(
      onConnecting: () => updateConnectionState('connecting'),
      onConnectSuccess: () => updateConnectionState('connected'),
      onConnectFailed: (code, message) {
        updateConnectionState('failed');
        logConnectionFailure(code, message);
      },
      onKickedOffline: handleKickedOffline,
      onUserTokenExpired: refreshSession,
      onUserTokenInvalid: redirectToSignIn,
    ),
  );

  return initialized == true;
}

参数说明

字段	类型	是否必填	说明
`platformID`	`int`	是	Android 使用 `IMPlatform.android`，iOS 使用 `IMPlatform.ios`。
`apiAddr`	`String`	是	OpenIMServer HTTP API 地址。
`wsAddr`	`String`	是	OpenIMServer WebSocket 地址。
`dataDir`	`String`	是	SDK 数据库和日志使用的应用沙盒目录。
`listener`	`OnConnectListener`	是	连接、Token 和账号下线 listener。
`logLevel`	`int`	否	SDK 日志等级，默认 `6`。生产环境应按隐私和排障需求收敛。
`isNeedEncryption`	`bool`	否	是否启用 SDK 数据加密，默认 `false`。
`isCompression`	`bool`	否	是否启用压缩，默认 `false`。
`isLogStandardOutput`	`bool`	否	是否输出 SDK 日志到标准输出。
`logFilePath`	`String?`	否	自定义日志目录；未设置时由 SDK 配置处理。

初始化 Future 成功只表示 SDK 初始化调用完成。登录后是否可调用依赖连接的业务 API，仍以 onConnectSuccess 为准。

Android 与 iOS 边界

Android

确认 manifest 允许网络访问，并使用应用私有目录保存 SDK 数据。
Android 模拟器访问开发电脑时，不能把 localhost 当作宿主机地址。
后台保活与推送到达由 Android 系统策略和应用推送集成共同决定。

iOS

使用应用沙盒内的持久化目录，不能保存到 bundle。
生产地址应使用有效 HTTPS/WSS 证书；如需修改 ATS，先评估安全影响。
真机推送、后台恢复和模拟器行为不同，应分别验证。

生命周期与释放

本文档当前核对的 Flutter SDK 没有公开的网络状态或前后台上报 Dart 方法。应用恢复时以连接 listener 为准，并重新查询当前页面所需快照。用户彻底退出应用的 SDK 作用域时可调用：

OpenIM.iMManager.unInitSDK();

unInitSDK() 不等于用户主动退出登录。切换账号时先等待 logout() 完成，再清理旧账号应用状态并登录新账号。

验证与排查

Android 与 iOS 各至少验证一次初始化、登录和 onConnectSuccess。
真机确认 HTTP、WebSocket 和媒体资源地址均可访问。
杀进程、进入后台、网络断开恢复后，确认连接状态和页面快照能恢复。
不要在多个 Widget 中重复初始化 SDK 或反复替换全局 listener。

下一步

这个页面有帮助吗？