# @didit-protocol/sdk-react-native 中文文档

规范地址：https://npmcn.com/package/%40didit-protocol/sdk-react-native/

版本：4\.14\.7
npm 元数据更新时间：2026-11-11T13:42:31.105Z
中文译文更新时间：2026-11-12T07:33:10.801Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40didit-protocol/sdk-react-native
原文对照：https://npmcn.com/package/%40didit-protocol/sdk-react-native/?lang=original
项目主页：https://github.com/didit-protocol/sdk-react-native#readme
源码仓库：https://github.com/didit-protocol/sdk-react-native

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：264 kB，52 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：react \*，react-native \*，@expo/config-plugins \>=7\.0\.0
- 首次发布：2026-02-16T17:22:21.693Z
- 最新版本发布：2026-11-11T13:42:30.728Z
- 近 30 天下载量：77890（2026-10-12 至 2026-11-10，npm 官方下载统计）
- 已发布版本数：66（近 12 个月 66 个）

## 中文简介

Didit 身份验证 SDK 的原生包装

## 安装

```sh
npm install @didit-protocol/sdk-react-native
```

也可以使用：`pnpm add @didit-protocol/sdk-react-native`、`yarn add @didit-protocol/sdk-react-native`、`bun add @didit-protocol/sdk-react-native`

## README

# 本地反应的 DiditSDK

用于 Didit 身份验证 SDK 的回放原生包装. 支持iOS和Android同时使用在React Industrial's New Architecture(Turbo Modules)上所构建的统一TypeScript API.

