Display a paywall

The SDK presents the paywall or onboarding flow that Studio shows at a paywall location, drawn natively on iOS and Android. You change what appears at a location in Studio, without an app release. See Paywalls in your app.

Add the paywall renderer

Paywalls are drawn by a native renderer that the published packages don't include yet. Build it from the Voidhash repository, then turn it on in your app. Without it, presenting fails with FLOW_RENDERER_MISSING and the SDK makes no paywall requests.

node scripts/build-voidhash-ui.mjs ios android

{
  "expo": {
    "plugins": [["@voidhash/react-native", { "renderer": true }]]
  }
}

Present it

presentFlow(placement) and usePresentFlow(placement) take a location slug, such as onboarding, despite the parameter's name. They present whatever is shown there and resolve when it ends. They never reject.

import { Button } from "react-native";
import { useRouter } from "expo-router";

import { voidhash } from "../src/lib/voidhash";

export function UpgradeButton() {
  const router = useRouter();
  const { present, isPresenting } = voidhash.usePresentFlow("onboarding");

  return (
    <Button
      disabled={isPresenting}
      title="See plans"
      onPress={async () => {
        const result = await present();
        if (result.status === "failed") router.push("/plans");
      }}
    />
  );
}

Outside React, call the client. A flow already on screen is closed first and resolves as closed. dismissFlow() also cancels a flow that is still loading, so it doesn't appear later.

const result = await voidhash.client.presentFlow("onboarding");
await voidhash.client.dismissFlow(); // closes it; the pending call resolves as closed

Handle the result

An onboarding flow doesn't end on a purchase or restore; it continues to its next screen. It ends with finished or closed and never returns purchased or restored, so check the perk after it ends. A failed or cancelled purchase leaves any flow open, so the user can try again.

A paywall with an On close action in Studio runs it the first time the user tries to close, for example to show a last offer, and presentFlow keeps waiting. dismissFlow() always closes at once.

Purchases from a paywall go through the SDK's purchase path. In observer mode they fail with READ_ONLY_PURCHASE_NOT_ALLOWED, and the paywall shows the failure.

Fall back when nothing was shown

Keep your own upgrade screen for failed, so important entry points always offer a way to upgrade.

To check what a location shows without presenting it, call getPaywallForLocation(slug). It resolves to Ok(null) when nothing is shown there.

Caching and preloading

The device caches what each location shows for up to 7 days, so a location shown before works offline, and a new deploy reaches devices within about an hour. Paywalls in your app explains when it asks Voidhash again.

presentFlow gives a paywall 15 seconds from the call to be ready to show. One that isn't ready by then is never shown: the call resolves as failed with FLOW_UNAVAILABLE, and the download finishes in the background for the next presentation. A paywall on screen has no time limit.

A paywall's images are kept on the device too, up to 64 MB, so a cached paywall shows them while their host can't be reached. The SDK fetches them ahead with the paywall, except on a metered connection such as cellular data. Only http and https images of up to 10 MB are loaded, and only PNG, JPEG, GIF and WebP images are kept. A kept image isn't downloaded again, so publish changed artwork under a new URL.

Locations the device has shown before download again at launch. List new ones in preloadPlacements to download them at launch too:

import { createVoidhashClient } from "@voidhash/react-native";

export const voidhash = createVoidhashClient("vh_pk_...", {
  preloadPlacements: ["onboarding"],
});

Choose what paywalls may do

Purchases, restores, closing, navigation and analytics always work. Other actions need a capability granted with flowCapabilities; by default only links is granted.

import { createVoidhashClient } from "@voidhash/react-native";

export const voidhash = createVoidhashClient("vh_pk_...", {
  flowCapabilities: ["links", "notifications", "attributes"],
});

An action whose capability isn't granted is skipped with a warning. In Expo, declare the requirements under android.permissions and ios.infoPlist in app.json.

Saved progress

A flow saves its variables on the device for each person and flow. Presenting the same flow again restores the variables, not the screen. A Finish flow action clears them, and so do identify() and reset(). A purchase inside an onboarding flow doesn't clear them.

Analytics

Events a paywall records carry paywall_location and paywall_id, and each screen is recorded as a $screen event. A purchase made on a paywall is credited, with its renewals, to the location, paywall and A/B test variant. Purchases made outside a paywall, and restores, aren't credited to one.

Next steps

• Set up paywall locations
• Build onboarding flows
• Check access after a purchase
• Build your own purchase screen