RevenueCat (in-app purchases)

The hosted helper

Add one script. It gives your website a single API for both worlds: inside the app it talks to the native store billing through the Native bridge; in a regular browser it loads RevenueCat's browser SDK (@revenuecat/purchases-js) and uses Web Billing. The script is static, needs no sign-in, and loads the browser SDK only when it runs in a browser.

<script src="https://www.webtoapp.app/sdk/webtoapp.js"></script>
<script type="module">
  const wta = await WebToAppSDK.init({
    webBillingApiKey: 'rcb_xxxxxxxxxxxx',  // RevenueCat Web Billing public key (browser only)
    appUserId: currentUser.id,             // same id on every surface; omit for anonymous
  });

  const offerings = await wta.purchases.getOfferings();
  const pkg = offerings.current.packages.find(p => p.packageType === 'monthly');
  try {
    const { customerInfo } = await wta.purchases.purchase({ packageId: pkg.identifier });
    if (customerInfo.activeEntitlements.includes('pro')) unlockPro();
  } catch (e) {
    if (e.code !== 'purchase_cancelled') showError(e.message);
  }
</script>

currentUser, unlockPro and showError stand for your own code. The same code runs in the iOS app, the Android app and the browser, and returns the same data shapes everywhere.

WebToAppSDK.init(options) returns a promise of the client. Options:

What the client offers

Methods that the client does not wrap, such as purchases.getAppUserId and purchases.presentCustomerCenter, are reachable in the app with wta.call(method, params) (see the Native bridge methods). In a browser call rejects with not_in_app.

if (wta.isInApp) {
  // iOS or Android app: store billing. wta.platform is 'ios' or 'android'
} else {
  // regular browser: Web Billing. wta.platform is 'web'
}

const isPro = await wta.purchases.hasEntitlement('pro');

type Store = 'app_store' | 'mac_app_store' | 'play_store' | 'amazon' | 'stripe' | 'rc_billing'
           | 'paddle' | 'promotional' | 'test_store' | 'external' | 'galaxy' | 'unknown';

interface Entitlement {
  id: string;
  isActive: boolean;
  willRenew: boolean;
  productIdentifier: string;
  store: Store;
  periodType: 'normal' | 'intro' | 'trial' | 'prepaid';
  isSandbox: boolean;
  expirationDate: string | null;      // null = lifetime
  latestPurchaseDate: string | null;
  originalPurchaseDate: string | null;
  unsubscribeDetectedAt: string | null;
  billingIssueDetectedAt: string | null;
}

interface CustomerInfo {
  appUserId: string;                   // current RevenueCat App User ID
  originalAppUserId: string;
  isAnonymous: boolean;                // true when the id starts with "$RCAnonymousID:"
  entitlements: { [id: string]: Entitlement };   // all known entitlements, active or not
  activeEntitlements: string[];        // ids with isActive === true
  activeSubscriptions: string[];       // product ids
  managementUrl: string | null;
  firstSeen: string | null;
  requestDate: string | null;
}

interface Product {
  identifier: string;
  title: string;
  description: string | null;
  price: number;                       // major units, e.g. 4.99
  priceString: string;                 // localised, e.g. "$4.99"
  currencyCode: string;                // "USD"
  type: 'subscription' | 'non_subscription' | 'unknown';
  period: string | null;               // ISO-8601 duration ("P1M", "P1Y") or null
  introductoryOffer: null | {
    type: 'free_trial' | 'intro_price';
    price: number; priceString: string;
    period: string | null;             // ISO-8601 per cycle
    cycles: number;
  };
}

interface Package {
  identifier: string;                  // "$rc_monthly", custom ids, …
  packageType: 'lifetime' | 'annual' | 'sixMonth' | 'threeMonth' | 'twoMonth'
             | 'monthly' | 'weekly' | 'custom' | 'unknown';
  offeringIdentifier: string;
  product: Product;
}

interface Offering {
  identifier: string;
  description: string;
  metadata: { [key: string]: unknown };
  packages: Package[];
  webCheckoutUrl: string | null;
}

interface Offerings {
  current: Offering | null;
  all: { [offeringId: string]: Offering };
}

Identify your users

Log your user in with the same id on every surface. That id becomes the RevenueCat App User ID, and it is what makes the entitlement a customer bought in one place available in the others. Until you identify a user, RevenueCat treats them as anonymous (customerInfo.isAnonymous is true).