正在准备作为单独的 [`@didit-protocol/auth-react-native`](https://npmcn.com/package/%40didit-protocol/sdk-react-native/packages/auth-react-native/README.md) 软件包. 在本地的DiditAuth人融入之前,这是私人的,无法使用.

## 所需资源

-   反应原生 0.76+ (新建筑 / TurboModules)
-   节点.js 20+
-   类型脚本 5+

### 平台要求

| 平台 | 最小版本 | 页:1 |
| --- | --- | --- |
| iOS系统 | 13.0+ (韩语) | NFC护照读取需要iOS 15.0+ |
| 机器人 | API 24+ (7.0) (中文(简体) ) | Kotlin 2.1.10+, Android Gradle插件 8.6.0+, Gradle 8.7+, JDK 17 |

## 权限

SDK只为位置验证步骤使用相机,可选为 NFC 和位置(参见 [银行和地点核查步骤](https://npmcn.com/package/%40didit-protocol/sdk-react-native/#readme-bank-and-location-verification-steps)) (中文(简体) ). 原生许可由基础原生SDK宣布,并在平台支持的地方自动合并.

### iOS系统

在您的应用程序中添加以下密钥 `Info.plist`数字 :

```xml
<key>NSCameraUsageDescription</key>
<string>Camera access is required to scan your identity documents for verification.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required to record video for liveness verification.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to upload document images.</string>
<key>NFCReaderUsageDescription</key>
<string>NFC is used to read passport chip data for identity verification.</string>
```

缺少需要的iOS隐私密钥会让iOS在SDK访问保护资源后立即终止应用.

#### NFC 配置(用于读取护照/ID芯片)

1.  **添加 NFC 能力** 在 Xcode 中:
    
    -   选择目标 > 签名( C) > + 能力 > 接近外地通讯标记读取
2.  **添加 ISO7816 标识符** 改为 `Info.plist`数字 :
    
    ```xml
    <key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
    <array>
        <string>D23300000045737445494420763335</string>
        <string>A0000002471001</string>
        <string>A0000002472001</string>
        <string>00000000000000</string>
    </array>
    ```
    
3.  **添加应享权利文件** 启用 NFC 标签读取 :
    
    ```xml
    <key>com.apple.developer.nfc.readersession.formats</key>
    <array>
        <string>TAG</string>
    </array>
    ```
    

确保应用程序的提供配置包括NFC标签阅读能力. NFC被禁用时不需要这种NFC配置.

### 机器人

以下权限在本地 SDK 中声明 `AndroidManifest.xml` 并自动合并 :

| 权限 | 说明 |
| --- | --- |
| `INTERNET` | API 通信的网络访问 |
| `ACCESS_NETWORK_STATE` | 检测网络可用性 |
| `CAMERA` | 文件扫描和面相验证 |
| `NFC` | 在护照/身份证上读取 NFC 芯片 |

相机和NFC硬件特性被宣布为可选(`android:required="false"`),因此你的应用程序可以安装在没有这些特性的设备上.

#### 运行时间权限

SDK自动处理Android运行时权限请求. 当用户到达需要相机访问的一步时:

1.  SDK 提示, 如果尚未获得相机许可
2.  如果用户 **否认** 中,使用“再次尝试”按钮显示错误消息
3.  如果用户 **赠款** 权限, 核查流量继续

您在拨打前不需要在您的应用代码中请求相机许可 `startVerification()` - SDK内部管理这个.

## 银行和地点核查步骤

工作流量可包括: **银行** 步骤(个人链接银行账户)和a **地点** 步骤(设备位置读取一次,并征得个人同意)。 两个屏幕都由本地的 SDK 绘制, 所以这个软件包不需要新的 API: 它们运行在内部 `startVerification()` 编号 : `startVerificationWithWorkflow()`,结果还是一样 `VerificationResult`。 。 。 .

### 银行

没有设置。 本地SDK在系统浏览器中打开了银行的页面(或一页Didit主机),因此没有权限,URL计划或深层链接来注册.

### IOS 上的位置

船舶在本地SDK中的位置完整 **位置变体**,而不是作为附加: `Core-Location`, (中文(简体) ), `NFC-Location` 财务报告和审定财务报表 `All-Location` 对于可可花, `DiditSDKCoreLocation`, (中文(简体) ), `DiditSDKNFCLocation` 财务报告和审定财务报表 `DiditSDKLocation` (所有与位置) SwiftPM。 完全可以宣布一个 DiditSDK 变体,所以这个包从您的变体中选择给你: `all` 地图到 `All-Location`, (中文(简体) ), `core` 财务报告和审定财务报表 `autodetection` 地图到 `Core-Location`, (中文(简体) ), `nfc` 地图到 `NFC-Location`。 。 。 .

设定 `$DiditSdkIosLocationEnabled = true` 在此之前 `use_native_modules!` (或 `DIDIT_SDK_IOS_LOCATION_ENABLED=true`)并保留一个单曲 `pod didit_sdk_subspec` 线条显示于 [反应原生 CLI](https://npmcn.com/package/%40didit-protocol/sdk-react-native/#readme-ios)与位置映射。 使用 SwiftPM 链接时, 同一旗子会选择位置产品, 并且不需要主干线 。 展览用户设置 `iosLocationEnabled: true` 在此套件的插件选项中运行预建。 不启用位置, 或不启用 `NSLocationWhenInUseUsageDescription`,该步骤没有显示即时性,报告设备不能放置人物,工作流程自己的规则决定.

添加目的字符串到 `Info.plist`。 。 。 . `NSLocationTemporaryUsageDescriptionDictionary` 是可选的:它允许步骤在只授予一个近似位置(iOS 14+)时要求精确位置一次,其密钥必须是准确的 `DiditLocationVerification`。 。 。 .

```xml
<key>NSLocationWhenInUseUsageDescription</key>
<string>Your location is used to confirm where you are for this verification.</string>
<key>NSLocationTemporaryUsageDescriptionDictionary</key>
<dict>
    <key>DiditLocationVerification</key>
    <string>This verification needs your precise location once.</string>
</dict>
```

iOS通过设备语言来选择这些字符串,而不是SDK的 `languageCode`,所以翻译在每一个中 `<lang>.lproj/InfoPlist.strings`。精确位置字符串在其目的键下翻译。 举个例子 `es.lproj/InfoPlist.strings`数字 :

```
"NSLocationWhenInUseUsageDescription" = "Tu ubicación se usa para confirmar dónde estás en esta verificación.";
"DiditLocationVerification" = "Esta verificación necesita tu ubicación precisa una vez.";
```

将相同的密钥设置在 Expo 中 `app.json` 并翻译为: [`locales`](https://docs.expo.dev/guides/localization/#translating-app-metadata)数字 :

```json
{
  "expo": {
    "plugins": [
      ["@didit-protocol/sdk-react-native", { "iosLocationEnabled": true }]
    ],
    "ios": {
      "infoPlist": {
        "NSLocationWhenInUseUsageDescription": "Your location is used to confirm where you are for this verification.",
        "NSLocationTemporaryUsageDescriptionDictionary": {
          "DiditLocationVerification": "This verification needs your precise location once."
        }
      }
    },
    "locales": {
      "es": "./locales/es.json"
    }
  }
}
```

地点 `locales/es.json` 为:

```json
{
  "ios": {
    "NSLocationWhenInUseUsageDescription": "Tu ubicación se usa para confirmar dónde estás en esta verificación.",
    "DiditLocationVerification": "Esta verificación necesita tu ubicación precisa una vez."
  }
}
```

此寄存器中的两个示例应用程序都用英语和西班牙语声明这些字符串.

一旦您的应用程序链接模块, 请声明 **准确位置** 财务报告和审定财务报表 **粗细位置** 在 App Store 连接中 **App 函数**,链接到用户而不用于跟踪。 SDK每次尝试读取一个位置,只在台阶被屏幕显示时,才从背景中读取.

### Android 上的位置( 地址 )

本地 SDK 声明 `ACCESS_FINE_LOCATION` 财务报告和审定财务报表 `ACCESS_COARSE_LOCATION`,加上位置硬件特性作为可选性(`android:required="false"`),它们自动地合并到您的应用中. 只有在一个工作流程到达台阶时,经过一个解释原因的屏幕之后,才能在运行时间提出这些要求,而且此人可以给出准确或大致的位置。 如果你的应用程序从未运行该步骤,你可以把它们从合并清单中删除 `<manifest>` 要素需求 `xmlns:tools="http://schemas.android.com/tools"`:

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" tools:node="remove" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" tools:node="remove" />
```

仍然达到该步骤的会话,然后报告该位置不可用,而不迅速。 如果你留着,就宣布 **大约位置** 财务报告和审定财务报表 **准确位置** 在您的 Google 游戏数据安全表中收集的数据.

## 原生 SDK 变体

NFC默认在两个平台上启用. 每个变体都有自动抓取功能.

React Natural插件可以安装被iOS和Android SDK所曝光的同一种原生SDK变体:

| 备选案文 | NFC 护照读取 | 使用时间 |
| --- | --- | --- |
| `all` | 对 | 您想要完整的 SDK( 默认) |
| `core` | 没有 | 您不需要 NFC 护照读取 |
| `nfc` | 对 | 你想要NFC变体 |
| `autodetection` | 没有 | 折旧:与 `core` |

当NFC被禁用时,你不需要iOS NFC能力,NFC应享权利,Android NFC包装规则,或NFC相关的提供设置.

## 安装

### 博览

```sh
npx expo install @didit-protocol/sdk-react-native
```

然后将配置插件添加到您的 `app.json` (或 `app.config.js`) (中文(简体) ). 默认的本地变体是 `all`数字 :

```json
{
  "expo": {
    "plugins": ["@didit-protocol/sdk-react-native"]
  }
}
```

要选择较小的本地变体 :

```json
{
  "expo": {
    "plugins": [
      [
        "@didit-protocol/sdk-react-native",
        {
          "iosVariant": "core",
          "androidVariant": "core"
        }
      ]
    ]
  }
}
```

就是这样。 插件自动配置两个平台 :

-   **机器人:** 将 Didit Maven 寄存器添加到 Gradle 并写入 `diditSdkAndroidVariant`
-   **iOS: (英语)** 将 DiditSDK 的 podspec 添加到 Pod 文件并设定 `$DiditSdkIosVariant`

支助 `iosVariant` 编号 : `androidVariant` 值为 `all`, (中文(简体) ), `core`, (中文(简体) ), `autodetection`,以及 `nfc`遗产布林斯`iosNfcEnabled`, (中文(简体) ), `iosAutoDetectionEnabled`, (中文(简体) ), `androidNfcEnabled`仍然工作,不过 `iosVariant` 编号 : `androidVariant` 倾向于采用新的整合.

过 `"iosLinkage": "spm"` 要通过 Swift 软件包管理器而不是 CocoaPods 解决本地 iOS SDK - 此插件会写出否 `pod 'DiditSDK'` 线条。 见 [Swift 软件包管理器](https://npmcn.com/package/%40didit-protocol/sdk-react-native/#readme-swift-package-manager-optional) 提醒你一下,我说... 默认是 `cocoapods`。 。 。 .

IOS postspec URL 来源于本软件包的 SDK 版本 (`diditNativeSdkVersions.ios` 联合国 `package.json`因此,它总是匹配 `DiditSDK` 版本的 post spec 取决于 。 用叉子、镜子或预先释放标记指向可可花,通过 `iosPodspecUrl`数字 :

```json
[
  "@didit-protocol/sdk-react-native",
  {
    "iosPodspecUrl": "https://raw.githubusercontent.com/didit-protocol/sdk-ios/4.14.7/DiditSDK.podspec"
  }
]
```

> **说明:** 此 SDK 使用 Expo Go 不可用的本地模块(相机, NFC). 你必须用一个 [发展](https://docs.expo.dev/develop/development-builds/introduction/) 运行 `npx expo prebuild` 开发本地项目.

### 反应原生 CLI

```sh
npm install @didit-protocol/sdk-react-native
# or
yarn add @didit-protocol/sdk-react-native
```

#### iOS系统

将 DiditSDK 显示器添加到您的 `Podfile` (不在可可花树干上) 默认的本地变体是 `all`数字 :

```ruby
# Pick one: 'all', 'core', 'nfc' ('autodetection' is deprecated and identical to 'core')
$DiditSdkIosVariant = 'all'

def max_ios_version(*versions)
  versions.map(&:to_s).max_by { |version| Gem::Version.new(version) }
end

didit_sdk_ios_deployment_target = ['all', 'nfc'].include?($DiditSdkIosVariant) ? max_ios_version(min_ios_version_supported, '15.0') : min_ios_version_supported
platform :ios, didit_sdk_ios_deployment_target

# Inside your app target:
# Location ships as complete variants (All-Location, Core-Location, NFC-Location)
$DiditSdkIosLocationEnabled = false # true to enable the Location step
didit_sdk_location_suffix = $DiditSdkIosLocationEnabled ? '-Location' : ''
didit_sdk_subspec = case $DiditSdkIosVariant
                    when 'all'           then "DiditSDK/All#{didit_sdk_location_suffix}"
                    when 'core', 'autodetection' then "DiditSDK/Core#{didit_sdk_location_suffix}"
                    when 'nfc'           then "DiditSDK/NFC#{didit_sdk_location_suffix}"
                    else
                      raise "Invalid $DiditSdkIosVariant '#{$DiditSdkIosVariant}'. Supported values: all, core, autodetection, nfc."
                    end
pod didit_sdk_subspec, :podspec => 'https://raw.githubusercontent.com/didit-protocol/sdk-ios/4.14.7/DiditSDK.podspec'
```

##### Swift 软件包管理器( 可选)

在本地 0.75+ 中, 您可以跳过 `pod` 并让 SwiftPM 直接从 `sdk-ios` 复发. 设定链接, 而不是声明主机 :

```ruby
# Pick one: 'all', 'core', 'autodetection', 'nfc'
$DiditSdkIosVariant = 'all'
$DiditSdkIosLinkage = 'spm'

def max_ios_version(*versions)
  versions.map(&:to_s).max_by { |version| Gem::Version.new(version) }
end

didit_sdk_ios_deployment_target = ['all', 'nfc'].include?($DiditSdkIosVariant) ? max_ios_version(min_ios_version_supported, '15.0') : min_ios_version_supported
platform :ios, didit_sdk_ios_deployment_target

# No `pod 'DiditSDK'` line needed - SdkReactNative.podspec declares it as a
# SwiftPM dependency on the matching sdk-ios tag.
```

`DIDIT_SDK_IOS_LINKAGE=spm` 也行,博览会用户可以通过 `"iosLinkage": "spm"` 到配置插件. `cocoapods` 仍然是默认.

如果您将已有工程切换到 `spm`, (中文(简体) ), **删除 `pod didit_sdk_subspec, :podspec => ...` 线条** - 将两个框架连接两次。 React Industrial警告说,SwiftPM包与静态连接的吊舱结合,可以产生链接器出错;如果击中这些,则用 `USE_FRAMEWORKS=dynamic` (单位:千美元)[细节](https://github.com/facebook/react-native/pull/44627#issuecomment-2123119711)) (中文(简体) ).

然后安装依赖性 :

```sh
cd ios
bundle exec pod install
```

要切换变体, 干净的可可Pods 首先, 所以前一个变体不重复使用 :

```sh
cd ios
rm -rf Pods Podfile.lock

# Edit $DiditSdkIosVariant in your Podfile, then:
bundle exec pod install
```

#### 机器人

添加 Didit Maven 寄存器到您的工程级别 `settings.gradle`数字 :

```groovy
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven {
            url "https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository"
            // Scope to Didit's group: unfiltered, Gradle probes this host for
            // every dependency and a 429 disables the repo mid-build (issue #40).
            content { includeGroup "me.didit" }
        }
        maven { url "https://jitpack.io" }
    }
}
```

默认情况下, React 本地插件依赖于完整的Android SDK(`all`) (中文(简体) ). 要选择另一个变体,请添加到 `android/gradle.properties`数字 :

```properties
diditSdkAndroidVariant=core
```

支持的值为 `all`, (中文(简体) ), `core`, (中文(简体) ), `autodetection`,以及 `nfc`遗产 `diditSdkAndroidNfcEnabled=false` 属性仍然映射到 `core` 用于后向兼容,但 `diditSdkAndroidVariant` 选择新的整合.

两个平台的原生SDK依赖性在库中宣告并自动解决.

## 快速启动

### 选项A:以会话符号开始校验

如果您的后端创建了校验会话并返回一个符号:

```tsx
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);
    console.log('Session ID:', result.session.sessionId);
    break;
  case 'cancelled':
    console.log('User cancelled');
    break;
  case 'failed':
    console.log('Error:', result.error.type, result.error.message);
    break;
}
```

### 备选案文B:以工作流程ID开始核查

如果您想要 SDK 使用工作流程ID创建会话 :

```tsx
import { startVerificationWithWorkflow } from '@didit-protocol/sdk-react-native';

const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  config: { loggingEnabled: true },
});
```

## 配置

两者 `startVerification` 财务报告和审定财务报表 `startVerificationWithWorkflow` 接受一个 `DiditConfig` 对象自定义 SDK 行为。 对于 `startVerification`,通过它作为第二个论点。 对于 `startVerificationWithWorkflow`传入里面 `options.config` 字段.

```tsx
import { startVerification } from '@didit-protocol/sdk-react-native';

