Expo Revenuecat Superwall Integration

Expo RevenueCat plus Superwall Integration

Use this skill to add or repair a modern RevenueCat plus Superwall stack in a React Native Expo app.

What this skill should do

• Choose the correct monetisation architecture before editing code.
• Integrate with the repository's existing app shell, auth layer, and state management.
• Prefer safe, production-ready defaults over the shortest possible demo.
• Leave the user with code changes plus a clear list of remaining dashboard, store, and testing steps.

Critical rules

• Treat this as an Expo development-build integration, not an Expo Go integration.
• Target Expo SDK 53 or newer.
• Target iOS deployment target 15.1 or newer and Android min SDK 23 or newer.
• Use public SDK keys only in the client.
• Configure RevenueCat exactly once.
• Mount Superwall near the app root exactly once.
• Use the same stable, non-guessable, non-PII user identifier in RevenueCat and Superwall when the product has authentication.
• Never use email addresses as RevenueCat or Superwall user IDs.
• Do not call syncPurchases() on every launch. Use it only for deliberate migration or account-recovery scenarios.
• restorePurchases() is user-triggered. Do not hide it inside startup code.
• On Android, ensure the launch mode is standard or singleTop.
• Prefer a full app restart after Superwall dashboard changes during Expo development.

First actions

1. Inspect the repository before editing:

• package.json
• app.json, app.config.js, or app.config.ts
• App.tsx or app/_layout.tsx
• any existing auth provider
• any existing purchase, paywall, or entitlement code

2. Run the validator if Python is available:

• python3 scripts/validate_expo_setup.py
• or python3 scripts/validate_expo_setup.py --project-root /path/to/app

3. Answer these six preflight questions before choosing code:

• Is the app login-first, login-optional, or guest-first
• Is there existing purchase completion logic already in the repo
• Does Google Play use multiple base plans or offers
• Are App Store Server Notifications, Google server notifications, webhooks, or backend attribution in scope
• Is the entitlement model single-tier or multi-tier
• Does the product need strict account ownership, or easy restore across account confusion

4. Open only the references you need:

• Core workflow: references/implementation-playbook.md
• Architecture choice: references/architecture-decision-tree.md
• Identity and restores: references/identity-and-restore-behaviour.md
• Android offers: references/android-base-plans-offers-and-pending.md
• iOS UUID and server notifications: references/ios-uuid-appaccounttoken-and-server-notifications.md
• Observability and verification: references/observability-and-entitlement-verification.md
• Test planning: references/testing-matrix.md
• Dashboard alignment: references/dashboard-checklist.md
• Failure modes: references/troubleshooting.md

Architecture choice

Default for most new Expo apps

Choose Architecture A: CustomPurchaseControllerProvider when:

• Superwall is the paywall surface.
• RevenueCat is the purchase and entitlement source of truth.
• The app does not already have its own mature purchase completion pipeline.
• You want the cleanest modern Expo integration.

Use:

• references/architecture-decision-tree.md
• references/examples/monetization.shared.tsx
• references/examples/app.example.tsx
• references/examples/expo-router-layout.example.tsx
• references/examples/custom-purchase-controller.android-offers.tsx

Use the migration path when the repo already owns purchase completion

Choose Architecture B: purchasesAreCompletedBy / observer-mode migration when:

• The app already finishes transactions itself.
• The user explicitly wants to keep existing IAP code.
• You are layering RevenueCat analytics, entitlements, or dashboards onto an existing billing implementation.
• You must import historical purchases carefully.

Use:

• references/architecture-decision-tree.md
• references/examples/observer-mode-migration.tsx
• references/identity-and-restore-behaviour.md

Shared implementation workflow

1. Audit the repo

Collect these facts before changing code:

• Expo SDK version
• package manager
• router style: Expo Router or plain App.tsx
• whether expo-superwall, react-native-purchases, and expo-build-properties are already installed
• current iOS deployment target and Android min SDK
• whether the app has auth
• whether the repo already has RevenueCat, Superwall, StoreKit, Google Play Billing, or react-native-iap code
• whether the project already ships one-time products in addition to subscriptions

2. Align dashboards before deep code edits

Confirm the conceptual setup first:

• RevenueCat project exists for iOS and Android
• store products exist
• entitlements exist
• offerings exist where needed
• Superwall project exists
• Superwall public keys exist for both platforms
• placements and campaigns exist
• product IDs and entitlement IDs match the intended runtime mapping

Use references/dashboard-checklist.md.

3. Install only the packages you actually need

Base stack:

• npx expo install expo-superwall react-native-purchases expo-build-properties

Optional only if the user explicitly wants RevenueCat UI screens such as a customer center:

• npx expo install react-native-purchases-ui

Do not add react-native-purchases-ui just because RevenueCat is installed.

