# Welcome
Source: https://superwall.com/docs/react-native/index

Welcome to the Superwall React Native SDK documentation

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Quick Links

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="hammer" href="/react-native/sdk-reference">
    Reference the Superwall React Native SDK
  </Card>

  <Card title="Migration Guide" icon="ArrowRight" href="/expo/guides/migrating-react-native">
    Step-by-step migration guide to the new Expo SDK
  </Card>

  <Card title="Expo SDK Docs" icon="sparkles" href="/expo">
    Documentation for the recommended Expo SDK
  </Card>
</CardGroup>

## Feedback

We are always improving our SDKs and documentation!

If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.

<SdkLatestVersion version="4.1.7" repoUrl="https://github.com/superwall/react-native-superwall" />


---

# PaywallOptions
Source: https://superwall.com/docs/react-native/sdk-reference/PaywallOptions

Options for configuring the appearance and behavior of paywalls.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Options for configuring the appearance and behavior of paywalls. Use this to customize how paywalls are presented and how purchase failures are handled.

<Note>
  `PaywallOptions` (and its `RestoreFailed` helper) do not take constructor arguments. Create an instance, then set properties directly.
</Note>

## Signature

```typescript
export class PaywallOptions {
  isHapticFeedbackEnabled = true
  restoreFailed: RestoreFailed = new RestoreFailed()
  shouldShowPurchaseFailureAlert = true
  shouldPreload = false
  automaticallyDismiss = true
  transactionBackgroundView: TransactionBackgroundView = TransactionBackgroundView.spinner
}
```

## Properties

<ParamTable>
  | Property                         | Type                        | Description                                                                                                                                          |
  | -------------------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `isHapticFeedbackEnabled`        | `boolean`                   | Whether haptic feedback is enabled when interacting with paywalls. Defaults to `true`.                                                               |
  | `restoreFailed`                  | `RestoreFailed`             | Configuration for the alert shown when restore purchases fails.                                                                                      |
  | `shouldShowPurchaseFailureAlert` | `boolean`                   | Whether to show an alert when a purchase fails. Defaults to `true`.                                                                                  |
  | `shouldPreload`                  | `boolean`                   | Whether paywalls should be preloaded. If `false`, you can manually preload using `preloadAllPaywalls()` or `preloadPaywalls()`. Defaults to `false`. |
  | `automaticallyDismiss`           | `boolean`                   | Whether paywalls should automatically dismiss after a successful purchase. Defaults to `true`.                                                       |
  | `transactionBackgroundView`      | `TransactionBackgroundView` | The view to show behind Apple's payment sheet during a transaction. Options: `spinner`, `none`. Defaults to `spinner`.                               |
</ParamTable>

## Usage

Create paywall options:

```typescript
import { PaywallOptions, TransactionBackgroundView, RestoreFailed } from "@superwall/react-native-superwall"

const paywallOptions = new PaywallOptions()
paywallOptions.isHapticFeedbackEnabled = true
paywallOptions.shouldShowPurchaseFailureAlert = false
paywallOptions.shouldPreload = true
paywallOptions.automaticallyDismiss = true
paywallOptions.transactionBackgroundView = TransactionBackgroundView.spinner

const restoreFailed = new RestoreFailed()
restoreFailed.title = "No Subscription Found"
restoreFailed.message = "We couldn't find an active subscription for your account."
restoreFailed.closeButtonTitle = "Okay"

paywallOptions.restoreFailed = restoreFailed

const superwallOptions = new SuperwallOptions({
  paywalls: paywallOptions
})

await Superwall.configure({
  apiKey: "pk_your_api_key",
  options: superwallOptions
})
```

## RestoreFailed

Customize the alert shown when restore purchases fails:

```typescript
const restoreFailed = new RestoreFailed()
restoreFailed.title = "No Subscription Found"
restoreFailed.message = "We couldn't find an active subscription for your account."
restoreFailed.closeButtonTitle = "Okay"

const paywallOptions = new PaywallOptions()
paywallOptions.restoreFailed = restoreFailed
```

## Transaction Background View

Control what appears behind Apple's payment sheet:

```typescript
// Show a spinner (default)
const options1 = new PaywallOptions({
  transactionBackgroundView: TransactionBackgroundView.spinner
})

// Show nothing
const options2 = new PaywallOptions({
  transactionBackgroundView: TransactionBackgroundView.none
})
```

## Related

* [`SuperwallOptions`](/react-native/sdk-reference/SuperwallOptions) - Main SDK configuration options
* [`preloadAllPaywalls()`](/react-native/sdk-reference/Superwall) - Manually preload all paywalls
* [`preloadPaywalls()`](/react-native/sdk-reference/Superwall) - Manually preload specific paywalls


---

# PaywallPresentationHandler
Source: https://superwall.com/docs/react-native/sdk-reference/PaywallPresentationHandler

Handles events related to paywall presentation.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Handles events related to paywall presentation. Use this to receive callbacks about the paywall lifecycle when registering a placement.

## Signature

```typescript
export class PaywallPresentationHandler {
  onPresentHandler?: (info: PaywallInfo) => void
  onDismissHandler?: (info: PaywallInfo, result: PaywallResult) => void
  onErrorHandler?: (error: string) => void
  onSkipHandler?: (reason: PaywallSkippedReason) => void

  onPresent(handler: (info: PaywallInfo) => void): void
  onDismiss(handler: (info: PaywallInfo, result: PaywallResult) => void): void
  onError(handler: (error: string) => void): void
  onSkip(handler: (reason: PaywallSkippedReason) => void): void
}
```

## Methods

