Skip to main content
SuperwallOptions defines the configuration options for the Superwall SDK. These options control SDK behavior, paywall appearance, logging, and platform-specific features.

Definition

interface SuperwallOptions {
  paywalls: PaywallOptions
  networkEnvironment: NetworkEnvironment
  isExternalDataCollectionEnabled: boolean
  localeIdentifier?: string
  isGameControllerEnabled: boolean
  logging: LoggingOptions
  passIdentifiersToPlayStore: boolean
  storeKitVersion?: "STOREKIT1" | "STOREKIT2"
  enableExperimentalDeviceVariables: boolean
  manualPurchaseManagement: boolean
  shouldObservePurchases: boolean
  shouldBypassAppTransactionCheck: boolean
  maxConfigRetryCount: number
  useMockReviews: boolean
  testModeBehavior: TestModeBehavior
}

Properties

Paywall Options

paywalls
PaywallOptions
required
Options for configuring the appearance and behavior of paywalls.

Network & Environment

networkEnvironment
NetworkEnvironment
default:"release"
The network environment for Superwall.
  • "release" - Production environment
  • "releaseCandidate" - Pre-production testing
  • "developer" - Development environment
isExternalDataCollectionEnabled
boolean
default:true
Enable external data collection for analytics and attribution.Set to false to disable data collection for privacy-sensitive apps.

Localization

localeIdentifier
string
Override the device’s locale for paywall content.Example: "en_US", "es_ES", "fr_FR"If not set, uses the device’s current locale.

Logging

logging
LoggingOptions
required
Configure SDK logging behavior.

Platform-Specific Options

isGameControllerEnabled
boolean
default:false
Enable game controller support for navigating paywalls.Platform: iOS only
passIdentifiersToPlayStore
boolean
default:false
Pass user identifiers to Google Play Store for purchase attribution.Platform: Android only
storeKitVersion
'STOREKIT1' | 'STOREKIT2'
The version of StoreKit to use for purchases.If not specified, the SDK will automatically choose the appropriate version.Platform: iOS only
shouldBypassAppTransactionCheck
boolean
default:false
Disable the app transaction check on SDK launch.Platform: iOS only
maxConfigRetryCount
number
default:6
Number of times the SDK will attempt to get the Superwall configuration after a network failure before timing out.Platform: iOS only
useMockReviews
boolean
default:false
Enable mock review functionality for testing.Platform: Android only

Purchase Management

manualPurchaseManagement
boolean
default:false
Enable manual purchase management mode.When true, you’re responsible for handling purchases through the onPurchase and onPurchaseRestore callbacks.
shouldObservePurchases
boolean
default:false
Observe purchases made outside of Superwall.When true, Superwall will observe StoreKit/Play Store transactions and report them.Platform: iOS and Android

Testing & Development

enableExperimentalDeviceVariables
boolean
default:false
Enable experimental device variables for advanced targeting.
testModeBehavior
TestModeBehavior
default:"automatic"
Controls when the SDK enters test mode.
  • "automatic" - Enter test mode when appropriate (default)
  • "whenEnabledForUser" - Only when enabled for specific users
  • "never" - Never enter test mode
  • "always" - Always in test mode
Platform: iOS and Android

Usage

Basic Configuration

import { SuperwallProvider } from 'expo-superwall'

export default function App() {
  return (
    <SuperwallProvider
      apiKey="YOUR_API_KEY"
      options={{
        logging: {
          level: 'info',
          scopes: ['all']
        },
        paywalls: {
          shouldPreload: true,
          automaticallyDismiss: true
        }
      }}
    >
      <YourApp />
    </SuperwallProvider>
  )
}

Production Configuration

import { SuperwallProvider } from 'expo-superwall'

export default function App() {
  return (
    <SuperwallProvider
      apiKey={process.env.EXPO_PUBLIC_SUPERWALL_API_KEY}
      options={{
        networkEnvironment: 'release',
        logging: {
          level: 'error', // Only log errors in production
          scopes: ['all']
        },
        paywalls: {
          shouldPreload: true,
          automaticallyDismiss: true,
          restoreFailed: {
            title: 'Restore Failed',
            message: 'We could not find your subscription. Please contact support.',
            closeButtonTitle: 'OK'
          }
        },
        isExternalDataCollectionEnabled: true,
        shouldObservePurchases: false
      }}
    >
      <YourApp />
    </SuperwallProvider>
  )
}

Development Configuration