4. Update Expo config

Add or repair expo-build-properties and set platform minimums. Preserve the repository's config style and existing plugins.

5. Configure RevenueCat once

• Use the correct public key for the current platform.
• Configure once on startup.
• If the app always requires a known user ID, prefer configuring with that ID instead of creating an anonymous state first.
• If the app allows guests, configure without an App User ID and later call logIn() when auth resolves.

6. Mount providers once near the root

For Architecture A, the normal order is:

1. configure RevenueCat 2. mount CustomPurchaseControllerProvider 3. mount SuperwallProvider 4. show SuperwallLoading 5. render the app inside SuperwallLoaded 6. mount one subscription sync component inside the loaded tree

7. Sync RevenueCat entitlements into Superwall

When Superwall is not directly owning purchase state, map RevenueCat entitlements into setSubscriptionStatus.

• Fetch CustomerInfo on launch or when premium UI opens.
• Subscribe to addCustomerInfoUpdateListener.
• Map active entitlement IDs into Superwall entitlements.
• Prefer syncing the full entitlement set, not just a boolean.

8. Sync identities deliberately

• Reuse the app's real auth state.
• For login-first apps, prefer configuring RevenueCat with a custom App User ID from the start.
• For guest-first apps, configure anonymously, then on login call Purchases.logIn(userId) and identify(userId).
• If switching from one known account to another, call logIn(newUserId) directly. Do not force a pointless logout first.
• Only call logOut() if the product truly supports an anonymous post-logout state.

See references/identity-and-restore-behaviour.md and references/examples/auth-sync.example.tsx.

9. Register placements from premium entry points

• Use business-action placement names such as upgrade_pro, remove_limits, or export_pdf.
• Prefer placement-driven gating and dashboard audiences over hard-coded paywall branching.
• Use getPresentationResult() only when you need to inspect what Superwall would do before presenting.

10. Add observability

• Forward Superwall events into the app's analytics pipeline.
• Keep debug logs enabled in development only.
• Consider checking RevenueCat trusted entitlement verification in high-risk apps.

See references/observability-and-entitlement-verification.md.

11. Test with a matrix, not one happy path

Always verify:

• cold start on iOS and Android
• purchase success
• cancel flow
• pending flow where relevant
• restore
• guest to logged-in transition
• account switch
• reinstall
• dashboard changes after a full restart
• entitlement unlock in UI
• webhook or server-notification identity consistency when relevant

Use references/testing-matrix.md.

What to avoid

• Do not use expo-superwall/compat for new work.
• Do not promise real Superwall support inside Expo Go.
• Do not call restorePurchases() automatically during startup.
• Do not call syncPurchases() on every launch.
• Do not use emails, IDFA, device IDs, or hardcoded strings as billing IDs.
• Do not leave duplicate purchase flows in place.
• Do not ship Android API 21 just because Superwall alone supports it; the combined stack needs Android 23 or newer.

Final answer expectations

When you finish editing a repo, your response should include:

• the files changed
• the chosen architecture and why
• any manual RevenueCat, Superwall, App Store Connect, or Play Console steps still required
• any assumptions about entitlements, product IDs, placements, restore behaviour, or account model
• any migration debt intentionally left in place
• how to run and test the development build

Android Base Plans, Offers, and Pending Purchases

Google Play subscriptions are often the place where a "working demo" breaks in production.

The problem

Superwall can tell your purchase callback more than just a productId. On Android it can also provide:

• basePlanId
• offerId when present

If you ignore those and simply call purchaseStoreProduct(product), you may buy the wrong option or rely on RevenueCat's default offer selection when the product actually needs explicit control.

Recommended handling

1. Resolve the RevenueCat StoreProduct by productId. 2. Read storeProduct.subscriptionOptions. 3. Build the option identifier from basePlanId plus optional offerId. 4. Find the matching SubscriptionOption. 5. If an explicit match does not exist, decide whether falling back to defaultOption is acceptable. 6. Purchase the selected option using the method exposed by the installed react-native-purchases version. 7. Only report success to Superwall when the returned CustomerInfo has the expected active entitlement.

When fallback to defaultOption is acceptable

Fallback is usually reasonable when:

• the dashboard is meant to choose the default trial or intro offer
• there is no special developer-determined offer logic
• the team is comfortable with RevenueCat selecting the longest free trial or cheapest eligible intro option

Fallback is not ideal when:

• specific Play offers map to specific campaigns or experiments
• you use developer-determined offers
• the business wants exact option control

Pending purchases

Google Play can place a purchase into a pending state, especially with delayed payment methods or family approval.

Treat pending as its own result, not as a clean success.

Suggested behaviour:

• return { type: "pending" } if your integration surface supports it
• otherwise return a clear failure-style message and explain that access will unlock after Google confirms payment
• keep entitlement checks in place because pending does not guarantee active access yet

Purchase success is not the same as entitlement success

Even after a purchase callback returns without throwing:

• inspect the CustomerInfo
• confirm the expected entitlement is active
• if not active, do not quietly mark the purchase as complete inside your app state

This catches configuration problems such as:

• product IDs exist but entitlements are not attached in RevenueCat
• Superwall and RevenueCat products are out of sync
• the wrong base plan or offer was selected
• a pending purchase has not completed yet

Developer-determined offer caveat

If the Play Console uses developer-determined offers, RevenueCat's automatic offer logic can still consider them unless you structure your offer setup carefully. For exact control, manually select the SubscriptionOption you intend to buy.

Implementation pointers

• see examples/custom-purchase-controller.android-offers.tsx
• see the helper functions in examples/monetization.shared.tsx

Debug checklist

If Android purchases behave unexpectedly:

• verify the incoming productId, basePlanId, and offerId
• inspect the resolved RevenueCat StoreProduct
• log the available subscriptionOptions
• confirm the expected entitlement becomes active in CustomerInfo
• confirm the same product and entitlement setup exists in both RevenueCat and Superwall
• confirm the Android main activity launch mode is standard or singleTop

Architecture Decision Tree

This document tells the agent which implementation style to choose.

Start here

Answer these questions in order.

1. Does the repo already complete purchases itself?

If yes, strongly consider Architecture B:

• RevenueCat configured with purchasesAreCompletedBy
• existing purchase code remains in charge
• RevenueCat adds entitlement state, dashboards, analytics, and migration support

If no, continue.

2. Is Superwall the desired paywall surface?

If yes, strongly prefer Architecture A:

• CustomPurchaseControllerProvider
• SuperwallProvider
• RevenueCat as entitlement source of truth
• Superwall for placement, targeting, and paywall presentation

If no, this skill may not be the right fit. The user might instead want RevenueCat UI or another billing surface.

3. Is the app greenfield, or is it migrating an existing billing stack?

• Greenfield or light integration: Architecture A
• Migration, existing transaction completion, or phased rollout: Architecture B

4. Is the app login-first or guest-first?

This does not change the architecture by itself, but it changes identity handling:

• login-first: configure RevenueCat with a custom App User ID immediately when possible
• guest-first: configure anonymously, then logIn() later
• strict-account products: reconsider restore behaviour and avoid logOut() if anonymous state is forbidden

5. Are App Store Server Notifications, Google server notifications, or backend attribution important?

If yes:

• identity design matters more than usual
• keep the same stable user ID across RevenueCat and Superwall
• prefer a UUID v4 style ID
• for iOS, understand appAccountToken fallback behaviour
• for Android, understand whether you need passIdentifiersToPlayStore

Read ios-uuid-appaccounttoken-and-server-notifications.md.

6. Does Google Play use multiple base plans or offers?

If yes, Architecture A still works, but the purchase callback must not just call purchaseStoreProduct(product) blindly. It must inspect basePlanId, optional offerId, and match a RevenueCat subscriptionOption.

Read android-base-plans-offers-and-pending.md.

Recommended defaults

Architecture A: CustomPurchaseControllerProvider

Choose this when:

• building a new Expo subscription stack
• Superwall is the paywall and campaign system
• RevenueCat is the billing source of truth
• the repo does not already own purchase completion
• the team wants the clearest Expo implementation

Key benefits:

• best fit for Superwall's Expo guidance
• modern React component model
• easiest place to route Android base plans and offers
• straightforward entitlement mirroring into Superwall

Main risks:

• forgetting to sync CustomerInfo into Superwall
• assuming Android offers work with a simple product purchase call
• not planning identity and restore behaviour early enough

Architecture B: purchasesAreCompletedBy / observer-mode migration

Choose this when:

• the repo already has purchase completion logic
• the team is migrating to RevenueCat without replacing everything immediately
• the project needs historical import behaviour via syncPurchases()
• changing store-facing billing logic right now would be risky

Key benefits:

• lowest migration risk
• RevenueCat can coexist with existing purchase code
• easier phased rollout in complex production apps

Main risks:

• calling syncPurchases() too often
• forgetting to set the iOS StoreKit version
• unclear ownership of restore flows
• duplicating or conflicting purchase completion paths

Escalate to the user only when truly necessary

Do not stop for small uncertainties. Make the best grounded choice and state the assumption.

Examples:

• If the repo already has react-native-iap receipt handling, default to Architecture B.
• If there is no purchase code and the user explicitly wants Superwall paywalls, default to Architecture A.
• If the repo is authenticated and the team mentions webhooks or server notifications, assume identity strategy is a top-priority design constraint.

Dashboard and Console Checklist

