跳到主要内容

WebView 容器 SDK 更新日志

1.4.0（2026-08-18）​

Added​

  • 容器模式顶栏高度配置：四端 TencentQianWebViewConfig（Android Kotlin / Java、iOS Swift / Objective-C TQWebViewConfig、HarmonyOS）新增可选字段 topBarHeight（Android Int? / Java Integer，单位 dp；iOS Swift CGFloat? / Objective-C NSNumber *，单位 pt；鸿蒙 number | null，单位 vp）。null 走各端默认高度（Android / 鸿蒙 48、iOS 44），显式传值时覆盖顶栏高度；仅容器模式生效（组件模式 / 配置模式顶栏由客户自绘，忽略此字段）

Changed​

  • Android（Kotlin / Java）全版本统一启用 Edge-to-Edge 布局：容器模式内容区改为全屏绘制，状态栏 / 导航栏 / 挖孔区域由 SDK 基于 WindowInsets 自动避让（叠加到根布局 padding，底部取系统栏与键盘高度较大值），软键盘弹出时自动顶起内容、不再遮挡 H5 输入框，不再依赖系统自动 resize 与 XML fitsSystemWindows（Android 15+ 已强制忽略）；同时清零下发给 WebView 的系统栏 / 挖孔 inset，使 H5 页面 CSS env(safe-area-inset-*) 归零、避让自动失效，消除与 SDK 避让叠加产生的双重 padding（底部灰带）。容器模式自动生效、客户零改动；配置 / 组件模式由宿主持有布局，SDK 不主动修改（避免与宿主自身 E2E 处理叠加出双 padding），可按 Demo 示范调用 applyEdgeToEdgeInsets 一行接入同款避让，浅色界面建议同时配置 windowLightStatusBar
  • 关闭确认弹窗按钮文案调整与自定义：五端默认文案统一由「离开 / 继续」改为「仍要离开 / 留在本页」（结果导向，消除"继续离开还是继续流程""离开对话框还是离开页面"歧义）；按钮位置与点击语义不变，升级后未配置的客户将自动使用新文案。同时 TencentQianWebViewConfig / TQWebViewConfig 新增可选字段 confirmLeaveText / confirmStayText（默认空，空则使用新默认文案），承载非签署类 H5 流程时可自定义按钮文案，与既有 confirmCloseTitle / confirmCloseMessage 语义对齐；如需保留旧文案，可通过 confirmLeaveText = "离开" / confirmStayText = "继续" 显式还原。仅容器模式生效
  • 三端容器模式顶栏返回/关闭图标统一为 chevron_left 形态：Android 用 vector、鸿蒙用 SVG；iOS（Swift / Objective-C）由 SF Symbol（需 iOS 13+、视觉偏大）改为手写 UIBezierPath 内置矢量，复刻 Material Icons 24×24 路径，三端像素级对齐且兼容 iOS 11+；新增公开 TencentQianWebViewIcon / TQWebViewIcon，容器模式与组件模式 Demo 共用，消除 #available 分支与文字 fallback

Fixed​

  • Android（Kotlin / Java）修复 Android 5（API 21-22）状态栏文字不可见：深色状态栏文字（StatusBarStyle.DARK_CONTENT，默认）为 Android 6.0（API 23）新增能力，Android 5 系统状态栏文字恒为白色，落在默认浅色背景上不可见；修复后 Android 5 上自动为状态栏叠加半透明深色底衬，保证文字可读。LIGHT_CONTENT（白色文字）为 Android 5 系统原生行为，不受影响；容器模式自动生效、客户零改动

1.3.0（2026-08-11）​