In the app, automatically (autoIdentify)

With autoIdentify on (the default), the userId message you may already send for push also logs the user in to RevenueCat, and posting null logs them out. No extra code.

if (window.FlutterWebView) {
  // after the user signs in
  window.FlutterWebView.postMessage(JSON.stringify({ type: 'userId', userId: 'user_12345' }));
  // after the user signs out
  window.FlutterWebView.postMessage(JSON.stringify({ type: 'userId', userId: null }));
}

Explicitly, with the helper (app and browser)

await wta.purchases.logIn('user_12345');   // app: Purchases.logIn, browser: changeUser
await wta.purchases.logOut();

// In the app you can also read who RevenueCat thinks the user is
const { appUserId, isAnonymous } = await wta.call('purchases.getAppUserId');

In a browser, pass the same id as appUserId to WebToAppSDK.init, as in the first example. Optionally add attributes to the customer in the app:

await wta.call('purchases.setAttributes', {
  attributes: { plan_hint: 'annual', source: 'landing' },
  email: 'user@example.com',
  displayName: 'Ada'
});

Listen for entitlement changes

The purchases.customerInfoUpdated event carries the latest CustomerInfo. It fires after setup, after every purchase, restore, log in and log out, and whenever RevenueCat reports a change: a renewal, an expiry, a refund, a deferred purchase that was approved. Use it to lock and unlock features.

const stop = wta.purchases.onCustomerInfoUpdated(function (customerInfo) {
  setPro(customerInfo.activeEntitlements.includes('pro'));
});
// stop() to unsubscribe

// Come back from the background? Refresh, someone may have subscribed elsewhere
wta.on('app.foreground', async function () {
  const customerInfo = await wta.purchases.getCustomerInfo();
  setPro(customerInfo.activeEntitlements.includes('pro'));
});

setPro stands for your own code. Without the helper, the same event is WebToApp.on('purchases.customerInfoUpdated', handler). Events are not replayed: a page that loads later should call getCustomerInfo(). Deferred Android purchases surface through this event, not through the purchase promise.

Paywalls and Customer Center

With paywalls on, presentPaywall shows your RevenueCat paywall natively. With requiredEntitlement it only appears if the user does not already have that entitlement. In the app it resolves to { result, customerInfo }, where result is purchased, restored, cancelled, error or notPresented.

const { result, customerInfo } = await wta.purchases.presentPaywall({ requiredEntitlement: 'pro' });
if (result === 'purchased' || result === 'restored') {
  // the user now has "pro"
} else if (result === 'notPresented') {
  // they already had it
}

// Let the user manage or cancel their subscription (app only; resolves when it is closed)
await wta.call('purchases.presentCustomerCenter');

With paywalls off, both app calls (presentPaywall and presentCustomerCenter) fail with paywalls_disabled.

Web payments with RevenueCat Web Billing

1. In RevenueCat, enable Web Billing (or the Stripe integration).
2. Create a Web Billing app and copy its public key, which starts with rcb_.
3. Pass it as webBillingApiKey to WebToAppSDK.init and call purchases.purchase as usual.

const wta = await WebToAppSDK.init({
  webBillingApiKey: 'rcb_xxxxxxxxxxxx',
  appUserId: currentUser.id
});

// In a browser this opens the Web Billing checkout; in the app it opens the store sheet
await wta.purchases.purchase({ packageId: pkg.identifier, customerEmail: currentUser.email });

Remember the store rules above: in the app the helper always uses store billing, never Web Billing.

Handle errors

try {
  await wta.purchases.purchase({ packageId: pkg.identifier });
} catch (e) {
  switch (e.code) {
    case 'purchase_cancelled':          // the user closed the sheet: not an error
      break;
    case 'payment_pending':             // Ask to Buy or a slow payment method
      showMessage('Waiting for approval…');   // the entitlement arrives on onCustomerInfoUpdated
      break;
    case 'product_already_purchased':
      await wta.purchases.restore();
      break;
    default:
      showError(e.message);
  }
}

Web Billing errors are mapped to the same codes as the native ones (for example a cancelled checkout is purchase_cancelled). The generic codes timeout, unsupported_method, invalid_params and unknown are listed in the Native bridge guide.