Superwall

https://superwall.com/docs
Admin
Superwall is a platform that enables app developers to remotely update and optimize in-app purchase...
Tokens:645,296
Snippets:6,104
Trust Score:9.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Create a Superwall project from an example

Source: https://superwall.com/docs/framework/quickstart

Scaffold any example as a complete project. Each example is a complete project.

```bash
superwall create --example multi-page
```

--------------------------------

### Install with bun

Source: https://superwall.com/docs/web/quickstart/install

Use bun to install the core SDK and the optional React package.

```bash
bun add @superwall/paywalls-js

# React apps
bun add @superwall/paywalls-react react
```

--------------------------------

### Install with npm

Source: https://superwall.com/docs/web/quickstart/install

Use npm to install the core SDK and the optional React package.

```bash
npm install @superwall/paywalls-js

# React apps
npm install @superwall/paywalls-react react
```

--------------------------------

### Install the plugin via npm

Source: https://superwall.com/docs/community/capacitor

Install the plugin and sync Capacitor.

```bash
npm install @capawesome/capacitor-superwall
npx cap sync
```

--------------------------------

### Install with pnpm

Source: https://superwall.com/docs/web/quickstart/install

Use pnpm to install the core SDK and the optional React package.

```bash
pnpm add @superwall/paywalls-js

# React apps
pnpm add @superwall/paywalls-react react
```

--------------------------------

### Scaffold and run a Superwall example

Source: https://superwall.com/docs/framework/examples

Use the CLI to create a new project from a specific example template and launch the development studio.

```bash
superwall create --example multi-page   # scaffold it as a new project
superwall dev                            # open it in the studio
```

--------------------------------

### Run pod install for iOS

Source: https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native

After installing the SDK, run this command in the ios directory to install iOS dependencies.

```bash
cd ios && pod install
```

--------------------------------

### Create a Superwall project

Source: https://superwall.com/docs/framework/quickstart

Scaffolds a self-contained superwall/ directory with its own package.json, a starter paywall, and everything wired up, then connects it to your Superwall app and installs dependencies. Your app itself needs no npm setup.

```bash
superwall create
```

--------------------------------

### Install Superwall Skill and Pairing Prompt

Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-mcp

Install the Superwall skill and then paste the generated pairing prompt into your agent to connect it to the editor.

```bash
npx skills add superwall/skills
```

```txt
Connect to the Superwall editor using the skill with pairing code: XXXX-XXXX-XXXX
```

--------------------------------

### Install Superwall CLI with Bun

Source: https://superwall.com/docs/framework/quickstart

Install the Superwall CLI globally using Bun. Requires Node 20.12+ or Bun and git.

```bash
bun add -g superwall
```

--------------------------------

### Get cached customer info synchronously

Source: https://superwall.com/docs/android/quickstart/tracking-subscription-state

Call Superwall.instance.getCustomerInfo() to immediately read the most recent snapshot, useful during cold start. Then render the cached data similarly to the flow example.

```kotlin
val cached = Superwall.instance.getCustomerInfo()
renderCustomerInfo(
  activeProducts = cached.activeSubscriptionProductIds,
  entitlements = cached.entitlements.filter { it.isActive }.map { it.id },
  subscriptions = cached.subscriptions.map { it.productId to it.purchaseDate },
  oneTimePurchases = cached.nonSubscriptions.map { it.productId to it.purchaseDate }
)
```

--------------------------------

### Trial Start Slack Message Example

Source: https://superwall.com/docs/integrations/slack

Example Slack message for a trial start event, showing the formatted output with product details, price, store, and transaction ID.

```text
🤩 Trial start
━━━━━━━━━━━━━━━━━━━━━
💵 $0.00 USD
📦 com.example.premium.monthly
🌍 Germany
👤 user_xyz789
🏪 PLAY_STORE
🔗 Transaction: GPA.1234-5678-9012
```

--------------------------------

### Getting current overrides

Source: https://superwall.com/docs/flutter/sdk-reference/overrideProductsByName

Example of retrieving the current global override mapping.

```dart
final overrides = await Superwall.shared.getOverrideProductsByName();
if (overrides != null) {
  print('Current overrides: $overrides');
} else {
  print('No overrides set');
}
```

--------------------------------

### Get Device Attributes

Source: https://superwall.com/docs/ios/sdk-reference/getDeviceAttributes

Example showing how to call getDeviceAttributes and print the results for debugging purposes.

```swift
let deviceAttributes = await Superwall.shared.getDeviceAttributes()

// Check specific attributes
// `isApplePayAvailable` is deprecated and always true in 4.11.2+

// Print all attributes for debugging
print("Device attributes: \(deviceAttributes)")
```

--------------------------------