// With startVerification — config is the second argument
const result = await startVerification('your-session-token', {
  languageCode: 'es',
  showLanguageSelector: true,
  fontFamily: 'Avenir',
  loggingEnabled: true,
  showCloseButton: true,
  showExitConfirmation: true,
  closeOnComplete: false,
});

// With startVerificationWithWorkflow — config is inside options
const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  config: {
    languageCode: 'es',
    showLanguageSelector: true,
    loggingEnabled: true,
    showCloseButton: true,
    showExitConfirmation: true,
  },
});
```

### 配置选项

| 选项 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| `languageCode` | `string` | 设备定位 | ISO 639-1语言代码(例如. `"en"`, (中文(简体) ), `"fr"`, (中文(简体) ), `"ar"`(中文(简体) ) |
| `showLanguageSelector` | `boolean` | `false` | 在欢迎屏幕上显示网络风格的语言选择器 |
| `fontFamily` | `string` | 系统字体 | 自定义字体姓氏 |
| `loggingEnabled` | `boolean` | `false` | 启用 SDK 调试记录 |
| `showCloseButton` | `boolean` | `true` | 在校验步骤屏幕上显示关闭( X) 按钮 |
| `showExitConfirmation` | `boolean` | `true` | 用户试图退出时显示确认对话框 |
| `closeOnComplete` | `boolean` | `false` | 完成时自动解除校验 |
| `defaultDocumentCamera` | `CameraLens` | 本地默认( N)`back`(中文(简体) ) | 第一次进入文档抓取屏幕时使用的镜头 |
| `defaultLivenessCamera` | `CameraLens` | 本地默认( N)`front`(中文(简体) ) | 第一次进入活性(被动面)抓取屏幕时使用的镜头 |
| `showDocumentCameraSwitchButton` | `boolean` | `true` | 在文档屏幕上显示抓取相机切换器 |
| `showLivenessCameraSwitchButton` | `boolean` | `true` | 在活性屏幕上显示抓取相机切换器 |

所有字段都是可选的. 如果不提供配置, SDK 会使用合理的默认值 .

### `languageCode`

设置整个验证 UI 的语言。 通过一个ISO 639-1代码(例如. `"en"`, (中文(简体) ), `"fr"`, (中文(简体) ), `"es"`, (中文(简体) ), `"ar"`) (中文(简体) ). 如果不设定,SDK会自动检测设备的地盘并倒回英语.

```tsx
// Force French
await startVerification(token, { languageCode: 'fr' });