Use this before deep code work and again before release.

RevenueCat

• project created
• iOS app added
• Android app added
• public SDK keys copied for both platforms
• store products imported or created
• products attached to the correct entitlement or entitlements
• offerings created if the app uses them
• restore behaviour chosen intentionally
• any one-time products reviewed for restore implications
• server notifications or webhook settings reviewed if backend attribution matters
• app user ID policy documented for the team

Superwall

• project created
• iOS public key copied
• Android public key copied
• placements created for the premium entry points
• paywalls and campaigns active
• products configured
• entitlements configured and matching the intended runtime mapping
• audience filters reviewed
• user attributes plan reviewed if segmentation matters
• event export or analytics plan reviewed

App Store Connect / Google Play Console

• bundle IDs and package names match the app
• subscription groups or base plans created
• offers configured intentionally
• test accounts prepared
• internal testing track or TestFlight path ready
• business wants exact Google Play offer control or is happy with defaults

Alignment rules between systems

The riskiest bugs usually come from mismatch.

Check:

• product IDs match store reality
• entitlement IDs are consistent with app feature names
• Superwall and RevenueCat both know about the relevant products
• the app knows which entitlement IDs should unlock which features
• if multi-tier, the app understands more than one active entitlement

Identity policy checklist

• guest-first, login-optional, or login-required is documented
• RevenueCat App User ID format is documented
• Superwall user ID format is documented
• iOS UUID requirement is understood when server notifications matter
• Android Play identifier passthrough policy is documented

Identity and Restore Behaviour

This is the highest-risk part of a RevenueCat plus Superwall integration.

Core identity rules

Use the same stable business identity in both systems whenever the product has authentication.

Good identifiers:

• UUID v4
• stable internal opaque IDs
• non-guessable backend-generated IDs

Bad identifiers:

• email addresses
• IDFA or device IDs
• hardcoded strings
• placeholder strings like guest, unknown, 0, or null

If the app already has numeric or human-readable legacy IDs, strongly consider adding a backend UUID mapping layer rather than sending raw legacy IDs everywhere.

RevenueCat identity model

Guest-first products

Recommended flow:

1. configure RevenueCat without appUserID 2. let RevenueCat create an anonymous App User ID 3. when auth resolves, call Purchases.logIn(userId)

Use this when the product allows purchasing before account creation.

Login-first products

Recommended flow:

1. resolve auth before configuring billing 2. configure RevenueCat with a known appUserID 3. do not call logOut() if the product never allows anonymous state

Use this when every purchase must belong to a real account.

Switching from one logged-in account to another

Use:

await Purchases.logIn(nextUserId);

Do not force a logOut() first. That just creates a temporary anonymous ID and adds unnecessary aliasing risk.

Logging out

Only call:

await Purchases.logOut();

when the product genuinely supports a guest state after logout.

If the product is custom-ID-only, do not log the SDK out. Wait until the next user logs in and then call logIn(nextUserId).

Superwall identity model

When auth resolves:

await identify(userId);

When signing out to guest state:

await signOut();

If users frequently reinstall or switch accounts and correct paywall assignments matter immediately, consider the restorePaywallAssignments option on identify. Use it deliberately because it changes paywall startup behaviour.

Restore behaviour in RevenueCat

RevenueCat restore behaviour is a dashboard-level policy. Pick it intentionally.

Default and usually recommended: Transfer to new App User ID

Use when:

• the app is guest-first
• login is optional
• easy recovery matters more than strict account ownership
• the team wants the least painful restore experience

Keep with original App User ID

Use only when:

• every purchaser must have an account
• purchases must never transfer across accounts
• the support team can recover lost account ownership safely

This is stricter and can create support burden.

Important nuance with anonymous users

Anonymous users can be aliased with a known App User ID later. That can be good for guest-first products, but confusing for strict-account products.

Restores versus sync

restorePurchases()

Use only from an explicit user action such as a Restore Purchases button.

Reason:

• it can trigger store account prompts
• it is the user-facing restore path

syncPurchases()

Use only for intentional cases such as:

• importing historical purchases during migration
• syncing past subscriptions after login in observer mode
• specific recovery flows

Do not run it on every launch.

Product-shape recommendations

Login required before purchase

• configure RevenueCat with custom App User ID from the start
• identify the same ID in Superwall
• avoid anonymous sessions
• consider whether Keep with original App User ID is worth the support cost

Login optional

• allow anonymous state
• logIn() when auth appears
• keep default transfer behaviour unless the business has a strong reason not to

Guest-first purchase flow

• anonymous configuration is normal
• users will later alias into known accounts
• make restore UX clear inside settings
• support staff should know how aliases and restores behave

Support and debugging advice

