@virex-tech/paywallo-sdk

Paywalls, subscriptions, analytics and feature flags for React Native.

Install

npm install @virex-tech/paywallo-sdk

iOS:

cd ios && pod install

That's it. The SDK includes its own native modules for storage, device info and StoreKit — no extra dependencies needed.

Optional: Ad tracking (IDFA)

If your app uses Facebook Ads, AppsFlyer or any attribution that needs the Apple IDFA, install the tracking transparency module:

npm install expo-tracking-transparency

This enables the ATT prompt ("Allow this app to track your activity?"). Without it, the SDK skips IDFA collection — everything else works normally.

Quick start

1. Wrap your app

import { PaywalloProvider } from '@virex-tech/paywallo-sdk';

export default function App() {
  return (
    <PaywalloProvider
      config={{
        appKey: 'your_app_key',
        debug: __DEV__,
      }}
    >
      <YourApp />
    </PaywalloProvider>
  );
}

2. Gate content with a paywall

import { PaywalloClient } from '@virex-tech/paywallo-sdk';

const hasAccess = await PaywalloClient.requireSubscriptionWithCampaign('my-campaign');
if (hasAccess) {
  // User has an active subscription or just purchased
}

3. Check subscription status

const isActive = await PaywalloClient.hasActiveSubscription();

Hooks

usePaywallo()

| Property | Type | Description | |---|---|---| | isInitialized | boolean | SDK ready | | isReady | boolean | SDK ready and products loaded | | distinctId | string | Current user ID | | presentCampaign(placement) | Promise<CampaignResult> | Show a campaign paywall | | hasActiveSubscription() | Promise<boolean> | Check subscription status | | getSubscription() | Promise<Subscription> | Get subscription data | | restorePurchases() | Promise<RestoreResult> | Restore previous purchases |

useSubscription()

| Property | Type | Description | |---|---|---| | subscription | Subscription \| null | Current subscription | | hasActiveSubscription | boolean | Whether subscription is active | | isLoading | boolean | Loading state | | refresh() | () => void | Refetch subscription data |

usePurchase()

| Property | Type | Description | |---|---|---| | purchase(productId) | Promise<PurchaseOutcome> | Purchase a product | | restore() | Promise<IAPPurchase[]> | Restore purchases | | isPurchasing | boolean | Purchase in progress | | isRestoring | boolean | Restore in progress | | error | PurchaseError \| null | Last error |

Plans & Offerings

An offering is a group of products configured in the dashboard that you display together on a paywall. You can swap the active offering in the dashboard without shipping a new app version.

useOfferings()

import { useOfferings, useOfferingPurchase } from "@virex-tech/paywallo-sdk";

// Fetch specific offerings by identifier
const { offerings } = useOfferings(["mensal", "anual", "lifetime"]);

// Fetch all offerings
const { offerings } = useOfferings();

// Purchase
const { purchase } = useOfferingPurchase();
purchase(offering.product.productId);

| Property | Type | Description | |---|---|---| | offerings | Offering[] | List of offerings | | isLoading | boolean | Loading state |

useOfferingPurchase()

| Property | Type | Description | |---|---|---| | purchase(productId) | Promise<PurchaseOutcome> | Purchase a product from the offering | | isPurchasing | boolean | Purchase in progress |

Offering type

interface Offering {
  id: string;
  name: string;
  identifier: string;
  isCurrent: boolean;
  product: OfferingProduct;
}

interface OfferingProduct {
  id: string;
  name: string;
  productId: string;           // App Store / Play Store identifier
  priceUsd: number;
  billingPeriod: string;       // "monthly" | "annual" | "lifetime" | ...
  trialDays: number | null;

  // Intro offer (synced automatically from Apple/Google)
  introOfferMode: "FREE_TRIAL" | "PAY_AS_YOU_GO" | "PAY_UP_FRONT" | null;
  introOfferPrice: number | null;
  introOfferCurrency: string | null;
  introOfferCycles: number | null;
}

Example

import { useOfferings, useOfferingPurchase } from "@virex-tech/paywallo-sdk";

function Paywall() {
  const { offerings, isLoading } = useOfferings(["mensal", "anual"]);
  const { purchase, isPurchasing } = useOfferingPurchase();

  if (isLoading) return null;

  return offerings.map(offering => (
    <View key={offering.id}>
      <Text>{offering.product.name} — ${offering.product.priceUsd}</Text>

      {offering.product.introOfferMode === "FREE_TRIAL" && (
        <Text>{offering.product.trialDays}-day free trial</Text>
      )}
      {offering.product.introOfferMode === "PAY_AS_YOU_GO" && (
        <Text>
          {offering.product.introOfferCurrency} {offering.product.introOfferPrice}/period
          for {offering.product.introOfferCycles} cycles
        </Text>
      )}

      <Button
        onPress={() => purchase(offering.product.productId)}
        disabled={isPurchasing}
      >
        Subscribe
      </Button>
    </View>
  ));
}

Intro offers are synced automatically from App Store Connect and Google Play — no manual setup needed.

Imperative API

For use outside React components:

import { PaywalloClient } from '@virex-tech/paywallo-sdk';

// Identify user
await PaywalloClient.identify({ email: '[email protected]' });

// Track events
await PaywalloClient.track('purchase_completed', { properties: { product: 'premium' } });

// Feature flags
const variant = await PaywalloClient.getVariant('new_feature');

// Subscription gate
const hasAccess = await PaywalloClient.requireSubscriptionWithCampaign('premium');

Config options

interface PaywalloConfig {
  appKey: string;        // Required — your app key from the dashboard
  apiUrl?: string;       // API URL (default: https://paywallo.com.br)
  debug?: boolean;       // Enable debug logs (default: false)
  autoStartSession?: boolean;  // Auto-start session on init (default: true)
  sessionFlags?: string[];     // Flags to resolve during session start
}

Types

interface Subscription {
  productId: string;
  status: 'active' | 'expired' | 'cancelled' | 'in_grace_period';
  expiresAt: Date | null;
  platform: 'ios' | 'android';
  autoRenewEnabled: boolean;
}

interface CampaignResult {
  presented: boolean;
  purchased: boolean;
  restored: boolean;
  cancelled: boolean;
  error?: Error;
  skippedReason?: 'subscriber';
}

interface PurchaseOutcome {
  status: 'success' | 'cancelled' | 'failed';
  purchase?: IAPPurchase;
  error?: PurchaseError;
}

License

MIT