@getvouch/mobile-sdk

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

React Native SDK for the Vouch proving flow

原始使用文档
文档目录12 节
  1. Requirements
  2. Installation
  3. Usage
  4. 1. Mount the provider
  5. 2. Start a flow and render it
  6. 3. Observe the state
  7. 4. Closing and re-entry
  8. Modal API
  9. Cleanup
  10. Video verification (optional)
  11. Error codes
  12. Migrating from @getvouch/react-native-sdk

@getvouch/mobile-sdk

The Vouch React Native SDK embeds the full Vouch verification flow in your app: screens, state machine, and backend transport that take a proof request from start to finished proof. To learn what Vouch is and how verification works, see the Vouch docs — this README covers integrating the SDK.

Requirements

  • React Native 0.81.5 – 0.83.x, React 19.1 – 19.2
  • iOS 16.4 or higher
  • Android API 26 (Android 8) or higher
  • Peer dependencies the host app must provide: 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)

The peer ranges in package.json are authoritative — your package manager will warn if your versions fall outside them.

Installation

npm install @getvouch/mobile-sdk

The SDK autolinks its native module on both platforms (iOS via CocoaPods, Android via Gradle). No manual native setup is needed for regular web-proof verification.

Usage

1. Mount the provider

Mount VouchVerifierProvider once at the app root. It owns the flow state; everything else renders under it.

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

function App() {
  return (
    <VouchVerifierProvider apiKey="API_KEY">
      <YourScreens />
    </VouchVerifierProvider>
  );
}
  • apiKey — your customer API key, required to create new proof requests. See First steps for where to find it.
  • customerId — required only by the Modal API; the hook API takes it per flow inside createProofRequest.
  • baseUrl — optional, defaults to https://app.getvouch.io.
  • languageCodeOverride — optional BCP 47 tag (en, pl-PL, …) overriding the device language for modal starts; the hook API takes it per flow on startProve.
  • webviewDebuggingEnabled — optional, off by default. Development builds are always inspectable; this opts release builds into Chrome DevTools / Safari Web Inspector too. Leave it off in production: the proof WebView holds the user's authenticated session with the data source.

2. Start a flow and render it

Drive the flow with the useVouch hook and render it with 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. Observe the state

state.status moves through idle → launching → processing → proving → success, or ends in error or cancelled (user closed the flow; carries the requestId it ended). Calling startProve again after any terminal state seeds a fresh flow — no explicit reset() needed; reset() returns the machine to idle without starting a new flow.

4. Closing and re-entry

The user can leave the flow from the SDK's own chrome — the close control in the proof browser's header, the close on the video and error screens, or the Android hardware back button on any of those steps. Every one of them ends the flow the same way:

  • Hooks API: the flow lands on the terminal cancelled status, carrying the requestId it ended. Compare that id against your own flow's before acting on it, so a shared provider's stale cancelled from an earlier flow does not move the wrong screen.
  • Modal API: start/startHeadless reject with description: "Vouch flow was closed" and reason 15.

Two stages carry no close of their own: launching, while the proof request loads, and proving, where cancelling would throw away a proof that is nearly finished. In hooks mode nothing interrupts those stages — hardware back falls through to your own navigation, and it is your screen that decides what to do; in modal mode Android back dismisses the modal from any stage. proving continues without the flow UI on screen, so hiding your own screen during it is safe.

Closing discards the attempt — the proof request is not finished, and nothing is uploaded. To let the user try again, call startProve (or start) again; a modal host always starts a fresh proof request that way. Hooks hosts can also pass startProve({ requestId }) with the closed flow's id to re-enter that same proof request from the beginning instead of creating a new one (VouchStartParams has no requestId, so the modal API cannot); WebView cookies survive the close, so the user is usually still signed in to the data source. A request that already produced a proof cannot be reused — start a new one.

Modal API

Hosts migrating from the legacy imperative SDK can use the provider-backed modal API instead of the hook. It presents the flow in a full-screen Modal and resolves a promise, so no VouchScreen is mounted. The provider must carry both customerId and apiKey — without either, start rejects with reason 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?) runs the same flow and takes the same params, but only presents UI during the sniffingRequests stage; it reports progress as downloadingConfig → sniffingRequests → proving → finished.

On iOS, the flow is presented as a full-screen modal over your app's root screen — by start right away, and by startHeadless when it reaches sniffingRequests — and iOS refuses that while your app is already presenting a sheet or modal. Start the flow once any sheet or modal you present has finished dismissing, or from a regular screen, and do not present one from the startHeadless progress callback. If the flow still cannot be shown, both reject after about 6 seconds with reason 16 and the description "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.".