<ParamTable>
  | Method      | Parameters                                                    | Description                                                                     |
  | ----------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------- |
  | `onPresent` | `handler: (info: PaywallInfo) => void`                        | Sets a handler that is called when a paywall is presented.                      |
  | `onDismiss` | `handler: (info: PaywallInfo, result: PaywallResult) => void` | Sets a handler that is called when a paywall is dismissed.                      |
  | `onError`   | `handler: (error: string) => void`                            | Sets a handler that is called when an error occurs during paywall presentation. |
  | `onSkip`    | `handler: (reason: PaywallSkippedReason) => void`             | Sets a handler that is called when a paywall is skipped (not shown).            |
</ParamTable>

## Usage

Create a handler and use it when registering a placement:

```typescript
import { PaywallPresentationHandler, PaywallResult, PaywallSkippedReason } from "@superwall/react-native-superwall"

const handler = new PaywallPresentationHandler()

handler.onPresent((info) => {
  console.log("Paywall presented:", info.name)
  // Pause video, hide UI, etc.
  pauseBackgroundTasks()
})

handler.onDismiss((info, result: PaywallResult) => {
  console.log("Paywall dismissed with result:", result.type)
  // Resume video, show UI, etc.
  resumeBackgroundTasks()
  
  if (result.type === "purchased") {
    console.log("User purchased!")
  } else if (result.type === "declined") {
    console.log("User dismissed without purchasing")
  } else if (result.type === "restored") {
    console.log("User restored a purchase")
  }
})

handler.onError((error) => {
  console.error("Paywall error:", error)
  // Handle error
})

handler.onSkip((reason) => {
  console.log("Paywall skipped:", reason)
  // Handle skip reason
})

// Use the handler when registering
Superwall.shared.register({
  placement: "premium_feature",
  handler: handler,
  feature: () => {
    // Feature code
  }
})
```

## Handler Callbacks

* **onPresent**: Called when a paywall is successfully presented to the user.
* **onDismiss**: Called when a paywall is dismissed. The `result` parameter has a `type` of `purchased`, `declined`, or `restored`.
* **onError**: Called when an error occurs during paywall presentation or loading.
* **onSkip**: Called when a paywall is skipped (not shown) for various reasons (user already subscribed, no audience match, etc.).

## Related

* [`register()`](/react-native/sdk-reference/register) - Register a placement with a handler
* [`PaywallResult`](/react-native/sdk-reference/types) - Result types for paywall dismissal
* [`PaywallSkippedReason`](/react-native/sdk-reference/types) - Reasons why a paywall might be skipped


---

# PurchaseController
Source: https://superwall.com/docs/react-native/sdk-reference/PurchaseController

An abstract class that defines the contract for a purchase controller.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Abstract class that defines the contract for a purchase controller. This is used for custom purchase handling when you want to manage all subscription-related logic yourself.

## Signature

```typescript
export abstract class PurchaseController {
  abstract purchaseFromAppStore(productId: string): Promise<PurchaseResult>
  abstract purchaseFromGooglePlay(
    productId: string,
    basePlanId?: string,
    offerId?: string
  ): Promise<PurchaseResult>
  abstract restorePurchases(): Promise<RestorationResult>
}
```

## Methods

<ParamTable>
  | Method                   | Parameters                             | Description                                                                                                   |
  | ------------------------ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
  | `purchaseFromAppStore`   | `productId`                            | Purchase a product from the App Store. Returns a Promise that resolves with the result of the purchase logic. |
  | `purchaseFromGooglePlay` | `productId`, `basePlanId?`, `offerId?` | Purchase a product from Google Play. Returns a Promise that resolves with the result of the purchase logic.   |
  | `restorePurchases`       | -                                      | Restore purchases. Returns a Promise that resolves with the restoration result.                               |
</ParamTable>

## Usage

Implement the `PurchaseController` class:

```typescript
import { PurchaseController, PurchaseResult, RestorationResult, PurchaseResultCancelled, PurchaseResultFailed, PurchaseResultPurchased } from "@superwall/react-native-superwall"

class MyPurchaseController extends PurchaseController {
  async purchaseFromAppStore(productId: string): Promise<PurchaseResult> {
    try {
      // Your iOS purchase logic here
      // For example, using RevenueCat:
      const purchase = await Purchases.purchaseProduct(productId)
      
      if (purchase.customerInfo.entitlements.active["pro"]) {
        return new PurchaseResultPurchased()
      } else {
        return new PurchaseResultFailed("Purchase completed but entitlement not active")
      }
    } catch (error) {
      if (error.userCancelled) {
        return new PurchaseResultCancelled()
      }
      return new PurchaseResultFailed(error.message)
    }
  }
  
  async purchaseFromGooglePlay(
    productId: string,
    basePlanId?: string,
    offerId?: string
  ): Promise<PurchaseResult> {
    try {
      // Your Android purchase logic here
      // For example, using RevenueCat:
      const purchase = await Purchases.purchaseProduct(productId)
      
      if (purchase.customerInfo.entitlements.active["pro"]) {
        return new PurchaseResultPurchased()
      } else {
        return new PurchaseResultFailed("Purchase completed but entitlement not active")
      }
    } catch (error) {
      if (error.userCancelled) {
        return new PurchaseResultCancelled()
      }
      return new PurchaseResultFailed(error.message)
    }
  }
  
  async restorePurchases(): Promise<RestorationResult> {
    try {
      // Your restore logic here
      // For example, using RevenueCat:
      const customerInfo = await Purchases.restorePurchases()
      
      if (customerInfo.entitlements.active["pro"]) {
        return RestorationResult.restored()
      } else {
        return RestorationResult.failed("No active subscription found")
      }
    } catch (error) {
      return RestorationResult.failed(error.message)
    }
  }
}
```

