# Tencent Qian H5 容器 SDK

> 在原生 / Hybrid App 中嵌入腾讯电子签 H5（合同签署 + 人脸核身）的 WebView 容器 + `qianapp://` 协议拦截 SDK。
> 已封装人脸核身权限、文件选择器、Scheme 拦截、Cookie / DOM Storage 持久化、文件下载等三端兼容性细节，最少 10 行代码即可接入。

---

## 1. 场景决策树

```mermaid
flowchart TD
    Start[客户场景] --> Q1{客户 App 类型?}

    Q1 -- 原生 / Hybrid App --> THIS[✅ 本 SDK 直接接入]
    Q1 -- 纯 Web 页面 --> H5_DIRECT[直接打开电子签 H5,不需要本仓库]
    Q1 -- UniApp / Hybrid 混合栈 --> UNI[UniApp web-view 接入,见 docs/qianuni-uniapp-guide.md]

    THIS --> S1{客户技术栈?}
    S1 -- Kotlin / Java --> KS[android-kotlin / android-java]
    S1 -- Swift / Objective-C --> IO[ios-swift / ios-objective-c]
    S1 -- ArkTS --> HA[harmonyos-arkts]

    KS --> S2{是「全新页面」还是「改造已有 WebView」?}
    IO --> S2
    HA --> S2
    S2 -- 全新页面,1 行调用 --> CONT[容器模式 TencentQianWebView.open]
    S2 -- 嵌入自有布局,自绘顶栏/进度条 --> COMP[组件模式 TencentQianWebViewComponent]
    S2 -- 已有自有 WebView 容器 --> CFG[配置模式 TencentQianWebViewConfigurator.apply]
```

## 2. 兼容矩阵

| 平台 | 语言 | 系统下限 | 内核 |
|---|---|---|---|
| Android | Kotlin / Java | Android 7.0（API 24） | 系统 WebView（WebKit），不支持 X5 / TBS |
| iOS | Swift / Objective-C | iOS 14.3 | WKWebView |
| HarmonyOS NEXT | ArkTS | API 12+（HarmonyOS NEXT 5.0+） | ArkWeb |

## 3. 集成方式

| 平台 | 推荐方式 | 说明 |
|------|---------|------|
| Android | **源码集成**（推荐） | `webview-container` 模块以 `project()` 依赖引入，源码与客户代码同编译单元，无需混淆配置 |
| HarmonyOS | **源码集成**（推荐） | `tencentqianwebview` 模块以 `file:` 依赖引入，源码与客户代码同编译单元 |
| iOS | **SPM 本地包**（推荐）> xcframework（备选）> 源文件直拖（兜底） | `File → Add Packages → Add Local…` 引入，Xcode 自动编译、自动处理架构 |

> Android / HarmonyOS 推荐源码集成，SDK 源码与客户代码在同一编译单元内一起编译，所有符号引用天然一致，无需构建产物分发。
>
> iOS 两个版本可选：`ios-swift/`（Swift，模块名 `TencentQianWebViewSDK`，仅支持 Swift 消费）或 `ios-objective-c/`（纯 OC，模块名 `TencentQianWebView`，与 Swift 版功能 1:1 对齐，支持 OC + Swift 消费）。

详见 [docs/integration-checklist.md](./docs/integration-checklist.md)。

## 4. Demo 预览

> 图为三端 Demo App 预览，依次展示**主页**（WebView 预热池、三种集成方式入口、兼容性自检入口）、**容器模式**（`TencentQianWebView.open` 一键唤起）与**自检页**（H5 兼容性自检）。

**Android（Kotlin / Java）**

<img src="./docs/images/android-demo.png" width="800" alt="Android Demo 预览"><br>

**iOS（Swift / Objective-C）**

<img src="./docs/images/ios-demo.png" width="800" alt="iOS Demo 预览"><br>

**HarmonyOS（ArkTS）**

<img src="./docs/images/harmony-demo.png" width="800" alt="HarmonyOS Demo 预览">

## 5. Quick Start

### 5.1 Android（Kotlin）

**集成**：将 `android-kotlin/webview-container/` 模块复制到客户工程，在 `settings.gradle` 中引入：

```groovy
include ':webview-container'
project(':webview-container').projectDir = new File('../webview-container')
```

在 App 模块的 `build.gradle` 中添加依赖：

```groovy
dependencies {
    implementation project(':webview-container')
}
```

最小集成代码：

```kotlin
TencentQianWebView.open(
    activity = this,
    url = signUrl,
    config = TencentQianWebViewConfig(topBarTitle = "电子签署"),
    callback = object : SignCallback {
        override fun onSignResult(result: SignResult) {
            // result.action / result.result / result.flowId / result.extras
        }
    }
)
```

运行 Demo：

```bash
cd android-kotlin
cp local.properties.template local.properties  # 填入本机 Android SDK 路径
./gradlew :app:installDebug
```

或直接在 Android Studio 打开 `android-kotlin/` 目录，选 `app` scheme 跑模拟器 / 真机。

### 5.2 iOS（Swift）

**集成**：Xcode → `File → Add Packages → Add Local…` → 选择 `ios-swift/` 目录 → 勾选 `TencentQianWebViewSDK` → Add Package。

最小集成代码：

```swift
import TencentQianWebViewSDK

TencentQianWebView.open(
    from: self,
    url: signUrl,
    config: TencentQianWebViewConfig(topBarTitle: "电子签署"),
    callbacks: SignCallbacks(onSignResult: { result in
        // result.action / result.result / result.flowId / result.extras
    })
)
```

