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
Options for configuring the appearance and behavior of paywalls. Show PaywallOptions properties
Enable haptic feedback on paywall interactions.
Messaging for the alert shown when transaction restoration fails. Show RestoreFailed properties
title
string
default: "No Subscription Found"
Alert title.
shouldShowPurchaseFailureAlert
Show an alert when a purchase fails.
Automatically preload paywalls on SDK initialization.
Automatically dismiss the paywall after a successful purchase or restore.
transactionBackgroundView
TransactionBackgroundView
default: "spinner"
View displayed behind Apple’s payment sheet during a transaction.
"spinner" - Show a loading spinner
"none" - Show nothing
shouldShowWebPurchaseConfirmationAlert
Show a confirmation alert for web-based purchases (Stripe, Paddle).
onBackPressed
(paywallInfo: PaywallInfo) => boolean
Android-only callback when the back button is pressed on a paywall. Return true to handle the back press yourself, or false to use default behavior. Platform: Android only
Network & Environment
networkEnvironment
NetworkEnvironment
default: "release"
The network environment for Superwall.
"release" - Production environment
"releaseCandidate" - Pre-production testing
"developer" - Development environment
isExternalDataCollectionEnabled
Enable external data collection for analytics and attribution. Set to false to disable data collection for privacy-sensitive apps.
Localization
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
Configure SDK logging behavior. Show LoggingOptions properties
The verbosity level for logs.
"debug" - Detailed debugging information
"info" - General information
"warn" - Warnings
"error" - Errors only
"none" - Disable all logging
scopes
LogScope[]
default: ["all"]
Specific SDK components to log. Examples: ["paywallEvents", "network", "productsManager"] Use ["all"] to log all scopes.
Enable game controller support for navigating paywalls. Platform: iOS only
passIdentifiersToPlayStore
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
Disable the app transaction check on SDK launch. Platform: iOS only
Number of times the SDK will attempt to get the Superwall configuration after a network failure before timing out. Platform: iOS only
Enable mock review functionality for testing. Platform: Android only
Purchase Management
Enable manual purchase management mode. When true, you’re responsible for handling purchases through the onPurchase and onPurchaseRestore callbacks.
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
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 >
)
}
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.