Conch API 详细文档

1. 核心 API

1.1 runAppWrapper - 应用启动包装器

1.1.1 功能概述

runAppWrapper 是 Conch SDK 的核心启动方法，用于包装 Flutter 应用的启动流程，自动处理补丁加载和应用初始化。

1.1.2 工作流程

1. 初始化阶段：自动完成 SDK 初始化，设置配置参数和回调。
2. 补丁处理：依据配置相应加载补丁。
3. 调用 appBuilder()：调用 appBuilder() 并返回根 Widget。

1.1.3 函数签名

static Widget runAppWrapper(
  ConchParams params, {
  required FutureOr<Widget> Function() appBuilder,
  PatchInstallCallback? patchInstallCallback,
  PatchLoadCallback? patchLoadCallback,
})

1.1.4 参数说明

ConchParams 参数详解

参数名	类型	必填	说明
appId	String	是	应用唯一标识，从 Shiply 平台获取
appKey	String	是	在 Shiply 发布平台获取，需与平台配置一致，用于安全校验。
moduleName	String	是	模块名称，与 Shiply 平台一致
appVersion	String	是	应用版本号，用于补丁下发时版本匹配
env	String	否	环境标识，默认为 "online" 正式环境
deviceId	String	否	设备标识，用于灰度发布，体验名单

注意： appId、appKey、moduleName 必须与 Shiply 平台配置完全一致，否则无法拉取到对应补丁。

runAppWrapper 参数详解

参数名	类型	必填	说明
params	ConchParams	是	Conch 运行时配置参数，包含 appId、appKey、moduleName 等关键信息。
appBuilder	FutureOr<Widget> Function()	是	App 根 Widget 构建器，支持同步返回 Widget 或异步返回 Future<Widget>。补丁加载完成后会调用此函数构建根 Widget
patchInstallCallback	PatchInstallCallback?	否	补丁安装完成回调，返回 PatchInstallResult 对象，包含安装结果码、版本号等信息
patchLoadCallback	PatchLoadCallback?	否	补丁加载完成回调，返回 PatchLoadResult 对象，包含加载结果码、模块名、版本号等信息

1.1.5 返回值

• 类型：Widget
• 说明：返回 appBuilder() 构建的 App 根 Widget

1.1.6 使用示例

void main() {
  runApp(
    ConchLoaderAPI.runAppWrapper(
      params,
      appBuilder: () => const MyApp(),
      patchInstallCallback: (result) {
        print('补丁安装结果: ${result.resultCode}');
      },
      patchLoadCallback: (result) {
        print('补丁加载结果: ${result.resultCode}');
      },
    ),
  );
}

1.1.7 注意事项

• appBuilder() 应返回 App 的根 Widget
• 补丁加载完成后会自动调用 appBuilder() 并展示应用界面
• 在 Debug 模式下Conch 不会生效，只在 Release 模式下生效

---

1.2 requestPatch - 补丁请求接口

1.2.1 功能概述

仅从服务器拉取补丁并安装到本地，不加载到运行时环境。

1.2.2 函数签名

static Future<PatchInstallResult> requestPatch()

1.2.3 核心特性

• 纯网络操作：只下载和解密补丁到本地，不加载到运行时
• 异步执行：不阻塞主线程，适合后台执行
• 独立调用：可在任意时机调用，不依赖应用启动流程

1.2.4 使用场景

• 预下载场景：提前下载补丁，稍后再加载

1.2.5 返回值

类型：Future<PatchInstallResult>

PatchInstallResult 对象包含：

• resultCode：安装状态码（SUCCESS、FETCH_NO_PATCH、NOT_INIT、INSTALL_FAIL 等）
• moduleName：模块名称
• version：补丁版本号
• taskId：任务 ID

1.2.6 使用示例

// 后台预下载补丁（不阻塞主流程）
ConchLoaderAPI.requestPatch().then((result) {
  if (result.resultCode == PatchInstallResultCode.SUCCESS) {
    print('补丁下载成功，已安装到本地: ${result.version}');
  } else {
    print('补丁安装失败或无可用补丁: ${result.resultCode}');
  }
});

1.2.7 注意事项

• 该方法只负责下载和安装补丁，不会加载补丁到运行时
• 下载的补丁会在下次应用启动时自动加载

---

1.3 queryPatchLoadResult - 补丁加载状态查询

1.3.1 功能概述

同步查询当前补丁的加载结果，不触发任何加载流程。

1.3.2 函数签名

static PatchLoadResult? queryPatchLoadResult()

1.3.3 核心特性

• 纯查询操作：不会触发网络请求或补丁加载

1.3.4 使用场景

• 在业务逻辑中判断补丁是否已加载成功
• 获取当前运行的补丁版本信息

1.3.5 返回值

类型：PatchLoadResult?

返回值说明：

• 非 null：包含当前补丁加载状态
  • resultCode：加载状态码（SUCCESS、NO_PATCH、PATCH_LOAD_FAIL 等）
  • moduleName：模块名称
  • version：补丁版本号
  • taskId：任务 ID
• null：以下情况会返回 null
  • 补丁尚未开始加载或补丁加载流程未完成

1.3.6 使用示例

// 基础用法
final result = ConchLoaderAPI.queryPatchLoadResult();
if (result != null) {
  if (result.resultCode == PatchLoadResultCode.SUCCESS) {
    print('当前已加载补丁版本: ${result.version}');
  } else {
    print('补丁未加载或加载失败: ${result.resultCode}');
  }
} else {
  print('SDK 未初始化、补丁尚未开始加载或加载流程未完成');
}

// 在业务逻辑中使用
Widget build(BuildContext context) {
  final patchResult = ConchLoaderAPI.queryPatchLoadResult();
  final version = patchResult?.version ?? '未知';
  
  return Text('当前补丁版本: $version');
}

1.3.7 注意事项

• 该方法为同步方法，不会阻塞线程
• 仅查询状态，不会改变任何运行时状态
• 建议在应用启动完成后调用