跳到主要内容

🚀 入门指南

在线试用 — 无需编写代码

您可以立即在**实时摄像头演示页面**体验 Web SDK 的实际效果——证件自动拍摄、面部主动活体检测、人脸验证和被动活体检测，全部在您的浏览器中运行。

iApp eKYC SDK 是一套免费开源（Apache-2.0）的客户端 SDK，面向艾艾普科技的企业级 eKYC API——泰国身份证 / 护照自动拍摄、面部主动活体检测、人脸验证和被动活体检测——支持 Flutter (Android/iOS) 和 网页 (HTML5/JavaScript)。

SDK 本身不收取任何费用。API 调用按请求通过您的 iApp API 密钥计费，费率与直接调用 API 相同——各功能的积分费用请参阅对应的功能页面。

源代码： https://github.com/iapp-technology/iapp-ekyc-sdk

SDK 为您做什么​

功能SDK 的工作内容计费 API
🪪 身份证自动拍摄检测证件边界、等待清晰稳定的画面、透视校正后提交正面 1.25 IC / 背面 0.75 IC
🛂 护照自动拍摄同一引擎，针对护照资料页 (MRZ) 调优0.75 IC
📇 官方证件自动拍摄驾驶证、银行存折、带签名的身份证复印件1.0–1.25 IC/页
🙂 面部主动活体检测设备端随机挑战动作、最佳帧选择、服务器签名判定1 IC
👥 人脸验证一次调用比较两张人脸图像0.3 IC
🛡️ 面部被动活体检测单张图像欺骗检测0.3 IC

安装​

Flutter​

在 pubspec.yaml 中将 SDK 添加为 git 依赖：

dependencies:
  iapp_ekyc_sdk:
    git:
      url: https://github.com/iapp-technology/iapp-ekyc-sdk.git
      path: flutter
import 'package:iapp_ekyc_sdk/iapp_ekyc_sdk.dart';

final client = IappEkycClient(apiKey: 'YOUR_API_KEY');

网页​

从 npm 安装：

npm install @iapp-technology/ekyc-sdk
import { IappEkyc } from '@iapp-technology/ekyc-sdk';

const ekyc = new IappEkyc({ apiKey: 'YOUR_API_KEY' });

或通过 script 标签加载 UMD 包，其会暴露 window.IappEkyc 命名空间 （类位于该命名空间内）：

<script src="https://unpkg.com/@iapp-technology/ekyc-sdk"></script>
<script>
  const ekyc = new window.IappEkyc.IappEkyc({ apiKey: 'YOUR_API_KEY' });
</script>

API 密钥设置​

请在 API 密钥管理 页面获取 API 密钥。

请勿将密钥打包进发布的客户端

任何随客户端应用一同发布的密钥都可能被提取（APK 反编译、浏览器开发者工具）。生产环境请使用 后端代理模式：将 SDK 指向您自己的后端，并将 iApp 密钥保存在服务器端。

IappEkycClient(apiKey: '', baseUrl: 'https://your-backend.example.com/ekyc')

当 apiKey 为空时，SDK 不会发送 apikey 请求头；您的代理附加真实密钥后转发到 https://api.iapp.co.th。至少请为每个应用创建专用的受限密钥，以便在密钥泄露时可以独立吊销。完整指南请参阅 GitHub 上的 SECURITY.md。

主题定制​

两个平台均内置同样专业的 浅蓝色默认主题，并支持完全自定义。各平台的令牌名称和默认值完全一致：

令牌默认值用途
primary#0284C7按钮、活动引导框、进度条
primaryDark#0C4A6E标题、提示文字
primaryLight#BAE6FD空闲引导框、浅色点缀
surface#F0F9FF面板、提示标签
onPrimary#FFFFFF主色上的文字/图标
success#22C55E四边形锁定成功、挑战通过
warning#F59E0B请保持不动 / 画面过于模糊
error#EF4444失败状态
overlayScrim#0C4A6E，60% 不透明度引导框外的摄像头遮罩
brandDeep#113F7B可选的 iApp 品牌点缀色
borderRadius16标签、按钮、结果卡片
guideStrokeWidth3引导框线宽
fontFamily平台默认可选覆盖

Flutter — EkycTheme 是一个普通的不可变类（不依赖 Theme.of）：

const theme = EkycTheme.lightBlue;             // 默认主题
final custom = EkycTheme.lightBlue.copyWith(
  primary: Color(0xFF113F7B),
  borderRadius: 12,
);
DocumentCaptureView.start(context, theme: custom, ...);

网页 — 令牌以 CSS 自定义属性的形式注入到挂载元素上：

new IappEkyc({ apiKey, theme: { primary: '#113F7B', borderRadius: 12 } });
/* 或者直接用 CSS 覆盖 */
#ekyc-mount { --iapp-ekyc-primary: #113f7b; --iapp-ekyc-border-radius: 12px; }

更多详情：GitHub 上的 THEMING.md。

多语言支持​

所有 UI 文字均内置 英语、泰语和中文：

// Flutter
DocumentCaptureView.start(context, client: client,
  documentType: DocumentType.thaiIdFront, locale: EkycLocale.th);
// 网页: 'en' | 'th' | 'zh'
await ekyc.captureDocument({ mount, documentType: 'thaiIdFront', locale: 'th' });

平台要求​

Flutter​

  • Flutter ≥ 3.32 / Dart ≥ 3.8
  • Android：minSdk 24
  • iOS：15.5 及以上，并需在 Info.plist 中添加 NSCameraUsageDescription 条目（所需权限说明文字请参考仓库中的 flutter/example 示例应用）

网页​

  • 支持 WebAssembly 和 getUserMedia 的现代浏览器
  • 必须使用 HTTPS（或 localhost）——浏览器会在不安全的源上阻止摄像头访问
  • OpenCV/MediaPipe 资源仅在拍摄流程启动时才按需加载；如果您的 CSP 禁止 CDN 请求，可通过 assetBaseUrl 选项自行托管这些资源

后续步骤​