Overview

@voidhash/react-native is the Voidhash SDK for in-app purchases and subscriptions in React Native apps. It talks to the stores natively — StoreKit 2 on iOS and Play Billing on Android — through Nitro Modules, so purchases run in Swift and Kotlin, not in a JavaScript wrapper. On top of the purchase flow it ships a native full-screen paywall presenter that preloads and displays the paywalls you build in Voidhash Studio, and built-in product analytics so purchase events and your own custom events land in the same place.

Everything is verified server-side: the SDK syncs every transaction to Voidhash, and store transactions are only finished/acknowledged after a successful server sync. Your app reads the result — active subscriptions and unlocked perks — from the Person, not from raw store receipts.

Requirements

• Expo development build. The SDK contains native code, so it cannot run in Expo Go. You need a development build (expo-dev-client) or a bare React Native app.
• react-native-nitro-modules@0.26.4 — an exact-version peer dependency. Install precisely this version; a range will not resolve correctly against the SDK's generated native bindings.
• effect and @react-native-async-storage/async-storage (^1.24.0 or ^2.0.0) as peer dependencies. The SDK is built on Effect internally, and AsyncStorage backs its on-device cache.
• Expo modules: expo, expo-constants, and expo-linking are peers used for configuration and deep-link callbacks.
• voidhash-cli (optional) — only needed if you want generated types, so product, perk, and location slugs autocomplete instead of being plain strings.

Get Started

The pages in this section are ordered as a path. Follow them in order:

1. Install the SDK — add @voidhash/react-native and its peer dependencies, then create a development build.
2. Quickstart — create the client with your publishable key, wrap your app in the Provider, and show your first paywall.
3. Check subscription status — read the current person's entitlements and subscriptions to gate features.
4. Identify users (optional) — link the anonymous person to your own user ID once someone signs in.

From there, the rest of the section covers individual features in depth: displaying paywalls, making purchases, feature flags, analytics, observer mode for coexisting with another billing SDK, and error handling.

Main Concepts

A few terms come up on every page. Learn them once here.

Product

Something you sell: a subscription, a one-time purchase, or a one-time-consumable. Each product has a slug you reference in code and per-store configuration mapping it to an App Store product ID and a Google Play product ID (plus base plan for subscriptions). Fetch them with useProducts() — the SDK merges your Voidhash configuration with live store data like localized prices.

Perk (Entitlement)

What a product unlocks. Instead of checking "did they buy the monthly or the yearly plan?", you check "does this person have the premium perk?". Perks decouple your feature gates from your pricing, so you can restructure products without touching gating code. A person's active perks appear as entitlement grants on the Person.

Paywall Location

A named slot in your app where a paywall can appear — for example onboarding or settings. Your code asks for the paywall at a location; which paywall actually shows is decided in Voidhash, so you can swap designs and run experiments without shipping an app update. See Displaying Paywalls.

Person

The user, as Voidhash sees them. Every install starts as an anonymous person with a generated distinct ID; calling identify() links them to your own user ID. The person snapshot carries entitlement grants, the current subscription state, and purchase history — it is the single source of truth for "what does this user have access to". See Identifying Users.

Schema

The definition of your products, perks, and paywall locations. The schema lives on the Voidhash server and is fetched by the SDK at startup — you do not bundle it into the app. For type-safe slugs, voidhash-cli types generate writes a voidhash.gen.d.ts file that turns slug parameters into literal unions; without it everything still works, slugs are just typed as string. See Schema & Types.