Migrating from the legacy SDK

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

What carries over unchanged

The Modal API exists to keep the rest of the migration small. All of the following work exactly as they did in the legacy SDK:

• VouchSDK.start(params) and VouchSDK.startHeadless(params, onProgress?)
• The start params: dataSourceId, webhookUrl, inputs, metadata
• The headless progress strings downloadingConfig → sniffingRequests → proving → finished, with UI shown only during sniffingRequests
• The numeric error codes
• 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.

npm uninstall @getvouch/react-native-sdk
npm install @getvouch/mobile-sdk react-native-safe-area-context react-native-svg react-native-video react-native-webview

Then rebuild the native projects (see Build the native projects).

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>;

The Modal API requires both customerId and apiKey on the provider — without either, start rejects with reason 14.

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.
• 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.

After the mechanical migration

The Modal API is a fully supported surface, so you can stop there. When you next touch the integration, consider moving to the hook API — useVouch plus VouchScreen gives you the flow as a screen you place in your own navigation, with observable state instead of a promise.