// Use device locale (default — no config needed)
await startVerification(token);
```

### `showLanguageSelector`

设定为 `true` 来让用户从欢迎屏幕中更改校验语言。 选择器默认隐藏 .

```tsx
await startVerification(token, { showLanguageSelector: true });
```

### `fontFamily`

覆盖整个SDK UI所使用的字体. 该字体必须在您的应用程序的本地配置中注册 :

-   **iOS: (英语)** 将字体文件添加到您的 Xcode 工程中并列出其中 `Info.plist` 下级 `UIAppFonts`。 。 。 .
-   **机器人:** 将字体文件放入 `android/app/src/main/res/font/`。 。 。 .

```tsx
await startVerification(token, { fontFamily: 'Avenir' });
```

如果不设定,SDK会使用平台的默认系统字体.

### `loggingEnabled`

启用本地 SDK 调试日志 。 开发期间用于检查SDK的内部状态,API调用,以及出错细节. 应在生产中被禁用.

```tsx
// Enable logging for debugging
await startVerification(token, { loggingEnabled: true });
```

### 相机设置

控制文档默认打开的相机镜头和活性捕捉屏幕,以及是否向用户显示摄入相机切换器.

```tsx
import { CameraLens, startVerification } from '@didit-protocol/sdk-react-native';