• show the current App User ID in app settings
• keep both RevenueCat and Superwall user IDs visible in debug builds if possible
• note the chosen restore-behaviour policy in the project README or team docs
• if you rely on webhooks or server notifications, verify that the ID observed on the backend matches the intended business user

Implementation Playbook

This is the main workflow for integrating RevenueCat plus Superwall into a React Native Expo app.

1. Preflight audit

Before editing code, answer:

1. Is the app using Expo Router or a plain App.tsx root? 2. Is auth required before purchase, optional, or absent? 3. Is there already purchase code in the repo? 4. Does the product have more than one entitlement tier? 5. Does Google Play use multiple base plans or offers? 6. Are webhooks, App Store Server Notifications, or backend attribution part of the project?

Then inspect:

• package.json
• app.json or app.config.*
• App.tsx or app/_layout.tsx
• auth provider files
• existing monetisation files
• environment handling

2. Choose the architecture

Architecture A: Superwall paywalls plus RevenueCat entitlements via CustomPurchaseControllerProvider

Use this for most new Expo work.

Choose it when:

• Superwall is the paywall UI
• RevenueCat is the billing and entitlement source of truth
• the app does not already own transaction completion
• you want the cleanest modern Expo integration

Architecture B: RevenueCat with purchasesAreCompletedBy and existing IAP code

Use this when:

• the repo already owns purchase completion logic
• the team is migrating an existing billing stack
• the team needs RevenueCat dashboards and entitlements without rewriting all purchase code at once
• you must import historical subscriptions carefully

Read architecture-decision-tree.md before choosing.

3. Install packages

Base install:

npx expo install expo-superwall react-native-purchases expo-build-properties

Optional RevenueCat UI only when explicitly requested:

npx expo install react-native-purchases-ui

Do not add the UI package if Superwall is the only paywall and management surface.

4. Update Expo config

Set minimum platform versions via expo-build-properties.

Example app.config.ts fragment:

export default {
  expo: {
    plugins: [
      [
        "expo-build-properties",
        {
          ios: {
            deploymentTarget: "15.1",
          },
          android: {
            minSdkVersion: 23,
          },
        },
      ],
    ],
  },
};

Also confirm:

• bundle identifiers and package names already exist
• EAS or native build pipeline is configured
• Android main activity launch mode is standard or singleTop

5. Add public environment variables

Typical keys:

EXPO_PUBLIC_REVENUECAT_IOS_API_KEY=appl_xxx
EXPO_PUBLIC_REVENUECAT_ANDROID_API_KEY=goog_xxx
EXPO_PUBLIC_SUPERWALL_IOS_API_KEY=sw_ios_xxx
EXPO_PUBLIC_SUPERWALL_ANDROID_API_KEY=sw_android_xxx

Optional:

EXPO_PUBLIC_DEFAULT_PLACEMENT=upgrade_pro

Never put RevenueCat secret keys or webhook secrets in the client.

6. Implement the root providers

Plain Expo app

Use references/examples/app.example.tsx.

Expo Router app

Use references/examples/expo-router-layout.example.tsx.

Normal root shape for Architecture A:

1. configure RevenueCat once 2. mount CustomPurchaseControllerProvider 3. mount SuperwallProvider 4. render SuperwallLoading 5. render the app inside SuperwallLoaded 6. mount one entitlement sync component inside the loaded tree 7. optionally mount one analytics bridge

Why this order

• RevenueCat should be ready before purchase callbacks run.
• Superwall should load before placements are used.
• Subscription sync should run only once and as close to the root as practical.

7. Configure RevenueCat deliberately

Guest-first apps

• configure without appUserID
• later call Purchases.logIn(userId) on auth success
• on logout, call logOut() only if the app genuinely supports anonymous state

Login-first apps

• configure with the custom App User ID from the start
• avoid generating anonymous IDs at all
• do not call logOut() if every app session must always belong to a known account

Production advice

• enable verbose or debug logging only in development
• reveal the App User ID somewhere in app settings for support
• use a UUID v4 or another non-guessable stable identifier
• never use an email address

8. Implement Architecture A purchase handling

Inside CustomPurchaseControllerProvider:

• resolve the requested RevenueCat StoreProduct using productId
• for Android subscriptions, use basePlanId and optional offerId to pick a matching subscriptionOption
• fall back to the product's default option only when appropriate
• call purchaseStoreProduct on iOS or when there is no special Android option selection
• return cancelled, pending, or failed explicitly when needed
• after purchase, check the resulting CustomerInfo
• only treat the purchase as successful when the expected entitlement state is active

See:

• examples/monetization.shared.tsx
• examples/custom-purchase-controller.android-offers.tsx
• android-base-plans-offers-and-pending.md

9. Implement Architecture B migration path

Use this only when the repo already owns purchase completion.