Configure Superwall with your purchase controller:

```typescript
await Superwall.configure({
  apiKey: "pk_your_api_key",
  purchaseController: new MyPurchaseController()
})
```

## Important Notes

* When using a `PurchaseController`, you must call [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) whenever the user's entitlements change.
* The purchase controller is responsible for handling all purchase and restore logic.
* You can use third-party services like RevenueCat, Stripe, or your own backend to handle purchases.

## Related

* [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Update subscription status after purchases
* [`SuperwallDelegate.subscriptionStatusDidChange`](/react-native/sdk-reference/SuperwallDelegate) - Receive subscription status change notifications


---

# Superwall
Source: https://superwall.com/docs/react-native/sdk-reference/Superwall

The shared instance of Superwall that provides access to all SDK features.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

<Note>
  You must call [`configure()`](/react-native/sdk-reference/configure) before accessing `Superwall.shared`, otherwise your app may crash or behave unexpectedly.
</Note>

## Purpose

Provides access to the configured Superwall instance after calling [`configure()`](/react-native/sdk-reference/configure).

## Signature

```typescript
static get shared(): Superwall
```

## Parameters

This is a static property with no parameters.

## Returns / State

Returns the shared `Superwall` instance that was configured via [`configure()`](/react-native/sdk-reference/configure).

## Usage

Configure first (typically in your app's entry point):

```typescript
import Superwall from "@superwall/react-native-superwall"

await Superwall.configure({
  apiKey: "pk_your_api_key"
})
```

Then access throughout your app:

```typescript
Superwall.shared.register({
  placement: "feature_access",
  feature: () => {
    // Feature code here
  }
})
```

Set user identity and attributes:

```typescript
await Superwall.shared.identify({
  userId: "user123"
})

await Superwall.shared.setUserAttributes({
  plan: "premium",
  signUpDate: new Date()
})
```

Set delegate:

```typescript
import { SuperwallDelegate } from "@superwall/react-native-superwall"

class MyDelegate extends SuperwallDelegate {
  subscriptionStatusDidChange(from, to) {
    console.log(`Subscription status changed from ${from} to ${to}`)
  }
}

await Superwall.shared.setDelegate(new MyDelegate())
```

## Main Methods

* [`register()`](/react-native/sdk-reference/register) - Register a placement to trigger paywalls
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user
* [`getUserAttributes()`](/react-native/sdk-reference/getUserAttributes) - Get user attributes
* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes
* [`handleDeepLink()`](/react-native/sdk-reference/handleDeepLink) - Handle deep links
* [`getSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Get subscription status
* [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Set subscription status


---

# SuperwallDelegate
Source: https://superwall.com/docs/react-native/sdk-reference/SuperwallDelegate

A class that handles Superwall lifecycle events and analytics.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

<Note>
  Set the delegate using `Superwall.shared.setDelegate(delegate)` to receive these callbacks.
</Note>

<Tip>
  Use `handleSuperwallEvent(eventInfo)` to track Superwall analytics events in your own analytics platform for a complete view of user behavior.
</Tip>

<Warning>
  `SuperwallDelegate` is an abstract class—all methods are required. Provide no-op implementations for callbacks you do not use.
</Warning>

## Purpose

Provides callbacks for Superwall lifecycle events, analytics tracking, and custom paywall interactions.

## Signature

```typescript
export abstract class SuperwallDelegate {
  abstract subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus): void
  abstract willRedeemLink(): void
  abstract didRedeemLink(result: RedemptionResult): void
  abstract handleSuperwallEvent(eventInfo: SuperwallEventInfo): void
  abstract handleCustomPaywallAction(name: string): void
  abstract willDismissPaywall(paywallInfo: PaywallInfo): void
  abstract willPresentPaywall(paywallInfo: PaywallInfo): void
  abstract didDismissPaywall(paywallInfo: PaywallInfo): void
  abstract didPresentPaywall(paywallInfo: PaywallInfo): void
  abstract paywallWillOpenURL(url: URL): void
  abstract paywallWillOpenDeepLink(url: URL): void
  abstract handleLog(
    level: string,
    scope: string,
    message?: string,
    info?: Map<string, any>,
    error?: string
  ): void
}
```

## Methods

All methods must be implemented (you can provide empty bodies). Key methods include:

<ParamTable>
  | Method                        | Parameters                                   | Description                                                                       |
  | ----------------------------- | -------------------------------------------- | --------------------------------------------------------------------------------- |
  | `subscriptionStatusDidChange` | `from`, `to`                                 | Called when subscription status changes.                                          |
  | `handleSuperwallEvent`        | `eventInfo`                                  | Called for all internal analytics events. Use for tracking in your own analytics. |
  | `handleCustomPaywallAction`   | `name`                                       | Called when user taps elements with `data-pw-custom` tags.                        |
  | `willPresentPaywall`          | `paywallInfo`                                | Called before paywall presentation.                                               |
  | `didPresentPaywall`           | `paywallInfo`                                | Called after paywall presentation.                                                |
  | `willDismissPaywall`          | `paywallInfo`                                | Called before paywall dismissal.                                                  |
  | `didDismissPaywall`           | `paywallInfo`                                | Called after paywall dismissal.                                                   |
  | `paywallWillOpenURL`          | `url`                                        | Called when paywall attempts to open a URL.                                       |
  | `paywallWillOpenDeepLink`     | `url`                                        | Called when paywall attempts to open a deep link.                                 |
  | `handleLog`                   | `level`, `scope`, `message`, `info`, `error` | Called for logging messages from the SDK.                                         |
  | `willRedeemLink`              | -                                            | Called before the SDK attempts to redeem a promotional link.                      |
  | `didRedeemLink`               | `result`                                     | Called after the SDK has attempted to redeem a promotional link.                  |
</ParamTable>

## Usage

Basic delegate setup:

```typescript
import { SuperwallDelegate, PaywallInfo, SubscriptionStatus } from "@superwall/react-native-superwall"

class MyDelegate extends SuperwallDelegate {
  subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus) {
    console.log(`Subscription changed from ${from.status} to ${to.status}`)
    // update UI here
  }
  
  handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
    // Track in your analytics
    Analytics.track("superwall_event", {
      event: eventInfo.event.type,
      paywall_id: eventInfo.paywallInfo?.id
    })
  }
  
  handleCustomPaywallAction(name: string) {
    switch (name) {
      case "help":
        this.presentHelpScreen()
        break
      case "contact":
        this.presentContactForm()
        break
    }
  }
  
  willPresentPaywall(paywallInfo: PaywallInfo) {
    // Pause video, hide UI, etc.
    this.pauseBackgroundTasks()
  }
  
  didDismissPaywall(paywallInfo: PaywallInfo) {
    // Resume video, show UI, etc.
    this.resumeBackgroundTasks()
  }

  // Required methods you might not use
  willRedeemLink() {}
  didRedeemLink() {}
  handleCustomPaywallAction() {}
  willPresentPaywall() {}
  didPresentPaywall() {}
  paywallWillOpenURL() {}
  paywallWillOpenDeepLink() {}
  handleLog() {}
}

