> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# 原生移动端 KYC SDK：iOS、Android、React Native、Flutter

> Didit 提供适用于 iOS、Android、React Native 和 Flutter 的原生 KYC SDK，支持 NFC 电子护照、活体检测和设备端采集。完整 KYC 检测每次 $0.33 起，每月 $10 免费额度。

> [!NOTE]
>
> 这些版本适用于身份验证 SDK。原生身份验证模块和封装库有单独的发布版本，请参阅 [身份验证快速入门](https://docs.didit.me/zh/authentication/overview.md)。

通过我们官方的 SDK，将 Didit 身份验证原生集成到您的移动应用中。与基于 WebView 的集成相比，原生 SDK 可提供**无缝的用户体验**、**更好的性能**以及**对设备功能的完整访问权限**。

> [!NOTE]
>
> ### **推荐方式**: 为获得最佳用户体验，请使用我们的原生 SDK，而不是 WebView 集成。原生 SDK 开箱即用，可处理相机权限、NFC 读取和活体检测的全部复杂性。

***

## SDK 可用性

| 平台 | 分发方式 | 最新版本 | NFC | 最低版本 | 文档 |
| - | - | - | :-: | - | - |
| iOS | Swift Package Manager、CocoaPods | 4.13.2 | ✅（iOS 15+） | iOS 13.0+（核心功能）、iOS 15.0+（NFC） | [iOS SDK 指南](https://docs.didit.me/zh/integration/native-sdks/ios-sdk.md) |
| Android | Maven（自定义仓库，`me.didit:didit-sdk`） | 4.13.2 | ✅ | API 23+（Android 6.0） | [Android SDK 指南](https://docs.didit.me/zh/integration/native-sdks/android-sdk.md) |
| React Native | npm / yarn（`@didit-protocol/sdk-react-native`） | 4.13.2 | ✅ | RN 0.76+（新架构）、iOS 13.0+ / Android API 24+ | [React Native SDK 指南](https://docs.didit.me/zh/integration/native-sdks/react-native-sdk.md) |
| Flutter | pub.dev（`didit_sdk`） | 4.13.2 | ✅ | Flutter 3.3+、Dart 3.11+、iOS 13.0+ / Android API 23+ | [Flutter SDK 指南](https://docs.didit.me/zh/integration/native-sdks/flutter-sdk.md) |
| Web（JS） | npm（`@didit-protocol/sdk-web`） | 0.4.0 | — | 任何现代浏览器 | [Web SDK 指南](https://docs.didit.me/zh/integration/web-sdks/javascript-sdk.md) |

> [!NOTE]
>
> **生物识别同意需要原生 SDK 4.10.0 或更高版本。** 对于受伊利诺伊州、德克萨斯州或科罗拉多州法律覆盖的人员，Didit 可以在首次人脸采集之前请求其明确的[生物识别同意](https://docs.didit.me/zh/getting-started/biometric-consent.md)。托管流程（Web SDK、WebView、浏览器）以及 4.10.0 或更高版本的原生 iOS 和 Android SDK 会显示该步骤；React Native 和 Flutter 则在固定使用原生 4.10.0 或更高版本的发布版本中显示该步骤。低于 4.10.0 的原生 SDK，或无法报告其版本的原生 SDK，无法显示该步骤：其会话照常运行，决策中会报告 `biometric_consent.status: "pending"` 与 `reason: "BIOMETRIC_CONSENT_UNSUPPORTED_SDK"`。如果您核验的人员属于这些情况，请升级。

### 4.13.2 版本新增内容

在 iOS 上，如果相机已打开但未输出任何画面，请求拍照时不再导致应用崩溃：每次拍照请求都会先检查是否存在带有活动视频连接的正在运行的相机会话，并改为在屏幕上显示相机错误或跳过提示。
在 Android 上，在 ID 查询自拍步骤中，如果相机未输出任何画面，拍照请求会在 5 秒后以该屏幕的相机错误结束，而不再无限等待。
在欢迎屏幕上，当步骤列表在底部渐隐区域下方仍有内容时，会出现一个圆形的“向下滚动”按钮，在列表上水平居中（从右到左的语言同样如此），与网页流程一致；点击后列表向下滚动，列表到底部以及弹出面板打开时，该按钮隐藏。
Android 4.13.1 是仅包含“向下滚动”按钮的过渡版本；4.13.2 将该功能引入 iOS、React Native 和 Flutter。
React Native 4.13.2 还修复了使用 R8 和 `proguard-android-optimize.txt` 进行混淆压缩的 Android 发布版本启动时崩溃的问题：该包现在自带其 R8 规则。
Flutter 4.13.2 还支持使用 Android Gradle Plugin 9 及其内置 Kotlin 进行构建。

### 4.13.0 版本新增内容

在手机步骤中，每个 +1（美国和加拿大）号码都会在“发送验证码”下方显示一条简短的运营商说明（“可能会收取标准短信和数据费用”），并附有短信条款和隐私政策的链接，内容使用该用户的语言。
自拍椭圆框现在会在较矮的屏幕上完整显示在其控件上方；绿色的“完成”标签、拍摄证件照后的“知道了”，以及“已拍摄自拍”屏幕均已移除：拍好的照片会直接进入“处理中”。
当证件拍摄只是备用方式、数字身份钱包优先时，钱包的启动屏幕只提供钱包选项；钱包重试会保持验证处于打开状态，且不提供证件链接。
为 Didit 可以发送的每个国家区号绘制对应的国旗，且绝不显示错误的国旗。
在已开始的会话上启用沙盒场景时，现在会显示具体原因，而不是通用错误。
在 Android 上，Credential Manager 钱包显示为“使用数字身份验证”，因为 Google Wallet 或其他持有兼容身份证件的 Android 钱包都可以响应该方式。iOS 不提供此方式。

### 4.12.2 版本新增内容

欢迎屏幕将标志居中置于左对齐标题上方，iOS 上客户标志的高度为 72 pt，与 Android 和网页一致。
在 KYB 关键人员步骤中，“添加代表”会在选中代表角色的情况下打开，即使工作流关闭了某些角色，保存的人员也会归入代表人员类别。
在问卷中，“由……提供安全保障”在较矮的屏幕和大字号下会固定在按钮下方；地址问题的国家选择器标题会针对地址显示；展开的下拉菜单采用字段的圆角。

### 4.12.1 版本新增内容

在存储空间已满的 iPhone 上，证件和自拍照的拍摄现在会保留视频：iOS SDK 会在内存中录制这些拍摄内容，且绝不会上传不含视频帧的录制内容。
在 iOS 和 Android 上，如果服务器的应答晚于提前给出的应答，将不再重新打开刚刚完成的步骤（NFC、自拍或证件步骤）。

### 4.12.0 版本新增内容

为网页流程显示的每一个数字身份钱包提供钱包标志（Mobile-ID、ConnectID、Finnish Trust Network、OneID、Bank iD、MojeID、FranceConnect、Auðkenni、爱沙尼亚身份证以及 GOV.UK Wallet），与网页使用相同的白色或黑色底板。
拍摄提示会说明自动拍摄未运行时该怎么做；欢迎屏幕在大字号下会固定显示其法律声明；被拒绝的会话启动不再提供无法成功的重试选项。
证件和自拍相机在快门旁新增“切换相机”按钮，“上传”移至“提示”中；弹出面板覆盖相机时，不会自动拍摄任何内容。
在 Android 上，“选择相机”面板在所有语言中都将相机命名为“前置相机”和“后置相机”。

### 4.11.0 版本新增内容

4.11.0 版本还包含原计划在 4.10.0 中发布、但从未公开发布的全部内容，因此请直接从 4.9.1 升级。
流程采用全新的界面框架，包括新的顶部栏、文字形式的进度显示以及重新设计的欢迎屏幕。
自动证件和自拍拍摄现在已覆盖所有变体，采用 Didit 自有的轻量级检测器，因此 `Core` 和 `AutoDetection` 变体的拍摄方式相同。
`AutoDetection` 变体以及 Android 的 `didit-sdk-autodetection` 构件已被弃用，与 `Core` 完全相同；Android 的 `didit-sdk-autodetection-play` 构件不再发布。
新增步骤：银行验证、位置（通过 `Core-Location`、`NFC-Location` 和 `All-Location` iOS 变体选择加入）、电子签名以及生物识别同意。

### 4.9.1 更新内容

在 iOS 和 Android 上，证件和地址证明的国家选择器现在会默认显示根据用户 IP 地址检测到的国家，即使该检测在页面显示后才完成。
会话中已设置的国家或用户已选择的国家从不会被覆盖。
在 Android 上，问卷的章节标题和字段会以 SDK 语言显示，完整版本中的 NFC 护照扫描也不再崩溃。
两个平台上的俄语和吉尔吉斯语验证文案均已改进。

### 4.9.0 更新内容

所有原生及跨平台移动端 SDK 现在都在验证欢迎页面上提供可选开启的语言选择器。
将 `showLanguageSelector` 设置为 `true`，即可显示与网页验证流程相同的紧凑型可搜索选择器。
该选择器默认隐藏，因此现有集成会保持当前行为，直到您主动启用它。

> [!NOTE]
>
> ### **替代方案**：如果您的平台暂不支持原生 SDK，可以使用 [WebView 集成](https://docs.didit.me/zh/integration/web-sdks/webview-in-ios-android.md) 作为备选方案。

***

## 验证会话的流程

每个原生 SDK 都使用同一个 Didit 验证会话。流程如下：

1. **你的后端**调用 [`POST /v3/session/`](https://docs.didit.me/zh/sessions-api/create-session)，传入 `workflow_id` 以及可选的上下文信息（`vendor_data`、`contact_details`、`expected_details`、`metadata`、`callback`）。
2. Didit 返回 `session_id`、有效期较短的 `session_token` 以及托管的 `url`。
3. **你的移动应用**从你的后端接收 `session_token`，并将其传递给 SDK（`startVerification(token: …)`）。
4. 原生 SDK 打开验证界面，用户完成各个步骤，随后 SDK 返回包含会话最终 `status` 的结果（`Approved`、`Declined`、`In Review` 等）。
5. **你的后端**通过 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)（`webhook_type: "status.updated"`）接收完整决策结果，并将其持久化保存。

> [!NOTE]
>
> SDK 结果告诉你工作流的结果（状态）。完整决策（证件字段、人脸比对分数、AML 命中结果、NFC 数据、警告）通过 Webhook 发送到你的服务器，也可以通过[获取会话决策 endpoint](https://docs.didit.me/zh/sessions-api/retrieve-session.md)获取。切勿仅依赖客户端的结果来做授权决策。

所有原生 SDK 还支持 **UniLink** 模式（仅需工作流 ID，无需后端）。快速原型请使用 UniLink，生产环境请使用会话 token 方式。

***

## iOS SDK

**适用场景**：面向 iOS 13+ 的原生 Swift / SwiftUI / UIKit 应用。

轻量级、服务端驱动的 iOS SDK，用于身份验证，所需配置极少。

> [card] [GitHub 仓库](https://github.com/didit-protocol/sdk-ios)
>
> 在 GitHub 上查看源代码和示例

**主要功能：**

* 支持 SwiftUI 和 UIKit
* NFC 护照/证件读取（iOS 15+；无 NFC 的 `Core` 和 `AutoDetection` 变体会移除 NFC 和 OpenSSL，并可部署到 iOS 13+）
* 支持 54 种语言
* 可自定义 UI 主题
* 支持会话 token 或工作流 ID 集成

**快速开始：**

```swift theme={null}
import DiditSDK

// Start verification
DiditSdk.shared.startVerification(token: "your-session-token")

// Handle result
.diditVerification { result in
    switch result {
    case .completed(let session):
        print("Status: \(session.status)")
    case .cancelled:
        print("Cancelled")
    case .failed(let error, _):
        print("Error: \(error)")
    }
}
```

→ [**iOS SDK 完整文档**](https://docs.didit.me/zh/integration/native-sdks/ios-sdk.md)

***

## Android SDK

**适用场景**：面向 Android 6.0（API 23）或更高版本的原生 Kotlin / Jetpack Compose / Java 应用。

轻量级、服务端驱动的 Android SDK，用于身份验证，所需配置极少。

> [card] [GitHub 仓库](https://github.com/didit-protocol/sdk-android)
>
> 在 GitHub 上查看源代码和示例

**主要功能：**

* 支持 Kotlin 和 Jetpack Compose
* NFC 护照/证件读取（可选的 `me.didit:didit-sdk-core` 构件会移除 NFC 依赖）
* API 24+ 上基于机器学习的证件和人脸自动检测（API 23 上会优雅降级为手动拍摄）
* 支持 54 种语言
* 可自定义 UI 主题
* 支持会话 token 或工作流 ID 集成

**快速开始：**

```kotlin theme={null}
import me.didit.sdk.DiditSdk
import me.didit.sdk.VerificationResult

// Initialize in Application.onCreate()
DiditSdk.initialize(this)

// Start verification
DiditSdk.startVerification(token = "your-session-token") { result ->
    when (result) {
        is VerificationResult.Completed -> Log.d("Didit", "Status: ${result.session.status}")
        is VerificationResult.Cancelled -> Log.d("Didit", "Cancelled")
        is VerificationResult.Failed -> Log.e("Didit", "Error: ${result.error.message}")
    }
}
```

→ [**Android SDK 完整文档**](https://docs.didit.me/zh/integration/native-sdks/android-sdk.md)

***

## React Native SDK

**适用场景**：需要在 iOS 和 Android 上使用统一 TypeScript API 的跨平台 React Native 或 Expo 应用（RN 0.76+，新架构）。

跨平台 React Native SDK，通过统一的 TypeScript API 封装原生 iOS 和 Android SDK。

> [card] [GitHub 仓库](https://github.com/didit-protocol/sdk-react-native)
>
> 在 GitHub 上查看源代码和示例

**主要功能：**

* iOS 和 Android 统一的 TypeScript API
* 支持 Expo，提供零配置插件（需要开发构建，不支持 Expo Go）
* 支持 React Native CLI
* NFC 护照/证件读取（可通过 `DIDIT_SDK_IOS_NFC_ENABLED=false` / `diditSdkAndroidNfcEnabled=false` 关闭）
* 支持 54 种语言（继承自原生 SDK）
* 支持会话 token 或工作流 ID 集成

**快速开始：**

```tsx theme={null}
import { startVerification, VerificationStatus } from '@didit-protocol/sdk-react-native';

const result = await startVerification('your-session-token');

switch (result.type) {
  case 'completed':
    console.log('Status:', result.session.status);
    break;
  case 'cancelled':
    console.log('Cancelled');
    break;
  case 'failed':
    console.log('Error:', result.error.message);
    break;
}
```

→ [**React Native SDK 完整文档**](https://docs.didit.me/zh/integration/native-sdks/react-native-sdk.md)

***

## Flutter SDK

**适用场景**：需要在 iOS 和 Android 上使用统一 Dart API 的跨平台 Flutter 应用（Flutter 3.3+，Dart 3.11+）。

跨平台 Flutter SDK，通过统一的 Dart API 封装原生 iOS 和 Android SDK。

> [card] [pub.dev 包](https://pub.dev/packages/didit_sdk)
>
> 在 pub.dev 上查看包

**主要功能：**

* iOS 和 Android 统一的 Dart API
* 通过平台通道与原生 SDK 集成
* NFC 护照/证件读取（可通过 `DIDIT_SDK_IOS_NFC_ENABLED=false` / `diditSdkAndroidNfcEnabled=false` 关闭）
* 支持 54 种语言（继承自原生 SDK）
* 支持会话 token 或工作流 ID 集成

**快速开始：**

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

final result = await DiditSdk.startVerification('your-session-token');

switch (result) {
  case VerificationCompleted(:final session):
    print('Status: ${session.status}');
  case VerificationCancelled():
    print('Cancelled');
  case VerificationFailed(:final error):
    print('Error: ${error.message}');
}
```

→ [**Flutter SDK 完整文档**](https://docs.didit.me/zh/integration/native-sdks/flutter-sdk.md)

***

## Web SDK (JavaScript)

**适用场景**：基于浏览器的应用和 Web 框架（React、Vue、Angular、Next.js、Nuxt、Svelte、原生 JS）。Web SDK 在弹窗或内嵌 iframe 中打开托管的验证流程；移动应用请优先使用上述原生 SDK。

面向 Web 应用的 JavaScript SDK，支持 React、Vue、Angular、Next.js、Nuxt、Svelte 和原生 JS。

> [card] [NPM 包](https://www.npmjs.com/package/@didit-protocol/sdk-web)
>
> 在 npm 上查看包

**主要功能：**

* 编程式会话管理和事件回调
* 支持 React、Vue、Angular、Next.js、Nuxt、Svelte 和原生 JS
* 完整的 TypeScript 支持
* 弹窗和内嵌（嵌入式）模式
* 面向自定义 UI 的状态管理

**快速开始：**

```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('Cancelled');
      break;
    case 'failed':
      console.error('Error:', result.error?.message);
      break;
  }
};

DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/session-token'
});
```

→ [**JavaScript SDK 完整文档**](https://docs.didit.me/zh/integration/web-sdks/javascript-sdk.md) | [**所有 Web SDK**](https://docs.didit.me/zh/integration/web-sdks/overview.md)

***

## 选择集成方式

原生 SDK 最适合需要读取 NFC 电子护照、要求最低延迟的摄像头采集，并且希望应用内体验与其他原生页面保持一致的场景。当您无法发布原生 SDK 更新时（例如无法重新构建的存量应用，或没有 Didit 原生 SDK 的平台），可以使用 **WebView 集成**作为备用方案。

| 功能 | 原生 SDK | WebView |
| - | :-: | :-: |
| 用户体验 | 原生界面，完整支持手势操作 | 在系统浏览器或 WebView 中运行的托管 Web 流程 |
| 摄像头采集 | 设备端采集，SDK 针对证件和自拍照做了优化 | 取决于浏览器 |
| NFC 电子护照读取 | ✅ 支持（iOS 15+，支持 NFC 的 Android 设备） | ❌ 不可用 |
| 活体检测性能 | 原生机器学习流程 | 浏览器端机器学习流程 |
| 白标主题定制 | ✅ 通过控制台配置 | ✅ 通过控制台配置 |
| App Store / Play Store 审核影响 | 增加 NFC 权限配置和安装包体积 | 无，只需打开一个 URL |
| 适用场景 | 正式上线的应用、NFC 流程、最佳用户体验 | 快速集成、仅 Web 技术栈、备用方案 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.