### Java usage for userId

Source: https://superwall.com/docs/android/sdk-reference/userId

Examples of getting the user ID and checking identification status in Java.

```java
// Get current user ID
String currentUserId = Superwall.getInstance().getUserId();
System.out.println("User ID: " + currentUserId);

// Check if user is identified
if (Superwall.getInstance().isLoggedIn()) {
    System.out.println("User is identified with ID: " + 
                      Superwall.getInstance().getUserId());
} else {
    System.out.println("User is anonymous with ID: " + 
                      Superwall.getInstance().getUserId());
}
```

--------------------------------

### Create a framework paywall from a dashboard paywall

Source: https://superwall.com/docs/framework/migrate-from-editor

Run this command in your app's root (or an empty directory) with the paywall's id from the dashboard URL. It reads the paywall and its served document, then scaffolds a project with config.ts, MIGRATION.md, an origins entry, and connects the project to the same app. Requires a login and cannot be combined with --example or --no-connect.

```bash
superwall create --from 65920
```

--------------------------------

### Usage example: getCustomerInfo in an AccountScreen

Source: https://superwall.com/docs/expo/sdk-reference/hooks/getCustomerInfo

Complete example using `useUser` to get `customerInfo` and `getCustomerInfo`. The function awaits the snapshot and logs active entitlements, while the UI shows subscription count and a refresh button.

```tsx
import { useUser } from "expo-superwall"

function AccountScreen() {
  const { customerInfo, getCustomerInfo } = useUser()

  const refresh = async () => {
    const info = await getCustomerInfo()
    console.log("Active entitlements:", info.entitlements)
  }

  return (
    <>
      <Text>Subscriptions: {customerInfo?.subscriptions.length ?? 0}</Text>
      <Button title="Refresh" onPress={refresh} />
    </>
  )
}
```

--------------------------------

### Debug configuration example

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Configures SuperwallOptions for development with verbose logging, detailed error alerts, and a test locale.

```swift
func configureSuperwallForDebug() {
  let options = SuperwallOptions()
  
  // Verbose logging for debugging
  options.logging.level = .debug
  options.logging.scopes = [.all]
  
  // Show detailed error alerts
  options.paywalls.shouldShowPurchaseFailureAlert = true
  
  // Test with specific locale
  options.localeIdentifier = "es_ES"
  
  Superwall.configure(
    apiKey: "pk_your_test_api_key",
    options: options
  )
}
```

--------------------------------

### Basic SuperwallOptions setup

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Configures paywall behavior, StoreKit version, logging, locale, transaction check bypass, event tracking, and max retry count, then passes options to Superwall.configure().

```swift
let options = SuperwallOptions()

// Configure paywall behavior
options.paywalls.shouldShowPurchaseFailureAlert = false
options.paywalls.shouldAutoShowPurchaseLoadingIndicator = true
options.paywalls.automaticallyDismiss = true

// Set StoreKit version preference
options.storeKitVersion = .storeKit2

// Configure logging
options.logging.level = .warn
options.logging.scopes = [.superwallCore, .paywallViewController]

// Set locale for testing
options.localeIdentifier = "en_GB"

// Bypass app transaction check (useful for testing)
options.shouldBypassAppTransactionCheck = true

// Control SDK event collection
options.eventTrackingBehavior = .superwallOnly

// Fail faster on a poor connection instead of retrying 6 times
options.maxConfigRetryCount = 2

// Use with configure
Superwall.configure(
  apiKey: "pk_your_api_key",
  options: options
)
```

--------------------------------

### Install Superwall Skill with npx superwall skills

Source: https://superwall.com/docs/android/guides/vibe-coding

Installs the Superwall Skill for coding agents like Claude Code, Cursor, or Codex. Provides live documentation, API access, dashboard links, and guided SDK integration flows for iOS, Android, Flutter, and Expo.

```bash
npx superwall skills
```

--------------------------------

### Get cached customer info and collect flow

Source: https://superwall.com/docs/android/sdk-reference/Superwall

Reads the latest cached customer info synchronously and also collects the flow for updates. Useful for cold start scenarios.

```kotlin
val cachedInfo = Superwall.instance.getCustomerInfo()
render(cachedInfo)

lifecycleScope.launch {
  Superwall.instance.customerInfo.collect { render(it) }
}
```

--------------------------------

### Production configuration example

Source: https://superwall.com/docs/ios/sdk-reference/SuperwallOptions

Configures SuperwallOptions for production with minimal logging, custom paywall behavior, and StoreKit 2.

