@capawesome/capacitor-superwall¶

Unofficial Capacitor plugin for Superwall SDK.¹

Deliver Live Updates to your Capacitor app with Capawesome Cloud

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.

This project is not affiliated with, endorsed by, sponsored by, or approved by Nest 22, Inc. or any of their affiliates or subsidiaries. ↩