// Set the delegate
await Superwall.shared.setDelegate(new MyDelegate())
```

Track subscription status changes:

```typescript
subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus) {
  console.log("Subscription changed from", from, "to", to)
  this.updateUI(for: to)
}
```

Forward analytics events:

```typescript
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
  switch (eventInfo.event.type) {
    case EventType.paywallOpen:
      Analytics.track("paywall_opened", {
        paywall_id: eventInfo.paywallInfo?.id,
        placement: eventInfo.placement
      })
      break
    case EventType.transactionComplete:
      Analytics.track("subscription_purchased", {
        product_id: eventInfo.product?.id,
        paywall_id: eventInfo.paywallInfo?.id
      })
      break
  }
}
```


---

# SuperwallOptions
Source: https://superwall.com/docs/react-native/sdk-reference/SuperwallOptions

Options for configuring the Superwall SDK.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Options for configuring the Superwall SDK. Use this to customize the appearance and behavior of paywalls, logging, and other SDK features.

## Signature

```typescript
export class SuperwallOptions {
  paywalls: PaywallOptions = new PaywallOptions()
  networkEnvironment: NetworkEnvironment = NetworkEnvironment.Release
  isExternalDataCollectionEnabled = true
  localeIdentifier?: string
  isGameControllerEnabled = false
  logging: LoggingOptions = new LoggingOptions()
  collectAdServicesAttribution = false
  passIdentifiersToPlayStore = false
  storeKitVersion?: "STOREKIT1" | "STOREKIT2"
  enableExperimentalDeviceVariables = false
}
```

## Properties

<ParamTable>
  | Property                            | Type                          | Description                                                                                                                              |
  | ----------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
  | `paywalls`                          | `PaywallOptions`              | Options for configuring paywall appearance and behavior. See [`PaywallOptions`](/react-native/sdk-reference/PaywallOptions) for details. |
  | `networkEnvironment`                | `NetworkEnvironment`          | The network environment to use. Options: `Release`, `ReleaseCandidate`, `Developer`. Defaults to `Release`.                              |
  | `isExternalDataCollectionEnabled`   | `boolean`                     | Whether external data collection is enabled. Defaults to `true`.                                                                         |
  | `localeIdentifier`                  | `string?`                     | The locale identifier to use. If not set, the system locale is used.                                                                     |
  | `isGameControllerEnabled`           | `boolean`                     | Whether game controller support is enabled. Defaults to `false`.                                                                         |
  | `logging`                           | `LoggingOptions`              | Options for configuring logging behavior. **Must be an instance of `LoggingOptions` so `toJson()` is available.**                        |
  | `collectAdServicesAttribution`      | `boolean`                     | Whether to collect AdServices attribution data. Defaults to `false`.                                                                     |
  | `passIdentifiersToPlayStore`        | `boolean`                     | Whether to pass identifiers to Play Store. Defaults to `false`.                                                                          |
  | `storeKitVersion`                   | `"STOREKIT1" \| "STOREKIT2"?` | The StoreKit version to use (iOS only). Defaults to `undefined` (auto-detect).                                                           |
  | `enableExperimentalDeviceVariables` | `boolean`                     | Whether to enable experimental device variables. Defaults to `false`.                                                                    |
</ParamTable>

## Usage

Create options when configuring the SDK:

```typescript
import { SuperwallOptions, PaywallOptions, LoggingOptions, NetworkEnvironment, LogLevel, LogScope } from "@superwall/react-native-superwall"

// Build logging options (must be an instance so toJson exists)
const logging = new LoggingOptions()
logging.level = LogLevel.Debug
logging.scopes = [LogScope.All]

// Build paywall options (set properties after construction)
const paywalls = new PaywallOptions()
paywalls.shouldShowPurchaseFailureAlert = false
paywalls.isHapticFeedbackEnabled = true

