@capawesome/capacitor-superwall

Unofficial Capacitor plugin for Superwall SDK.[^1]

Features

We are proud to offer a comprehensive Capacitor plugin for Superwall SDK integration. Here are some of the key features:

• 🖥️ Cross-platform: Supports Android and iOS.
• 💰 Paywall Presentation: Show beautiful, remotely-configured paywalls to drive subscriptions.
• 🎯 Feature Gating: Control feature access based on subscription status.
• 📊 Analytics Events: Forward Superwall events to your analytics platform.
• 👤 User Management: Identify users, set custom attributes, and manage subscription status.
• 🧪 A/B Testing: Built-in support for paywall experiments and holdout groups.
• 🔗 Deep Linking: Handle deep links for paywall campaigns.
• 🎨 Customization: Configure paywall behavior, logging, and appearance.
• 🔁 Up-to-date: Always supports the latest Capacitor version.

Missing a feature? Just open an issue and we'll take a look!

Compatibility

| Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.1.x | >=8.x.x | Active support |

Installation

npm install @capawesome/capacitor-superwall
npx cap sync

Android

Variables

This plugin will use the following project variables (defined in your app's variables.gradle file):

• $superwallAndroidVersion version of com.superwall.sdk:superwall-android (default: 2.6.6)

Manifest

Add the required activities to your AndroidManifest.xml file:

<activity
  android:name="com.superwall.sdk.paywall.view.SuperwallPaywallActivity"
  android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar"
  android:configChanges="orientation|screenSize|keyboardHidden">
</activity>
<activity android:name="com.superwall.sdk.debug.DebugViewActivity" />
<activity android:name="com.superwall.sdk.debug.localizations.SWLocalizationActivity" />
<activity android:name="com.superwall.sdk.debug.SWConsoleActivity" />

Set your app's theme in the android:theme section of the SuperwallPaywallActivity.

Configuration

No configuration required for this plugin.

Usage

import { Superwall } from '@capawesome/capacitor-superwall';

const configureSuperwall = async () => {
  await Superwall.configure({
    apiKey: 'pk_your_api_key_here',
    options: {
      paywalls: {
        shouldPreload: true,
        automaticallyDismiss: true,
      },
      logging: {
        level: 'WARN',
        scopes: ['ALL'],
      },
    },
  });
};

const showPaywall = async () => {
  const result = await Superwall.register({
    placement: 'premium_feature',
    params: {
      user_level: 5,
      source: 'settings',
    },
  });

  console.log('Paywall result:', result.result); // 'PURCHASED', 'CANCELLED', or 'RESTORED'
};

const checkPaywall = async () => {
  const result = await Superwall.getPresentationResult({
    placement: 'premium_feature',
  });

  if (result.type === 'PAYWALL') {
    console.log('Paywall would be shown');
  } else if (result.type === 'NO_AUDIENCE_MATCH') {
    console.log('User does not match audience, no paywall');
  }
};

const identifyUser = async (userId: string) => {
  await Superwall.identify({
    userId: userId,
    options: {
      restorePaywallAssignments: true,
    },
  });
};

const setAttributes = async () => {
  await Superwall.setUserAttributes({
    attributes: {
      username: 'john_doe',
      subscription_tier: 'free',
      total_purchases: 5,
    },
  });
};

const checkSubscription = async () => {
  const result = await Superwall.getSubscriptionStatus();
  console.log('Subscription status:', result.status); // 'ACTIVE', 'INACTIVE', or 'UNKNOWN'
};

const addListeners = async () => {
  // Forward analytics events to your platform
  await Superwall.addListener('superwallEvent', (event) => {
    console.log('Superwall event:', event.type, event.data);
    // Forward to your analytics: Analytics.track(event.type, event.data);
  });

  // Track subscription status changes
  await Superwall.addListener('subscriptionStatusDidChange', (event) => {
    console.log('Subscription status changed to:', event.status);
  });

  // Handle paywall lifecycle events
  await Superwall.addListener('paywallPresented', (event) => {
    console.log('Paywall presented:', event.paywallInfo.placement);
  });

  await Superwall.addListener('paywallDismissed', (event) => {
    console.log('Paywall dismissed:', event.paywallInfo.placement);
  });

  // Handle custom paywall actions
  await Superwall.addListener('customPaywallAction', (event) => {
    console.log('Custom action:', event.name);
    // Handle custom actions like 'help', 'contact', etc.
  });
};

const handleCampaignDeepLink = async (url: string) => {
  await Superwall.handleDeepLink({ url });
};

const logout = async () => {
  await Superwall.reset();
};

API

• configure(...)
• register(...)
• getPresentationResult(...)
• identify(...)
• reset()
• getUserId()
• getIsLoggedIn()
• setUserAttributes(...)
• handleDeepLink(...)
• getSubscriptionStatus()
• addListener('superwallEvent', ...)
• addListener('subscriptionStatusDidChange', ...)
• addListener('paywallPresented', ...)
• addListener('paywallWillDismiss', ...)
• addListener('paywallDismissed', ...)
• addListener('customPaywallAction', ...)
• removeAllListeners()
• Interfaces
• Enums

configure(...)

configure(options: ConfigureOptions) => Promise<void>

Configure the Superwall SDK.

This method must be called once before all other methods.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------- | | options | ConfigureOptions |

Since: 0.0.1

register(...)

register(options: RegisterOptions) => Promise<RegisterResult>

Register a placement and present a paywall if the user doesn't have an active subscription.

This is the primary method for feature gating and paywall presentation. The feature closure will execute based on the gating mode:

• Non-gated: Executes immediately
• Gated: Executes after subscription or if already subscribed

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | RegisterOptions |

Returns: Promise<RegisterResult>

Since: 0.0.1

getPresentationResult(...)

getPresentationResult(options: GetPresentationResultOptions) => Promise<GetPresentationResultResult>

Check if a paywall would be presented for a placement without actually presenting it.

Useful for determining whether to show a feature or paywall before the user interacts.

Only available on Android and iOS.

| Param | Type | | ------------- | ------------------------------------------------------------------------------------- | | options | GetPresentationResultOptions |

Returns: Promise<GetPresentationResultResult>

Since: 0.0.1

identify(...)

identify(options: IdentifyOptions) => Promise<void>

Identify the current user with a unique ID.

This links the user ID to their anonymous alias for analytics and paywall assignments.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------- | | options | IdentifyOptions |

Since: 0.0.1

reset()

reset() => Promise<void>

Reset the user identity.

This rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download configuration. Should only be called on explicit logout.

Only available on Android and iOS.

Since: 0.0.1

getUserId()

getUserId() => Promise<GetUserIdResult>

Get the current user ID.

Returns the identified user ID if set, otherwise returns the anonymous ID.

Only available on Android and iOS.

Returns: Promise<GetUserIdResult>

Since: 0.0.1

getIsLoggedIn()

getIsLoggedIn() => Promise<GetIsLoggedInResult>

Check if the user is logged in (identified).

Only available on Android and iOS.

Returns: Promise<GetIsLoggedInResult>

Since: 0.0.1

setUserAttributes(...)

setUserAttributes(options: SetUserAttributesOptions) => Promise<void>

Set custom user attributes for personalization and audience filtering.

Attributes can be used in audience filters on the Superwall dashboard. Keys starting with $ are reserved for Superwall use. Arrays and nested structures are not supported. Set values to null to remove attributes.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------------------- | | options | SetUserAttributesOptions |

Since: 0.0.1

handleDeepLink(...)

handleDeepLink(options: HandleDeepLinkOptions) => Promise<void>

Handle a deep link URL for paywall campaigns.

This processes deep links associated with Superwall campaigns configured on the dashboard.

Only available on Android and iOS.

| Param | Type | | ------------- | ----------------------------------------------------------------------- | | options | HandleDeepLinkOptions |

Since: 0.0.1

getSubscriptionStatus()

getSubscriptionStatus() => Promise<GetSubscriptionStatusResult>

Get the current subscription status.

Only available on Android and iOS.

Returns: Promise<GetSubscriptionStatusResult>

Since: 0.0.1

addListener('superwallEvent', ...)

addListener(eventName: 'superwallEvent', listenerFunc: (event: SuperwallEventInfo) => void) => Promise<PluginListenerHandle>

Add a listener for Superwall analytics events.

These events can be forwarded to your analytics platform.

Only available on Android and iOS.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------- | | eventName | 'superwallEvent' | | listenerFunc | (event: SuperwallEventInfo) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('subscriptionStatusDidChange', ...)

addListener(eventName: 'subscriptionStatusDidChange', listenerFunc: (event: SubscriptionStatusDidChangeEvent) => void) => Promise<PluginListenerHandle>

Add a listener for subscription status changes.

Only available on Android and iOS.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------------------------- | | eventName | 'subscriptionStatusDidChange' | | listenerFunc | (event: SubscriptionStatusDidChangeEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('paywallPresented', ...)

addListener(eventName: 'paywallPresented', listenerFunc: (event: PaywallPresentedEvent) => void) => Promise<PluginListenerHandle>

Add a listener for when a paywall is presented.

Only available on Android and iOS.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'paywallPresented' | | listenerFunc | (event: PaywallPresentedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('paywallWillDismiss', ...)

addListener(eventName: 'paywallWillDismiss', listenerFunc: (event: PaywallWillDismissEvent) => void) => Promise<PluginListenerHandle>

Add a listener for when a paywall will dismiss.

Only available on Android and iOS.

| Param | Type | | ------------------ | ----------------------------------------------------------------------------------------------- | | eventName | 'paywallWillDismiss' | | listenerFunc | (event: PaywallWillDismissEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('paywallDismissed', ...)

addListener(eventName: 'paywallDismissed', listenerFunc: (event: PaywallDismissedEvent) => void) => Promise<PluginListenerHandle>

Add a listener for when a paywall is dismissed.

Only available on Android and iOS.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------- | | eventName | 'paywallDismissed' | | listenerFunc | (event: PaywallDismissedEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

addListener('customPaywallAction', ...)

addListener(eventName: 'customPaywallAction', listenerFunc: (event: CustomPaywallActionEvent) => void) => Promise<PluginListenerHandle>

Add a listener for custom paywall actions.

Triggered when a user taps an element with the data-pw-custom attribute.

Only available on Android and iOS.

| Param | Type | | ------------------ | ------------------------------------------------------------------------------------------------- | | eventName | 'customPaywallAction' | | listenerFunc | (event: CustomPaywallActionEvent) => void |

Returns: Promise<PluginListenerHandle>

Since: 0.0.1

removeAllListeners()

removeAllListeners() => Promise<void>

Remove all listeners for this plugin.

Since: 0.0.1

Interfaces

ConfigureOptions

| Prop | Type | Description | Since | | ------------- | ------------------------------------------------------------- | ------------------------------------------- | ----- | | apiKey | string | The Superwall API key from your dashboard. | 0.0.1 | | options | SuperwallOptions | Optional configuration options for the SDK. | 0.0.1 |

SuperwallOptions

| Prop | Type | Description | Default | Since | | ------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------- | ----- | | paywalls | PaywallOptions | Paywall presentation and behavior options. | | 0.0.1 | | logging | LoggingOptions | Logging configuration. | | 0.0.1 | | networkEnvironment | NetworkEnvironment | Network environment for API requests. | NetworkEnvironment.Release | 0.0.1 | | localeIdentifier | string | Override the locale identifier for localization. | | 0.0.1 | | shouldObservePurchases | boolean | Observe external Google Play purchases. Only available on Android. | true | 0.0.1 | | isExternalDataCollectionEnabled | boolean | Enable or disable external data collection for analytics. Only available on Android. | true | 0.0.1 |

PaywallOptions

| Prop | Type | Description | Default | Since | | ------------------------------------ | -------------------- | ----------------------------------------------------- | ----------------- | ----- | | isHapticFeedbackEnabled | boolean | Enable haptic feedback on paywall interactions. | true | 0.0.1 | | shouldShowPurchaseFailureAlert | boolean | Show an alert when purchase restoration fails. | true | 0.0.1 | | shouldPreload | boolean | Preload paywalls during SDK initialization. | true | 0.0.1 | | automaticallyDismiss | boolean | Automatically dismiss paywall on purchase or restore. | true | 0.0.1 |

LoggingOptions

| Prop | Type | Description | Default | Since | | ------------ | --------------------------------------------- | --------------------------- | --------------------------- | ----- | | level | LogLevel | The log level for SDK logs. | LogLevel.Warn | 0.0.1 | | scopes | LogScope[] | The log scopes to enable. | [LogScope.All] | 0.0.1 |

RegisterResult

| Prop | Type | Description | Since | | ------------ | ------------------------------------------------------- | --------------------------------------- | ----- | | result | PaywallResult | The result of the paywall presentation. | 0.0.1 |

RegisterOptions

| Prop | Type | Description | Since | | --------------- | -------------------------------------- | -------------------------------------------------------------------------------------------------- | ----- | | placement | string | The placement identifier configured in the Superwall dashboard. | 0.0.1 | | params | Record<string, any> | Optional parameters for audience filtering. Keys starting with $ are reserved for Superwall use. | 0.0.1 |

GetPresentationResultResult

| Prop | Type | Description | Since | | ---------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | ----- | | type | PresentationResultType | The type of presentation result. | 0.0.1 | | experiment | Experiment | Experiment information if the result is a paywall or holdout. | 0.0.1 |

Experiment

| Prop | Type | Description | Since | | ------------- | ------------------- | ----------------------------------------- | ----- | | id | string | The unique identifier for the experiment. | 0.0.1 | | variant | string | The variant assigned to the user. | 0.0.1 |

GetPresentationResultOptions

| Prop | Type | Description | Since | | --------------- | -------------------------------------- | ------------------------------------------- | ----- | | placement | string | The placement identifier to check. | 0.0.1 | | params | Record<string, any> | Optional parameters for audience filtering. | 0.0.1 |

IdentifyOptions

| Prop | Type | Description | Since | | ------------- | ----------------------------------------------------------------------- | ---------------------------------------- | ----- | | userId | string | The unique user ID to identify the user. | 0.0.1 | | options | IdentifyOptionsConfig | Additional options for identification. | 0.0.1 |

IdentifyOptionsConfig

| Prop | Type | Description | Default | Since | | ------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- | ------------------ | ----- | | restorePaywallAssignments | boolean | Restore paywall assignments from the server. Set to true when switching accounts to restore assignments. | false | 0.0.1 |

GetUserIdResult

| Prop | Type | Description | Since | | ------------ | ------------------- | ---------------------------------------------- | ----- | | userId | string | The current user ID (identified or anonymous). | 0.0.1 |

GetIsLoggedInResult

| Prop | Type | Description | Since | | ---------------- | -------------------- | ------------------------------------------- | ----- | | isLoggedIn | boolean | Whether the user is logged in (identified). | 0.0.1 |

SetUserAttributesOptions

| Prop | Type | Description | Since | | ---------------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ----- | | attributes | Record<string, any> | User attributes as key-value pairs. Keys starting with $ are reserved. Set values to null to remove attributes. | 0.0.1 |

HandleDeepLinkOptions

| Prop | Type | Description | Since | | --------- | ------------------- | ---------------------------- | ----- | | url | string | The deep link URL to handle. | 0.0.1 |

GetSubscriptionStatusResult

| Prop | Type | Description | Since | | ------------ | ----------------------------------------------------------------- | -------------------------------- | ----- | | status | SubscriptionStatus | The current subscription status. | 0.0.1 |

PluginListenerHandle

| Prop | Type | | ------------ | ----------------------------------------- | | remove | () => Promise<void> |

SuperwallEventInfo

| Prop | Type | Description | Since | | ---------- | ----------------------------------------------------------------- | ----------------------------------------- | ----- | | type | SuperwallEventType | The type of Superwall event. | 0.0.1 | | data | Record<string, any> | Additional event data as key-value pairs. | 0.0.1 |

SubscriptionStatusDidChangeEvent

| Prop | Type | Description | Since | | ------------ | ----------------------------------------------------------------- | ---------------------------- | ----- | | status | SubscriptionStatus | The new subscription status. | 0.0.1 |

PaywallPresentedEvent

| Prop | Type | Description | Since | | ----------------- | --------------------------------------------------- | ---------------------------------------- | ----- | | paywallInfo | PaywallInfo | Information about the presented paywall. | 0.0.1 |

PaywallInfo

| Prop | Type | Description | Since | | ---------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | ----- | | id | string | The unique identifier for the paywall. | 0.0.1 | | placement | string | The placement identifier. | 0.0.1 | | experiment | Experiment | Experiment information if the paywall is part of an A/B test. | 0.0.1 | | data | Record<string, any> | Additional paywall metadata. | 0.0.1 |

PaywallWillDismissEvent

| Prop | Type | Description | Since | | ----------------- | --------------------------------------------------- | ---------------------------------------------- | ----- | | paywallInfo | PaywallInfo | Information about the paywall being dismissed. | 0.0.1 |

PaywallDismissedEvent

| Prop | Type | Description | Since | | ----------------- | --------------------------------------------------- | ---------------------------------------- | ----- | | paywallInfo | PaywallInfo | Information about the dismissed paywall. | 0.0.1 |

CustomPaywallActionEvent

| Prop | Type | Description | Since | | ---------- | ------------------- | ------------------------------ | ----- | | name | string | The name of the custom action. | 0.0.1 |

Enums

LogLevel

| Members | Value | Description | Since | | ----------- | -------------------- | ---------------------- | ----- | | Debug | 'DEBUG' | Debug level logging. | 0.0.1 | | Info | 'INFO' | Info level logging. | 0.0.1 | | Warn | 'WARN' | Warning level logging. | 0.0.1 | | Error | 'ERROR' | Error level logging. | 0.0.1 |

LogScope

| Members | Value | Description | Since | | --------------- | ------------------------ | --------------------------- | ----- | | All | 'ALL' | All log scopes. | 0.0.1 | | Analytics | 'ANALYTICS' | Analytics related logs. | 0.0.1 | | Config | 'CONFIG' | Configuration related logs. | 0.0.1 | | Events | 'EVENTS' | Event tracking logs. | 0.0.1 | | Paywalls | 'PAYWALLS' | Paywall related logs. | 0.0.1 | | Purchases | 'PURCHASES' | Purchase related logs. | 0.0.1 |

NetworkEnvironment

| Members | Value | Description | Since | | --------------- | ------------------------ | ------------------------------------ | ----- | | Release | 'RELEASE' | Production environment. | 0.0.1 | | Developer | 'DEVELOPER' | Development environment for testing. | 0.0.1 |

PaywallResult

| Members | Value | Description | Since | | --------------- | ------------------------ | --------------------------- | ----- | | Purchased | 'PURCHASED' | User completed a purchase. | 0.0.1 | | Cancelled | 'CANCELLED' | User cancelled the paywall. | 0.0.1 | | Restored | 'RESTORED' | User restored purchases. | 0.0.1 |

PresentationResultType

| Members | Value | Description | Since | | ------------------------- | ------------------------------------ | --------------------------------------- | ----- | | PlacementNotFound | 'PLACEMENT_NOT_FOUND' | The placement was not found. | 0.0.1 | | NoAudienceMatch | 'NO_AUDIENCE_MATCH' | No audience matched for this placement. | 0.0.1 | | Paywall | 'PAYWALL' | A paywall would be presented. | 0.0.1 | | Holdout | 'HOLDOUT' | User is in a holdout group. | 0.0.1 | | PaywallNotAvailable | 'PAYWALL_NOT_AVAILABLE' | Paywall is not available. | 0.0.1 |

SubscriptionStatus

| Members | Value | Description | Since | | -------------- | ----------------------- | ------------------------------------------ | ----- | | Unknown | 'UNKNOWN' | Subscription status is unknown. | 0.0.1 | | Active | 'ACTIVE' | User has an active subscription. | 0.0.1 | | Inactive | 'INACTIVE' | User does not have an active subscription. | 0.0.1 |

SuperwallEventType

| Members | Value | Description | Since | | --------------------------------- | --------------------------------------------- | ---------------------------- | ----- | | FirstSeen | 'FIRST_SEEN' | First time user is seen. | 0.0.1 | | AppOpen | 'APP_OPEN' | App was opened. | 0.0.1 | | AppLaunch | 'APP_LAUNCH' | App was launched. | 0.0.1 | | AppClose | 'APP_CLOSE' | App was closed. | 0.0.1 | | SessionStart | 'SESSION_START' | Session started. | 0.0.1 | | DeepLink | 'DEEP_LINK' | Deep link was opened. | 0.0.1 | | TriggerFire | 'TRIGGER_FIRE' | Trigger was fired. | 0.0.1 | | PaywallOpen | 'PAYWALL_OPEN' | Paywall was opened. | 0.0.1 | | PaywallClose | 'PAYWALL_CLOSE' | Paywall was closed. | 0.0.1 | | PaywallDecline | 'PAYWALL_DECLINE' | Paywall was declined. | 0.0.1 | | TransactionStart | 'TRANSACTION_START' | Transaction started. | 0.0.1 | | TransactionComplete | 'TRANSACTION_COMPLETE' | Transaction completed. | 0.0.1 | | TransactionFail | 'TRANSACTION_FAIL' | Transaction failed. | 0.0.1 | | TransactionAbandon | 'TRANSACTION_ABANDON' | Transaction was abandoned. | 0.0.1 | | TransactionRestore | 'TRANSACTION_RESTORE' | Transaction restore. | 0.0.1 | | TransactionTimeout | 'TRANSACTION_TIMEOUT' | Transaction timeout. | 0.0.1 | | SubscriptionStart | 'SUBSCRIPTION_START' | Subscription started. | 0.0.1 | | FreeTrialStart | 'FREE_TRIAL_START' | Free trial started. | 0.0.1 | | SubscriptionStatusDidChange | 'SUBSCRIPTION_STATUS_DID_CHANGE' | Subscription status changed. | 0.0.1 |

Changelog

See CHANGELOG.md.

License

See LICENSE.

[^1]: This project is not affiliated with, endorsed by, sponsored by, or approved by Nest 22, Inc. or any of their affiliates or subsidiaries.