await startVerification(token, {
  defaultDocumentCamera: CameraLens.Back, // back is the native default
  defaultLivenessCamera: CameraLens.Front, // front is the native default
  showDocumentCameraSwitchButton: true, // false to lock to the chosen lens
  showLivenessCameraSwitchButton: true,
});
```

如果设备上没有所请求的镜头,则原生的SDK会倒回第一台可用的相机,因此捕获仍然有效. 切换器也自动隐藏在单相机设备上,而不论 `show…SwitchButton` 旗帜.

### 语言设置

SDK支持54种语言. 如果没有指定语言,SDK则使用有英语的器件locale作为倒置.

```tsx
// Use device locale (default)
await startVerification(token);

// Force a specific language
await startVerification(token, { languageCode: 'fr' });
```

#### 支持的语言

| 语言 | 代码 | 语言 | 代码 |
| --- | --- | --- | --- |
| 阿尔巴尼亚语Name | `sq` | 哈萨克语Name | `kk` |
| 阿拉伯语 | `ar` | 韩文 | `ko` |
| 亚美尼亚语Name | `hy` | 吉尔吉斯 | `ky` |
| 孟加拉语 | `bn` | 拉脱维亚语Name | `lv` |
| 波斯尼亚语 | `bs` | 立陶宛语Name | `lt` |
| 保加利亚语Name | `bg` | 马其顿 | `mk` |
| 加泰罗尼亚语Name | `ca` | 马来语Name | `ms` |
| 中文 | `zh` | 黑山 | `cnr` |
| 汉语 (简化) | `zh-CN` | 挪威语 | `no` |
| 中文( 传统) | `zh-TW` | 波斯语Name | `fa` |
| 克罗地亚 | `hr` | 波兰语Name | `pl` |
| 捷克语 | `cs` | 葡萄牙语 | `pt` |
| 丹麦语Name | `da` | 葡萄牙语( 巴西) | `pt-BR` |
| 荷兰语Name | `nl` | 罗马尼亚语Name | `ro` |
| 联合国 | `en` | 俄语 | `ru` |
| 爱沙尼亚语 | `et` | 塞尔维亚语 | `sr` |
| 芬兰语 | `fi` | 斯洛伐克语 | `sk` |
| 法语 | `fr` | 斯洛文尼亚语Name | `sl` |
| 格鲁吉亚语Name | `ka` | 索马里 | `so` |
| 德语 | `de` | 西班牙语 | `es` |
| 希腊语Name | `el` | 瑞典语 | `sv` |
| 希伯来语Name | `he` | 泰国语Name | `th` |
| 印地语 | `hi` | 土耳其语Name | `tr` |
| 匈牙利语Name | `hu` | 乌克兰语Name | `uk` |
| 印度尼西亚语Name | `id` | 乌兹别克斯坦语Name | `uz` |
| 意大利语 | `it` | 越南语Name | `vi` |
| 日本语 | `ja` | 蒙古语 | `mn` |

## 高级会话参数

对于高级会话参数,例如: `contact_details`, (中文(简体) ), `expected_details`, (中文(简体) ), `metadata`,以及 `callback`,使用 **后端会话** 方法。 你的后端电话 [POST /v3/会话/会话](https://docs.didit.me/) 然后通过 `session_token` 给SDK:

```tsx
// Your backend creates the session with advanced parameters:
// POST /v3/session/ with contact_details, expected_details, metadata, etc.
// Then passes the session_token to the SDK:
const result = await startVerification(sessionTokenFromBackend);
```

> **说明:** 这个 `startVerificationWithWorkflow` 仅支持方法 `vendorData`。对于任何其他会话参数,请使用后端会话方法.

### 完整工作流程示例

```tsx
const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  config: {
    languageCode: 'en',
    loggingEnabled: true,
    showCloseButton: true,
    showExitConfirmation: true,
  },
});
```

## 核查结果

两者 `startVerification` 财务报告和审定财务报表 `startVerificationWithWorkflow` 返回 a `Promise<VerificationResult>`其结果是存在歧视的工会——使用 `type` 字段来决定结果.

### 结果类型

| 类型 | 说明 | 字段 |
| --- | --- | --- |
| `completed` | 核查流程完成 | `session` (永远存在) |
| `cancelled` | 用户取消了流量 | `session` (可选) |
| `failed` | 发生了错误 | `error` (总是在), `session` (可选) |

### 会话数据

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `sessionId` | `string` | 唯一会话标识符 |
| `status` | `VerificationStatus` | `Approved`, (中文(简体) ), `Pending`,或 `Declined` |

### 校验错误

| 财产 | 类型 | 说明 |
| --- | --- | --- |
| `type` | `VerificationErrorType` | 错误类别(见下表) |
| `message` | `string` | 可读错误描述 |

### 错误类型

| 错误类型 | 说明 |
| --- | --- |
| `sessionExpired` | 会话已过期 |
| `networkError` | 网络连接问题 |
| `cameraAccessDenied` | 未获得相机许可 |
| `notInitialized` | SDK 未初始化( 只有Android) |
| `apiError` | API 请求失败 |
| `retryBlocked` | 先前的核查未获核准并达到最高复试次数 |
| `unknown` | 信件中的其他错误 |

### 处理结果

```tsx
import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