const options = new SuperwallOptions({
  networkEnvironment: NetworkEnvironment.Developer,
  isExternalDataCollectionEnabled: true,
  localeIdentifier: "en_US",
  logging,
  paywalls
})

await Superwall.configure({
  apiKey: "pk_your_api_key",
  options: options
})
```

## Network Environment

Use different network environments for different build configurations:

```typescript
// Development builds
const devOptions = new SuperwallOptions({
  networkEnvironment: NetworkEnvironment.Developer
})

// Release candidate builds
const rcOptions = new SuperwallOptions({
  networkEnvironment: NetworkEnvironment.ReleaseCandidate
})

// Production builds
const prodOptions = new SuperwallOptions({
  networkEnvironment: NetworkEnvironment.Release
})
```

## Related

* [`PaywallOptions`](/react-native/sdk-reference/PaywallOptions) - Paywall-specific options
* [`configure()`](/react-native/sdk-reference/configure) - Configure the SDK with options


---

# configure()
Source: https://superwall.com/docs/react-native/sdk-reference/configure

A static function that configures a shared instance of Superwall for use throughout your app.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

<Note>
  This is a static method called on the `Superwall` class itself, not on the shared instance.
</Note>

## Purpose

Configures the shared instance of Superwall with your API key and optional configurations, making it ready for use throughout your app.

## Signature

```typescript
static async configure({
  apiKey,
  options,
  purchaseController,
  completion,
}: {
  apiKey: string
  options?: SuperwallOptions
  purchaseController?: PurchaseController
  completion?: () => void
}): Promise<Superwall>
```

## Parameters

<ParamTable>
  | Name                 | Type                  | Description                                                                                                                                                                                 |
  | -------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `apiKey`             | `string`              | Your Public API Key from the Superwall dashboard settings.                                                                                                                                  |
  | `options`            | `SuperwallOptions?`   | Optional configuration object for customizing paywall appearance and behavior. See [`SuperwallOptions`](/react-native/sdk-reference/SuperwallOptions) for details. Defaults to `undefined`. |
  | `purchaseController` | `PurchaseController?` | Optional object for handling all subscription-related logic yourself. If omitted, Superwall handles subscription logic. Defaults to `undefined`.                                            |
  | `completion`         | `(() => void)?`       | Optional completion handler called when Superwall finishes configuring. Defaults to `undefined`.                                                                                            |
</ParamTable>

## Returns / State

Returns a Promise that resolves to the configured `Superwall` instance. The instance is also accessible via [`Superwall.shared`](/react-native/sdk-reference/Superwall).

## Usage

Basic configuration:

```typescript
import Superwall from "@superwall/react-native-superwall"

await Superwall.configure({
  apiKey: "pk_your_api_key"
})
```

With custom options:

```typescript
import Superwall, { SuperwallOptions } from "@superwall/react-native-superwall"

const options = new SuperwallOptions({
  paywalls: {
    shouldShowPurchaseFailureAlert: false
  }
})

await Superwall.configure({
  apiKey: "pk_your_api_key",
  options: options,
  completion: () => {
    console.log("Superwall configured successfully")
  }
})
```

With custom purchase controller:

```typescript
import Superwall, { PurchaseController } from "@superwall/react-native-superwall"

class MyPurchaseController extends PurchaseController {
  async purchaseFromAppStore(productId: string): Promise<PurchaseResult> {
    // Your purchase logic
  }
  
  async purchaseFromGooglePlay(productId: string, basePlanId?: string, offerId?: string): Promise<PurchaseResult> {
    // Your purchase logic
  }
  
  async restorePurchases(): Promise<RestorationResult> {
    // Your restore logic
  }
}

await Superwall.configure({
  apiKey: "pk_your_api_key",
  purchaseController: new MyPurchaseController()
})
```


---

# getUserAttributes()
Source: https://superwall.com/docs/react-native/sdk-reference/getUserAttributes

Retrieves the user attributes, set using setUserAttributes.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Retrieves the user attributes that were previously set using [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes).

## Signature

```typescript
async getUserAttributes(): Promise<UserAttributes>
```

## Parameters

This method takes no parameters.

## Returns / State

Returns a Promise that resolves with an object representing the user's attributes. The object has string keys and values can be any JSON-encodable value, URLs, or Dates.

## Usage

```typescript
const attributes = await Superwall.shared.getUserAttributes()
console.log("User attributes:", attributes)
// Example output: { name: "John", email: "john@example.com", plan: "premium" }
```

## Related

* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user


---

# handleDeepLink()
Source: https://superwall.com/docs/react-native/sdk-reference/handleDeepLink

Handles a deep link.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Handles a deep link that may be related to Superwall functionality (e.g., promotional links, paywall deep links).

## Signature

```typescript
async handleDeepLink(url: string): Promise<boolean>
```

## Parameters

<ParamTable>
  | Name  | Type     | Description                  |
  | ----- | -------- | ---------------------------- |
  | `url` | `string` | The deep link URL to handle. |
</ParamTable>

## Returns / State

Returns a Promise that resolves to a boolean indicating whether the deep link was handled by Superwall. Returns `true` if Superwall handled the link, `false` otherwise.

## Usage

```typescript
// In your deep link handler
const url = "https://your-app.com/paywall?placement=onboarding"
const wasHandled = await Superwall.shared.handleDeepLink(url)

if (!wasHandled) {
  // Handle other deep links in your app
  handleOtherDeepLink(url)
}
```

## Integration

Typically, you'll call this method from your app's deep link handler:

```typescript
import { Linking } from "react-native"

