Installation

The tiun React Native SDK renders the tiun snippet inside a WebView and bridges login and checkout to native, with the user's session bound to a hardware-backed device key.

NPM: @tiun/react-native-sdk

---

Install the SDK

npm

npm install @tiun/react-native-sdk

pnpm

pnpm add @tiun/react-native-sdk

yarn

yarn add @tiun/react-native-sdk

---

Install the native dependencies

The SDK relies on native modules for the WebView, the device key, session storage, and the payment redirect. All of them are peer dependencies — install them alongside the SDK. There are no JavaScript fallbacks; a missing module fails at bundle time.

Package	Role
react-native-webview	Hosts the tiun snippet.
react-native-secure-sign	Hardware-backed device key (Secure Enclave / Android Keystore).
react-native-keychain	Stores the session token in the Keychain / Keystore.
react-native-inappbrowser-nitro	Opens the payment redirect in the in-app browser.
react-native-nitro-modules	Runtime required by the in-app browser.

npm

npm install react-native-webview react-native-secure-sign \
  react-native-keychain react-native-inappbrowser-nitro \
  react-native-nitro-modules

pnpm

pnpm add react-native-webview react-native-secure-sign \
  react-native-keychain react-native-inappbrowser-nitro \
  react-native-nitro-modules

yarn

yarn add react-native-webview react-native-secure-sign \
  react-native-keychain react-native-inappbrowser-nitro \
  react-native-nitro-modules

react-native-webview is verified against 13.x. The SDK's peer range is permissive, but 13.x is the line it's developed and tested against — pin it there unless you have a reason not to.

On iOS, install the pods afterwards:

cd ios && bundle exec pod install

These are native modules, so you need a native rebuild. Adding the SDK is not a JavaScript-only change — rebuild and reinstall the app on your device or emulator after installing.

---

Register the return deep link

After payment, the provider redirects back to your app through a deep link. You pick the URL — for example myapp://tiun/return — pass it to the SDK as returnUrl, and register its scheme in your native config. Checkout cannot complete without it.

Register the same scheme in the dashboard too. In my.tiun.business, go to Settings → Environment setup, turn on App, and enter the scheme (for example myapp://) in the environment you're targeting. Only the scheme has to match — the host and path in your returnUrl are up to you. See setting up your environment.

iOS

Add the scheme to ios/<YourApp>/Info.plist:

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLName</key>
    <string>tiun.checkout.return</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>myapp</string>
    </array>
  </dict>
</array>

Then forward incoming links to React Native's Linking module, which is what the SDK listens on. Add this to ios/<YourApp>/AppDelegate.swift:

// Forward incoming deep links (e.g. myapp://tiun/return) to React Native's
// Linking module so the tiun SDK can resolve checkout on return.
func application(
  _ application: UIApplication,
  open url: URL,
  options: [UIApplication.OpenURLOptionsKey: Any] = [:]
) -> Bool {
  return RCTLinkingManager.application(application, open: url, options: options)
}

Registering the scheme in Info.plist is not enough on its own. Without the RCTLinkingManager forwarding above, iOS hands the return link to your app and it stops there — React Native never sees it, and the checkout doesn't resolve.

Android

Add an intent filter to your main activity in android/app/src/main/AndroidManifest.xml:

<activity
  android:name=".MainActivity"
  android:launchMode="singleTask"
  android:exported="true">

  <intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
  </intent-filter>

  <intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="myapp" android:host="tiun" android:pathPrefix="/return" />
  </intent-filter>
</activity>

android:launchMode="singleTask" is required. Without it, returning from payment starts a second instance of your activity instead of delivering the link to the running app, and the checkout never resolves.

The scheme, host, and path here must match the returnUrl you pass to the SDK. See Configuration.

---

Device requirements

The user's session is bound to a non-exportable key in the device's secure hardware, which affects where you can test.

Target	Login and checkout
Physical iPhone	Works.
iOS Simulator	Not supported — there is no Secure Enclave, so the device key can't be created.
Android emulator	Works.
Physical Android device	Works.

Make sure Metro can actually reach your device. Because iOS testing has to happen on a physical iPhone, your phone and your Mac need to be on a network that lets them talk to each other. Networks with client isolation — most office and guest Wi-Fi — block it, and the symptom is misleading: the app keeps running your last cached bundle, so code changes appear to have no effect and fixes look like they didn't work. If you're debugging something that won't budge, put the phone on Personal Hotspot and confirm the bundle actually reloaded before trusting the result.

On iOS, checkout shows a one-time system prompt — "…wants to use…to sign in". This is expected: it's the only iOS mechanism that can hand a custom-scheme redirect back to your app after payment. Android shows no such prompt.

---

Next: mount the provider and configure it in Configuration.