Skip to main content
The Superwall class is the main entry point for the Compat SDK. It provides methods for configuring the SDK, registering placements, managing user identity, and controlling paywall presentation.

​
Installation

npx expo install expo-superwall

​
Import

import Superwall from "expo-superwall/compat"

​
Configuration

​
configure()

Configures a shared instance of Superwall for use throughout your app. Call this as soon as your app starts to initialize the SDK. 
static async configure({
  apiKey: string,
  options?: PartialSuperwallOptions,
  purchaseController?: PurchaseController,
  completion?: () => void
}): Promise<Superwall>
​
apiKey
string
required
Your Superwall API Key from the dashboard settings. Get your key from the Superwall Dashboard.
​
options
PartialSuperwallOptions
Optional configuration object to customize SDK appearance and behavior. See SuperwallOptions for available options.
​
purchaseController
PurchaseController
Optional purchase controller for handling subscription logic yourself. See PurchaseController for implementation details.
​
completion
() => void
Optional callback invoked when Superwall finishes configuring.
​
return
Promise<Superwall>
Returns a promise that resolves to the configured Superwall instance.

​
Example

import Superwall from "expo-superwall/compat"
import { Platform } from "react-native"

useEffect(() => {
  const apiKey = Platform.OS === "ios"
    ? "yourSuperwall_iOSKey"
    : "yourSuperwall_androidKey"
  
  Superwall.configure({
    apiKey,
    options: {
      paywalls: {
        shouldPreload: true
      }
    },
    completion: () => {
      console.log("Superwall configured")
    }
  })
}, [])

​
shared

Returns the configured shared instance of Superwall. 
static get shared(): Superwall
You must call Superwall.configure() before accessing Superwall.shared.
​
return
Superwall
The shared Superwall instance.

​
Example

const superwall = Superwall.shared

​
Placement Registration

​
register()

Registers a placement to access a feature. When added to a campaign on the Superwall Dashboard, it can trigger a paywall based on audience filters and subscription status. 
async register({
  placement: string,
  params?: Map<string, any> | Record<string, any>,
  handler?: PaywallPresentationHandler,
  feature?: () => void
}): Promise<void>
​
placement
string
required
The name of the placement to register. Must match a placement configured in your Superwall Dashboard.
​
params
Map<string, any> | Record<string, any>
Optional parameters to pass with the placement. Can be referenced in campaign audience filters. Keys beginning with $ are reserved. Arrays and dictionaries are not supported.
​
handler
PaywallPresentationHandler
Optional handler that receives status updates about paywall presentation. See PaywallPresentationHandler.
​
feature
() => void
Optional callback executed after registration. For non-gated paywalls, runs when dismissed or if user is paying. For gated paywalls, runs only if user is paying or begins paying.
​
return
Promise<void>
Resolves when registration completes. If feature callback is provided, resolves after feature is executed.

​
Example with Feature Callback

Superwall.shared.register({
  placement: "premium_feature",
  params: {
    source: "main_menu"
  },
  feature: () => {
    // Execute feature logic after paywall handling
    console.log("User accessed premium feature")
  }
})

​
Example with Promise Chaining

await Superwall.shared.register({
  placement: "premium_feature"
})

// Execute feature logic after registration
console.log("Placement registered")

​
Example with Presentation Handler

import { PaywallPresentationHandler } from "expo-superwall/compat"

const handler = new PaywallPresentationHandler()

handler.onPresent((info) => {
  console.log("Paywall presented:", info.name)
})

handler.onDismiss((info, result) => {
  console.log("Paywall dismissed:", result)
})

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

Superwall.shared.register({
  placement: "premium_feature",
  handler
})

​
getPresentationResult()

Preemptively gets the result of registering a placement without presenting a paywall. 
async getPresentationResult({
  placement: string,
  params?: Map<string, any>
}): Promise<PresentationResult>
​
placement
string
required
The placement name to check.
​
params
Map<string, any>
Optional parameters to pass with the placement.
​
return
Promise<PresentationResult>
Result indicating whether a paywall would be presented. See PresentationResult.

​
Example

const result = await Superwall.shared.getPresentationResult({
  placement: "premium_feature"
})

if (result instanceof PresentationResultPaywall) {
  console.log("Paywall would be presented")
}

​
User Management

​
identify()