// Handle initial URL (if app was opened via deep link)
Linking.getInitialURL().then((url) => {
  if (url) {
    Superwall.shared.handleDeepLink(url)
  }
})

// Handle deep links while app is running
Linking.addEventListener("url", (event) => {
  Superwall.shared.handleDeepLink(event.url)
})
```

## Related

* [`SuperwallDelegate.paywallWillOpenDeepLink`](/react-native/sdk-reference/SuperwallDelegate) - Delegate method called before opening a deep link


---

# identify()
Source: https://superwall.com/docs/react-native/sdk-reference/identify

Creates an account with Superwall by linking the provided userId to Superwall's automatically generated alias.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Creates an account with Superwall by linking the provided `userId` to Superwall's automatically generated alias. Call this function as soon as you have a valid `userId`.

## Signature

```typescript
async identify({
  userId,
  options,
}: {
  userId: string
  options?: IdentityOptions
}): Promise<void>
```

## Parameters

<ParamTable>
  | Name      | Type               | Description                                                                                                                                                                                                                                                                                                                                                    |
  | --------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `userId`  | `string`           | Your user's unique identifier as defined by your backend system.                                                                                                                                                                                                                                                                                               |
  | `options` | `IdentityOptions?` | An optional `IdentityOptions` object. You can set the `restorePaywallAssignments` property to `true` to instruct the SDK to wait to restore paywall assignments from the server before presenting any paywalls. This option should be used only in advanced cases (e.g., when users frequently switch accounts or reinstall the app). Defaults to `undefined`. |
</ParamTable>

## Returns / State

Returns a Promise that resolves once the identification process is complete.

## Usage

Basic identification:

```typescript
await Superwall.shared.identify({
  userId: "user123"
})
```

With options to restore paywall assignments:

```typescript
import { IdentityOptions } from "@superwall/react-native-superwall"

const options = new IdentityOptions()
options.restorePaywallAssignments = true

await Superwall.shared.identify({
  userId: "user123",
  options: options
})
```

## When to Call

Call `identify()` as soon as you have a valid `userId` in your app. This is typically:

* After user login
* After user registration
* When restoring a previous session
* On app launch if the user is already logged in

## Related

* [`reset()`](/react-native/sdk-reference/Superwall) - Reset the user identity
* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes after identification


---

# Overview
Source: https://superwall.com/docs/react-native/sdk-reference/index

Reference documentation for the Superwall React Native SDK.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Welcome to the Superwall React Native SDK Reference

This reference documentation covers the legacy React Native SDK (`react-native-superwall`).

You can find the source code for the SDK [on GitHub](https://github.com/superwall/react-native-superwall).

## Feedback

We are always improving our SDKs and documentation!

If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.

<SdkLatestVersion version="4.1.7" repoUrl="https://github.com/superwall/react-native-superwall" />


---

# register()
Source: https://superwall.com/docs/react-native/sdk-reference/register

A function that registers a placement that can be remotely configured to show a paywall and gate feature access.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Registers a placement so that when it's added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature.

## Signature

```typescript
async register(params: {
  placement: string
  params?: Map<string, any> | Record<string, any>
  handler?: PaywallPresentationHandler
  feature?: () => void
}): Promise<void>
```

## Parameters

<ParamTable>
  | Name        | Type                                       | Description                                                                                                                                                                                                                                                                                                 |
  | ----------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `placement` | `string`                                   | The name of the placement you wish to register.                                                                                                                                                                                                                                                             |
  | `params`    | `Map<string, any> \| Record<string, any>?` | Optional parameters to pass with your placement. These can be referenced within audience filters in your campaign. Keys beginning with `$` are reserved for Superwall and will be dropped. Arrays and dictionaries as values are not supported and will be omitted. Defaults to `undefined`.                |
  | `handler`   | `PaywallPresentationHandler?`              | A handler whose functions provide status updates for the paywall lifecycle. Defaults to `undefined`.                                                                                                                                                                                                        |
  | `feature`   | `(() => void)?`                            | An optional completion callback representing the gated feature. It is executed based on the paywall's gating mode: called immediately for **Non-Gated**, called after the user subscribes or if already subscribed for **Gated**. If not provided, you can chain a `.then()` block to the returned promise. |
</ParamTable>

## Returns / State

Returns a Promise that resolves when registration completes. If you supply a `feature` callback, it will be executed according to the paywall's gating configuration, as described above.

## Usage

With feature callback:

```typescript
Superwall.shared.register({
  placement: "premium_feature",
  params: {
    source: "onboarding"
  },
  feature: () => {
    // Code that unlocks the premium feature
    openPremiumScreen()
  }
})
```

Using promise chaining:

```typescript
await Superwall.shared.register({
  placement: "premium_feature",
  params: {
    source: "onboarding"
  }
}).then(() => {
  // Code that unlocks the premium feature
  openPremiumScreen()
})
```

With presentation handler:

```typescript
import { PaywallPresentationHandler } from "@superwall/react-native-superwall"

const handler = new PaywallPresentationHandler()
handler.onPresent((info) => {
  console.log("Paywall presented:", info.name)
})
handler.onDismiss((info, result) => {
  console.log("Paywall dismissed:", result)
})