async function verify(token: string) {
  const result: VerificationResult = await startVerification(token);

  switch (result.type) {
    case 'completed':
      switch (result.session.status) {
        case VerificationStatus.Approved:
          console.log('Identity verified!');
          break;
        case VerificationStatus.Pending:
          console.log('Verification under review.');
          break;
        case VerificationStatus.Declined:
          console.log('Verification declined.');
          break;
      }
      console.log('Session ID:', result.session.sessionId);
      break;

    case 'cancelled':
      console.log('User cancelled the verification.');
      if (result.session) {
        console.log('Session ID:', result.session.sessionId);
      }
      break;

    case 'failed':
      console.log(`Error [${result.error.type}]: ${result.error.message}`);
      break;
  }
}
```

## 完整示例

```tsx
import { useState, useCallback } from 'react';
import {
  Text,
  View,
  TextInput,
  TouchableOpacity,
  Alert,
  ActivityIndicator,
  SafeAreaView,
} from 'react-native';
import {
  startVerification,
  startVerificationWithWorkflow,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

export default function App() {
  const [token, setToken] = useState('');
  const [loading, setLoading] = useState(false);

  const handleVerify = useCallback(async () => {
    if (!token.trim()) {
      Alert.alert('Error', 'Please enter a session token.');
      return;
    }

    setLoading(true);
    try {
      const result = await startVerification(token.trim(), {
        loggingEnabled: true,
      });
      showResult(result);
    } catch (error) {
      Alert.alert('Error', `Unexpected error: ${error}`);
    } finally {
      setLoading(false);
    }
  }, [token]);

  const showResult = (result: VerificationResult) => {
    switch (result.type) {
      case 'completed':
        Alert.alert(
          'Verification Complete',
          `Status: ${result.session.status}\nSession: ${result.session.sessionId}`
        );
        break;
      case 'cancelled':
        Alert.alert('Cancelled', 'The user cancelled the verification.');
        break;
      case 'failed':
        Alert.alert('Failed', `${result.error.type}: ${result.error.message}`);
        break;
    }
  };

  return (
    <SafeAreaView style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
      <TextInput
        placeholder="Enter session token..."
        value={token}
        onChangeText={setToken}
        autoCapitalize="none"
        style={{
          borderWidth: 1,
          borderColor: '#ccc',
          borderRadius: 8,
          padding: 12,
          marginBottom: 16,
        }}
      />
      <TouchableOpacity
        onPress={handleVerify}
        disabled={loading}
        style={{
          backgroundColor: '#1a1a1a',
          borderRadius: 8,
          padding: 16,
          alignItems: 'center',
        }}
      >
        {loading ? (
          <ActivityIndicator color="#fff" />
        ) : (
          <Text style={{ color: '#fff', fontWeight: '600' }}>
            Start Verification
          </Text>
        )}
      </TouchableOpacity>
    </SafeAreaView>
  );
}
```

## API 参考

### `startVerification(token, config?)`

以现有的会话符号开始校验 .

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `token` | `string` | 对 | 来自 Didit API 的会话令牌 |
| `config` | `DiditConfig` | 没有 | SDK 配置选项 |

回返情况: `Promise<VerificationResult>`

### `startVerificationWithWorkflow(workflowId, options?)`

通过创建一个带有工作流程ID的新会话开始校验.

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `workflowId` | `string` | 对 | 定义验证步骤的工作流程 ID |
| `options` | `WorkflowOptions` | 没有 | 工作流程备选方案(见下文) |

回返情况: `Promise<VerificationResult>`

#### 工作流程选项

| 外地 | 类型 | 说明 |
| --- | --- | --- |
| `vendorData` | `string` | 您的用户标识符或引用 |
| `config` | `DiditConfig` | SDK 配置选项 |

> **说明:** 高级会话参数(`contactDetails`, (中文(简体) ), `expectedDetails`, (中文(简体) ), `metadata`),使用后端会话方法(`startVerification` 通过 POST /v3/ session/ 创建一个令牌.

### `submitTransaction(transactionToken, transaction, options?)`

从设备直接提交交易 。 需要由您的后端通过 : `POST /v3/transactions/sdk-token/`。设备智能自动附加. `autoLaunchAction` (默认) `true`(a) 自动发射 `wallet_ownership` 本土行动,援引 `options.onTransactionUpdated` 完成后; a `verification_session` 动作从不自动发射,总是返回 `result.actionRequired` 您的应用程序将启动自己的 Didit 验证集成。 全向导 : [SDK 交易提交](https://docs.didit.me/transaction-monitoring/sdk-transaction-submission)。 。 。 .

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `transactionToken` | `string` | 对 | 交易 SDK 令牌( 同意为 `X-Transaction-Token`(中文(简体) ) |
| `transaction` | `DiditTransaction` | 对 | 交易有效载荷`txnId` 需要; `info`, (中文(简体) ), `subject`, (中文(简体) ), `counterparty`, (中文(简体) ), `travelRule`, (...) (中文(简体) ) |
| `options` | `DiditTransactionOptions` | 没有 | `baseUrl`, (中文(简体) ), `autoLaunchAction` (默认) `true`, (中文(简体) ), `onTransactionUpdated` 回调 |

回返情况: `Promise<DiditTransactionResult>` 与 `transactionId`, (中文(简体) ), `status`, (中文(简体) ), `travelRuleStatus?`,以及 `actionRequired?`。 。 。 .

掷出 : `DiditTransactionError` 与 `code` 设置为 `invalid_token`, (中文(简体) ), `expired_token`, (中文(简体) ), `validation` (见 `fieldErrors`),或 `network`。 。 。 .

```tsx
import { submitTransaction, DiditTransactionError } from '@didit-protocol/sdk-react-native';

try {
  const result = await submitTransaction(sdkToken, {
    txnId: 'order-123',
    type: 'crypto',
    info: { direction: 'outbound', amount: 0.25, currency: 'ETH' },
    travelRule: { required: true },
  }, {
    onTransactionUpdated: (updated) => console.log('Refreshed:', updated.status),
  });
  console.log(result.transactionId, result.actionRequired?.type);
} catch (error) {
  if (error instanceof DiditTransactionError) {
    console.log(error.code, error.fieldErrors);
  }
}
```

A 类 `verification_session` 动作返回,而不是自动发射 - 自行发射 `startVerification`数字 :

```tsx
import { submitTransaction, startVerification } from '@didit-protocol/sdk-react-native';

const result = await submitTransaction(sdkToken, transaction);

if (result.actionRequired?.type === 'verification_session') {
  const { sessionToken } = result.actionRequired;
  const verification = await startVerification(sessionToken!);
  console.log('Verification result:', verification.type);
}
```

### `getTransaction(transactionToken, transactionId, options?)`

获取先前以相同符号提交的交易的当前状态 .

| 参数 | 类型 | 需求 | 说明 |
| --- | --- | --- | --- |
| `transactionToken` | `string` | 对 | 交易 SDK 令牌 |
| `transactionId` | `string` | 对 | `transactionId` 返回时间 `submitTransaction` |
| `options` | `DiditTransactionOptions` | 没有 | `baseUrl` 覆盖 |

回返情况: `Promise<DiditTransactionResult>`

## 导出类型

```tsx
import {
  // Functions
  startVerification,
  startVerificationWithWorkflow,
  submitTransaction,
  getTransaction,

  // Enum
  VerificationStatus,

  // Classes
  DiditTransactionError,

  // Types
  type VerificationResult,
  type VerificationCompleted,
  type VerificationCancelled,
  type VerificationFailed,
  type VerificationError,
  type VerificationErrorType,
  type SessionData,
  type DiditConfig,
  type ContactDetails,
  type ExpectedDetails,
  type WorkflowOptions,
  type DiditTransaction,
  type DiditTransactionInfo,
  type DiditTransactionParticipant,
  type DiditTransactionPaymentMethod,
  type DiditTravelRule,
  type DiditTransactionActionRequired,
  type DiditTransactionResult,
  type DiditTransactionOptions,
  type DiditTransactionErrorCode,
} from '@didit-protocol/sdk-react-native';
```

## 运行示例应用程序

该寄存器包括一个功能完备的示例应用.

### iOS系统

```sh
yarn install
cd example/ios && bundle exec pod install && cd ../..
yarn run:ios
```

要运行在真正的设备上,打开 `example/ios/SdkReactNativeExample.xcworkspace` 在 Xcode 中,配置您的签名团队,并选择您的设备.

### 机器人

```sh
yarn install
yarn run:android
```

## 许可证

版权 (c) 2026 Didit. 版权所有.

## 常见问题

### @didit-protocol/sdk-react-native 是什么？

Didit 身份验证 SDK 的原生包装

### 如何安装 @didit-protocol/sdk-react-native？

在项目目录运行 npm install @didit-protocol/sdk-react-native，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\*）、react-native（\*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @didit-protocol/sdk-react-native 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @didit-protocol/sdk-react-native 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @didit-protocol/sdk-react-native 可以商用吗？

@didit-protocol/sdk-react-native 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @didit-protocol/sdk-react-native 的下载量有多少？

根据 npm 官方下载统计，@didit-protocol/sdk-react-native 在 2026/10/12 – 2026/11/10 这 30 天内被下载 77,890 次，日均约 2,596 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @didit-protocol/sdk-react-native 还在维护吗？

最新版本 4\.14\.7 发布于 2026/11/11（今天）；至今共发布 66 个版本，其中过去 12 个月发布了 66 个；首次发布于 2026/02/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。