跳到主要内容

WebView 容器 SDK 更新日志

1.2.0（2026-07-31）​

Added​

  • WebView 预热能力（五端统一）：新增 TencentQianWebViewPrewarmer（OC 版 TQWebViewPrewarmer）统一入口，纯新增、不改任何已放开 API。两个正交维度——网络预热（省网络加载时间）+ WebView 复用池（省实例创建 100–300ms）。
    • 意图三档 PrewarmLevel { MINIMAL, LIGHT, HEAVY }：MINIMAL = 纯 DNS 预解析（无需 bizType）；LIGHT = 内核/进程首次初始化（鸿蒙 initializeWebEngine + prepareForPageLoad、Android/iOS 离屏预建空实例）；HEAVY = 池实例加载 warmup.html 网络热身。SDK 内部按档位叠加补做低档动作，单调去重不允许降级重热。
    • 多环境 PrewarmEnvironment { PROD, BETA }（默认 PROD）+ manifestUrl 覆盖；在线 warmup-manifest.json 为唯一数据源。
    • manifest configure 后台拉 + prewarm 懒兜底 + stale-while-revalidate，TTL 读自响应头 Cache-Control: max-age（默认 300s）；manifest version 变化整体重置去重状态。
    • WebView 复用池：容器模式 open() 透明复用预热态实例。Android + 鸿蒙 = 跨流程借还池（归还 about:blank + clearHistory 不销毁，客户主动 release/releaseAll 释放）；iOS = 单流程一次性（无 clearHistory，关闭销毁，靠共享 WKProcessPool + .default() DataStore 复用）。池容量固定为 1。
    • open(url) 环境错配检测（仅 3 个已知 quick.* 环境搭错才告警，非 quick 域名不告警，不阻断）。
    • getMenuBizTypes(callback)（五端对齐）：异步返回 manifest 可用于菜单展示的业务列表，manifest 新增可选 menuBizTypes 字段（精选子集，缺省回退全量 bizTypes keys）。
    • PrewarmConfig 新增 preferredLanguage（语言偏好；L4 拼 &lang= 委托 warmup.html、L3 按 i18nAutoDetect 门控）、injectUserAgent + userAgentExtra（池实例按 UA 创建，复用门控改为预热 UA == open config UA）。
    • 鸿蒙 TencentQianWebViewComponent（嵌入模式）新增 reusePrewarmPool 开关（默认 false），开启后复用预热池。
    • 平台能力：HarmonyOS = L1 DNS + L2 预连接 + HEAVY NodeContainer 离屏池；Android = L1 + 借还池 + L4(warmup.html)；iOS = L1 + 一次性池 + L4（共享 .default() DataStore 磁盘缓存跨实例复用）。
    • 全程 best-effort：任何预热失败静默降级，绝不阻塞 / 影响 open() 主流程；容器模式池复用对客户透明。
  • 鸿蒙嵌入模式（TencentQianWebViewComponent）宿主联动能力补齐：此前嵌入模式仅暴露 onSignResult / onSdkEvent，宿主自绘顶栏 / 进度条 / 错误处理时缺少必要的联动与控制手段（Page 模式已内置）。本次对齐补齐两类能力，全部可选、向后兼容：
    • 感知回调：新增 onTitleChanged（H5 标题 + 可后退快照，供自绘顶栏）、onProgressChanged（加载进度，供自绘进度条）、onRenderUnrecoverable（渲染进程连续崩溃且 SDK 放弃自动恢复的终态，供显示错误页 / 返回 / 重试；与 RenderProcessGoneEvent 的「每次崩溃」语义互补）。
    • 控制能力：新增 TencentQianWebViewController（供 TencentQianWebViewComponent 使用），宿主可主动 canGoBack() / goBack() / handleBack()（逐级后退 H5 历史，覆盖 SPA 软路由）/ reload()（配合不可恢复回调做「重试」），修正此前宿主返回按钮只能直接退出、绕过 H5 多级历史的问题。
  • 渲染进程崩溃恢复（三端对齐）：池实例在预热/借出/归还三态的渲染进程崩溃回调均正确善后。Android/iOS 走"销毁 + 新建"（精准回退崩溃前页面）、鸿蒙走"原地重载（loadUrl 优先、refresh 兜底）"；重试上限 3 + 冷却窗口 30s + 延迟恢复（防必崩页面死循环 / 二次崩溃）；鸿蒙借出态崩溃"脱池不销毁活节点"原地恢复。对客户透明，不新增公开 API。

Changed​

  • Android 最低系统要求降至 Android 5.0（API 21）：minSdk 从 24 降至 21，Java 编译目标降至 1.8（sourceCompatibility/targetCompatibility = 1.8，Kotlin jvmTarget = 1.8）。SDK 源码改用 androidx.core.util.Consumer/Supplier 替代 java.util.function.*，"UTF-8" 字符串替代 StandardCharsets，不引入 core library desugaring，AAR / 源码集成客户无需额外配置。JDK 17 仍为构建工具链，源码不使用任何 JDK 9+ 语法或标准库 API，兼容客户的 Java 8 编译目标
  • iOS 最低部署目标降至 iOS 11.0：Deployment Target 从 14.3 降至 11.0。SDK 对 iOS 13+/14+ API（WKWebpagePreferences、os.Logger、UIColor 系统颜色、SF Symbols、UIStatusBarStyle.darkContent、HTTPURLResponse.value(forHTTPHeaderField:)）增加 #available/@available 版本分支与兼容层，iOS 11-12 降级为旧 API / 静态颜色 / 文字符号（返回 ‹、关闭 ✕）/ NSLog。safeAreaLayoutGuide 与 httpCookieStore 恰为 iOS 11，无需改动
  • WebRTC / getUserMedia 系统门槛不变：仍需 Android 7.0+（API 24）/ iOS 14.3+，由系统 WebView 内核决定。低版本系统（Android 5.0~6.x / iOS 11~14.2）走 <input type="file" capture> 系统相机录制/拍照上传路径，本次改造确保该路径在 minSdk 21 / iOS 11 正常工作