• configure RevenueCat with purchasesAreCompletedBy
• on iOS, set the StoreKit version to match the app
• keep the existing purchase completion logic
• call syncPurchases() after login or migration checkpoints, not every launch
• audit restore behaviour carefully before shipping

See examples/observer-mode-migration.tsx.

10. Sync entitlements into Superwall

This step is easy to miss and causes "purchase succeeded but app is still locked" bugs.

Recommended pattern:

• call Purchases.getCustomerInfo() on launch and when premium areas open
• add Purchases.addCustomerInfoUpdateListener(...)
• map customerInfo.entitlements.active keys into Superwall entitlements
• pass ACTIVE, INACTIVE, or UNKNOWN as appropriate

Prefer syncing the full entitlement set instead of just isSubscribed.

11. Sync identities across both systems

When auth resolves:

• RevenueCat: logIn(userId) or configure with appUserID
• Superwall: identify(userId)

When switching known account A to known account B:

• call logIn(nextUserId) directly
• call identify(nextUserId) directly
• do not force a pointless logOut() first

When signing out to guest state:

• RevenueCat: logOut() only if guest mode is real and desired
• Superwall: signOut()

When account switching or reinstall-heavy usage makes paywall assignment restoration important, consider Superwall's restorePaywallAssignments identity option. Use it intentionally, not by default.

12. Register placements

Examples:

• upgrade_pro
• export_pdf
• voice_clone
• remove_generation_limit

Recommendations:

• use one placement per business action
• keep names dashboard-friendly
• do not pre-emptively block every call with manual entitlement checks
• let Superwall audiences and entitlements decide whether to show a paywall when possible
• use getPresentationResult() when you need to inspect what would happen before presenting

See examples/premium-gate.example.tsx.

13. Add observability

Implement at least one of these:

• Superwall event forwarding via useSuperwallEvents
• analytics forwarding for paywall shown, purchase started, purchase result, restore started, restore result
• RevenueCat debug logging in development
• optional entitlement verification checks for high-risk products

14. Test with a real matrix

Use testing-matrix.md. Minimum cases:

• iOS purchase success
• Android purchase success
• cancel flow
• pending flow
• restore flow
• guest-to-authenticated upgrade
• authenticated purchase on a second account
• reinstall and restore
• full restart after dashboard changes
• webhook or server-notification identity checks when applicable

15. Final delivery checklist

When editing the user's repo, finish with:

• changed file list
• chosen architecture and why
• manual dashboard and console work still required
• assumptions and open questions
• exact run command for the development build
• test steps that cover the riskiest path first

iOS UUID, appAccountToken, and Server Notifications

This document matters whenever the project cares about backend attribution, webhooks, or server notifications.

Why this exists

On iOS, Superwall supplies an appAccountToken with StoreKit 2 transactions.

That sounds great, but there is a crucial nuance:

• if you call identify(userId) with a valid UUID, that UUID can flow through as the appAccountToken
• if you have not identified yet, Superwall uses the anonymous alias UUID
• if you pass a non-UUID user ID, StoreKit rejects it and Superwall falls back to the alias UUID

This means the backend-observed identifier can differ from the app-level ID unless identity is designed carefully.

Strong recommendation

If the project uses any of the following:

• App Store Server Notifications
• RevenueCat server-side purchase tracking
• custom attribution
• backend entitlement reconciliation
• webhook-driven account linking

then use the same stable UUID v4 for:

• the app's billing identity
• RevenueCat App User ID
• Superwall identify ID

If the existing backend uses some other primary key, add a UUID mapping layer.

RevenueCat interaction

RevenueCat warns that when using server-to-server tracking together with appAccountToken or obfuscatedExternalAccountId, those values should match the RevenueCat App User ID and that ID should be a valid UUID v4.

This is one of the most important production details in the whole integration.

What to do in practice

Login-first app

• generate or fetch the user's stable UUID before billing initialisation
• configure RevenueCat with that App User ID
• call Superwall identify() with the same UUID before the user purchases

Guest-first app

• accept that early anonymous transactions may carry an alias UUID
• when the user later logs in, aliasing can still work, but historical server-side attribution may point at the earlier anonymous identifier
• if this is unacceptable, redesign the product flow so billing only begins after a known UUID exists

Android note

If the business needs the Play-side identifier to map cleanly back to the app user, review whether Superwall should pass identifiers through to Google Play on Android. This is useful, but only if the identifier policy is compatible with exposing that stable opaque ID.

Webhook troubleshooting checklist

If webhook or server-notification identities look wrong:

• confirm identify() runs before any purchase
• confirm the identifier is a UUID
• confirm the same value is used in RevenueCat and Superwall
• confirm Android identifier passthrough settings if testing Google Play
• update old SDK versions before debugging historical mismatches
• remember that historical purchases made before the identity fix may remain attached to the old alias identity

