# @getvouch/mobile-sdk 中文文档

规范地址：https://npmcn.com/package/%40getvouch/mobile-sdk/

版本：0\.1\.12
npm 元数据更新时间：2026-10-29T13:58:57.138Z
中文译文更新时间：2026-11-16T06:59:58.198Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40getvouch/mobile-sdk
原文对照：https://npmcn.com/package/%40getvouch/mobile-sdk/?lang=original
项目主页：https://github.com/vlayer-xyz/vouch/tree/main/packages/mobile-sdk#readme
源码仓库：https://github.com/vlayer-xyz/vouch

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

- 包体积（解压后）：3.4 MB，135 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：react \>=19\.1\.0 \<19\.3\.0，react-native \>=0\.81\.5 \<0\.84\.0，react-native-svg \>=15\.12\.1 \<16\.0\.0，react-native-video \>=6\.17\.0 \<7\.0\.0，react-native-webview \>=13\.15\.0 \<14\.0\.0，react-native-safe-area-context \>=5\.6\.0 \<6\.0\.0
- 首次发布：2026-07-24T11:15:12.096Z
- 最新版本发布：2026-10-29T13:58:56.911Z
- 近 30 天下载量：3549（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

反应原生 SDK 用于证明流

## 安装

```sh
npm install @getvouch/mobile-sdk
```

也可以使用：`pnpm add @getvouch/mobile-sdk`、`yarn add @getvouch/mobile-sdk`、`bun add @getvouch/mobile-sdk`

## README

# @ getvouch/ 移动 sdk