Superwall.shared.register({
  placement: "onboarding_complete",
  params: {
    source: "onboarding"
  },
  handler: handler
})
```

## Behavior

This behavior is remotely configurable via the Superwall Dashboard:

* For **Non-Gated** paywalls, the feature callback is executed when the paywall is dismissed or if the user is already paying.
* For **Gated** paywalls, the feature callback is executed only if the user is already paying or if they begin paying.
* If no paywall is configured, the feature callback is executed immediately.
* If no feature callback is provided, the returned promise resolves when registration completes.
* If a feature callback is provided, the returned promise always resolves after the feature callback is executed.

Note: The feature callback will not be executed if an error occurs during registration. Such errors can be detected via the `handler`.


---

# setUserAttributes()
Source: https://superwall.com/docs/react-native/sdk-reference/setUserAttributes

Sets user attributes for use in paywalls and on the Superwall dashboard.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Sets user attributes for use in paywalls and on the Superwall dashboard. If an attribute already exists, its value will be overwritten while other attributes remain unchanged. This is useful for analytics and campaign audience filters you may define in the Superwall Dashboard.

<Note>
  **Note:** These attributes should not be used as a source of truth for sensitive information.
</Note>

## Signature

```typescript
async setUserAttributes(userAttributes: UserAttributes): Promise<void>
```

## Parameters

<ParamTable>
  | Name             | Type             | Description                                                                                                                                                                                                                                                            |
  | ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  | `userAttributes` | `UserAttributes` | An object containing custom attributes to store for the user. Values can be any JSON-encodable value, URLs, or Dates. Keys beginning with `$` are reserved for Superwall and will be dropped. Arrays and dictionaries as values are not supported and will be omitted. |
</ParamTable>

## Returns / State

Returns a Promise that resolves once the user attributes have been updated.

## Usage

```typescript
await Superwall.shared.setUserAttributes({
  name: user.name,
  email: user.email,
  username: user.username,
  profilePic: user.profilePicUrl,
  plan: "premium",
  signUpDate: new Date()
})
```

## Best Practices

* Set user attributes after calling [`identify()`](/react-native/sdk-reference/identify)
* Update attributes whenever relevant user information changes
* Use attributes in campaign audience filters on the Superwall Dashboard
* Don't store sensitive information (passwords, tokens, etc.) as user attributes

## Related

* [`getUserAttributes()`](/react-native/sdk-reference/getUserAttributes) - Get user attributes
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user


---

# Subscription Status
Source: https://superwall.com/docs/react-native/sdk-reference/subscriptionStatus

Methods for getting and setting the user's subscription status.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Purpose

Methods for managing the user's subscription status. When using a `PurchaseController`, you must call `setSubscriptionStatus()` to update the user's subscription status whenever entitlements change.

## Methods

### getSubscriptionStatus()

Retrieves the current subscription status of the user.

**Signature:**

```typescript
async getSubscriptionStatus(): Promise<SubscriptionStatus>
```

**Returns:** A Promise that resolves to the current `SubscriptionStatus`.

**Usage:**

```typescript
const status = await Superwall.shared.getSubscriptionStatus()
console.log("Subscription status:", status)
```

### setSubscriptionStatus()

Sets the subscription status of the user. When using a `PurchaseController`, you must call this method to update the user's subscription status. Alternatively, you can implement the [`SuperwallDelegate.subscriptionStatusDidChange`](/react-native/sdk-reference/SuperwallDelegate) delegate callback to receive notifications whenever the subscription status changes.

**Signature:**

```typescript
async setSubscriptionStatus(status: SubscriptionStatus): Promise<void>
```

**Parameters:**

<ParamTable>
  | Name     | Type                 | Description                  |
  | -------- | -------------------- | ---------------------------- |
  | `status` | `SubscriptionStatus` | The new subscription status. |
</ParamTable>

**Returns:** A Promise that resolves once the subscription status has been updated.

**Usage:**

```typescript
import { SubscriptionStatus } from "@superwall/react-native-superwall"

// Set active subscription with entitlements
const activeStatus = SubscriptionStatus.Active(["pro"])
await Superwall.shared.setSubscriptionStatus(activeStatus)

// Set inactive subscription
const inactiveStatus = SubscriptionStatus.Inactive()
await Superwall.shared.setSubscriptionStatus(inactiveStatus)
```

## SubscriptionStatus Type

The `SubscriptionStatus` type represents the user's subscription state:

* `SubscriptionStatus.Active(entitlements: string[] \| Entitlement[])` - User has an active subscription with the specified entitlements
* `SubscriptionStatus.Inactive()` - User does not have an active subscription
* `SubscriptionStatus.Unknown()` - Subscription status is unknown

## When to Update

* After a successful purchase
* After a purchase restoration
* When a subscription expires
* When a subscription is cancelled
* On app launch (to sync with your backend)

## Related

* [`PurchaseController`](/react-native/sdk-reference/PurchaseController) - Handle purchases and update subscription status
* [`SuperwallDelegate`](/react-native/sdk-reference/SuperwallDelegate) - Receive subscription status change notifications


---

# Types and Enums
Source: https://superwall.com/docs/react-native/sdk-reference/types

Reference for types, enums, and result objects used in the React Native SDK.

<Warning>
  **Deprecated SDK**

  We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
</Warning>

## Overview

This page provides reference documentation for types, enums, and result objects used throughout the React Native SDK.

## SubscriptionStatus

Represents the subscription status of a user.

```typescript
type SubscriptionStatus =
  | SubscriptionStatus.Active
  | SubscriptionStatus.Inactive
  | SubscriptionStatus.Unknown

// Create instances
const active = SubscriptionStatus.Active(["pro", "premium"])
const inactive = SubscriptionStatus.Inactive()
const unknown = SubscriptionStatus.Unknown()
```

* **Active**: `status: "ACTIVE"` and an `entitlements` array (string IDs or `Entitlement` objects)
* **Inactive**: `status: "INACTIVE"`
* **Unknown**: `status: "UNKNOWN"`

## PaywallResult

Result of a paywall presentation.

```typescript
type PaywallResult =
  | { type: "purchased"; productId: string }
  | { type: "declined" }
  | { type: "restored" }