Both reject with a plain VouchError object — { reason, description, proofId? }, not an Error. A user who closes the flow rejects it too, with reason 15 and description: "Vouch flow was closed"; see Closing and re-entry and Error codes.

Cleanup

Call await VouchSDK.destroy() to remove WebView cookies. This works without a mounted provider. On Android it clears the dedicated Vouch WebView profile when the installed provider supports profiles; older providers use the process default cookie store, so cleanup also removes cookies created by host WebViews. On iOS it clears the shared default WebKit cookie store, including cookies created by other WebViews in the host app. It does not clear other website data or cancel an active proof flow.

Video verification (optional)

Some data sources use video verification instead of a cryptographic web proof. Regular web-proof flows need no extra setup, and Android video verification autolinks too. Video verification on iOS additionally requires the SDK's Expo config plugin, which adds the App Group entitlement and the VouchBroadcast screen-recording extension:

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

appGroupIdentifier is optional and defaults to group.<your-bundle-id>.vouch. The plugin changes the native project, so after adding it regenerate the native directories with npx expo prebuild, then rebuild and install the app — npx expo run:ios, or a new EAS build. Reloading JS is not enough to pick up the entitlement.

If a data source runs in video mode and the plugin is missing, the SDK fails the flow immediately with a clear error (and, in development, logs the exact fix) instead of failing after the user has recorded.

Error codes

A modal-API rejection carries a numeric VouchError.reason. Codes 0–14 are unchanged from the legacy SDK:

CodeMeaning
0Data source or customer not found
1Outdated SDK version
2Failed to create verification
3Background timeout
4Request too large
5Data source misconfigured
6Verification failed
7Verification upload failed
8Attachment reupload failed
9Verification ID already taken
10Network connection lost
11Processing timeout
12Wrong API key
13Internal server error
14Provider missing or unconfigured
15User closed the flow
16Flow could not be shown (iOS: the host app is already presenting another screen)
17Provider unmounted before the flow completed
18Another Vouch flow is already active

Code 2 also covers a start or startHeadless call that fails before the flow begins, with a description starting "VouchSDK.start failed". Codes 15–18 have no legacy equivalent. Before 0.1.10, this SDK reported each of those cases, and that start failure, with code 0; from 0.1.10, code 0 means only that the data source or customer was not found.

Migrating from @getvouch/react-native-sdk

The legacy @getvouch/react-native-sdk (latest 0.9.9) wrapped prebuilt native SDKs: the io.getvouch:android-sdk Gradle artifact and the vouch-ios-sdk pod. This package replaces that native stack with React Native and JavaScript over @vouch/prover-mobile-js. It is a different package on a different release line, so there is no version bump that carries you across.

The Modal API exists to keep the rest of the migration small. start, startHeadless, VouchStartParams (dataSourceId, webhookUrl, inputs, metadata), the downloadingConfig → sniffingRequests → proving → finished progress strings, headless showing UI only during sniffingRequests, and the numeric error codes 0–14 all carry over unchanged. VouchSuccess still carries proofId, and now also an optional redirectBackUrl.

What you have to change:

  1. Swap the package and install four peer dependencies. The legacy package peered only react and react-native; this one also needs react-native-safe-area-context, react-native-svg, react-native-video, and react-native-webview (see Requirements).

  2. Replace initialize() with the provider. initialize() and isInitialized() are gone, so VouchSDK.initialize(...) now throws a TypeError. (isSupported() is gone too, though 0.9.9 never actually exported the method its docs described.) Move the same configuration onto VouchVerifierProvider, mounted once at the app root:

    // 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. Rework error handling. VouchError.proofId is now optional: present once a proof request exists, omitted for failures before that, where the legacy SDK sent "" — so error.proofId.length throws. The legacy -1 ("SDK not initialized or internal error") is never emitted; a missing or incompletely configured provider reports 14 instead. A user closing the flow now rejects with 15, not 0, and the other modal-only failures have their own codes 16–18 (see Error codes), so code 0 means only that the data source or customer was not found. And startHeadless now rejects with the same VouchError object as start, where the legacy one rejected with a bare Error carrying no reason or description.

  4. Re-check what destroy() does for you. The legacy destroy() tore down initialization state and forced a fresh initialize(). This one only clears WebView cookies and leaves the mounted provider usable — see Cleanup.

  5. Re-check your platform floors. React Native 0.81.5 – 0.83.x and React 19.1 – 19.2 are enforced peer ranges, where the legacy package accepted anything. Android's minimum drops from API 33 to API 26, and iOS no longer needs use_frameworks! in your Podfile.

版本与发布记录

@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 是什么?

React Native SDK for the Vouch proving flow

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