这个 [邮袋](https://getvouch.io/) React Industrial SDK在您的应用程序中嵌入了完整的Vouch验证流:屏幕,状态机器,以及后端传输,从开始到完成证明需要验证请求. 为了了解什么是沃克,核查如何运作,请看 [邮袋文件](https://docs.getvouch.io/) ——这个README覆盖集成SDK.

## 所需资源

-   **原生反应** 0.81.5 — 0.83.x, (中文(简体) ), **反应** 19.1 - 19.2 (中文(简体) )
-   **iOS系统** 16.4或16.4级以上
-   **机器人** API 26 (Android 8) 或更高级
-   主机应用程序必须提供的对等依赖性 : `react-native-safe-area-context` (>= 5.6 < 6), `react-native-svg` (>=15.12 < 16), `react-native-video` (>=6.17 < 7), `react-native-webview` (>=13.15 < 14)

同行范围在 `package.json` 权威 —— 您的软件包管理器会警告您的版本是否超出它们的范围 .

## 安装

```sh
npm install @getvouch/mobile-sdk
```

SDK自動連接了自己在两个平台上的原生模块(iOS通过CocoaPods,Android通过Gradle). 定期进行网络防伪核查不需要人工本土设置.

## 使用量

### 1\. 供货商上架

挂载 `VouchVerifierProvider` 一次在应用根。 它拥有流动状态; 其它一切在其之下.

```tsx
import { VouchVerifierProvider } from "@getvouch/mobile-sdk";

function App() {
  return (
    <VouchVerifierProvider apiKey="API_KEY">
      <YourScreens />
    </VouchVerifierProvider>
  );
}
```

-   `apiKey` 您的客户 API 密钥, 需要创建新的验证请求 。 见 [第一步](https://docs.getvouch.io/getting-started/first-steps) 为了找到它.
-   `customerId` - 仅由 [缩写 API](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-modal-api); 钩子 API 将其取入内流 `createProofRequest`。 。 。 .
-   `baseUrl` ——可选,默认为 `https://app.getvouch.io`。 。 。 .
-   `languageCodeOverride` ——可选 BCP 47 标签(`en`, (中文(简体) ), `pl-PL`,.) 压倒用于模式启动的设备语言; 钩子 API 将其每流取入 `startProve`。 。 。 .
-   `webviewDebuggingEnabled` ——可选,默认关闭. 开发大楼总是可以检查的;这一选择的发布也建入了Chrome DevTools/Safari网络检查员。 在制作中离开它: 证明 WebView 持有用户与数据源的认证会话.

### 2\. 启动并实现流动

驱动流动与 `useVouch` 钩上并把它 `VouchScreen`数字 :

```tsx
import { useEffect } from "react";
import { VouchScreen, useVouch } from "@getvouch/mobile-sdk";

function ProveScreen() {
  const { state, startProve, reset } = useVouch();

  useEffect(() => {
    // a. Resume a proof request your backend already created:
    startProve({ requestId: "EXISTING_REQUEST_ID" });
    // b. …or create one on the fly:
    // startProve({
    //   createProofRequest: {
    //     customerId: "CUSTOMER_ID",
    //     dataSourceId: "DATA_SOURCE_ID",
    //     webhookUrl: "https://your-server.com/webhook",
    //     inputs: { INPUT_NAME: "value" },
    //   },
    // });
    return () => reset();
  }, [startProve, reset]);

  useEffect(() => {
    if (state.status === "success") {
      // state.result.proofId identifies the finished proof — navigate away here.
    }
  }, [state]);

  return <VouchScreen />;
}
```

### 3\. 观察国家

`state.status` 移动通过 `idle → launching → processing → proving → success`,或结束于 `error` 或者说 `cancelled` (用户关闭流量;携带 `requestId` 结束了。 通话 `startProve` 在任何末端状态种子之后, 会有一股新鲜的流出—— 没有明确的 `reset()` 需要; `reset()` 返回机器到 `idle` 不启动新流程.

### 4\. 关闭和重返大气层

用户可以将流出自SDK自有的染色体——校对浏览器头部的相近控制,视频和出错屏幕上的相近控制,或者任何这些步骤上的Android硬件后键. 每一个都以同样的方式结束流动:

-   **钩子 API**: 终端上的流出地 `cancelled` 状态,带有 `requestId` 它结束了。 把ID和你自己的流量比起来 在行动之前,所以一个共享提供者的停滞 `cancelled` 从更早的流量中不会移动错误的屏幕.
-   **[缩写 API](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-modal-api)**数字 : `start`编号 :`startHeadless` 拒绝 `description: "Vouch flow was closed"` 和原因 `15`。 。 。 .

两个阶段本身没有接近: `launching`,而证明请求装入 `proving`,取消会丢掉一个 即将完成的证据。 在钩子模式中,没有任何东西会打断这些阶段——硬件回落到你自己的导航中,由你的屏幕来决定该做什么;在模式模式中,Android回落将模式从任何阶段中剔除. `proving` 在屏幕上继续时没有流量 UI , 因此在屏幕上隐藏自己的屏幕是安全的 .

关闭丢弃尝试——举证请求未完成,没有上传. 要让用户再次尝试,请打电话 `startProve` (或 `start`)再次;模式主机总是以这种方式开始新的证明请求. Hooks 主机也可以通过 `startProve({ requestId })` 与闭路流量的 id 重新输入同样的证明请求 从开始,而不是创建一个新的(`VouchStartParams` 没有 `requestId`,因此模式 API 无法); WebView cookie 在关闭后幸存,因此用户通常仍然被签入到数据源. 已经提出证据的请求不能重复使用——开始新的请求.

### 缩写 API

主机从遗留的要务SDK中迁移,可以使用提供者支持的模式API来代替钩子. 它以全屏显示流量 `Modal` 并达成一个承诺,所以没有 `VouchScreen` 已挂载。 供应商必须携带 **两者** `customerId` 财务报告和审定财务报表 `apiKey` - 没有, `start` 理性拒绝 `14`数字 :

```tsx
import VouchSDK, { VouchVerifierProvider } from "@getvouch/mobile-sdk";

function App() {
  return (
    <VouchVerifierProvider customerId="CUSTOMER_ID" apiKey="API_KEY">
      <YourScreens />
    </VouchVerifierProvider>
  );
}

// Call this from a handler on a screen under the provider. `start` resolves the
// controller the mounted provider registers, so calling it at module scope —
// before that happens — rejects with reason 14.
async function verify() {
  const { proofId } = await VouchSDK.start({
    dataSourceId: "DATA_SOURCE_ID",
    webhookUrl: "https://your-server.com/webhook",
    inputs: { INPUT_NAME: "value" },
    metadata: "YOUR_OWN_REFERENCE", // optional, travels with the proof
  });

  return proofId;
}
```

`VouchSDK.startHeadless(params, onProgress?)` 运行相同的流并取出相同的参数,但只在 : `sniffingRequests` 阶段;它报告进展情况为 `downloadingConfig → sniffingRequests → proving → finished`。 。 。 .

在iOS上,流被呈现为全屏模式来覆盖您的应用的根屏幕——由 `start` 马上,然后 `startHeadless` 当它到达时 `sniffingRequests` iOS 拒绝, 而您的应用程序已经在显示工作表或模式 。 一旦您所呈现的任何工作表或模式完成丢弃,或从正则屏幕上跳出,即启动此流程,不从 `startHeadless` 进步召回。 如果流量仍然无法显示, 双方在大约6秒后拒绝 `16` 和说明 `"Vouch flow could not be shown because the host app is already presenting another screen. Dismiss host sheets and modals before starting a Vouch flow."`。 。 。 .

他们俩都原是否认的 `VouchError` 对象 - `{ reason, description, proofId? }`,而不是一个 `Error`。关闭流量的用户也拒绝,理由 `15` 财务报告和审定财务报表 `description: "Vouch flow was closed"`; 见 [关闭和再入](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-4-closing-and-re-entry) 财务报告和审定财务报表 [错误代码](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-error-codes)。 。 。 .

### 清理

打电话 `await VouchSDK.destroy()` 删除 WebView 饼干。 这个没有挂载的提供者。 在Android上,当安装的提供者支持配置时,它清除了专用的Vouch WebView配置;更古老的提供者使用进程默认的cookie商店,因此清理也去掉了由主机Web Victors创建的cookie. 在iOS上,它清除了共享默认的WebKit cookie商店,包括由主机应用程序中由其他Web Victors创建的cookie. 它不清除其他网站数据或取消活性证明流量.

## 视频校验( 可选)

一些数据来源的使用 [视频校验](https://docs.getvouch.io/getting-started/video-verification) 而不是密码网络证明。 常规的防网流不需要额外的设置,Android视频验证自动链接也. **IOS 上的视频校验需要 SDK 的 Expo 配置插件**,增加了 App Group 应享权利和 `VouchBroadcast` 屏幕记录扩展名 :

```json
{
  "expo": {
    "plugins": [["@getvouch/mobile-sdk", { "appGroupIdentifier": "group.<your-bundle-id>" }]]
  }
}
```

`appGroupIdentifier` 是可选的,默认为 `group.<your-bundle-id>.vouch`。插件修改了原生项目,所以在添加后,将原生目录重新生成 `npx expo prebuild`,然后重建并安装应用程序 -- `npx expo run:ios`,或者一个新的EAS建筑。 重新装入联署材料不足以领取这项权利.

如果一个数据源以视频模式运行而插件缺失,则SDK会立即以明显的出错(并在开发中记录准确的定律)而不会在用户录制后出现故障而导致流量倒闭.

## 错误代码

模式- API 拒绝包含数字 `VouchError.reason`代码 `0`– 说吧 –`14` 与遗留的SDK相同:

| 代码 | 含义 |
| --- | --- |
| 0 个 | 未找到数据源或客户 |
| 1个 | 过时的 SDK 版本 |
| 2个 | 创建校验失败 |
| 3个 | 背景超时 |
| 页:1 | 请求太大了 |
| 页:1 | 数据源配置错误 |
| 6个 | 验证失败 |
| 第7条 | 验证上传失败 |
| 第8条 | 附件重载失败 |
| 第9条 | 已获取的验证身份 |
| 10个 | 网络连接已丢失 |
| 第11个 | 处理超时 |
| 第12条 | 错误的 API 密钥 |
| 第13条 | 内部服务器出错 |
| 页:1 | 提供者缺失或未配置 |
| 15个 | 用户关闭流量 |
| 16个 | 无法显示流程( iOS: 主机应用程序已显示另一个屏幕) |
| 页:1 | 在流量完成前卸载提供者 |
| 第 18 条 | 另一个口袋流已经激活 |

代码 `2` 还涵盖a `start` 或者说 `startHeadless` 调用在流量开始前失败, 并开始描述 `"VouchSDK.start failed"`代码 `15`– 说吧 –`18` 没有同等遗产。 在此之前 `0.1.10`,这个SDK上报了其中的每个案例, 并且这个启动失败,有代码 `0`; 从 `0.1.10`代码 `0` 仅指未找到数据源或客户.

## 从 `@getvouch/react-native-sdk`

遗产 `@getvouch/react-native-sdk` (最近一次) `0.9.9`(a) 包裹的已预先建造的原生SDK: `io.getvouch:android-sdk` 格拉德工艺品和 `vouch-ios-sdk` 舱。 此套件将本地堆栈替换为 React 本地和 JavaScript over `@vouch/prover-mobile-js`。它是不同放行上不同的软件包,所以没有版本的凸起可以带你穿过.

这个 [缩写 API](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-modal-api) 以保持移徙的其余部分. `start`, (中文(简体) ), `startHeadless`, (中文(简体) ), `VouchStartParams` (单位:千美元)`dataSourceId`, (中文(简体) ), `webhookUrl`, (中文(简体) ), `inputs`, (中文(简体) ), `metadata`页:1 `downloadingConfig → sniffingRequests → proving → finished` 进度字符串, 无头仅显示在 URI 期间 `sniffingRequests`数字 [错误代码](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-error-codes) `0`– 说吧 –`14` 所有结转不变. `VouchSuccess` 仍然携带 `proofId`,现在也可以选择 `redirectBackUrl`。 。 。 .

你必须要改变什么:

1.  **交换软件包并安装四个对等依赖.** 仅对等遗留的软件包 `react` 财务报告和审定财务报表 `react-native`;这个也需要 `react-native-safe-area-context`, (中文(简体) ), `react-native-svg`, (中文(简体) ), `react-native-video`,以及 `react-native-webview` (见 [所需资源](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-requirements)) (中文(简体) ).
    
2.  **替换 `initialize()` 与供养.** `initialize()` 财务报告和审定财务报表 `isInitialized()` 不见了,所以 `VouchSDK.initialize(...)` 现在扔一个 `TypeError`. (中文(简体) )`isSupported()` 也不见了,虽然 `0.9.9` 从未实际导出其文件描述的方法。 ) 将相同的配置移动到 `VouchVerifierProvider`,在应用程序根上挂载一次 :
    
    ```tsx
    // before
    await VouchSDK.initialize({ customerId: "CUSTOMER_ID", apiKey: "API_KEY", languageCodeOverride: "pl-PL" });
    
    // after
    <VouchVerifierProvider customerId="CUSTOMER_ID" apiKey="API_KEY" languageCodeOverride="pl-PL">
      <YourScreens />
    </VouchVerifierProvider>;
    ```
    
3.  **重做错误处理 .** `VouchError.proofId` 现在可选 : 一旦证据请求存在, 则在SDK 寄出之前省略 `""` 这样啊 `error.proofId.length` 掷出. 遗产 `-1` (“ SDK 未初始化或内部出错 ” ) 永远不会发布; 缺少或配置不完整的提供者报告 `14` 换句话说 关闭流量的用户现在拒绝使用 `15`没有 `0`,而其他只使用模式的失败则有自己的代码 `16`– 说吧 –`18` (见 [错误代码](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-error-codes)),所以代码 `0` 仅指未找到数据源或客户. 还有 `startHeadless` 现在用同样的方法拒绝 `VouchError` 对象为 `start`即那被弃绝的遗产 `Error` 无 `reason` 或者说 `description`。 。 。 .
    
4.  **重新检查什么 `destroy()` 为你做.** 遗产 `destroy()` 拆除初始状态并强制更新 `initialize()`。这个只清除了WebView cookie, 并让挂载的提供者能够使用—— 看 [清理](https://npmcn.com/package/%40getvouch/mobile-sdk/#readme-cleanup)。 。 。 .
    
5.  **重新检查你的站台地板.** React Industrial 0.81.5 – 0.83.x和React 19.1 – 19.2是强制同龄人范围,其中遗留包接受任何东西. Android从API 33到API 26的最小下降,而iOS不再需要了 `use_frameworks!` 在您的 Pod 文件中.

## 常见问题

### @getvouch/mobile-sdk 是什么？

反应原生 SDK 用于证明流

### 如何安装 @getvouch/mobile-sdk？

在项目目录运行 npm install @getvouch/mobile-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（\>=19\.1\.0 \<19\.3\.0）、react-native（\>=0\.81\.5 \<0\.84\.0）、react-native-svg（\>=15\.12\.1 \<16\.0\.0）、react-native-video（\>=6\.17\.0 \<7\.0\.0）、react-native-webview（\>=13\.15\.0 \<14\.0\.0）、react-native-safe-area-context（\>=5\.6\.0 \<6\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @getvouch/mobile-sdk 支持 TypeScript 吗？

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

### @getvouch/mobile-sdk 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @getvouch/mobile-sdk 可以商用吗？

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

### @getvouch/mobile-sdk 的下载量有多少？

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

### @getvouch/mobile-sdk 还在维护吗？

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