```

* **purchased**: User successfully purchased (includes `productId`)
* **declined**: User dismissed/declined the paywall
* **restored**: User restored a previous purchase

## PresentationResult

Result of checking whether a placement will present a paywall.

```typescript
type PresentationResult =
  | PresentationResultPaywall      // contains an Experiment
  | PresentationResultHoldout      // contains an Experiment
  | PresentationResultNoAudienceMatch
  | PresentationResultPlacementNotFound
  | PresentationResultUserIsSubscribed
  | PresentationResultPaywallNotAvailable
```

* Use `PresentationResult.fromJson(...)` to materialize instances returned from the native bridge.
* Holdout/Paywall results include the associated `Experiment`.

## TriggerResult

Result of registering a placement.

```typescript
enum TriggerResultType {
  placementNotFound,
  noAudienceMatch,
  paywall,
  holdout,
  error,
}

class TriggerResult {
  type: TriggerResultType
  experiment?: Experiment
  error?: string
}
```

* Use `TriggerResult.fromJson(...)` to parse responses.

## ConfigurationStatus

Status of SDK configuration.

```typescript
enum ConfigurationStatus {
  PENDING = "PENDING",
  CONFIGURED = "CONFIGURED",
  FAILED = "FAILED"
}
```

* **PENDING**: Configuration is in progress
* **CONFIGURED**: Configuration completed successfully
* **FAILED**: Configuration failed

## EntitlementsInfo

Information about user entitlements.

```typescript
interface EntitlementsInfo {
  status: SubscriptionStatus
  active: Entitlement[]
  all: Entitlement[]
  inactive: Entitlement[]
}
```

## PaywallInfo

Information about a paywall.

```typescript
interface PaywallInfo {
  identifier: string
  name: string
  url: string
  experiment?: Experiment
  products: Product[]
  productIds: string[]
  // ...additional timing and metadata fields
}
```

## PaywallSkippedReason

Reason why a paywall was skipped.

```typescript
type PaywallSkippedReason =
  | PaywallSkippedReasonHoldout    // includes Experiment
  | PaywallSkippedReasonNoAudienceMatch
  | PaywallSkippedReasonPlacementNotFound
  | PaywallSkippedReasonUserIsSubscribed
```

* Holdout and paywall decisions include the associated `Experiment` instance.

## PurchaseResult

Result of a purchase attempt.

```typescript
class PurchaseResult { type: string; error?: string }
class PurchaseResultPurchased extends PurchaseResult {}
class PurchaseResultCancelled extends PurchaseResult {}
class PurchaseResultFailed extends PurchaseResult { error: string }
class PurchaseResultPending extends PurchaseResult {}
```

## RestorationResult

Result of a restore purchases attempt.

```typescript
abstract class RestorationResult {
  static restored(): RestorationResult
  static failed(error?: Error): RestorationResult
}
```

* `RestorationResult.restored()` when purchases are restored
* `RestorationResult.failed(error?)` when restoration fails

## RedemptionResults

Result of redeeming a promotional link.

```typescript
type RedemptionResult =
  | { status: "SUCCESS"; code: string; redemptionInfo: RedemptionInfo }
  | { status: "ERROR"; code: string; error: { message: string } }
  | { status: "CODE_EXPIRED"; code: string; expired: { resent: boolean; obfuscatedEmail?: string } }
  | { status: "INVALID_CODE"; code: string }
  | { status: "EXPIRED_SUBSCRIPTION"; code: string; redemptionInfo: RedemptionInfo }
```

## LogLevel

Logging level.

```typescript
enum LogLevel {
  Debug = "debug",
  Info = "info",
  Warn = "warn",
  Error = "error",
  None = "none"
}
```

## LogScope

Logging scope.

```typescript
enum LogScope {
  LocalizationManager = "localizationManager",
  BounceButton = "bounceButton",
  CoreData = "coreData",
  ConfigManager = "configManager",
  IdentityManager = "identityManager",
  DebugManager = "debugManager",
  DebugViewController = "debugViewController",
  LocalizationViewController = "localizationViewController",
  GameControllerManager = "gameControllerManager",
  Device = "device",
  Network = "network",
  PaywallEvents = "paywallEvents",
  ProductsManager = "productsManager",
  StoreKitManager = "storeKitManager",
  Placements = "placements",
  Receipts = "receipts",
  SuperwallCore = "superwallCore",
  PaywallPresentation = "paywallPresentation",
  PaywallTransactions = "paywallTransactions",
  PaywallViewController = "paywallViewController",
  Cache = "cache",
  All = "all",
}
```

## InterfaceStyle

Interface style preference.

```typescript
enum InterfaceStyle {
  LIGHT = "LIGHT",
  DARK = "DARK"
}
```

## NetworkEnvironment

Network environment.

```typescript
enum NetworkEnvironment {
  Release = "release",
  ReleaseCandidate = "releaseCandidate",
  Developer = "developer"
}
```

## TransactionBackgroundView

View to show behind Apple's payment sheet.

```typescript
enum TransactionBackgroundView {
  spinner = "spinner",
  none = "none"
}
```

## Related

* [`SubscriptionStatus` methods](/react-native/sdk-reference/subscriptionStatus) - Getting and setting subscription status
* [`PaywallResult` usage](/react-native/sdk-reference/PaywallPresentationHandler) - Handling paywall results