运行 Demo：

```bash
brew install xcodegen
cd ios-swift
xcodegen generate
open Demo.xcodeproj
```

选 `Demo` scheme，⌘+R 跑模拟器 / 真机。

### 5.3 iOS（Objective-C）

**集成**：Xcode → `File → Add Packages → Add Local…` → 选择 `ios-objective-c/` 目录 → 勾选 `TencentQianWebView` → Add Package。

最小集成代码：

```objc
@import TencentQianWebView;

TQWebViewConfig *config = [TQWebViewConfig defaultConfig];
config.topBarTitle = @"电子签署";
[TQWebView openFromPresenter:self
                          url:signUrl
                       config:config
                    callbacks:[TQSignCallbacks callbacksWithOnSignResult:^(TQSignResult *result) {
                        // result.action / result.result / result.flowId / result.extras
                    } onEvent:nil]
                     animated:YES
                   completion:nil];
```

运行 Demo：

```bash
brew install xcodegen
cd ios-objective-c
xcodegen generate
open Demo.xcodeproj
```

选 `Demo` scheme，⌘+R 跑模拟器 / 真机。

### 5.4 HarmonyOS（ArkTS）

**集成**：将 `harmonyos-arkts/tencentqianwebview/` 模块复制到客户工程同级目录，在 Entry 模块的 `oh-package.json5` 中添加：

```json5
{
  "dependencies": {
    "tencentqianwebview": "file:../tencentqianwebview"
  }
}
```

最小集成代码：

```typescript
import {
  TencentQianWebView,
  TencentQianWebViewConfig,
  SignResult,
} from 'tencentqianwebview';

TencentQianWebView.open(
  context,                                  // UIAbilityContext
  signUrl,
  new TencentQianWebViewConfig(),
  (result: SignResult) => {
    // result.action / result.result / result.flowId / result.extras
  },
);
```

运行 Demo：用 DevEco Studio 打开 `harmonyos-arkts/` 目录，选 `entry` 模块运行到 HarmonyOS NEXT 设备 / 模拟器。

## 6. 目录结构

```
h5-in-app-integration/
├── android-kotlin/             Android Kotlin SDK + Demo
│   ├── webview-container/      SDK Library（源码集成用此模块）
│   └── app/                    Demo Application
├── android-java/               Android Java SDK + Demo
│   ├── webview-container/      SDK Library（源码集成用此模块）
│   └── app/                    Demo Application
├── ios-swift/                  iOS Swift SDK + Demo
│   ├── TencentQianWebView/     SDK 源码（含 Package.swift，SPM 集成用此目录）
│   ├── Demo/                   Demo App
│   └── project.yml             XcodeGen 工程定义
├── ios-objective-c/            iOS Objective-C SDK + Demo（与 Swift 版 1:1 对齐，支持 OC + Swift 消费）
│   ├── TencentQianWebView/     SDK 源码（含 Package.swift，SPM 集成用此目录）
│   ├── Demo/                   Demo App（OC 消费 OC SDK）
│   ├── DemoSwift/              Demo App（Swift 消费 OC SDK，无需 bridging header）
│   └── project.yml             XcodeGen 工程定义
├── harmonyos-arkts/            HarmonyOS ArkTS SDK + Demo
│   ├── tencentqianwebview/     SDK 模块（源码集成用此模块）
│   └── entry/                  Demo 模块（HAP）
├── docs/                       接入指南、协议规范、自检清单、常见问题
├── scripts/                    构建与测试脚本
└── README.md                   本文件
```

## 7. 文档导航

| 文档 | 内容 | 适合谁 |
|---|---|---|
| [docs/usage-guide.md](./docs/usage-guide.md) | 接入指南（容器模式 / 组件模式 / 配置模式 / 自行适配） | 所有客户 |
| [docs/qianapp-protocol.md](./docs/qianapp-protocol.md) | `qianapp://` 协议规范，跨端唯一权威 | 需要理解回调格式的客户 |
| [docs/integration-checklist.md](./docs/integration-checklist.md) | 三端接入自检清单 | 所有客户 |
| [docs/troubleshooting.md](./docs/troubleshooting.md) | 排错决策树 + FAQ | 遇到问题时的客户 |
| [docs/qianuni-uniapp-guide.md](./docs/qianuni-uniapp-guide.md) | UniApp web-view 接入指南 | UniApp 客户 |

## 8. 构建与打包

仓库根 `scripts/` 提供命令行构建脚本：

```bash
# Android（源码集成，构建产物仅供验证）
bash scripts/build-android-kotlin.sh sdk          # Kotlin AAR
bash scripts/build-android-java.sh sdk            # Java AAR

# iOS xcframework（用于 xcframework 集成方式，device + simulator 双 slice）
bash scripts/build-ios-swift.sh xcframework       # Swift 版 .xcframework
bash scripts/build-ios-objectivec.sh xcframework  # OC 版 .xcframework

# HarmonyOS（源码集成，构建产物仅供验证）
bash scripts/build-harmony.sh sdk                 # HAR

# iOS SPM + xcframework 集成验证（6 种组合 × simulator + device）
bash scripts/verify-ios-integration.sh all
```

> Android / HarmonyOS 推荐源码集成，无需构建产物分发，`sdk` 子命令仅供开发验证。
> iOS 推荐 SPM 本地包（零构建），`xcframework` 适合不想拿源码的客户。

各脚本详情见 `--help`。