Creates an account with Superwall by linking the provided userId to Superwall’s automatically generated alias. 
async identify({
  userId: string,
  options?: IdentityOptions
}): Promise<void>
​
userId
string
required
Your user’s unique identifier from your backend system.
​
options
IdentityOptions
Optional identity options. Set restorePaywallAssignments to true to restore paywall assignments from the server.

​
Example

await Superwall.shared.identify({ 
  userId: "user_123" 
})

​
reset()

Resets the userId, on-device paywall assignments, and data stored by Superwall. 
async reset(): Promise<void>

​
Example

await Superwall.shared.reset()

​
setUserAttributes()

Sets user attributes for use in paywalls and on the Superwall dashboard. 
async setUserAttributes(
  userAttributes: UserAttributes
): Promise<void>
​
userAttributes
UserAttributes
required
Object containing custom attributes. Values can be any JSON-encodable value, URLs, or Dates. Keys beginning with $ are reserved. Arrays and dictionaries are not supported.

​
Example

await Superwall.shared.setUserAttributes({
  name: "John Doe",
  email: "[email protected]",
  age: 30,
  isPremium: false
})

​
getUserAttributes()

Retrieves the user attributes set using setUserAttributes(). 
async getUserAttributes(): Promise<UserAttributes>
​
return
Promise<UserAttributes>
Object representing the user’s attributes.

​
Example

const attributes = await Superwall.shared.getUserAttributes()
console.log(attributes)

​
Subscription Status

​
setSubscriptionStatus()

Sets the subscription status of the user. Required when using a PurchaseController. 
async setSubscriptionStatus(
  status: SubscriptionStatus
): Promise<void>
​
status
SubscriptionStatus
required
The new subscription status. See SubscriptionStatus.

​
Example

import { SubscriptionStatus } from "expo-superwall/compat"

await Superwall.shared.setSubscriptionStatus(
  SubscriptionStatus.Active(["premium"])
)

​
getSubscriptionStatus()

Retrieves the current subscription status. 
async getSubscriptionStatus(): Promise<SubscriptionStatus>
​
return
Promise<SubscriptionStatus>
The current subscription status.

​
Example

const status = await Superwall.shared.getSubscriptionStatus()
if (status.status === "ACTIVE") {
  console.log("User is subscribed")
}

​
Experiment Assignments

​
getAssignments()

Gets all experiment assignments and returns them in an array. 
async getAssignments(): Promise<Assignment[]>
​
return
Promise<Assignment[]>
Array of experiment assignments.
This method tracks the getAssignments event in the delegate.

​
Example

const assignments = await Superwall.shared.getAssignments()
console.log("Assignments:", assignments)

​
confirmAllAssignments()

Confirms all experiment assignments and returns them in an array. 
async confirmAllAssignments(): Promise<Assignment[]>
​
return
Promise<Assignment[]>
Array of confirmed experiment assignments.
Assignments may differ when a placement is registered due to changes in user, placement, or device parameters.

​
Example

const assignments = await Superwall.shared.confirmAllAssignments()

​
Paywall Control

​
dismiss()

Dismisses the presented paywall, if one exists. 
async dismiss(): Promise<void>

​
Example

await Superwall.shared.dismiss()

​
preloadAllPaywalls()

Preloads all paywalls that the user may see based on campaigns and placements. 
async preloadAllPaywalls(): Promise<void>
First set PaywallOptions.shouldPreload to false when configuring the SDK, then call this function when you want preloading to begin.

​
Example

await Superwall.shared.preloadAllPaywalls()

​
preloadPaywalls()

Preloads paywalls for specific placements. 
async preloadPaywalls(
  placementNames: Set<string>
): Promise<void>
​
placementNames
Set<string>
required
Set of placement names to preload.

​
Example

await Superwall.shared.preloadPaywalls(
  new Set(["premium_feature", "onboarding"])
)

​
Delegate

​
setDelegate()

Sets the delegate that handles Superwall lifecycle events. 
async setDelegate(
  delegate: SuperwallDelegate | undefined
): Promise<void>
​
delegate
SuperwallDelegate | undefined
required
An object implementing the SuperwallDelegate interface, or undefined to remove the delegate. See SuperwallDelegate.

​
Example

import { SuperwallDelegate } from "expo-superwall/compat"

class MyDelegate extends SuperwallDelegate {
  handleSuperwallEvent(eventInfo) {
    console.log("Event:", eventInfo.event.type)
  }
  
  subscriptionStatusDidChange(from, to) {
    console.log(`Status changed from ${from.status} to ${to.status}`)
  }
}