Suggested team policy

Write this into the project docs:

• the canonical billing user ID format
• whether the app allows anonymous purchases
• whether server notifications are enabled
• whether Android Play-side identifier passthrough is enabled
• what support should do when a webhook points at an older alias ID

Observability and Entitlement Verification

A production integration should be observable, not just compilable.

Minimum observability

Add these in development at least:

• RevenueCat debug or verbose logging
• Superwall placement callbacks or useSuperwallEvents
• logs for current billing identity after auth changes
• logs for active entitlements after CustomerInfo updates

Forward Superwall events to analytics

Useful events to forward:

• paywall will present
• paywall did present
• paywall dismissed
• paywall skipped
• purchase started
• purchase result
• restore started
• restore result
• subscription status changed
• custom paywall action tapped

These events are valuable for:

• funnel analysis
• experiment validation
• debugging
• support

Suggested analytics payload shape

Keep a consistent envelope:

type BillingAnalyticsEvent = {
  name: string;
  appUserId?: string | null;
  superwallUserId?: string | null;
  placement?: string;
  paywallId?: string;
  productId?: string;
  entitlementIds?: string[];
  result?: "presented" | "dismissed" | "purchased" | "restored" | "failed" | "cancelled" | "pending";
  platform: "ios" | "android";
};

RevenueCat trusted entitlements

Trusted Entitlements can provide integrity verification data for entitlement responses.

Important nuance:

• newer RevenueCat SDKs provide verification data by default
• the result is informational only unless the app actually checks it
• RevenueCat does not automatically block unverified entitlements for you

Use this when the app has a strong fraud or tampering risk model.

Sensible default policy

For most apps:

• log the verification result in debug builds
• keep access decisions based on normal entitlement state
• escalate to stricter handling only if the business has a clear need

For high-risk apps:

• inspect the verification result
• decide whether unverified entitlements should reduce access or trigger review
• coordinate this with backend policy, not just the mobile app

Other useful signals

Also log:

• current App User ID
• current Superwall identified user
• active offering and product IDs during test purchases
• current restore-behaviour policy in team docs
• launch mode on Android when debugging odd cancellation paths

Example wiring

See examples/monetization.shared.tsx for a simple event bridge shape and examples/premium-gate.example.tsx for placement-level hooks.

Source Notes for Maintainers

This skill was revised as v2 on 2026-03-08.

Key documentation reviewed while preparing this version:

Agent Skills resources

• agentskills.io home and what-are-skills pages
• agentskills.io specification
• BEST_PRACTICES_FOR_WRITING_AND_USING_SKILLS_MD_FILES.md
• the bundled PDF guide about building skills

Key skill-specific takeaways applied here:

• keep SKILL.md focused
• push detailed material into references/
• make the description explicit about what and when
• keep the folder in kebab-case and include SKILL.md exactly
• include examples, references, validation help, and a zipped deliverable

Superwall resources

Reviewed areas included:

• Expo install and development-build requirements
• RevenueCat integration guide
• subscription-state tracking
• user management
• webhook and original-app-user-id troubleshooting
• placement troubleshooting
• analytics and useSuperwallEvents
• CustomPurchaseControllerProvider docs

RevenueCat resources

Reviewed areas included:

• Expo and React Native installation
• identifying customers
• restoring purchases
• restore behaviour
• trusted entitlements
• observer mode / purchasesAreCompletedBy
• Test Store and sandbox guidance
• Billing Client 8 restore issue notes

Intent of v2

The main improvement over v1 is that the skill is now decision-led rather than happy-path-only. It explicitly teaches the agent to reason about:

• architecture choice
• identity model
• restore policy
• Android base plans and offers
• iOS UUID and server-notification consequences
• observability
• test coverage

Testing Matrix

Do not ship based on one successful sandbox purchase.

Build setup checks

Before purchase testing:

• development build works on iOS and Android
• public SDK keys load correctly per platform
• app compiles with the chosen architecture
• at least one placement is active in Superwall
• products and entitlements exist in RevenueCat
• test users are ready in sandbox or test store as needed

Recommended environments

Early code validation

Use:

• development builds
• RevenueCat Test Store when appropriate
• mocked or internal analytics

Pre-release validation

Use:

• iOS sandbox or TestFlight test accounts
• Google Play internal testing or closed testing
• real purchase flows through store sandboxes
• backend logging if server notifications or webhooks matter

Scenario matrix

A. App startup

1. cold start without auth 2. cold start with known authenticated user 3. cold start after reinstall 4. full restart after changing Superwall placements or campaigns

Expected results:

• providers initialise once
• no duplicate purchase listeners
• no placement-not-found surprises after a restart
• entitlement sync runs once

B. Purchase flows

