@getvouch/mobile-sdk

中文文档
0.1.12发布于 2026/10/29MITTypeScriptCommonJS近 30 天下载 3549

反应原生 SDK 用于证明流

中文使用文档
文档目录12 节
  1. 所需资源
  2. 安装
  3. 使用量
  4. 1. 供货商上架
  5. 2. 启动并实现流动
  6. 3. 观察国家
  7. 4. 关闭和重返大气层
  8. 缩写 API
  9. 清理
  10. 视频校验( 可选)
  11. 错误代码
  12. 从 @getvouch/react-native-sdk

@ getvouch/ 移动 sdk

这个 邮袋 React Industrial SDK在您的应用程序中嵌入了完整的Vouch验证流:屏幕,状态机器,以及后端传输,从开始到完成证明需要验证请求. 为了了解什么是沃克,核查如何运作,请看 邮袋文件 ——这个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 权威 —— 您的软件包管理器会警告您的版本是否超出它们的范围 .

安装

npm install @getvouch/mobile-sdk

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

使用量

1. 供货商上架

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

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

function App() {
  return (
    <VouchVerifierProvider apiKey="API_KEY">
      <YourScreens />
    </VouchVerifierProvider>
  );
}
  • apiKey 您的客户 API 密钥, 需要创建新的验证请求 。 见 第一步 为了找到它.
  • customerId - 仅由 缩写 API; 钩子 API 将其取入内流 createProofRequest。 。 。 .
  • baseUrl ——可选,默认为 https://app.getvouch.io。 。 。 .
  • languageCodeOverride ——可选 BCP 47 标签(en, (中文(简体) ), pl-PL,.) 压倒用于模式启动的设备语言; 钩子 API 将其每流取入 startProve。 。 。 .
  • webviewDebuggingEnabled ——可选,默认关闭. 开发大楼总是可以检查的;这一选择的发布也建入了Chrome DevTools/Safari网络检查员。 在制作中离开它: 证明 WebView 持有用户与数据源的认证会话.

2. 启动并实现流动

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

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数字 : 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数字 :

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"; 见 关闭和再入 财务报告和审定财务报表 错误代码。 。 。 .

清理

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

视频校验( 可选)

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

{
  "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 以保持移徙的其余部分. start, (中文(简体) ), startHeadless, (中文(简体) ), VouchStartParams (单位:千美元)dataSourceId, (中文(简体) ), webhookUrl, (中文(简体) ), inputs, (中文(简体) ), metadata页:1 downloadingConfig → sniffingRequests → proving → finished 进度字符串, 无头仅显示在 URI 期间 sniffingRequests数字 错误代码 0– 说吧 –14 所有结转不变. VouchSuccess 仍然携带 proofId,现在也可以选择 redirectBackUrl。 。 。 .

你必须要改变什么:

  1. 交换软件包并安装四个对等依赖. 仅对等遗留的软件包 react 财务报告和审定财务报表 react-native;这个也需要 react-native-safe-area-context, (中文(简体) ), react-native-svg, (中文(简体) ), react-native-video,以及 react-native-webview (见 所需资源) (中文(简体) ).

  2. 替换 initialize() 与供养. initialize() 财务报告和审定财务报表 isInitialized() 不见了,所以 VouchSDK.initialize(...) 现在扔一个 TypeError. (中文(简体) )isSupported() 也不见了,虽然 0.9.9 从未实际导出其文件描述的方法。 ) 将相同的配置移动到 VouchVerifierProvider,在应用程序根上挂载一次 :

    // 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 (见 错误代码),所以代码 0 仅指未找到数据源或客户. 还有 startHeadless 现在用同样的方法拒绝 VouchError 对象为 start即那被弃绝的遗产 Error 无 reason 或者说 description。 。 。 .

  4. 重新检查什么 destroy() 为你做. 遗产 destroy() 拆除初始状态并强制更新 initialize()。这个只清除了WebView cookie, 并让挂载的提供者能够使用—— 看 清理。 。 。 .

  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 共发布 13 个版本,首次发布于 2026/07/24;过去 12 个月发布了 13 个版本。

版本发布日期距今
0.1.12latest2026/10/2917 天前
0.1.112026/10/2719 天前
0.1.102026/10/2224 天前
0.1.92026/10/1927 天前
0.1.82026/09/092 个月前
0.1.72026/09/042 个月前

关于 @getvouch/mobile-sdk 的常见问题

@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 和提交记录判断。