跳到主要内容

📲 iOS、Android 与 React Native

eKYC SDK 提供 原生封装包,支持 iOS(Swift / Objective-C)、Android(Kotlin / Java)与 React Native。每个封装包展示一个全屏 WebView,通过托管的桥接页面运行与 Web SDK 完全相同的生产级引擎——证件自动拍摄与人脸主动活体检测在各平台表现一致,引擎改进无需发版即可触达您的应用,且几乎不增加安装包体积。

所有封装包提供相同的三种摄像头流程:

流程功能API 计费
documentCapture自动拍摄证件并提交 OCR 识别(身份证、护照、其他官方证件)0.75–1.25 IC
activeLiveness人脸主动活体检测指令挑战 + 服务器签名判定1 IC
faceCapture自动拍摄清晰正面自拍(无指令挑战),用于人脸比对 / 静默活体检测免费(仅拍摄)

要求:运行时需访问 https://iapp.co.th/sdk/webview.html(eKYC 调用 API 本身即需联网),并需要摄像头。

iOS(Swift / Objective-C)​

安装: 在 Xcode 中选择 File → Add Package Dependencies… → https://github.com/iapp-technology/iapp-ekyc-sdk → 产品 IappEkyc。要求 iOS 15 及以上,并在 Info.plist 中添加 NSCameraUsageDescription。

import IappEkyc

let config = IappEkycConfig(apiKey: "YOUR_API_KEY", flow: .documentCapture)
config.documentType = .thaiIdFront   // .thaiIdBack .passport .thaiDriverLicense .bookBank .thaiIdWithSignature
config.locale = .zh                  // .en / .th / .zh

IappEkycSdk.present(from: self, config: config) { result in
    switch result {
    case .success(let outcome):
        print(outcome.document?.rawJSON ?? [:])          // 完整 OCR 响应
    case .failure(let error as NSError)
    where error.code == IappEkycErrorCode.cancelled.rawValue:
        break                                            // 用户取消
    case .failure(let error):
        print(error.localizedDescription)                // error.code: IappEkycErrorCode
    }
}

主动活体检测返回服务器签名判定:

let config = IappEkycConfig(apiKey: "YOUR_API_KEY", flow: .activeLiveness)
IappEkycSdk.present(from: self, config: config) { result in
    if case .success(let outcome) = result, let liveness = outcome.liveness {
        // 请务必在您的服务器端验证 verdictJSON + signature——
        // 切勿仅信任设备端的 `passed` 值。
        upload(liveness.verdictJSON, liveness.signature, liveness.selfieImageData)
    }
}

Objective-C 通过 delegate 使用同一套类:

@import IappEkyc;

IappEkycConfig *config = [[IappEkycConfig alloc] initWithApiKey:@"YOUR_API_KEY"
                                                           flow:IappEkycFlowTypeDocumentCapture];
config.documentType = IappEkycDocumentTypeThaiIdFront;
[IappEkycSdk presentFrom:self config:config delegate:self];
// 实现 IappEkycViewControllerDelegate: didFinishWithResult / didFailWithError / didCancel

Android(Kotlin / Java)​

通过 JitPack 安装 — minSdk 24,需最新版 Android System WebView:

// settings.gradle.kts
dependencyResolutionManagement {
    repositories { google(); mavenCentral(); maven("https://jitpack.io") }
}
// app/build.gradle.kts
dependencies { implementation("com.github.iapp-technology:iapp-ekyc-sdk:v0.2.0") }

库已自行声明 CAMERA 权限并在运行时自动请求。

val config = IappEkycConfig.Builder("YOUR_API_KEY").locale(EkycLocale.ZH).build()

private val ekyc = registerForActivityResult(IappEkycContract()) { result ->
    when (result) {
        is IappEkycResult.DocumentCaptured -> handleOcr(result.rawJson)
        is IappEkycResult.LivenessPassed ->
            // 在您的服务器端验证 verdictJson + signature。
            upload(result.verdictJson, result.signature, result.selfieImage)
        is IappEkycResult.FaceCaptured -> useSelfie(result.image)
        is IappEkycResult.Failed -> show(result.error)   // error.code: EkycErrorCode
        IappEkycResult.Cancelled -> {}
    }
}

// 启动任意流程:
ekyc.launch(IappEkycRequest.DocumentCapture(config, EkycDocumentType.THAI_ID_FRONT))
ekyc.launch(IappEkycRequest.ActiveLiveness(config))
ekyc.launch(IappEkycRequest.FaceCapture(config))

通过回调 API 完整支持 Java:

IappEkyc.start(this,
        new IappEkycRequest.DocumentCapture(config, EkycDocumentType.THAI_ID_FRONT),
        new IappEkycCallback() {
            @Override public void onResult(IappEkycResult result) { /* ... */ }
            @Override public void onError(IappEkycError error) { /* ... */ }
            @Override public void onCancelled() { }
        });

React Native​

安装(npm 发布准备中——请从源码安装),需 react-native-webview 对等依赖:

git clone https://github.com/iapp-technology/iapp-ekyc-sdk
npm install ./iapp-ekyc-sdk/react-native react-native-webview
cd ios && pod install

iOS:添加 NSCameraUsageDescription。Android:添加 CAMERA 权限并在挂载流程之前请求。

import { useState } from 'react';
import { Button, Modal, PermissionsAndroid, Platform } from 'react-native';
import { IappEkycFlow } from '@iapp-technology/react-native-ekyc-sdk';

function KycScreen() {
  const [active, setActive] = useState(false);

  const start = async () => {
    if (Platform.OS === 'android') {
      const granted = await PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.CAMERA);
      if (granted !== PermissionsAndroid.RESULTS.GRANTED) return;
    }
    setActive(true);
  };

  return (
    <>
      <Button title="拍摄身份证" onPress={start} />
      <Modal visible={active} animationType="slide" presentationStyle="fullScreen">
        <IappEkycFlow
          flow="documentCapture"        // 'documentCapture' | 'activeLiveness' | 'faceCapture'
          documentType="thaiIdFront"
          apiKey="YOUR_API_KEY"
          locale="zh"
          onResult={(result) => { setActive(false); console.log(result); }}
          onError={(error) => setActive(false)}     // error.code,例如 'INSUFFICIENT_CREDIT'
          onCancel={() => setActive(false)}
        />
      </Modal>
    </>
  );
}

各平台共享行为​

  • API 密钥安全 — 传入 apiKey: "" 并将 baseUrl 指向您的后端即可将密钥保留在服务器端(代理模式)。密钥在页面加载后才注入桥接页面,绝不经过 URL。详见 GitHub 上的 SECURITY.md。
  • 主题与语言 — 与 Web SDK 相同的主题令牌与 en/th/zh 语言,通过各平台的 config 对象传入。
  • 判定结果 — 主动活体检测结果仅以服务器签名判定为准:在您的服务器端重新计算 HMAC 后再信任 passed。参见人脸主动活体检测。
  • 取消 — 流程内取消按钮、Android 返回键与 iOS 下滑关闭均以取消结果返回;关闭/卸载流程会干净地停止摄像头并中止流程。
  • 桥接协议 — 封装包与引擎之间的完整协议见 GitHub 上的 WEBVIEW_BRIDGE.md。