```swift
func configureSuperwallForProduction() {
  let options = SuperwallOptions()
  
  // Minimal logging for production
  options.logging.level = .error
  
  // Customize paywall behavior
  options.paywalls.shouldShowPurchaseFailureAlert = true
  options.paywalls.automaticallyDismiss = true
  
  // Use StoreKit 2 for better performance on iOS 15+
  options.storeKitVersion = .storeKit2
  
  Superwall.configure(
    apiKey: "pk_your_production_api_key",
    options: options
  )
}
```

--------------------------------

### Basic Setup with expo-superwall/compat

Source: https://superwall.com/docs/expo/guides/migrating-react-native

Configure the SDK with your Public API Key. The key is selected based on the platform (iOS or Android). The `await` is optional if not chaining or needing immediate confirmation.

```tsx
import Superwall from "expo-superwall/compat"
import { useEffect, useState } from "react"
import { Platform } from "react-native"

// Initialize Superwall
useEffect(()=> {
	const apiKey = Platform.OS === "ios"
        ? "yourSuperwall_iOSKey"
        : "yourSuperwall_androidKey";
	Superwall.configure({ // `await` is optional here if not chaining or needing immediate confirmation
		apiKey,
	});
})
```

--------------------------------

### Install expo package manually

Source: https://superwall.com/docs/expo/guides/using-expo-sdk-in-bare-react-native

If automatic installation fails, install the expo package manually.

```bash
npm install expo
```

--------------------------------

### Preload All Paywalls

Source: https://superwall.com/docs/android/guides/configuring

Shows how to manually preload all paywalls.

```kotlin
Superwall.instance.preloadAllPaywalls()
```

--------------------------------

### Manage agent skill installation

Source: https://superwall.com/docs/dashboard/guides/superwall-cli

Commands to install specific skills by name or force a refresh of existing installations.

```bash
superwall skills --skill superwall        # install specific skills by name
superwall skills --force                  # reinstall even if already up to date
```

--------------------------------

### Register all core functionality

Source: https://superwall.com/docs/expo/quickstart/feature-gating

Example showing recommended pattern of registering all core functionality using `usePlacement` and `registerPlacement` on multiple buttons, allowing remote configuration without app updates.

```tsx
import { usePlacement } from "expo-superwall";

// on the welcome screen
function SignUpButton() {
  const { registerPlacement } = usePlacement();

  const handlePress = async () => {
    await registerPlacement({
      placement: 'SignUp',
      feature: () => {
        navigation.beginOnboarding();
      },
    });
  };

  return <Button onPress={handlePress} title="Sign Up" />;
}

function WorkoutButton() {
  const { registerPlacement } = usePlacement();

  const handlePress = async () => {
    await registerPlacement({
      placement: 'StartWorkout',
      feature: () => {
        navigation.startWorkout();
      },
    });
  };

  return <Button onPress={handlePress} title="Start Workout" />;
}
```

--------------------------------

### Java usage examples

Source: https://superwall.com/docs/android/sdk-reference/advanced/setSubscriptionStatus

Shows how to set active and inactive subscription statuses in Java. The active example passes entitlement strings, the inactive example uses SubscriptionStatus.Inactive.INSTANCE.

```java
// Set active subscription
Superwall.getInstance().setSubscriptionStatus("premium", "pro_features");

// Set inactive subscription
Superwall.getInstance().setSubscriptionStatus(
    SubscriptionStatus.Inactive.INSTANCE
);
```

--------------------------------

### Register multiple placements (Kotlin)

Source: https://superwall.com/docs/android/quickstart/feature-gating

Example of registering core functionality on the welcome screen and in another view controller. Recommended to register all core functionality for remote configuration without app updates.

```Kotlin
// on the welcome screen
fun pressedSignUp() {
  Superwall.instance.register("SignUp") {
    navigation.beginOnboarding()
  }
}

// in another view controller
fun pressedWorkoutButton() {
  Superwall.instance.register("StartWorkout") {
    navigation.startWorkout()
  }
}
```

--------------------------------

### Basic PaywallPresentationHandler setup with lifecycle callbacks

Source: https://superwall.com/docs/ios/sdk-reference/PaywallPresentationHandler

Sets up a PaywallPresentationHandler with onPresent, onWillDismiss, and onDismiss callbacks, then registers it with Superwall.shared.register for the "premium_feature" placement. The onDismiss callback switches on the result to handle purchased, cancelled, and restored cases.