Fixed​

  • 修复 iOS 渲染进程崩溃恢复白屏隐患：容器 webViewWebContentProcessDidTerminate 从 reload 改为"销毁 + 新建 WKWebView"，消除原 reload 导致的白屏问题
  • 修复 iOS（Swift + OC）下载文件名路径穿越：新增 sanitizedFilename 归一化文件名，防服务器返回含 ../ 或 / 的恶意文件名写入任意目录
  • 修复鸿蒙下载文件名路径穿越：DownloadHandler 文件名 sanitize 加固，防 ../ 路径穿越写入任意目录

1.1.0（2026-07-17）​

Added​

  • iOS SPM（Swift Package Manager）本地源码包集成支持：新增 ios-swift/Package.swift（TencentQianWebViewSDK module）与 ios-objective-c/Package.swift（TencentQianWebView module），Swift / Objective-C 客户均可通过 Xcode「File → Add Packages → Add Local…」一键引入源码集成，Xcode 自动编译、自动处理架构、保留模块边界
  • iOS xcframework 二进制分发：scripts/build-ios-swift.sh 与 scripts/build-ios-objectivec.sh 新增 xcframework 子命令，合成含 ios-arm64 + ios-arm64_x86_64-simulator 双 slice 的 .xcframework，解决 Apple Silicon Mac 模拟器 arm64 架构冲突（传统 fat framework 在 Apple Silicon 上直接编译报错的硬伤）
  • iOS SPM + xcframework 集成验证脚本 scripts/verify-ios-integration.sh：覆盖 SPM Add Local / xcframework 两种集成方式 × Swift 版 + OC 版 × simulator + device 的全量验证矩阵，全程无需开发者证书
  • iOS Objective-C 工程：新增 DemoSwift target，作为纯 Swift 应用通过 framework module 消费 OC 版 TencentQianWebView 的集成范本，适用于 Swift 主语言存量客户接入 OC 版 SDK

Changed​

  • 更新 Android 端混淆规则说明
  • 收拢 ios-objective-c 公共头文件到 Public/ 目录，使 SPM 单 publicHeadersPath 约束可满足，并简化 project.yml 头文件可见性配置
  • 更新 iOS 集成文档（usage-guide / integration-checklist / troubleshooting）：明确集成方式优先级（SPM 源码包 > xcframework 二进制 > 源文件直拖），补充 Apple Silicon arm64 冲突排错
  • 更新 qianuni UniApp web-view 接入指南
  • UA 版本号固定在源码中，方便多种集成方式使用

1.0.5（2026-06-25）​

Changed​

  • 文档补齐 HarmonyOS 接入自检清单、协议常量、排错决策树与三端下载行为对照，同步修正 iOS 权限文案与 HarmonyOS module.json5 权限配置

1.0.4（2026-06-18）​

Fixed​

  • Android 与 鸿蒙 SPA 路由切换导致进度条误显示且无法关闭

1.0.3（2026-06-12）​

Fixed​

  • 鸿蒙端手动关闭容器不回调 EMPTY，与其他端对齐

1.0.2（2026-06-12）​

Fixed​

  • 修复 SignResult.EMPTY 共享 Map 污染、关闭流程双回调、Component 网络监听泄漏，并补齐外部 scheme 失败上报与下载文件名路径穿越防御

1.0.1（2026-06-12）​

Changed​

  • 优化版本号管理

1.0.0（2026-06-11）​

Added​

  • Android Kotlin SDK：容器模式 TencentQianWebView.open 与配置模式 TencentQianWebViewConfigurator.apply
  • Android Java SDK：与 Kotlin 版功能与 API 对等的纯 Java 实现（Builder 模式 Config、abstract class + static final 子类替代 sealed class），适用于不引入 Kotlin 运行时的存量工程
  • iOS Swift SDK：容器模式 TencentQianWebView.open 与配置模式 TencentQianWebViewConfigurator.apply
  • iOS Objective-C SDK：与 Swift 版 1:1 对齐的纯 OC 实现（ARC），适用于 100% Objective-C 代码库存量客户
  • HarmonyOS ArkTS SDK：基于 ArkWeb 的容器模式 TencentQianWebView.open 与配置模式 TencentQianWebViewConfigurator.apply
  • qianapp:// 协议解析：跨端一致的 SignResult 结构（action / result / flowId / from / extras）
  • 三端 UA 注入 qianwv/<version> 标识，便于 H5 侧识别 SDK 容器
  • 文件下载兼容（Android DownloadListener、iOS URLSession + 分享 sheet、HarmonyOS request.downloadFile + DocumentViewPicker）
  • 文件选择器、JS 弹窗、getUserMedia 权限链路、SSL 错误处理、渲染进程崩溃恢复等三端兼容性适配
  • 接入指南、qianapp:// 协议规范、自检清单、排错决策树 + 常见问题