const delegate = new MyDelegate()
await Superwall.shared.setDelegate(delegate)

​
Configuration Status

​
getConfigurationStatus()

Retrieves the current configuration status of the SDK. 
async getConfigurationStatus(): Promise<ConfigurationStatus>
​
return
Promise<ConfigurationStatus>
The configuration status: PENDING, CONFIGURED, or FAILED.

​
Example

const status = await Superwall.shared.getConfigurationStatus()
if (status === ConfigurationStatus.CONFIGURED) {
  console.log("SDK is ready")
}

​
Entitlements

​
getEntitlements()

Retrieves the entitlements tied to the device. 
async getEntitlements(): Promise<EntitlementsInfo>
​
return
Promise<EntitlementsInfo>
Object containing entitlements information.

​
Example

const entitlements = await Superwall.shared.getEntitlements()
console.log("Entitlements:", entitlements)
Handles a deep link URL. 
async handleDeepLink(url: string): Promise<boolean>
​
url
string
required
The deep link URL to handle.
​
return
Promise<boolean>
Returns true if the deep link was handled by Superwall.

​
Example

const handled = await Superwall.shared.handleDeepLink(
  "myapp://paywall"
)
if (handled) {
  console.log("Deep link handled by Superwall")
}

​
UI Customization

​
setInterfaceStyle()

Sets the user interface style, overriding the system setting. 
async setInterfaceStyle(
  style: InterfaceStyle | null
): Promise<void>
​
style
InterfaceStyle | null
required
The desired interface style (light, dark), or null to use system setting.

​
Example

import { InterfaceStyle } from "expo-superwall/compat"

await Superwall.shared.setInterfaceStyle(InterfaceStyle.Dark)

​
setLogLevel()

Sets the logging level for the SDK. 
async setLogLevel(level: LogLevel): Promise<void>
​
level
LogLevel
required
The log level to set.

​
Example

import { LogLevel } from "expo-superwall/compat"

await Superwall.shared.setLogLevel(LogLevel.Debug)

​
Integration Attributes

​
setIntegrationAttributes()

Sets attributes for third-party integrations. 
async setIntegrationAttributes(
  attributes: IntegrationAttributes
): Promise<void>
​
attributes
IntegrationAttributes
required
Object mapping integration attribute keys to their IDs.

​
Example

await Superwall.shared.setIntegrationAttributes({
  mixpanelDistinctId: "user_123"
})

​
getIntegrationAttributes()

Gets the currently set integration attributes. 
async getIntegrationAttributes(): Promise<Record<string, string>>
​
return
Promise<Record<string, string>>
Object mapping integration attributes to their IDs.

​
Example

const attributes = await Superwall.shared.getIntegrationAttributes()
console.log(attributes)

​
Complete Example

import Superwall, {
  SuperwallDelegate,
  EventType,
  SubscriptionStatus
} from "expo-superwall/compat"
import { Platform, useEffect } from "react-native"

// Define delegate
class MyDelegate extends SuperwallDelegate {
  handleSuperwallEvent(eventInfo) {
    switch (eventInfo.event.type) {
      case EventType.paywallOpen:
        console.log("Paywall opened")
        break
      case EventType.paywallClose:
        console.log("Paywall closed")
        break
      case EventType.transactionComplete:
        console.log("Purchase completed")
        break
    }
  }

  subscriptionStatusDidChange(from, to) {
    console.log(`Subscription changed: ${from.status} -> ${to.status}`)
  }
}

function App() {
  useEffect(() => {
    const initialize = async () => {
      // Configure SDK
      const apiKey = Platform.OS === "ios"
        ? "pk_ios_xxxxx"
        : "pk_android_xxxxx"
      
      await Superwall.configure({ apiKey })
      
      // Set delegate
      const delegate = new MyDelegate()
      await Superwall.shared.setDelegate(delegate)
      
      // Identify user
      await Superwall.shared.identify({ userId: "user_123" })
      
      // Set user attributes
      await Superwall.shared.setUserAttributes({
        name: "John Doe",
        email: "[email protected]"
      })
    }
    
    initialize()
  }, [])
  
  const showPremiumFeature = () => {
    Superwall.shared.register({
      placement: "premium_feature",
      feature: () => {
        console.log("User accessed premium feature")
      }
    })
  }
  
  return (
    // Your app UI
  )
}

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us