```swift
func registerFeatureWithHandler() {
  let handler = PaywallPresentationHandler()
  
  handler.onPresent { paywallInfo in
    print("Paywall presented: \(paywallInfo.id)")
    // Pause background tasks, analytics, etc.
  }
  
  handler.onWillDismiss { paywallInfo, result in
    print("Paywall will dismiss: \(paywallInfo.id)")
    // Prepare for dismissal, save state, etc.
  }
  
  handler.onDismiss { paywallInfo, result in
    print("Paywall dismissed with result: \(result)")
    
    switch result {
    case .purchased:
      showSuccessMessage()
    case .cancelled:
      showPromotionalOffer()
    case .restored:
      updateUIForActiveSubscription()
    }
  }
  
  Superwall.shared.register(
    placement: "premium_feature",
    params: ["source": "feature_screen"],
    handler: handler
  ) {
    unlockPremiumFeature()
  }
}
```

--------------------------------

### Verify Package Installation

Source: https://superwall.com/docs/expo/guides/debugging

Confirm that the expo-superwall package is correctly installed in your project.

```bash
npm ls expo-superwall
```

--------------------------------

### Import SDK modules

Source: https://superwall.com/docs/web/quickstart/install

Demonstrates importing the core SDK for any environment and the browser-specific storage module.

```ts
import { createSuperwall } from "@superwall/paywalls-js";           // anywhere
import { createBrowserStorage } from "@superwall/paywalls-js/browser"; // browser-intended
```

--------------------------------

### Create products via CLI

Source: https://superwall.com/docs/framework/cli

Lists entitlements to retrieve the numeric ID, then creates a new product. The --entitlement flag requires the numeric ID, and --price uses major units.

```sh
superwall entitlements list --json                 # grab the NUMERIC entitlement id
superwall products create pro_3999_year \
  --project <id> --app <id> \
  --name "Annual" --price 39.99 --period year \
  --trial-days 7 --entitlement <numeric-id> --json
```

--------------------------------

### Basic handler setup with onPresent and onDismiss

Source: https://superwall.com/docs/flutter/sdk-reference/PaywallPresentationHandler

Sets up a PaywallPresentationHandler with onPresent and onDismiss callbacks, then registers a placement. The onDismiss handler switches on PaywallResult to show different UI responses.

```dart
Future<void> _registerFeatureWithHandler() async {
  final handler = PaywallPresentationHandler();

  handler.onPresent((paywallInfo) {
    print('Paywall presented: ${paywallInfo.identifier}');
    print('Paywall state: ${paywallInfo.state}');
  });

  handler.onDismiss((paywallInfo, result) {
    print('Paywall dismissed with result: $result');

    switch (result) {
      case PaywallResult.purchased:
        _showSuccessMessage();
        break;
      case PaywallResult.cancelled:
        _showPromotionalOffer();
        break;
      case PaywallResult.restored:
        _updateUIForActiveSubscription();
        break;
    }
  });

  await Superwall.shared.registerPlacement(
    'premium_feature',
    params: {'source': 'feature_screen'},
    handler: handler,
    feature: () {
      _unlockPremiumFeature();
    },
  );
}
```

--------------------------------

### Create SuperwallOptions and configure SDK

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

Shows how to build LoggingOptions, PaywallOptions, and SuperwallOptions, then pass them to Superwall.configure(). Note that logging must be an instance of LoggingOptions so toJson() is available.

```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
})
```

--------------------------------

### Get Device Attributes

Source: https://superwall.com/docs/ios/sdk-reference/Superwall

Get device attributes asynchronously. Useful for audience filters or debugging.

```swift
let deviceAttributes = await Superwall.shared.getDeviceAttributes()
// Use in audience filters or for debugging
print("Device attributes: \(deviceAttributes)")
```

--------------------------------

### Get CustomerInfo Signature

Source: https://superwall.com/docs/flutter/sdk-reference/getCustomerInfo

The method signature for getting customer information. It returns a `Future<CustomerInfo>`.

```dart
Future<CustomerInfo> getCustomerInfo()
```

--------------------------------

### Configure PaywallOptions

Source: https://superwall.com/docs/flutter/sdk-reference/PaywallOptions

Demonstrates how to instantiate PaywallOptions with various settings and pass them to Superwall.configure.

```dart
final paywallOptions = PaywallOptions()
  ..isHapticFeedbackEnabled = true
  ..shouldShowPurchaseFailureAlert = false
  ..shouldPreload = true
  ..automaticallyDismiss = true
  ..transactionBackgroundView = TransactionBackgroundView.spinner
  ..overrideProductsByName = {
    'primary': 'com.example.premium_monthly',
    'tertiary': 'com.example.premium_annual',
  }
  ..shouldShowWebRestorationAlert = true
  ..shouldShowWebPurchaseConfirmationAlert = true
  ..onBackPressed = (paywallInfo) {
    // Android-only callback
    Superwall.shared.dismiss();
  };

final options = SuperwallOptions(
  paywalls: paywallOptions,
);

await Superwall.configure(
  'pk_your_api_key',
  options: options,
);
```
Tokens:
Raw