1. successful purchase on iOS 2. successful purchase on Android 3. user-cancelled purchase 4. network or store failure 5. pending Android purchase 6. purchase completes but entitlement is misconfigured

Expected results:

• success unlocks the correct entitlement
• cancellation is not shown as success
• pending does not falsely unlock premium access
• misconfigured entitlements are visible in logs and UI state

C. Restore flows

1. explicit Restore Purchases button tapped by a guest user 2. restore on a signed-in user 3. restore after reinstall 4. restore when transfer behaviour matters across two accounts

Expected results:

• restore is user-triggered
• entitlement state updates correctly
• account ownership behaviour matches the chosen RevenueCat restore policy

D. Identity transitions

1. guest uses app, then logs in 2. user A signs out to guest state 3. user A switches directly to user B 4. login-first app launches with custom ID from the start

Expected results:

• same ID is used in RevenueCat and Superwall
• direct account switch does not create unnecessary anonymous IDs
• support can inspect the active billing identity

E. Webhook and attribution checks

Only for projects that need them.

1. make a fresh purchase after identify() 2. inspect backend webhook or server-notification payload 3. compare app identity, RevenueCat App User ID, and server-observed identifier 4. repeat with Android if Play-side identifier passthrough matters

Expected results:

• backend identifiers match the intended user model
• UUID expectations are met on iOS
• historical purchases made before the identity fix are understood and documented

Release gate

Before sign-off, the project should be able to answer:

• which architecture is in use and why
• whether guest purchases are allowed
• which restore behaviour is configured in RevenueCat
• whether webhooks and server notifications rely on UUID billing IDs
• which entitlements unlock which features
• how support staff can find a user's App User ID

Troubleshooting

1. The app builds in Expo Go but monetisation does not work

Expected. The combined integration should be treated as a development-build setup, not a real Expo Go path.

Fix:

• create a development build
• confirm native modules are installed
• if native folders are stale, consider a clean prebuild path before rebuilding

2. PlacementNotFound for a placement that exists in the dashboard

In Expo development, Superwall dashboard changes do not hot-reload into the running app.

Fix:

• completely quit the development app
• relaunch the app
• then retry the placement

3. Purchase succeeded but premium UI stayed locked

Common causes:

• entitlement sync into Superwall is missing
• the wrong entitlement IDs are being mapped
• products exist in one dashboard but not the other
• entitlements do not match exactly
• Android selected the wrong base plan or offer
• the purchase is pending, not active

Fix:

• inspect CustomerInfo.entitlements.active
• inspect what setSubscriptionStatus receives
• confirm Superwall and RevenueCat dashboard products and entitlements align
• inspect Android basePlanId and offerId

4. Webhooks or server notifications show the wrong user

Common causes:

• identify() ran after the first purchase
• the billing ID is not a UUID on iOS
• old SDK versions are still in use
• Android identifier passthrough is not configured as intended
• historical purchases happened before the identity fix

Fix:

• identify before purchase
• use the same UUID billing ID in RevenueCat and Superwall
• update SDK versions
• document that old historical purchases may remain linked to alias IDs

5. Account switching creates confusing identity states

Common cause:

• logging out RevenueCat before logging in the next known account

Fix:

• when switching account A to account B, call logIn(nextUserId) directly
• call Superwall identify(nextUserId) directly
• only use logOut() when the product really supports guest state

6. Restore behaves differently than expected

Common causes:

• the RevenueCat restore-behaviour setting was never chosen intentionally
• the team expects strict account ownership but the dashboard is still on the default transfer model
• the product is guest-first but support expects login-first semantics

Fix:

• review identity-and-restore-behaviour.md
• confirm the dashboard setting
• document the chosen policy for support

7. Android purchase gets cancelled when the app backgrounds

Common cause:

• main activity launch mode is incompatible with Play verification flows

Fix:

• ensure Android launch mode is standard or singleTop

8. Existing subscribers do not show up after migration

Common cause:

• RevenueCat was added in observer mode or purchasesAreCompletedBy mode but no migration sync ran

Fix:

• call syncPurchases() after the user logs in or during a deliberate migration checkpoint
• do not add it to every app launch

9. Restoring old consumables or one-time purchases on Android is inconsistent

Common cause:

• the app uses affected versions around Google Billing Client 8 and older RevenueCat fixes are missing

Fix:

• upgrade react-native-purchases
• if one-time products matter, test reinstall and restore flows explicitly
• do not assume subscription testing covers one-time product recovery

10. The app seems right but dashboard targeting still feels wrong

Common causes:

• placements are too generic
• user attributes are missing
• the team manually gates too much in code and bypasses audience logic

Fix:

• register business-action placements
• set useful user attributes
• let Superwall audience targeting and entitlements do more of the work