Added​

  • Android（Kotlin / Java）组件模式（嵌入形态）：新增 TencentQianWebViewComponent（自定义 View + DSL 工厂），宿主在自定义布局中嵌入完整配置的签署 WebView，镜像鸿蒙嵌入模式，补齐第三种集成形态（容器模式 / 组件模式 / 配置模式）：

    • DSL 参数：url / config / onSignResult / onSdkEvent / onTitleChanged / onProgressChanged / onRenderUnrecoverable / controller / reusePrewarmPool
    • 感知回调：onTitleChanged（标题 + 可后退快照，供自绘顶栏）/ onProgressChanged（进度 + 可见性门控，SPA 软路由不误显示）/ onRenderUnrecoverable（渲染崩溃终态，供自绘错误页 + 重试）
    • 控制能力：新增 TencentQianWebViewController，宿主可主动 canGoBack() / goBack() / handleBack()（逐级后退 H5 历史，覆盖 SPA 软路由）/ reload()（配合不可恢复回调做「重试」）
    • TencentQianWebViewConfigurator.apply() 末尾追加可选参数 onTitleChanged（@JvmOverloads，默认 null）；其余参数（含 progressListener）不变，现有调用零改动
    • ActivityResult 依赖新增基于 ActivityResultRegistry 的注册路径（RuntimePermissionRequester / FileChooserLauncher），组件可在 View 创建后（Activity 已过 onCreate）随时初始化，绕开 registerForActivityResult 的「onCreate 前注册」约束；原 register(activity) / register(fragment) 路径保留
    • 渲染进程崩溃恢复逻辑从容器 Activity 抽取为 internal 共享状态机（计数 / 30s 冷却窗口 / 上限 3 / 门控清零），容器与组件共用同一实现；组件模式在放弃恢复时触发 onRenderUnrecoverable
    • 组件默认自建自管（reusePrewarmPool 默认 false）：生命周期由宿主 UI 树掌控（视图移除 ≠ 签署结束），onDetachedFromWindow 仅暂停渲染，显式 release() 才归还池 / 销毁 WebView 并复位命令对象
    • Android（Java）：android-java 模块 1:1 对齐（TencentQianWebViewComponent.Builder 链式 setter + @FunctionalInterface 回调 + apply() 重载追加 OnTitleChanged 末参），参数面 / 回调时序 / 崩溃恢复与终态重试语义与 Kotlin 版完全一致，全部公开 API 保持 Java 8 / minSdk 21 可调用

  • iOS（Swift / Objective-C）组件模式（嵌入形态）：新增 TencentQianWebViewComponent（UIView 子类），宿主在自定义布局中嵌入完整配置的签署 WebView，与 Android / HarmonyOS 组件模式对齐，iOS 补齐第三种集成形态（容器模式 / 组件模式 / 配置模式）：

    • 参数面：url / config / hostController（可选，缺省 responder chain 解析）/ onSignResult / onSdkEvent / onTitleChanged / onProgressChanged / onRenderUnrecoverable / controller；无 reusePrewarmPool（iOS 预热池实例永不复用到页面，与容器模式一致）
    • 感知回调：onTitleChanged（pageFinished 标题 + 可后退快照，SPA 软路由不刷新）、onProgressChanged（0~100 + 可见性门控）、onRenderUnrecoverable（连续崩溃终态，供宿主自绘错误页 + 重试）
    • 控制能力：嵌套命令对象 TencentQianWebViewComponent.Controller（TencentQianWebViewController 已被容器模式占用），canGoBack() / goBack() / handleBack() / reload() 语义与 Android / HarmonyOS 一致
    • 崩溃恢复复用容器模式内核：iOS WebContent 进程被杀后 WKWebView 实例仍有效，原地 load(URLRequest) 恢复（与鸿蒙同语义，非 Android 销毁重建）；超限放弃时触发 onRenderUnrecoverable
    • TencentQianWebViewConfigurator.Handle 新增可写属性 onRenderUnrecoverable（默认 nil），apply() 签名不变，现有调用零改动
    • release() 显式收口（幂等）：解绑 delegate + 销毁 WebView + 命令对象复位 no-op
    • Demo 新增组件模式示例页（自绘顶栏 / 进度条 / 错误覆盖层重试）
    • iOS（Objective-C）：ios-objective-c 模块 1:1 对齐（TQWebViewComponent + block typedef 回调（TQUiCallbacks.h）+ 独立 TQWebViewComponentController；显式收口命名 invalidate，同 NSTimer.invalidate；TQWebViewHandle 同步新增可写属性 onRenderUnrecoverable），Demo/ 与 DemoSwift/ 均含组件模式示例页