import { SuperwallProvider } from 'expo-superwall'
import { Platform } from 'react-native'

export default function App() {
  return (
    <SuperwallProvider
      apiKey={process.env.EXPO_PUBLIC_SUPERWALL_API_KEY}
      options={{
        networkEnvironment: 'developer',
        logging: {
          level: 'debug', // Detailed logging for development
          scopes: ['all']
        },
        paywalls: {
          shouldPreload: false, // Faster testing without preload
          isHapticFeedbackEnabled: Platform.OS === 'ios'
        },
        testModeBehavior: 'always'
      }}
    >
      <YourApp />
    </SuperwallProvider>
  )
}

Manual Purchase Management

import { SuperwallProvider, usePurchaseController } from 'expo-superwall'

function PurchaseHandler() {
  const purchaseController = usePurchaseController({
    onPurchase: async (params) => {
      console.log('Purchase initiated:', params.productId)
      
      // Handle purchase with your own logic
      const result = await myPurchaseSystem.purchase(params.productId)
      
      return result.success ? 'purchased' : 'cancelled'
    },
    onPurchaseRestore: async () => {
      console.log('Restore initiated')
      
      // Handle restore with your own logic
      const result = await myPurchaseSystem.restore()
      
      return result.success ? 'restored' : 'failed'
    }
  })
  
  return null
}

export default function App() {
  return (
    <SuperwallProvider
      apiKey="YOUR_API_KEY"
      options={{
        manualPurchaseManagement: true
      }}
    >
      <PurchaseHandler />
      <YourApp />
    </SuperwallProvider>
  )
}

Localized Configuration

import { SuperwallProvider } from 'expo-superwall'
import * as Localization from 'expo-localization'

export default function App() {
  return (
    <SuperwallProvider
      apiKey="YOUR_API_KEY"
      options={{
        localeIdentifier: Localization.locale, // e.g., "en-US"
        paywalls: {
          restoreFailed: {
            title: 'No se encontró suscripción',
            message: 'No pudimos encontrar una suscripción activa.',
            closeButtonTitle: 'OK'
          }
        }
      }}
    >
      <YourApp />
    </SuperwallProvider>
  )
}

Platform-Specific Configuration

import { SuperwallProvider } from 'expo-superwall'
import { Platform } from 'react-native'

export default function App() {
  return (
    <SuperwallProvider
      apiKey="YOUR_API_KEY"
      options={{
        paywalls: {
          isHapticFeedbackEnabled: Platform.OS === 'ios',
          onBackPressed: Platform.OS === 'android' 
            ? (info) => {
                console.log('Back pressed on paywall:', info.identifier)
                return false // Use default behavior
              }
            : undefined
        },
        storeKitVersion: Platform.OS === 'ios' ? 'STOREKIT2' : undefined,
        passIdentifiersToPlayStore: Platform.OS === 'android',
        useMockReviews: Platform.OS === 'android' && __DEV__
      }}
    >
      <YourApp />
    </SuperwallProvider>
  )
}

Default Options

All options have sensible defaults. You can provide partial options, and the SDK will merge them with the defaults:
import { DefaultSuperwallOptions } from 'expo-superwall'

// These are the default values
const defaults: SuperwallOptions = {
  paywalls: {
    isHapticFeedbackEnabled: true,
    restoreFailed: {
      title: "No Subscription Found",
      message: "We couldn't find an active subscription for your account.",
      closeButtonTitle: "Okay",
    },
    shouldShowPurchaseFailureAlert: true,
    shouldPreload: false,
    automaticallyDismiss: true,
    transactionBackgroundView: "spinner",
    shouldShowWebPurchaseConfirmationAlert: false,
  },
  networkEnvironment: "release",
  isExternalDataCollectionEnabled: true,
  isGameControllerEnabled: false,
  logging: {
    level: "info",
    scopes: ["all"],
  },
  passIdentifiersToPlayStore: false,
  enableExperimentalDeviceVariables: false,
  manualPurchaseManagement: false,
  shouldObservePurchases: false,
  shouldBypassAppTransactionCheck: false,
  maxConfigRetryCount: 6,
  useMockReviews: false,
  testModeBehavior: "automatic",
}

Best Practices

Use environment variables for API keys and environment-specific configuration to keep your code clean and secure.
Don’t hardcode production API keys in your source code. Use Expo’s environment variables or a secure configuration management system.
Enable debug logging during development to troubleshoot issues, but use error-only logging in production to reduce noise.

Build docs developers (and LLMs) love