Changed​

  • 客户回调异常隔离（Android Kotlin / Java、HarmonyOS、iOS-OC）：客户回调（onSignResult / onSdkEvent / onTitleChanged / onProgressChanged / onRenderUnrecoverable 等）实现抛出未捕获异常时，SDK 仅记 warning 日志并继续运行，不再穿透崩溃整个进程；容器模式收尾不受影响（客户 onSignResult 抛异常时容器照常关闭，协议结果不丢）。iOS-Swift 例外：Swift 运行时错误为 runtime trap，语言层面无法被 SDK 捕获，请保证回调实现自身健壮。纯防御性增强，API 与派发语义零变化

Fixed​

  • iOS（Swift / Objective-C）URL 入口校验：修复无 scheme 输入（如 www.qq.com）裸 URL(string:) 判 nil 漏过（得到相对 URL）、加载后 WebKit 报 WebKitErrorDomain 101 (Cannot Show URL) 的问题。新增 SDK 内部统一校验（http/https scheme + 非空 host 确定性判定，不依赖 URL(string:) 的版本解析差异；OC 版为 TQSignURLValidator），非法 URL 加载前即拦截并通过 onSdkEvent 上报 loadError（errorCode = NSURLErrorBadURL）；容器模式由「静默 dismiss」改为「先上报再 dismiss」，宿主可感知
  • iOS（Swift / Objective-C）detach 后误加载：修复 detach / detachAndDestroy 后内核 delegate 仍被强持、常驻 didBecomeActive 监听残留，App 下次激活时白屏自检可能向已解绑 / 已销毁的 WebView 重新发起旧签署 URL 加载的问题；detach 现在先对内核 delegate 做幂等失效（移除监听 / 取消网络监测 / 解绑白屏自检）
  • iOS（Swift / Objective-C）容器模式崩溃终态永久白屏：修复渲染进程连续崩溃超限、SDK 放弃自动恢复后容器既不关页也不提示、用户停留永久白屏的问题；容器现在经 Handle.onRenderUnrecoverable 接终态回调自动关页，对齐 Android 容器超限 finish() / 鸿蒙容器 doClose() 语义（终态前的每次崩溃事件 webContentProcessTerminated 仍照常上报，宿主埋点不受影响）
  • 鸿蒙 onTitleChanged 标题归一化：SDK 将「空 / 等于当前页 URL / 为去 scheme 的当前页 URL 且落在 path 边界」的标题统一归一化为空串（与 Android normalizePageTitle 规则镜像一致），Page 模式顶栏 / 组件模式 onTitleChanged 统一受益，宿主 title.length > 0 ? title : 默认标题 即可稳定兜底；纯空白标题原样透传，由宿主决定是否兜底；真实标题恰为域名前缀不再被误判为无标题

Security​

  • iOS（Swift / Objective-C）下载 Cookie 同步过滤：非 https 下载链接不再携带 Secure 标记的 Cookie（对齐浏览器行为），消除 http 下载时安全 Cookie 被明文发出的风险

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 / 鸿蒙走"原地重载"（实例仍有效：iOS load(URLRequest(lastProvisionalURL))、鸿蒙 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() 改为以保存的 lastProvisionalURL 原地 load(URLRequest) 恢复（进程被杀后 webView.url 常为 nil，reload() 变 no-op 导致持久白屏）
  • 修复 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:// 协议规范、自检清单、排错决策树 + 常见问题