# Users
Source: https://superwall.com/docs/dashboard/overview-users
Get a snapshot view of users who recently triggered a placement in your app, see their user journey, revenue events and more.
To view information about users who've recently triggered a placement in your app, **click** on the **Users** button in the sidebar. Looking for a summary of how Superwall keeps subscription states in sync and where this data surfaces? See [Subscription Management](/dashboard/subscription-management).
Once there, you'll see a list of users who've had a session within the last 24 hours by default (or you can filter them by a specific event):
### Searching by user identifier
If you need to find a specific user, use the search box at the top:
This will find users by their Superwall identifier (i.e. `$SuperwallAlias:44409AAF-244D-9F08-A18A-8F66B52FDZ01`). Hit **Enter** once you've copied or typed in an identifier, and the matched user's details will display.
### Filtering by event
Use the toggle at the right-hand side to toggle by a specific [placement](/campaigns-placements) or [standard placement](/campaigns-standard-placements) (such as session start, app close, app open, etc).
Below, Superwall displays all of the users who have opened a paywall the last 24 hours:
Any placements that are specific to your own app (i.e. ones that you've manually added to a campaign) will show with your app's logo next to it. All of Superwall's standard placements will have a Superwall logo.
Another great use of the Users dashboard? Get a quick preview of how many times one of your
placements has fired within the last day. Choose one from the placement toggle, and then you can
quickly see how many times it's been hit by the resulting users Superwall returns.
### Viewing user profiles
To see more details about a user, click anywhere on one of the rows. Then, the user profile will be presented where you can review revenue events, SDK events, and more:
It's divided into these sections:
1. **Overview:** Displays key user information including App User ID, Country, Total Spent, SDK Version, and user registration/last seen dates.
2. **Recent Events:** View revenue events and conversions, SDK events, and see the overall breadcrumb of actions the user has taken. You can filter or search by certain events as well.
3. **Entitlements:** Displays any active entitlements the user has attached, how long they'll be active and their corresponding identifiers. See "Granting entitlements" below for more.
4. **Aliases:** Any alias that Superwall has assigned the user will show here. Read more about how user aliases are created [here](/identity-management).
5. **Apple Search Ads:** If you have the [Apple Search Ads](/integrations/apple-search-ads) integration activated, you'll see any A.S.A. data that relates to the user (such as the keywords used which led to install, etc).
6. **User:** This houses basic information about the user, such as their install date, user seed and more.
7. **Device:** The user's device details. All device attributes are searchable here as well.
The user profile contains a wealth of information. You can search events by name by using the **Search Events** textbox, and quickly filter by event domains using the toggle at the top-right of the event browser:
The domains of events you can search and filter by are:
1. **Overview:** The default option, this shows all of the key events from today.
2. **Superwall Events:** These are [events](/tracking-analytics) automatically tracked by Superwall.
3. **App Events:** Placements that you've manually added to a campaign.
4. **Subscriptions Events:** Any transactions, trial starts, and similar subscription events.
5. **All Events:** Displays every single event that's occurred today.
Click on any of them to see more information about the event:
### Granting entitlements
You can manually grant a user any entitlement your app offers. This is useful for activating pro features for someone, handling support issues, and more.
To grant an entitlement, **click** on the **+** icon:
Then, select an entitlement, expiration date, and optionally a reason for granting it:
**Click** on the **Grant Entitlement** button to save your changes.
To revoke any entitlement you've granted, **click** on the **Trash icon**:
If you are using a purchase controller, take care to follow our [implementation guide](/docs/ios/guides/advanced-configuration). For example, manually granted entitlements register in our SDK as web entitlements. If you aren't accounting for those in your purchase controller code, manually granted entitlements will not work. See the example linked above under "Complete example for iOS" for guidance.
---
# Account Management
Source: https://superwall.com/docs/dashboard/manage-account
Manage your Superwall account preferences, security settings, and authentication methods.
The Account Settings page allows you to manage your personal profile information, security preferences, connected accounts, and passkeys. You can access this page by clicking on the profile menu in the bottom left corner of the dashboard and selecting **Manage**:
The account management page is organized into four main sections:
1. **Profile Information:** Manage your account details and email preferences.
2. **Security Settings:** Configure password and two-factor authentication.
3. **Connected Accounts:** Link social accounts for easier sign-in.
4. **Passkeys:** Set up password-free authentication using passkeys.
## Profile Information
The Profile Information section displays your account details and email verification status.
### Name
Your account display name. This field can be edited to update how your name appears throughout the Superwall dashboard.
### Email
Your account email address is used for:
* Signing into your Superwall account.
* Receiving notifications about your apps and campaigns.
* Account recovery and security alerts.
#### Email Verification
If your email is not verified, you'll see a **Not Verified** badge next to your email address. To verify your email:
1. Click the **Resend verification email** link below the email field.
2. Check your inbox for a verification email from Superwall.
3. Click the verification link in the email to complete the process.
Verifying your email ensures you can receive important notifications and helps secure your account.
## Security Settings
The Security Settings section helps you protect your account with password management and two-factor authentication.
### Password
Manage your account password to keep your account secure. If you need to change your password:
1. Click the **Request Password Reset** button.
2. Check your email for a password reset link.
3. Follow the instructions in the email to set a new password.
Use a strong, unique password for your Superwall account to maintain security best practices.
### Two-Factor Authentication (2FA)
Two-factor authentication adds an extra layer of security to your account by requiring a second form of verification in addition to your password.
When 2FA is **Disabled**, you'll see a **Disabled** badge and an **Enable 2FA** button. To enable two-factor authentication:
1. Click the **Enable 2FA** button.
2. Follow the setup wizard to configure 2FA using an authenticator app.
3. Save your backup codes in a secure location.
Once enabled, you'll need to provide a verification code from your authenticator app each time you sign in.
Make sure to save your backup codes when setting up 2FA. These codes can be used to access your account if you lose access to your authenticator app.
## Connected Accounts
The Connected Accounts section allows you to link your Google or GitHub accounts for faster, more convenient sign-in to Superwall.
### Google Account
Connect your Google account to sign in to Superwall using Google authentication.
**When not connected:**
* You'll see a **Not Connected** badge.
* Click **Connect Google** to link your Google account.
* You'll be redirected to Google's authentication page to authorize the connection.
**After connecting:**
* You can use "Sign in with Google" on the Superwall login page.
* You can disconnect your Google account at any time.
### GitHub Account
Connect your GitHub account to sign in to Superwall using GitHub authentication.
**When not connected:**
* You'll see a **Not Connected** badge.
* Click **Connect GitHub** to link your GitHub account.
* You'll be redirected to GitHub's authorization page to approve the connection.
**After connecting:**
* You can use "Sign in with GitHub" on the Superwall login page.
* You can disconnect your GitHub account at any time.
## Passkeys
Passkeys provide a secure, password-free way to sign in to your Superwall account using your device's biometrics (like Face ID, Touch ID, or Windows Hello) or a security key.
### What are Passkeys?
Passkeys are a modern authentication method that:
* Eliminate the need to remember passwords.
* Provide stronger security against phishing and credential theft.
* Use your device's built-in biometric authentication.
* Work across your devices when synced through your operating system.
### Adding Your First Passkey
When you haven't set up any passkeys yet, you'll see an empty state with instructions. To add a passkey, click the **Add Passkey** button to open the passkey creation dialog:
#### Passkey Name
Give your passkey a descriptive name to help you identify it later, such as "MacBook Pro," "YubiKey," or "iPhone." This is especially helpful when managing multiple passkeys across different devices.
#### Authenticator Type
Choose between two authenticator types:
**Cross-Platform (Recommended)**
Use a physical security key like YubiKey that works across multiple devices. This option is ideal if you want to use the same passkey on different computers or need a portable authentication method.
**Platform Authenticator**
Use your current device's built-in biometrics (Touch ID, Face ID, or Windows Hello). This option ties the passkey to your specific device and is convenient for single-device use.
Once you've entered a name and selected your authenticator type, click **Add Passkey** to complete the setup. Your browser or device will prompt you to authenticate, and your new passkey will be ready to use.
### Managing Multiple Passkeys
You can add multiple passkeys to your account, which is useful if you:
* Sign in from different devices (work computer, personal laptop, tablet, etc.).
* Want backup authentication methods.
* Share access across different locations.
Each passkey will be listed in this section with options to remove or rename them.
We recommend adding at least two passkeys to your account as a backup in case you lose access to one of your devices.
### Using Passkeys to Sign In
Once you've added a passkey:
1. Go to the Superwall login page.
2. Select the "Sign in with Passkey" option.
3. Your device will prompt you to authenticate using biometrics or your security key.
4. You'll be signed in immediately without entering a password.
Passkeys are tied to specific devices and browsers. If you clear your browser data or switch to a new device, you'll need to add a new passkey or use an alternative sign-in method.
---
# Overview
Source: https://superwall.com/docs/dashboard/overview-metrics
The Overview page gives you a holistic look at how your app is performing, complete with easy-to-find key metrics and top-level campaign data.
Once you've logged into Superwall, you'll be taken to the **Overview** page. Here, you can view key metrics and important campaign performance about your app.
You can toggle between your other apps to view with the Overview page too. Just use the toggle at the top left to choose another app.
### Quickstart
When you log in for the first time or add a new app, the Overview page displays a Quickstart wizard to help you get up and running. Complete the interactive checklist to finish your Superwall integration:
You can also get started with AI using our MCP and prompts:
### Dashboard sections
The overview dashboard is broken down between five main sections:
1. **Toggles:** Switch between new install or all users, and apply different time filters between them.
2. **Key Metrics:** Critical data about how your app is performing.
3. **SDK Alerts & News:** Alerts about new SDK versions available and company news.
4. **Campaigns:** Breakdowns of your active campaigns.
5. **Recent Transactions:** Displays the most recent transactions from the selected app.
### New installs versus all users
Using the toggles at the top, you can switch between viewing data about **New Installs** or **All Users**, along with changing date ranges between either of them:
Here's the difference between New Installs and All Users:
* **New Installs:** Represents users who installed your app within the selected time frame.
* **All Users:** Represents any user of your app, including returning and new users.
### Changing dates
Use the toggles at the top to change date ranges:
All of the key metrics and campaign data will be updated based on the range you select. If you need fine-grain control, choose **Custom** and choose any date range you like.
### Key metrics
View insightful metrics at the top of the overview page:
Here's what they mean, from left-to-right:
Each metric is representative of the data you've selected from the toggles above them.
| Name | Description |
| ----------------- | --------------------------------------------------------------------------------------------------------- |
| Users | The number of unique users who opened your app. |
| Paywall Opens | How many paywall presentations occurred. |
| Conversions | A total number of Conversions resulting from a presented paywall. |
| Paywalls Per User | The percentage of paywalls shown per user. Remember, each user may see more than one paywall per session. |
| Paywalled | The percentage of how many users were shown a paywall in total. |
| Converted | The percentage of users who converted (trial or paid). |
Use these metrics as a way to quickly get a sense of how your app is performing from a monetization standpoint.
Click on any metric to view a chart breakdown with more details about it.
### Campaigns
The active campaigns section gives you a quick overview of how your selected app's campaigns are performing:
For each campaign, Superwall will show:
* The **[placements](https://youtube.com/shorts/lZx8fAL8Nvw)** in-use by the campaign.
* How many **opens** those placements resulted in. Put differently, how many paywall presentations have occurred for the campaign.
* How many **conversions** the campaign has produced.
* The **conversion rate** the campaign currently holds.
Like the metrics section, all the data here is representative of the users or new installs and
time frame you've chosen from the toggles at the top of the Overview page.
Click on any campaign to dig deeper into them. If you would like to view all campaigns (active or paused), click **All Campaigns** at the top-right. Learn more about campaign [here](/campaigns).
### Recent transactions
To view recent transactions from your app, use the "Recent Transactions" view:
The transaction view displays:
* **User**: The user ID the event belongs to, along with an emoji flag representing their territory. Click on this value to quickly copy it to your clipboard.
* **Placement**: The placement that the event associates to. You can click this to open the campaign that the placement belongs to.
* **Paywall**: The paywall that the event took place on. Click this value to quickly open a modal preview of the paywall.
* **Product**: The product the event represents. Hover over this value to get a tooltip that will display the product's identifier.
* **Revenue**: Any revenue generated from the event.
* **Purchased**: The time the event occurred.
* **Type**: The event type. The list of events can be found below.
Keep in mind that Superwall displays transaction events based on the moment a server notification is received from the relevant store front. That means that the timing of the event may not necessarily be right when it actually occurred.
#### Transaction event types
Each of the following transaction types can show up in the transaction view:
| Event Name | Description |
| ------------------------- | ---------------------------------------------------------------------------- |
| **Main Events (Default)** | A collection of key subscription events for tracking purposes. |
| **All Events** | Includes every possible subscription-related event for complete tracking. |
| **Paywall Conversion** | Triggered when a user successfully converts or starts a trial via a paywall. |
| **Trial Start** | Indicates the beginning of a free trial period. |
| **Direct Sub Start** | A subscription starts without a trial period. |
| **One Time Purchase** | A non-subscription, single-payment transaction is completed. |
| **Intro Offer** | A user subscribes using an introductory offer. |
| **Trial Convert** | A trial that successfully converted into a paid subscription. |
| **Renewal** | An existing subscription renews for another billing period. |
| **Refund** | A user is refunded for a previous purchase. |
| **Trial Cancel** | A user cancels their trial before it converts to a paid subscription. |
| **Trial Expire** | A free trial ends without converting to a paid subscription. |
| **Cancel** | A user cancels their active subscription. |
| **Uncancel** | A previously canceled subscription is reactivated before expiration. |
| **Expire** | A subscription fully expires and is no longer active. |
You can filter the transaction view by any of these using the toggle at the top right:
If you see the paywall or placement values blank — don't worry. This means the user started a subscription, reactivated or whatever the event may be out *outside* of your app. Typically, this occurs when they visit their Apple ID's settings and change subscription or products there manually. Further, processing simply represents just that — Superwall received an event, but some of the details are still being fetched. Typically, this shouldn't make more than a few minutes.
---
# Placements
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-placements
undefined
Placements are the building blocks of a campaign. There are two types of placements:
1. **Standard placements:** These are placements you can use which Superwall already tracks and manages for you. Things like app installs, session start, failed transactions and more. We go into more detail about them [here](/campaigns-standard-placements).
2. **Placements you create:** These are app-specific placements you create. They usually correlate to some "pro" action in your app, like "chartsOpened" or "workoutStarted" in a weight lifting app.
At their core, you register placements that, in turn, present paywalls. They can be as simple as that, or you can combine them with [audiences](/campaigns-audience) to create specific filtering rules to control paywall presentations, create holdouts and more.
To see how they work with our SDK, check out the [docs](/feature-gating). For a quick example, here's what it looks like on iOS:
```swift
Superwall.shared.register(placement: "caffeineLogged") {
// Action to take if they are on a paid plan
}
```
**Don't be shy about adding placements.** If you think you *might* want to use a certain feature in your app with a placement — do it now. You can add the placement, and keep it paused. Then, if you ever want to feature-gate that particular flow, you can enable it. No app update required.
In short, add placements for everything you want to feature gate, and things you may *want* to in the future.
### Placement parameters
Placement parameters let you attach contextual data when registering a placement ([SDK docs](/docs/sdk/quickstart/feature-gating)). That data travels with the placement into the dashboard so you can branch logic or personalize the experience without shipping new app code.
Once parameters arrive in the dashboard, you can:
* Reference them in [audience filters](/campaigns-audience#using-user-properties-or-placement-parameters) to decide which users should see a paywall, holdout, or rule group.
* Surface them in the paywall editor as custom variables to drive copy, images, or logic. See [Using Placement Parameters](/docs/using-placement-parameters) for templating examples.
* Pass them along to analytics exports or downstream workflows so your broader stack understands the same context the campaign used.
### The placements interface
Under the placements section, you can:
* **Add** new placements.
* **Pause** running placements.
* **Delete** existing placements.
#### Adding a placement
To add a placement, **click** the "+" button in the top-right side of the placements section:
A modal will appear, and from there you can add a placement via two different means:
1. **Use an existing Superwall event:** Superwall automatically manages several events that can be used as placements. For example, the `survey_response` event could be used to show an entirely different paywall with a discounted offering if a user responded with a particular answer. See the [list](/campaigns-standard-placements) of the Superwall-managed events to learn more.
2. **Create your own, app-specific placement:** Here, you type in whatever event you want to use as a placement in your own app. In a caffeine tracking app, one of them might be when a user logs caffeine — something like `caffeineLogged`.
Either way, once you've selected one from our existing events or typed in your own, **click** on **Add Event** to associate the placement to your campaign:
You can also add placements "on the fly" by invoking `register(placement:"myNewPlacement")`. If
the placement you pass doesn't exist for a campaign, Superwall will automatically add it.
### Basic example of placement usage
Consider a caffeine tracking app. At a basic level, we want a paywall to show when a user tries to log caffeine, and they are not on a "pro" plan:
#### Step One: Make the placement
We'd make a placement called `caffeineLogged` inside a campaign:
#### Step Two: Assign a paywall
You can use the same paywall across different campaigns, placements, filters and more. In our case, we have one that we to show. So, since this campaign has a paywall linked to it already — we are good to go:
#### Step Three: Register inside our app
Inside our caffeine tracking app, when the user taps a button to log caffeine, we would register the `caffeineLogged` event. This way, if the user is pro, the closure is called and the interface to log caffeine is shown. If they are not pro, then our paywall will show:
```swift
Button("Log") {
Superwall.shared.register(placement: "caffeineLogged") {
presentLogCaffeine.toggle()
}
}
```
And that's it!
Remember, you can pause placements at any point. So here, if you wanted to run a campaign where
logging caffeine was free for a weekend — no update would be required. Just tell your users, and
pause the placement in your Superwall dashboard. No app update required.
There are also several out-of-the box placements you can use, learn more about standard placements [here](/campaigns-standard-placements).
---
# Rules
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaign-rules
Rules allow you to decide _which users_ see a paywall.
This page is outdated. Please visit this [one](/campaigns-audience) for the most relevant
information.
1. Rules are evaluated in order.
2. Once a rule is matched, no other rules are evaluated within the campaign.
3. A user's paywall assignment is sticky.
**Assignments Are "Sticky"**
Once a user is assigned a paywall or a holdout within a rule, they will continue to see that assignment, regardless of the paywall's percentage, unless you reset assignments by clicking the reset icon next to Assigned or remove the paywall from the rule via the X button.
Remember: Changing a paywall's percentage only affects **new users**. It doesn't affect assignments for users who already saw that paywall.
This allows you to decide if you should continue showing an old paywall to users who already saw it. For example, you may decide to increase prices but keep the paywall with the old pricing visible for those who've already seen it.
### Adding Rules
Add a rule to a campaign by clicking the **Add Rule** button from within a [campaign](/docs/campaigns).
### Updating Conditions with the Rule Editor
Change a rule's condition by clicking the highlighted condition itself:
In this example, we add a condition that evaluates to true if user has logged greater than or equal to 3 days.
This opens the **Rule Editor**. Here, you can edit the rule to set conditions based on user, device or event parameters and set a limit to how often the rule is matched:
In this example, only users who have the `en` `deviceLanguageCode` and have a `creator` `account_type` will match this rule. They will only match this rule once every 2 days.
Clicking on the condition reveals a dropdown of possible conditions which you can filter on:
Conditions are added to this list when data is retrieved from the SDK via registering events or setting user attributes. If a condition doesn't yet exist in the drop down, you can manually add it by referencing it with dot syntax. For example, `user.custom_parameter` would reference `custom_parameter` on the `user` object. As with [paywall text variables](/paywall-editor-variables), the following objects are all available to use:
| Object | Description |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| user | User attributes that you set via the SDK using setUserAttributes(\_:). See [Setting User Attributes](/docs/setting-user-properties) |
| params | Parameters defined when [registering an event](/docs/feature-gating). |
| device | Device attributes that are gathered by the SDK. |
Additionally, you can use the following device properties: `device.minutesSince_X`, `device.hoursSince_X`, `device.daysSince_X`, `device.monthsSince_X`, and `device.yearsSince_X`, where X is the name of an event that you've [registered](/docs/feature-gating) or a [Superwall event](/docs/tracking-analytics). This gives you the days etc since the last occurrence of the event that you specify, excluding the event that triggered the paywall. For example, a campaign with an `app_open` event and the rule `device.daysSince_app_open > 3` will present a paywall on app open only if the last `app_open` event was over 3 days ago.
### Limit
You can also add a limit to how often a rule should trigger. This allows you to
say "show this once per day" or "show this once per week". It allows you to
balance between number of paywall impressions (which increase conversions) with
the potential impact on retention if you show the paywall too often.
### Segmenting Users into Cohorts Across Campaigns
Users are assigned a random number from 0 to 99 on app install (which is reassigned if you call `reset()`). You can use this to segment users into cohorts across campaigns. For example, in campaign A you may have a rule `if user.seed < 50 { show variant A } else { show variant B }`, in campaign B you may a rule `if user.seed < 50 { show variant X } else { show variant Y }`. Therefore users who see variant A will then see variant X.
### Rule Settings
The following settings can be access by clicking the ellipse icon to the right of any rule
| Setting | Description |
| --------- | ----------------------------------------------------------------- |
| Move Up | Swaps the rule's order with the rule directly above it. |
| Move Down | Swaps the rule's order with the rule directly below it. |
| Pause | Pauses the rule, preventing it from being evaluated all together. |
| Delete | Deletes the rule. |
---
# Understanding Experiment Results
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-understanding-experiment-results
undefined
To view the results of any paywall experiment that's running, **click** the **Results** tab in the campaign details view:
There are three main sections: **Paywalls**, **Placements**, and **Graphs (defaults to Proceeds Per User)**. Each section has a toggle at the top right to change associated metrics.
### Paywalls
Here, you'll see each paywall being used (or that was used) in an experiment. Superwall will show you metrics such as proceeds, users and much more. There are several metric to explore, and you can hover over any of them to get more details about what each metric represents:
Subscription lifecycle events (i.e. renewals, cancellations, etc) are matched to paywall
conversions using unique identifiers provided by the platform at checkout and via webhook events.
You can also filter results per paywall. Click the checkbox next to one to have the results page only show data for that specific paywall:
### Placements
Here, you can get a detailed breakdown of each placement associated with the campaign. This helps you form a clear picture of what features or actions are leading to conversions.
### Graphs
Finally, the last section has several graphs to explore campaign performance. It defaults to Proceeds Per User.
### Setting up revenue tracking
Before any metrics based on revenue will display, you need to set up revenue tracking. To set up revenue tracking:
1. **Click** on **Settings** in the dashboard.
2. **Click** on **Revenue Tracking**.
3. Use the guides to follow any of the revenue tracking methods. For more details, check out our [docs](/overview-settings-revenue-tracking).
If you don't have revenue tracking setup, you will see a banner on your dashboard:
### A note on conversions, trial starts, and subscription starts
Each experiment will notably report **conversions**, **trials starts** and **subscription starts**. In some cases, it may seem like these numbers don't match up quite how you'd expect. That could be due to a few different reasons:
1. **Reporting methods:** Conversions are an *SDK reported* event, while trial and subscription starts are *server reported* events. Sometimes, the server events might be a little behind on their reporting — whereas SDK events are usually instantaneous.
2. **Understanding Resubscriptions and Cancellations:** When someone resubscribes or restarts a paused subscription through a paywall, it *won't* be considered a new trial or a new subscription start. However, it *will* be counted as a **conversion**. As such, any revenue generated will be linked to that paywall. If they later decide to cancel the subscription, the cancellation will also be linked to the same paywall.
3. **Attribution:** And finally, attribution can sometimes be a complicated metric to track. If something doesn't look right on your end, please feel free to reach out to us and we'll always export your data so you can exactly where our numbers are coming from.
### Confidence intervals
Use confidence intervals to gauge how each paywall is performing against the other ones in your experiments. Hover over a specific metric to view the confience interval (i.e. Conversion Rate, Proceeds Per User, etc.):
Keep in mind that these intervals represent the percentage of users converted, it doesn't take into account revenue. Put differently, paywall A could have a higher conversion rate, but with a much cheaper offering than paywall B. Paywall B could still be making more money, but at a lower conversion rate with the higher-priced product.
For more on confidence intervals, check out our in-depth [blog post](https://superwall.com/blog/confidence-intervals-in-experiment-readouts).
### Identifiers and cohorting with 3rd party analytics
If you scroll to the end of the experiment results table, you'll find some useful identifiers which you can use to interface with third-party tools you may be using:
1. **Experiment id:** The identifier of the experiment that the paywall is a part of.
2. **Variant id:** The identifier representing the variant the paywall represented in the experiment.
3. **Paywall id:** The identifier for the paywall in the experiment, which associates back to the variant.
To learn more about interfacing with 3rd party analytics, check out this [doc](/cohorting-in-3rd-party-tools).
---
# Audiences
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-audience
undefined
Audiences allow you to set up simple or complex filtering rules to match certain users and show a paywall to them. For a user to see a paywall, they must be matched to an audience. An audience can show one or more paywalls based on a percentage you set (i.e. show paywall A to 70% of users, and paywall B to 30%).
**Another way to think of them is this: If you're wanting to create conditions, filters or certain rules or flows that must happen to show a paywall — then you create an audience for it.**
If creating filters to show a paywall under certain conditions doesn't apply to you, then you can simply leave the default audience on — it'll match everyone who hits a [placement](/campaigns-placements).
In the audience view, you can set up filtering rules, check results of experiments and recent transactions resulting from them. All of your current audiences will show in the left-hand side of the campaign details screen:
The audience section lets you [edit the order](#reordering-audiences) in which audiences are evaluated. **Superwall evaluates audiences top-to-bottom.** For example, consider you had three audiences for a caffeine tracking app:
* An audience for users who tried to set a custom app icon.
* An audience for users who've logged caffeine late at night.
* And, everyone else.
If a user logged caffeine in the morning, Superwall would first check if they matched the custom app icon audience, and then the audience for logging caffeine late at night. Since neither of those match (since they are logging caffeine in the morning, and not setting a custom icon), they'd land in the "everyone else" audience bucket.
### Adding a new audience
To create a new audience, **click** the **+** button in the audiences section, located at the left-hand side of the campaign details view:
You have two options for creating a new audience:
1. **From scratch:** This is the default option. It will create a new audience with no filters.
2. **Import existing...:** Use this to copy an existing audience and use it as a template for a new one. See [Duplicate an audience](#duplicate-an-audience) for more details.
### Renaming Audiences
To rename an audience, **click** the **pencil icon**, located at the top of a selected audience:
### Configuring an audience
To use an audience to filter for a particular set of events, rules or any other condition — you use **filters**, specify if an **entitlement** should be evaluated, along with an optional **limit**.
#### Creating filters
You can add filters (i.e. rules or conditions to match against) by **clicking** on an audience, and then clicking the **+ Add Filter** button:
From there, select any of the events to create a filter with. For example, if you want to use a placement you've made to match against:
1. Click "+ Add Filter".
2. Type in "event\_name".
3. For the evaluation operator, choose "is".
4. And then, type in the placement's name.
For example, if we wanted to show a certain paywall for users who tried to set a custom icon, it might look like this:
When you have a condition setup, **click** the **Save** button towards the bottom to apply it:
If you don't want to save any filter you're working on, **click** the **Discard** button by the save button.
You can combine rules together, too. In the following example, if we only wanted the paywall to show on iOS, and not Android, you can simply click "+Add Filter" once more, and add the condition:
#### Using user properties or placement parameters
You can reference [user attributes](/sdk/quickstart/setting-user-properties) and [placement parameters](/docs/using-placement-parameters) in campaign filters. For example, if you were to set `hasLoggedCoffee` on your user, you could use that in a filter.
**Adding user properties**
1. **Click** on Add Filter, and then click the **+** icon:
2. Select **User** and name the property, then save it:
3. Now you can select **User** (or type the property name) and the new property is available for user in your filter. Here, it's at the bottom:
**Adding placement parameters**
This works exactly the same as above, just choose "Placement" instead:
#### Using rule groups
You can combine rules together in groups. For example, you can mix **AND** and **OR** operators in the same group. To create a rule group, **click** on **+ Add Group** in the filter editor.
In the following example, we've created a filter that matches...
* Users who have logged caffeine at least 5 times in the last week.
* And their user seed greater than or equal to 60.
* And if the app has been launched at least twice this week *and* they are on iOS.
For a hands on tutorial of creating multiple filters to show different paywalls, check out this video:
Assignments Are "Sticky". Once a user is assigned a paywall or a holdout within an audience, they
will continue to see that assignment unless you reset them (by clicking the reset icon next to
Assigned) or remove the paywall from the rule via the X button. Remember: Changing a paywall's
percentage only affects **new users**. It doesn't affect assignments for users who already saw
that paywall.
#### Matching to entitlements or subscription status
To match your campaign to specific entitlement, or base it on the user's current subscription status, **click** the entitlements button and choose an option:
1. **Unsubscribed users (default):** Users without an active entitlement match.
2. **All users**: All users match.
3. **Auto-renew disabled**: Users who have opted out of auto-renew.
4. **Active trials, auto-renew disabled**: Users currently in an active trial, but they've already cancelled it before their trial period expired.
5. **Active subscriptions, auto-renew disabled**: Users with an active subscription who have auto-renew turned off (i.e. these users will eventually churn).
6. **Expired entitlements**: Users whose entitlements have expired.
7. **Specify entitlements...**: Users with the specified entitlement(s) and state are matched. Here, you can combine multiple entitlement checks, too. For example, if `gold` is `active` but `platinum` is `inactive`:
Once you've set up entitlement checks for the campaign, **click** the **Save** button that appears at the bottom:
#### Setting a limit
To set a limit for an audience, **click** the **+ Add Limit** button — located below the entitlements section:
This is useful if you want to limit how many times a user can match with the audience. You can choose how many times the limit should be placed, along with a time duration and time span. For example: 1 (times) every 60 (time duration) minutes (time span):
Once you've set up a limit, **click** the **Save** button at the bottom:
#### Using AI audience generation
Superwall can generate an audience for you based on a description of the audience you want to target. To do this, **click** the **AI Audience** button — located here:
Then, simply describe the audience you want to target, and Superwall will generate a filter for you. Superwall can use your custom placements and user attributes to generate a filter for you. For example, you could type "Target all users in the United States who have opened at least once":
From there, Superwall will generate a filter for you. You can then **click** the **Save** button to apply it:
### Audience details
When you select an audience, you can toggle between four main sections:
#### Filters
This is where you can configure filters and limits. If there isn't one set, this will say "Everyone", indicating the audience will match all users.
#### Paywalls
This section displays the paywalls which will present for the audience.
You can add new paywalls for the audience to use, or set a percentage to show across multiple paywalls when the audience is matched. To add a new paywall, click on **+ Add Paywall** to associate one to the current campaign.
#### Results
Here, you can see how paywalls are performing for the given audience.
Superwall will show top-level metrics here, but if you want to see more details, **click** the **Charts** button at the top-right hand side of the metrics.
#### Users
Finally, the users section shows **recent matches** in the audience from filters set up for it, and **transactions** that have resulted from them.
When viewing either one, Superwall will show which placement resulted in the paywall being presented (recent matches), and which placement led to a conversion (transactions).
### Reordering audiences
To change the order that Superwall evaluates audiences, simply drag and drop them in the left-hand sidebar of any opened campaign:
Remember, Superwall will check the audience at the top of the list here, and then go down one-by-one until it hits a match. These checks occur when a user hits a code path where you've registered a [placement](/campaigns-placements) or if an automatically tracked placement is triggered (i.e. something like `survey_response`).
### Changing audience status
You can **duplicate**, **delete**, **pause** or **archive** an audience using the buttons at the top of open audience:
Archived audiences can be restored at any point. Paused campaigns are not evaluated by Superwall.
### Duplicate an audience
To duplicate or copy an existing audience, **click** the **+** button and choose "Import existing...". Then, you can select the audience you want to copy. Click it to use it as a template for a new audience:
From there, you can edit its name, filters, paywalls, and more.
### Common filters
#### Event count filters
Requires SDK version 4.7.0 and above.
Event count filters are a powerful way to target users based on the number of times they've performed an action or fired a placement. In this example, we would target users who have triggered the `caffeineLogged` placement at least 3 times in the last week:
You can choose from the following time ranges:
* Hour
* Day
* Week
* Month
* Since install
To create an event count filter, **click** on the **+ Add Filter** button, and then select one of the "Occurrences..." options:
Then, filter for the event or placement you want to target. In our example, we're filtering for the `caffeineLogged` placement:
Then choose the operator you want to use and the number of times the event or placement must have occurred. In our example above, we're targeting users who have logged caffeine at least 5 times in the last week. Be sure to **click** the **Save** button to save it:
#### App versions
To filter by app version, add `appVersion` as a filter. This is helpful if you want to show a paywall to users on a specific version of your app. For example, to target users on version 1.0.1 or later, add a filter for `appVersion`, the operator to is greater than or equal to, and the value to 1.0.1:
Another useful app version filter is `appVersionPadded`. When filtering by app version, string comparisons can cause unexpected behavior for versions with triple digits. For example, `3.100.0` would incorrectly compare as less than `3.65.0` when using a standard `appVersion` filter.
To solve this, use the `appVersionPadded` in your filter. It automatically zero-pads each segment of the version (e.g., `3.65.0` becomes `003.065.000` and `3.100.0` becomes `003.100.000`), allowing greater than and less than comparisons to work as expected.
Use `appVersionPadded` instead of `appVersion` whenever you're doing a greater than or less than comparison across major or minor version updates that could exceed two digits.
Here's an example:
| Version | `appVersion` Comparison to 3.65.0 | `appVersionPadded` Comparison to 003.065.000 |
| ------- | --------------------------------- | -------------------------------------------- |
| 3.64.0 | Less than | Less than |
| 3.65.0 | Equal | Equal |
| 3.66.0 | Greater than | Greater than |
| 3.100.0 | **Less than** ❌ | **Greater than** ✅ |
#### User seeds
One particularly useful property to filter by are *user seeds*, which are automatically assigned by Superwall to a user from 0-99. You can add them as a filter by entering `user.seed`. User seeds are primarily used to control entirely different user experiences across different campaigns.
For example, imagine testing whether showing a paywall early in onboarding or at the end of it works better for conversion:
**Campaign A: Placement early in onboarding**
For your audience filter, you could use user seeds 0-49.
Here's what that would look like when setting up the filter:
**Campaign B: Placement late in onboarding**
And here, you'd filter by user seeds 50-99.
Even though these are filters that were set up across two entirely different campaigns, you can still define certain user audiences without creating custom placements for each of them. Using user seeds, you can easily compare the campaign results, too.
---
# Paywalled Users
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-paywalled-users
undefined
Paywalled users are users that have been presented a paywall from the selected audience. To see recent matches from your audience filter and its resulting transactions, **click** on the **Users** tab above the campaign details:
You'll find two main sections:
1. **Recent Matches:** Here, you'll see every user which matched your audience filter.
2. **Transactions:** Next, this displays any resulting transaction which occurred within the audience.
Note that both Recent Matches and Transactions show the [placement](/campaigns-placements) which
triggered the match or transaction. This is incredibly useful in helping you gauge which actions
are resulting in conversions.
### Recent matches
Recent Matches show you each user, their locale, and the placement which matched them to your selected audience (among other data) from the last 24 hours:
You can click on any user to see more details about them, including the history of the actions they took. You can also filter events by Superwall-managed events, your own app events and more:
For more on viewing users, check out this [doc](/overview-users).
### Transactions
The transactions shows all transactions which came from the campaign in the last 24 hours:
You can click on any user here, too, to see more details about them. Again, take note of the placements here — because they were directly linked to a conversion.
---
# Starting an Experiment
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-starting-an-experiment
undefined
You run experiments in Superwall by adding multiple paywalls to an audience. To start an experiment:
1. Select an audience.
2. Click the Paywalls tab.
3. Add two or more paywalls.
Here's a .gif, beginning to end, setting up an experiment:
It's as simple as that to start a paywall experiment.
### Setting presentation percentages
You must set a presentation percentage between your paywalls within the experiment. This determines how often they'll show based off of the percentage set for each one.
To set a percentage, **click** the **pencil icon** above *any* of the paywalls attached to the audience:
Then, assign percentages from 0%-100% for each of them. In total, your percentages should equal 100 (i.e. paywall A shows 10%, paywall B shows 30%, and paywall c shows 60% of the time) unless you're purposely creating a [holdout](/campaigns-starting-an-experiment#creating-holdouts). When you're done, **click** the **Checkmark** icon below any paywall:
### Resetting assignments
If you change your experiment, or simply want to change the presentation percentages between your paywalls, you might want to reset your assignments. Remember that when an audience matches a user, it's *sticky* — and the same is true of when someone is matched to a paywall within an experiment.
So, if you want to make sure everyone is matched again to a paywall based off new percentages, **click** the refresh button below a paywall when editing percentages (next to where it says "X assigned"):
Resetting assignments also resets the stats for the experiment.
### Creating holdouts
A *holdout* occurs when you purposely edit an audience to *not* present a paywall in some cases. Setting a holdout is useful when you want to test the effectiveness of showing a paywall.
**To create a holdout, set your paywall presentation percentages to be less than 100% across all of the paywall you're using.**
Here's an example of one paywall set to show 50% of the time, meaning the other 50% of users who match this audience will be in a holdout:
It's common to pair holdouts to certain [placements](/campaigns-placements) to see whether a holdout increases or decreases transactions. The holdout group will act as a control which you can compare against.
### Removing variants
During an experiment, you may find that one or more paywalls are performing significantly worse than the others. In that case, you would probably consider removing it. You can simply remove the paywall, or set its presentation percent to 0%, and your experiment will continue. No metrics will be affected or reset. **Resetting assignments will reset metrics, removing paywalls will not.**
---
# Campaigns
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns
Campaigns are logical groupings of paywalls to show when certain _events_ are registered and _conditions_ are met. They are an incredibly powerful tool for creating experiments and managing best-in-class monetization flows.
View **Campaigns** by clicking them over on the left-hand **sidebar**:
Campaigns consist of three main concepts:
1. [Placements](/feature-gating)
2. [Audiences](/campaigns-audience)
3. [Paywalls](/paywall-editor-overview)
Campaigns are the centerpiece of Superwall. You can use one, or several, campaigns that can run concurrently. To understand campaigns, think of them like this:
* In a campaign, you add **placements** — which are actions you want to result in a paywall, or might someday want to result in a paywall(i.e. `loggedCaffeine`, `addedEntry`, etc).
* Then, as users take actions in your app, those placements are **registered** in the Superwall SDK.
* When a placement is registered, it's then evaluated by Superwall. Superwall looks at your campaign **[filters](/campaigns-audience#configuring-an-audience)**, and may or may not show a matching **paywall**.
With this setup, you can be incredibly simple or make in-depth, complex filters which determine when (and what) paywall is shown. You can set the percentage of new users that see each paywall, or even configure no paywall (a.k.a. a holdout) to be shown for certain placements.
### Toggling campaigns by status
You can toggle between campaigns by their status using the tabs at the top (above the campaigns):
* **All:** The default view. This shows all of your campaigns, regardless of their status.
* **Active:** Campaigns being used in production and serving up paywalls.
* **Inactive:** Campaigns that are not serving paywalls in production, but can be quickly re-enabled.
* **Archived:** Campaigns that have been archived, and not attached to any campaign. These can be restored.
### Viewing campaign top-level metrics
Each campaign will also display its active placements and top-level metrics (if any are available). In this example, the campaign at the top has data, while the one below it doesn't:
Metrics shown include:
* **Opens:** The amount of time any of the campaign's placements resulted in a paywall being presented.
* **Conversions:** The number of conversions produced from any paywall attached to the campaign.
* **Conversion Rate:** The conversion rate of the current campaign.
If the campaign isn't currently serving any paywalls because none have been attached to it, you'll
see a wanting indicating that in this view. In the image above, that's the case for the campaign
at the bottom, called "Survey".
### Toggling campaigns by date
To toggle the date range that the metrics previously mentioned should display within, use the date toggle at the top-right side:
### Viewing campaign details
To view more about any campaign, to set up filters, edit placements, paywalls and more — simply **click** on any campaign listed in the table. Then, campaigns details will be presented. More on that in the next [page](/campaigns-structure).
---
# Campaign Structure
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-structure
undefined
Once you open a campaign, you can edit its details, placements, control experiments, view results, manage paywalls and more. The campaign detail screen is divided into three separate sections:
### Placements
Under the placements section, you can add, pause or delete existing placements. Placements are actions, or implicit events, which you can use to show a paywall or implement feature gating. Be liberal with adding placements, you can always pause them on-the-fly without app updates. Or, if you later decide to paywall a particular feature, it gives you more flexibility if you already have a placement for that particular action.
Learn more about placements [here](/campaigns-placements).
### Audiences
Audiences allow you to set up simple or complex filtering rules to match against certain users, show a particular paywall to them, view results of experiments and recent transactions resulting from them. All of your current audiences will show in the left-hand side of the campaign details screen.
Learn more about audiences [here](/campaigns-audience).
### Experiments
Audiences are also where you set up paywall experiments, and view their performance. Experiments allow you to show one or more paywalls, and see which one is "winning".
Learn more about experiments [here](/campaigns-starting-an-experiment).
### Renaming campaigns
To rename a campaign, click on the pencil icon next to the campaign's name, located in the top-left hand side of the campaign details screen:
---
# Standard Placements
Source: https://superwall.com/docs/dashboard/dashboard-campaigns/campaigns-standard-placements
undefined
Standard placements are events that Superwall automatically manages. The following [Superwall Events](/tracking-analytics) are registered by the SDK and can be added as placements in campaigns to present paywalls:
* [`app_install`](#app_install)
* [`app_launch`](#app_launch)
* [`deepLink_open`](#deeplink_open)
* [`session_start`](#session_start)
* [`paywall_decline`](#paywall_decline)
* [`transaction_fail`](#transaction_fail)
* [`transaction_abandon`](#transaction_abandon)
* [`survey_response`](#survey_response)
* [`touches_began`](#touches_began)
## `app_install`
### Usage
This is registered when the SDK is configured for the first time. Use it for first-launch onboarding flows or one-time offers.
### Parameters
These parameters are always available:
| Name | Type | Description | Required |
| --------------------------- | ------- | ----------------------------------------------------- | -------- |
| app\_session\_id | string | Identifier for the current app session. | yes |
| is\_superwall | boolean | Always true for Superwall events. | yes |
| using\_purchase\_controller | boolean | True when a custom purchase controller is configured. | yes |
## `app_launch`
### Usage
This is registered when the app is launched from a cold start. Use it to present paywalls on fresh launches.
### Parameters
Same as `app_install`:
| Name | Type | Description | Required |
| --------------------------- | ------- | ----------------------------------------------------- | -------- |
| app\_session\_id | string | Identifier for the current app session. | yes |
| is\_superwall | boolean | Always true for Superwall events. | yes |
| using\_purchase\_controller | boolean | True when a custom purchase controller is configured. | yes |
## `deepLink_open`
### Usage
This is registered when a user opens the app via a deep link. First, you need to make sure to [tell Superwall when a deep link has been opened](/in-app-paywall-previews).
You can use the URL parameters of the deep link within your rules. This works for both URL schemes and universal links.
For example, you could make three conditions to match this deep link: `myapp://paywall?offer=July20`. Here's how:
1. Add a rule to see if the event is `deepLink_open`. See the `paywall_decline` example below for how to add a standard placement.
2. Add `params.offer` is equal to whatever you've made, like `July20` for a timeboxed offer you made in that month.
3. Then, you'd also add `params.path` is equal to the text of a path you setup, like `paywall`.
### Parameters
After the app has emitted the first `deepLink_open` event for a given URL, these fields become available to audience filters:
| Name | Type | Description | Required |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------- | -------- |
| params.url | string | Full deep link URL. | yes |
| params.path | string | Path portion of the URL. | yes |
| params.host | string | Host portion of the URL. | yes |
| params.query | string | Full query string. | yes |
| params.pathExtension | string | Path extension of the URL. | yes |
| params.lastPathComponent | string | Last path component of the URL. | yes |
| params.fragment | string | Fragment portion of the URL. | yes |
| params.\ | string | Optional. Any query string parameter (for example, \`params.offer\` for \`?offer=July20\`). | no |
## `session_start`
### Usage
This is registered when the app is opened after at least 60 minutes since the last `app_close`.
### Parameters
Same as `app_install`:
| Name | Type | Description | Required |
| --------------------------- | ------- | ----------------------------------------------------- | -------- |
| app\_session\_id | string | Identifier for the current app session. | yes |
| is\_superwall | boolean | Always true for Superwall events. | yes |
| using\_purchase\_controller | boolean | True when a custom purchase controller is configured. | yes |
## `paywall_decline`
### Usage
This is registered when a user manually dismisses any paywall. You can combine this with rules to show a paywall when a user closes a specific paywall. First, [add](/campaigns-placements#adding-a-placement) the standard placement to a campaign:
Then, create a filter in the audience using it:
Here, when a user closes the paywall named `PaywallA`, a new paywall will show.
Note that you can't reference parameters that you've passed in to your original register call in your rules for `paywall_decline`.
### Parameters
Audience filters for `paywall_decline` placements can use the following parameters (empty values mean the field isn't applicable):
| Name | Type | Description | Required |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| paywall\_id | string | The paywall ID where the decline occurred. | yes |
| paywall\_name | string | The paywall name shown in the dashboard. | yes |
| presented\_by\_event\_name | string | The placement name that originally presented the paywall (for example, \`onboarding\`). Empty if the paywall was presented programmatically. | yes |
| presented\_by | string | How the paywall was presented (\`placement\` or \`programmatically\`). | yes |
| paywall\_product\_ids | string | Comma-separated product identifiers attached to the paywall. | yes |
| primary\_product\_id | string | The first product on the paywall, or empty if none. | yes |
| secondary\_product\_id | string | The second product on the paywall, or empty if none. | yes |
| tertiary\_product\_id | string | The third product on the paywall, or empty if none. | yes |
| \\_product\_id | string | Product identifier keyed by the product name (for example, \`annual\_product\_id\`). | yes |
| is\_free\_trial\_available | boolean | True when any introductory offer is available (including both free and paid trials). | yes |
| feature\_gating | string | Feature gating behavior for the paywall. | yes |
## `transaction_fail`
### Usage
This is registered when the payment sheet fails to complete a transaction (this does not include user cancellation). Use it to show an exit offer after a failed attempt.
### Parameters
Audience filters for `transaction_fail` placements can use the following parameters (empty values mean the field isn't applicable):
| Name | Type | Description | Required |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| paywall\_id | string | The paywall ID where the failure occurred. | yes |
| paywall\_name | string | The paywall name shown in the dashboard. | yes |
| presented\_by\_event\_name | string | The placement name that originally presented the paywall (for example, \`onboarding\`). Empty if the paywall was presented programmatically. | yes |
| presented\_by | string | How the paywall was presented (\`placement\` or \`programmatically\`). | yes |
| paywall\_product\_ids | string | Comma-separated product identifiers attached to the paywall. | yes |
| primary\_product\_id | string | The first product on the paywall, or empty if none. | yes |
| secondary\_product\_id | string | The second product on the paywall, or empty if none. | yes |
| tertiary\_product\_id | string | The third product on the paywall, or empty if none. | yes |
| \\_product\_id | string | Product identifier keyed by the product name (for example, \`annual\_product\_id\`). | yes |
| is\_free\_trial\_available | boolean | True when any introductory offer is available (including both free and paid trials). | yes |
| feature\_gating | string | Feature gating behavior for the paywall. | yes |
The event payload also includes a failure `message`; see [Superwall Events](/tracking-analytics) for full details.
## `transaction_abandon`
### Usage
This is registered when a user dismisses the store purchase sheet before the transaction completes. If a transaction-abandon paywall matches, Superwall immediately closes the current paywall and presents the new one.
### Parameters
Audience filters for `transaction_abandon` placements can use the following parameters (empty values mean the field isn't applicable):
| Name | Type | Description | Required |
| ----------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| paywall\_id | string | The paywall ID where the transaction was started. | yes |
| paywall\_name | string | The paywall name shown in the dashboard. | yes |
| presented\_by\_event\_name | string | The placement name that originally presented the paywall (for example, \`onboarding\`). Empty if the paywall was presented programmatically. | yes |
| presented\_by | string | How the paywall was presented (\`placement\` or \`programmatically\`). | yes |
| abandoned\_product\_id | string | The product identifier the user attempted to purchase before canceling. | yes |
| paywall\_product\_ids | string | Comma-separated product identifiers attached to the paywall. | yes |
| primary\_product\_id | string | The first product on the paywall, or empty if none. | yes |
| secondary\_product\_id | string | The second product on the paywall, or empty if none. | yes |
| tertiary\_product\_id | string | The third product on the paywall, or empty if none. | yes |
| \\_product\_id | string | Product identifier keyed by the product name (for example, \`annual\_product\_id\`). | yes |
| is\_free\_trial\_available | boolean | True when any introductory offer is available (including both free and paid trials). | yes |
| feature\_gating | string | Feature gating behavior for the paywall. | yes |
For example, to show a transaction-abandon paywall only for onboarding paywalls, add a `transaction_abandon` placement and set `presented_by_event_name` to `onboarding`. To limit it to a single paywall, add `paywall_id` as an additional condition.
## `survey_response`
### Usage
This is registered when a response to a paywall survey has been recorded. First, you need to make sure your paywall [has a survey attached](/surveys).
You can combine this with rules to show a paywall whenever a survey response is recorded or when the user gives a specific response. Again, [add](/campaigns-placements#adding-a-placement) the standard placement `survey_response` to a campaign. Then, add another condition using `survey_selected_option_title` that's equal to the text of a particular response.
For example, if the user selected a survey option named `Too Expensive`, you could present another paywall with a discounted option. This is a great opportunity to show a discounted paywall to improve your conversion rate.
### Parameters
Audience filters for `survey_response` placements can use the following parameters (empty values mean the field isn't applicable):
| Name | Type | Description | Required |
| ------------------------------- | ------ | ----------------------------------------------------------------------- | -------- |
| survey\_selected\_option\_title | string | The text of the selected survey option. | yes |
| survey\_selected\_option\_id | string | The ID of the selected survey option. | yes |
| survey\_custom\_response | string | Optional. Custom response text when the user provides their own answer. | no |
| survey\_id | string | The survey ID. | yes |
| survey\_assignment\_key | string | The survey assignment key. | yes |
## `touches_began`
### Usage
This is registered when the user touches the app's UIWindow for the first time. It is only tracked if there is an active `touches_began` placement in a campaign.
### Parameters
Same as `app_install`:
| Name | Type | Description | Required |
| --------------------------- | ------- | ----------------------------------------------------- | -------- |
| app\_session\_id | string | Identifier for the current app session. | yes |
| is\_superwall | boolean | Always true for Superwall events. | yes |
| using\_purchase\_controller | boolean | True when a custom purchase controller is configured. | yes |
---
# Billing
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-billing
undefined
In the **Billing** section in **Settings**, you can enter, or change, billing details for your Superwall account:
### Enter or edit billing details
Below the invoice section, you can enter (or edit) your billing details at any point. When you're finished, **click** the **Update Billing Details** button to save your changes.
### View past invoices
You can view upcoming and previous invoices from Superwall in this section, along with your subscription status right above it as well. The table will show payment status, the amount owed or paid, and the period the invoice fell within.
You can also click any invoice row to download it as a .pdf.
### Entering in or editing a card on file
To enter in a credit card for payments, **click** the **Add Card** button above the invoice section:
From there, you can manually enter in your card details:
Or, you can use the Autofill Link service by clicking the green "Autofill Link" button:
If you have a card already present, you can remove it and add a different one here as well.
If you have any questions about your billing details or invoices, please feel free to reach out to us.
---
# Apple Search Ads
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-apple-search-ads
Integrate Apple Search Ads with Superwall. View details on users acquired via search ads, visualize conversions from Apple Search Ads in charts, and create powerful campaign filters to target users using search ad data. Search ad integration requires 3.12.0 of the Superwall SDK or higher.
In the **Apple Search Ads** section within **Integrations**, you can the enable Apple Search Ads integration with Superwall:
Apple offers two different search ad services, "Basic" and "Advanced" tiers. Superwall supports
both of them, though more data is available with the Advanced ads.
### Basic search ads setup
If you're only using basic search ads, **click** the toggle next to **Basic Apple Search Ads** to enable the integration:
That's it, you're all set. With basic Apple Search Ads enabled, you'll be to see users acquired via search ads in the [users page](/overview-users).
To see what you can do with advanced search ads data, skip down to the [use cases](#use-cases) section.
### Advanced search ads setup
Advanced search ads takes a few more steps since it requires the [Campaign Management API](https://searchads.apple.com/help/campaigns/0022-use-the-campaign-management-api). The overview is as follows, with more details about each step below them:
* First, you'll need to create a user in Apple Search Ads **using a different Apple Account** than your primary Apple Account.
* This new user will need to be set up with either the API Account Manager or API Account Read Only role.
* Then, you'll generate three things by pasting in a public key from Superwall: a client ID, team ID and key ID.
* Finally, you'll enter those three values into Superwall.
**Step One: Invite a new user**
1. Go to [searchads.apple.com](https://searchads.apple.com) and click **Sign In -> Advanced**.
2. Locate your account name in the top right corner and click **Account Name -> Settings**.
3. Under User Management, click **Invite Users**.
4. Grant the user appropriate permissions and enter in the rest of the details. The email address here is the one you'll want to use to create a new user in Apple Search Ads:
**Step Two: Accept the invitation**
Open the email and follow Apple's instructions to set up a new user with Apple Search ads. The email will look similar to this:
Once you've accepted the invitation using the invited Apple Account:
1. Once again, go to [searchads.apple.com](https://searchads.apple.com) and click **Sign In -> Advanced**.
2. Locate your account name in the top right corner and click **Account Name -> Settings**.
3. Over in Superwall, go to the **Settings -> Apple Search Ads -> click copy** under the public key:
4. Back in Apple Search Ads, paste the public key under **Public Key** and click **Generate API Client**:
**Step Three: Generate the client ID, team ID and key ID**
Now, you should see three values that have been generated by Apple Search Ads, a client ID, team ID and key ID.
1. Copy each generated value.
2. In Superwall, paste each value in and click "Update ASA Configuration."
3. Finally, click on "Check Configuration" and confirm everything is set up properly.
### Use cases
Once you've enabled Apple Search Ads, you can use the data in a few ways. First, users who've been acquired from a search ad will display that information in the users page under "Apple Search Ads." This is available with either the basic or advanced search ads. This can be useful for understanding the quality of users acquired from search ads.
If you're using advanced search ads, you get significantly more capabilities:
* You can leverage search ad data in your campaigns. This opens up the ability to do things like showing a specific paywall to a user who was acquired via a search ad, tailor messaging from the keyword that was used, and more.
* You can view search ads data in charts, breaking down metrics by campaign name and more.
#### Viewing users acquired via Apple Search Ads
If any user was acquired via a search ad, you'll see that data in the [users page](/overview-users). This can be useful for understanding the quality of users acquired from search ads:
Here's a breakdown of the attributes you'll see:
| Attribute | Example | Description |
| ----------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Ad Group Id | 1684936422 | The identifier for the ad group. Use Get Ad Group-Level Reports to correlate your attribution response by adGroupId. |
| Ad Group Name | Primary Ad Group | The name of the ad group for organizational and reporting purposes. |
| Ad Id | -1 | The identifier representing the assignment relationship between an ad object and an ad group. Applies to devices running iOS 15.2 and later. |
| Attribution | true | A Boolean value indicating if the attribution was successful. Returns true if a user clicks an ad up to 30 days before downloading your app. |
| Bid Amount | 0.25 | The cost-per-click (CPC) bid amount placed for this ad group. |
| Bid Currency | GBP | The currency used for the bid amount. |
| Campaign Id | 1633810596 | The unique identifier for the campaign. Use Get Campaign-Level Reports to correlate your attribution response by campaignId. |
| Campaign Name | Primary Campaign (US) | The name of the campaign, useful for tracking and organizational purposes. |
| Conversion Type | Download | The type of conversion, either Download or Redownload. |
| Country Or Region | US | The country or region for the campaign. |
| Keyword Id | 1685193881 | The identifier for the keyword. |
| Keyword Name | baskeball app | The specific keyword that triggered the ad. |
| Match Type | EXACT | The keyword matching type used to trigger the ad (e.g., EXACT, BROAD, or PHRASE). |
| Org Id | 3621140 | The identifier of the organization that owns the campaign. This is the same as your account in the Apple Search Ads UI. |
#### Using search ad data in campaigns
Using the table above, you can turn around and use any of those values to create [campaign filters](/campaigns-audience#filters):
There is a delay from the moment a user downloads your app via a search ad to the time that event
is sent to Superwall from Apple's servers. For that reason, using search ad data as a filter on
events like an app's launch is discouraged.
#### Charts
Use data from Apple Search Ads in our [charts](/charts) as a breakdown and filter:
Apple Search Ads data can be used in the following charts:
* **Proceeds**
* **Sales**
* **Conversions**
* **New Subscriptions**
* **New Trials**
* **Trial Conversions**
* **Refund Rate**
As far as search ads data, you can create breakdowns using the following:
* **Ad Group Name**
* **Campaign Name**
* **Keywords Match Name**
* **Match Type**
Some common use cases here are:
* Attributing new trials from a search campaign.
* Seeing which keywords generate the most revenue.
* Understanding the quality of users acquired from a search ad.
* etc.
---
# Localization
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-localization
undefined
Todo.
---
# Keys
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-keys
undefined
In the **Keys** section under **Settings**, you can easily view or copy your API key, view session starts by the last seven days, and app version sessions from the last seven days.
### API Key
You'll use your API key to initialize the Superwall client in your apps. Each one is prepended with `pk_` and then the identifier. To easily copy it, **click** the **Copy** icon on the right-hand side:
### Session starts by SDK version
Use the session starts by SDK chart to see how many sessions are being started, split out by the SDK version of Superwall.
This helps debug any potential issues that may occur by comparing sessions against the version of our SDK users are on. Of course, if your issue appears to be related to Superwall's SDK — always feel free to reach out so we can investigate.
### App version
Similarly, the app version chart helps you narrow down issues by showing sessions split out by app versions. If the use of our SDK didn't change, but your app version did, and an issue is occurring — then it may related to your app specific logic.
---
# General
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings
Use the Settings area to set up API keys, metadata and more.
To access settings for your Superwall account, **click** the **Settings** button in the sidebar:
Under the General section, you can set or edit metadata and some integration API keys for your app:
Some sections will hide or show depending on the platform your app is on. For example, for an
Android app, Superwall will hide Apple-specific items.
**Name**
The name for your application in Superwall. This isn't user-facing and only used within Superwall. You can change it anytime.
**Revenue Cat Public API Key**
Add in your Revenue Cat [public API key](https://www.revenuecat.com/docs/welcome/authentication) to have Superwall automatically pull in product identifiers. Note that you'll need to create products in Superwall along with their pricing — this just makes it a bit easier to do by fetching identifiers for you.
**Apple App ID**
Fill in your app's Apple identifier here. You can find it by going to **App Store Connect -> General -> App Information**.
**Apple Custom URL Scheme**
We use URL schemes to perform deep link logic and for in-app previews of paywalls for iOS apps. To learn more about setting up deep links, visit this [doc](/in-app-paywall-previews#using-deep-links-to-present-paywalls).
**Google Custom URL Scheme**
We use URL schemes to perform deep link logic and for in-app previews of paywalls for Android apps. To learn more about setting up deep links, visit this [doc](/in-app-paywall-previews#using-deep-links-to-present-paywalls).
**Apple Small Business Program**
If you are a part of Apple's small business program, add in the date you were accepted into it. Optionally, add the date you were removed (if applicable). We'll use this to accurately report revenue metrics.
If you added your Apple Small Business program status later on, Superwall will accurately reflect
revenue for any new data. It doesn't backfill existing revenue metrics.
### Application settings
Here, you can enter metadata about your iOS app that corresponds to your Stripe integration.
1. **Icon:** An icon to represent your app, we recommend using the same one that your iOS app does. This will appear on the checkout and subscription management pages.
2. **Web Paywall Domain:** The domain your paywalls will be shown from. This was set when the Stripe app was created, and cannot be changed.
3. **Application Name:** The name of your app, we recommend using the same name as your iOS app.
4. **Support URL:** A URL to your support page. This will be shown on the checkout and subscription management pages.
5. **Support Email:** An email you provide customers for support questions and general reach out
6. **Redeemable on Desktop:** If your app is an iPad app on Mac, enable this option so that users can redeem products on their Mac. If you aren't using iPads Apps on the Mac, you can disable this. If this is disabled, Superwall enforces redemption on an iOS device.
### Stripe Live Configuration
This section allows you to connect Stripe keys with Superwall. You will need a:
1. **Publishable Key:** A Stripe publishable key. Stripe creates this key for you, you don't need to generate it yourself.
2. **Secret Key:** A Stripe secret key that you create. Once you've made one, paste it here.
You can find these keys [in your Stripe account](https://dashboard.stripe.com/apikeys). If you need help getting set up, check out the docs [here](/web-checkout-configuring-stripe-keys-and-settings).
### Stripe Sandbox Configuration
The sandbox configuration allows you to test purchasing flows with your web checkout integration. If you need to find these keys, you can find them in [your Stripe account](https://dashboard.stripe.com/test/apikeys).
1. **Publishable Key:** A Stripe publishable key. Stripe creates this key for you, you don't need to generate it yourself.
2. **Secret Key:** A Stripe secret key that you create. Once you've made one, paste it here.
### iOS configuration
This section has critical information for your iOS app. Without it, web checkout won't work.
1. **Apple Custom URL Scheme (no slashes)**: Your custom URL scheme. If you haven't set this up, view the [documentation](/in-app-paywall-previews).
2. **Apple App ID**: Your app's Apple ID. You can find this in **App Store Connect -> General -> App Information**.
---
# Team
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-team
undefined
In the **Team** section within **Settings**, you can view and edit your Superwall team:
Team members have access to all of your apps within Superwall, making collaboration seamless.
### Invite users
To invite a user to collaborate on your apps, **click** on the **Invite Users** button at the top right:
From there, fill out the details (name and email address) and **click** the **Invite** button:
Once the user accepts the invite, they'll show up in your Team section. You can add or remove team members at anytime. To remove a team member, **click** the **trashcan** icon under **Actions**.
### Team roles
Only **Owners** or **Admins** can change team member roles.
#### Owner — Full control
* Can perform all actions on the team/organization
* Can invite/remove team members
* Can assign or change any team member's role including other Owners
* Can modify billing and organization settings
* Access to all features including sensitive data (webhooks, API keys)
* Maximum privileges
#### Admin — Full access, limited team management
* Can perform most administrative actions
* Can invite/remove team members
* Cannot assign or change Owner roles (can only assign Admin, Editor, or Reader)
* Access to sensitive features like webhook destinations
* Full create/update/delete permissions on paywalls, campaigns, products, etc.
#### Editor — Can create and modify content
* Can read, create, and update:
* Paywalls and paywall triggers
* Campaigns and A/B tests
* Products
* Notifications
* Projects
* Can view applications and organizations
* Cannot delete applications
* Cannot access team management (invite/remove members)
* Cannot access sensitive settings like webhooks or billing
#### Reader — View-only access
* Can view/read all resources (paywalls, campaigns, analytics, etc.)
* Cannot create, update, or delete anything
* Useful for stakeholders who need visibility but shouldn't make changes
### Renaming your team
To rename your team, enter in a new value name under the **Team Name** section, and **click** the **Save** button:
---
# Projects
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-projects
undefined
In the **Projects** section within **Settings**, you logically group your apps together (regardless of the platform they are on):
Projects are typically the same app on multiple platforms. That is, the same app on iOS and Android. Grouping them together as a project can help with organization and make reporting a bit easier to manage.
### Creating a new project
To create a new project, **click** the **Create Project** button at the top right:
From there, give it a name and **click** the **Save** button:
### Adding apps to a project
After you've created a project, you can select an app for the iOS and Android platform by clicking their respective buttons:
---
# Revenue Tracking
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-revenue-tracking
undefined
In the **Revenue Tracking** section under **Settings**, you can set up revenue tracking three different ways. Revenue tracking is required to show revenue metrics in the Superwall dashboard.
## Status
Your revenue tracking status will be listed at the top, indicating if you've successfully set it up or not:
Until we receive the first event for your app (including Sandbox events), the configuration will still show as **missing**.
## Methods
There are different methods for revenue tracking depending on your platform:
* iOS: [App Store Connect](#ios-app-store-connect)
* Android: [Google Play](#android-google-play)
If you're using RevenueCat for purchase handling: [RevenueCat](#revenuecat)
Choose only **one** of these methods.
As soon as you've completed the steps for any of them, you should see integrated events begin to show up in Superwall's metrics.
### iOS: App Store Connect
#### Option 1 - App Store Connect Server Notifications
Use this method to forward subscriptions events from App Store Connect back to Superwall. To get started, go to **App Store Connect → App Information → App Store Server Notifications → Production & Sandbox URL fields:**
For the URL, use the value in Superwall that was prefilled by clicking the copy button:
Then, enter this in App Store Connect modal:
**Click** the **Save** button once you've entered in the URL.
#### Option 2 - Event Forwarding
If you handle subscription logic on your own server and are using Apple's subscription events notifications, use this method. It will forward Apple subscription events from your server to Superwall.
To implement this method, simply forward the **unmodified request** to Superwall before any other application logic.
Here's a Node.js example, just be sure to use your own API key in place of `YOUR_PRIVATE_KEY` in the snippet below:
Your private key is **not** the same as your public key. Superwall will prefill your private key in the code snippets on the Revenue Tracking page for both Event Forwarding and App Store Connect setup.
```javascript
request.post(
{
url: "https://superwall.com/api/integrations/app-store-connect/webhook?pk=YOUR_PRIVATE_KEY",
headers: { "Content-Type": "application/json" },
body: JSON.stringify(req.body),
timeout: 5000,
},
(error, response, body) => {
if (!error && response.statusCode == 200) {
console.log("Successfully forwarded to Superwall")
} else {
console.error("Failed to send notification to Superwall", error)
}
}
)
```
#### In-App Purchase configuration
Setting up the in-app purchase configuration for iOS apps allows Superwall to power features like refund
consumption.{" "}
To complete setup, follow these steps:
* Navigate to [App Store Connect](https://appstoreconnect.apple.com). - Click on **Users and
Access**.
* Click on **Integrations** at the top. - Under **Keys**, choose **In-App Purchase**.
* Click on **+** to create a new key if you don't have one. Add a name, and click **Generate**.
You can reuse the **same key** for all of the apps falling under the same App Store Connect
account. Though, you must still have access to the one-time download of its generated P8 key
file. If you don't have access to this anymore, simply create a new one.
* **Click** on "**Download In-App Purchase Key**" for the new key. On the resulting
modal, click **Download**.
**IMPORTANT**: You only have one chance to download the key file. Make sure to save it in a
secure location.
* Upload the key file you downloaded in the previous step to Superwall under "P8 Key File." -
Fill in the **Bundle ID** of your app. - Enter the **Key ID** of the key you created in App
Store Connect. You can find it in the "Key ID" column shown in the image from step 3. Locate the
row for the key you made and copy the corresponding Key ID here.
- For **Issuer ID**, fill in
the value found at **Users and Access -> Integrations -> In-App Purchase** in App Store Connect:
- **Click** on
**Update** and confirm everything is set up correctly.
#### App Store Connect API
Setting up the App Store Connect API helps Superwall pull product data from the App Store.
To complete setup, follow these steps:
* Navigate to [App Store Connect](https://appstoreconnect.apple.com). - Click on **Users and
Access**.
* Click on **Integrations** at the top. - Under **Keys**, choose **App Store Connect API**.
* Choose **Team Keys** and create a new one. - Add a name, and for **Role** choose **App
Manager**. - **Click** on **Generate**. - **Click** on **Download** for the new key. On the
resulting modal, click **Download**.
**IMPORTANT**: You only have one chance to download the key file. Make sure to save it in a
secure location.
* Upload the key file you downloaded in the previous step to Superwall under "P8 Key File." -
Enter the **Key ID** of the key you created in App Store Connect. You can find it in the "Key
ID" column shown in the image from step 3. Locate the row for the key you made and copy the
corresponding Key ID here.
- For **Issuer ID**,
fill in the value found at **Users and Access -> Integrations -> In-App Purchase** in App Store Connect:
- **Click** on
**Update** and confirm everything is set up correctly.
### Android: Google Play
You can now forward subscription events directly from Google Play to Superwall. For implementation details, please refer to our guide on [Revenue Tracking for Google Play](/dashboard/dashboard-settings/overview-settings-revenue-tracking-google-play).
### RevenueCat
Finally, if you're using RevenueCat, you can forward subscription events from RevenueCat to back to Superwall. For implementation details, please refer to their [documentation](https://www.revenuecat.com/docs/superwall).
#### Tracking Revenue with RevenueCat for iOS and Android Projects
If you are using RevenueCat and have *both* an Android and iOS app under the same project, be aware that you should have **two** Superwall apps (one for Android and iOS). Then, you can link them together as one project under [Settings -> Projects](/overview-settings-projects). In your RevenueCat project, you can refer to either the iOS or Android key from Superwall. Superwall will still segment the data by platform.
Here's an example, this app has both an Android and iOS project in Superwall. Both of them use RevenueCat:
In Superwall, those have been linked together as a project:
For *either* the iOS or Android project, go to **Settings -> Revenue Tracking -> RevenueCat** and get the integration token (or make one if you haven't yet):
Finally, in RevenueCat, use the token in their integration settings for Superwall:
---
# All teams
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-all-teams
undefined
In the **All Teams** section within **Settings**, you can easily view each team that's part of your Superwall account:
When you click on that link, a modal appears to quickly filter through available options:
You can also activate this by using the ⌘+K keyboard shortcut.
---
# Public Beta
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-public-beta
undefined
In the **Public Beta** section within **Settings**, you can opt-in to Superwall beta features:
Simply toggle which features you'd like to activate for your Superwall account.
These features are in beta for a reason. You may encounter bugs or errors.
---
# Advanced
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-advanced
undefined
In the **Advanced** section within **Settings**, you can view system health and remove your app:
### Disabling Superwall
If you'd like to temporarily disable Superwall, **click** the **Disable Superwall** button. You can later resume it, but disabling Superwall stops all paywalls from being presented or placements being evaluated.
### Removing your app
To permanently remove your app from Superwall, **click** the **Delete Application** button. You cannot undo this action.
---
# Refund Protection
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-refund-protection
undefined
In the **Refund Protection** section under **Settings**, you can configure settings to better equip Apple to handle refund requests from your iOS app. This could result in fewer refunds being issued based on the context you provide Apple:
Before you configure this, make sure you have [revenue tracking](/overview-settings-revenue-tracking) set up.
### Refund protection options
When you opt into refund protection, there are four different options to choose from:
1. **Do not handle (default):** The default option, which means Apple will handle refunds as they see fit.
2. **Ask Apple to grant all refunds:** This option will inform Apple to grant **all** refunds, regardless of the context you provide.
3. **Ask Apple to decline all refunds:** This option will inform Apple that you wish to default to declining refunds. For example, if you have an app that has a credits-based system and a user requests a refund, you may want to try and decline that refund if the services were provided.
4. **Submit data and let Apple decide:** This option will inform Apple that you wish to submit data to them for each refund request. This data could be used to help Apple make a more informed decision on whether to grant or decline the refund.
### In-app purchase Configuration
You'll need to have in-app purchases configured with Superwall to use refund protection. For more information on setup, check this doc [out](/overview-settings-revenue-tracking#in-app-purchase-configuration).
---
# Google Play Revenue Tracking
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-revenue-tracking-google-play
undefined
In the **Revenue Tracking** section under **Settings**, you can now setup Google
Play Revenue Tracking.
Google has made this really hard, so if you don't exactly follow the steps
below, you might not get it working.
Once configured, it can take up to 36 hours for the keys to start working.
### 1. Enable Required APIs
* Enable: [Google Play Android Developer
API](https://console.cloud.google.com/apis/library/androidpublisher.googleapis.com)
* Enable: [Cloud Pub/Sub
API](https://console.cloud.google.com/apis/library/pubsub.googleapis.com)
If these are enabled, you'll see a blue "Manage" button next to the "Try this
API" button and a green API Enabled check.
### 2. Create a Service Account
#### Create a new service account
* Visit [Service
Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts) and
create a new user.
* 1. Create service account
You can specify anything here.
* 2. Permissions
* Add the "Pub/Sub Admin" role
* Add the "Monitoring Viewer" role
* 3. Principals with access
Skip this step.
#### Download the service account credentials
1. Click on the newly created service account
2. Go to the "Keys" tab
3. Click "Add key"
4. Select "Create new key"
5. Select "JSON"
6. Click "Create"
7. Upload that key file to Superwall under "Google Play Private Key"
### 3. Add Service Account to Google Play Console
1. Visit [Google Play Console](https://play.google.com/console/u/0/signup)
2. Select "Users and Permissions"
3. Click "Invite new users"
4. Paste in the email address of the service account you created. You'll find this under the "Details" tab of your service account.
5. Select "Account Permissions"
6. Add the following permissions:
* "View app information and download bulk reports"
* "View financial data, orders, and cancellation survey responses"
* "Manage orders and subscriptions"
7. Click "Invite"
### 4. Setup Pub/Sub Topic
1. Go to your app within the Google Play Console
2. Select "Monetize with Play"
3. Select "Monetization setup"
4. Under "Google Play Billing", check "Enable real-time notifications"
5. Copy the "Topic Name" from Superwall and paste it into the "Topic name" field in the Google Play Console.
* If you do not see this field, ensure the service account from [Step 3](#3-add-service-account-to-google-play-console) has been correctly added to the Play Console
6. Under "Notification content", select "Subscriptions, voided purchases, and all one-time products"
7. Click "Save"
---
# Adding Products
Source: https://superwall.com/docs/dashboard/products
undefined
Add your existing products from their respective storefront, such as the App Store or the Google Play Store, to an app so they can be used in one or more paywalls. For adding Stripe products, please view [this doc](/web-checkout-adding-a-stripe-product).
Before you attempt to test a paywall on iOS via TestFlight, make sure they are in the "Ready to Submit" phase if it's their initial launch. For local testing, you can use a [StoreKit configuration file](/testing-purchases) at any point.
Right now, Superwall for iOS does not support [Promotional
Offers](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/setting_up_promotional_offers),
only [Introductory
Offers](https://developer.apple.com/documentation/storekit/in-app_purchase/original_api_for_in-app_purchase/subscriptions_and_offers/implementing_introductory_offers_in_your_app).
Superwall for Android only supports 1 billing phase per offer.
To get started, select an app. Then **click** the **Products** button from the sidebar. Choose **+ Add Product**:
From there, you have five fields to fill out:
| Field | Description |
| ------------ | ---------------------------------------------------------------------------------------------------------- |
| Identifier | The StoreKit or Google Play product identifier for your product. |
| Trial | The trial duration attached to the product, if any. |
| Price | The price attached to the product. Either type one in, or just the dropdown to select common price points. |
| Period | The length of the subscription. |
| Entitlements | The entitlements this product belongs to. |
When you're done, click **Save**.
Note that the pricing information you enter here is **only** used in the Paywall Editor. On
device, that information is pulled directly from the App Store or Google Play Store and will be
localized.
Take care to make sure your product identifier is correct and matches its storefront. This is the
most common cause for products not working correctly when testing.
## Entitlements
Entitlements represent the amount of access or features users are entitled to. They can be used to offer different tiers of service, or just represent a single "active" subscription if your app only has one level of service (i.e. "Pro" unlocks everything). All products are granted a default entitlement.
**Subscription status is determined by entitlements.**
If a product has no entitlements then when a user purchases it their subscription status will be **Inactive**.
Ensure each subscription product is linked to at least one entitlement.
If you don't have multiple tiers of service, you can use only the default `pro` entitlement — you don't need to create any additional entitlements.
To add an entitlement, **click** on the **Entitlements** tab within the products page. Then click **Add Entitlement**:
From there, give it a name, and click **Create**:
At this point, you can go back to your products and attach one or more entitlements to each one.
### Editing entitlements
To edit or delete an entitlement, click on the trailing pencil icon or the trash can icon to remove one. Note that if your entitlement is associated with any product, you'll need to remove it first before you can delete it.
## Getting product identifiers
*If you use RevenueCat to handle in-app subscriptions, skip to [Using RevenueCat](/products#using-revenuecat)*
### Using App Store Connect
On **App Store Connect**, head over to **Your App ▸ App Store ▸ Subscriptions ▸ *Your Subscription Group***:
Then, copy your **Product ID**:
Your products, whether live or pre-release, shouldn't be in the "Missing Metadata" state. If they are, you won't be able to test them on device. To fix this, make sure your products are in the "Ready to Submit" or "Approved" state. Superwall will automatically warn you if they are in this state when you have the [App Store Connect API set up](/overview-settings-revenue-tracking#app-store-connect-api):
### Using Google Play Console
To add subscription products, on **Google Play Console**, head over to **Your App ▸ Monetize ▸ Products ▸
Subscriptions**:
You can also grab your **base plan id** and any offer ids if you're going to use
them.
To add in-app products, no base plan id is required. For **period**, select **None(Lifetime/Consumable)**:
#### Google Play Offers
Google play allows you to create multiple base plans and multiple offers for
each base plan. When using Superwall, you can either specify a specific offer
or let Superwall choose the best offer for the user.
**Automatically Choosing Offers**
Once Google has returned offers that are applicable for that user, Superwall
will use the following logic to choose the best offer for the user:
* Find the longest free trial the customer is eligible for
* If there is no free trial, find the cheapest introductory period the customer is eligible for
* If there is none, fall back to the base plan
* If you have an offer on one of your products that you never want to automatically be selected by this logic (for example, because it is a discount only used for a specific customer group), add the tag `sw-ignore-offer` to that offer in Google Play Console.
To add the `sw-ignore-offer` tag in **Google Play Console**:
1. Open the subscription offer you want to exclude and choose **Advanced settings**.
2. In **Tags**, add `sw-ignore-offer` (all lowercase) and click **Save**.
Superwall will ignore any offer that includes this tag when selecting the best offer for the user.
That means that if your eligibility criteria is set so that someone can use an
offer only once, we'll respect that and choose from the best remaining offers.
**Specifying Offers**
Let's say you have a base plan with two or more offers which differ in trial
duration. You may want to A/B test these offers to see which one performs best.
To achieve this, you can specify the offer id in the Superwall dashboard.
When we specify an offer id, we'll ignore the logic above and always use the
offer **if the user is eligible**. If the user is not eligible for the offer,
we'll fall back to the base plan. The [eligiblity criteria](https://support.google.com/googleplay/android-developer/answer/12154973?hl=en#:~\:text=or%20inactive%20states.-,Offer%20eligibility%C2%A0,-You%20can%20provide) is set in the Google
Play Console, and is based on the user's purchase history.
### Using RevenueCat
For those who use RevenueCat, Superwall can automatically pre-populate your product identifiers to choose from when adding a product. In the **Add Product** modal, Superwall will display **any product attached to an offering** by following the steps below.
On RevenueCat, make sure your products are associated with an offering (it doesn't need to be the current offering):
Then, add your [RevenueCat Public API Key](https://docs.revenuecat.com/docs/authentication) inside of settings by clicking the **cog wheel icon** in the navigation bar from any page and selecting **Settings**. Paste your API key then click **Update Application**:
## Using products in paywalls
After you've added products to an app, you're ready to start using them in paywalls. Check out our [docs](/paywall-editor-products) for a step-by-step guide on how to do that.
## Understanding how consumable and non-consumable products work
Superwall uses entitlements to determine access to features instead of treating purchases as a simple “subscribed/unsubscribed” status. To that end, here is how to work with consumable and non-consumable products:
* **Consumable products** (e.g., credits, tokens, energy boosts) generally *aren't* associated with an entitlement.
* **Non-consumable products** (e.g., a lifetime unlock) *should* be linked to an entitlement in Superwall. This ensures users who purchase them receive the appropriate access to features.
Note that on iOS, if you're using consumables you need to include `SKIncludeConsumableInAppPurchaseHistory` (Apple's docs [here](https://developer.apple.com/documentation/bundleresources/information-property-list/skincludeconsumableinapppurchasehistory)) in your `info.plist` file. Ensure its type is set to `Boolean` and its value is `YES`. Note that on pre-iOS 18 devices, StoreKit 1 will be used when this key is present.
## Understanding paid offer types
Any **paid up front** or **pay as you go** product offer types will also be referenced using the `trial` variables. In Superwall, these are represented as "paid trials". For example, to reference the product's trial price of $3.99 in the image below, you'd use `products.selected.trialPeriodPrice`:
For more on setting customized text using Liquid Templating, visit this [doc](/paywall-editor-liquid).
## A note on StoreKit configuration files
If you're using a StoreKit Configuration file, pricing information will come from there during local testing. Therefore, it's important to keep your StoreKit Configuration file, Superwall, and the App Store products all in sync. Follow our [Setting up StoreKit testing](/testing-purchases) guide for more information.
Having an issue on device with products not appearing? Run through [this
checklist](/docs/troubleshooting#my-products-arent-loading) to make sure everything is configured
correctly.
---
# Managing Localization Updates
Source: https://superwall.com/docs/dashboard/overview-localization
undefined
If you're only dealing with one paywall, or trying to get started with localizing — read this
[doc](/paywall-editor-localization) first.
When you make changes to a localized string referenced across more than one paywall, or one is changed via a localization platform provider — you can review those changes by **clicking** on the **Localization** button from the sidebar:
You can also use the `⌘+5` keyboard shortcut to open the Localization page from the Overview
screen.
When you open the Localization page, you'll see two primary sections:
1. **Missing Translations:** Any keys that are missing a localized value will show up here to address.
2. **Review & Publish:** Any localizations that have changed which are used on multiple paywalls (or changed from an external localization provider) show up here. Paywalls using any edited localization key here will continue to use the "old" value it had before it was changed, and you can publish the updates live for the other paywalls after reviewing them.
For example, here the key `dominate_the_pitch` had its value changed on Paywall A and it's now live. But, here, Paywall B also references the key `dominate_the_pitch`, so you can hover over each locale identifier and see its old and new value. From there, you can either ignore those changes or put them live for each paywall.
---
# Notifications
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-notifications
undefined
To configure a notification which displays before a free trial ends, click the **Notifications** button from the **sidebar**:
You can add a local notification that fires before a free trial ends. After the user starts a free trial, the app will ask them to enable notifications if they haven't already done so.
In sandbox mode, the free trial reminder will fire after x minutes, instead of x days.
### Configuration
To turn on a trial reminder notification, click **+ Add Notification**. From there, there are four fields to configure:
1. **Title**: Shows at the top of the notification.
2. **Subtitle**: Displays directly below the title in a smaller font. Not required.
3. **Body**: Shows in the primary body of the notification.
4. **Delay**: How many days before the trial ends the notification should fire.
Here's where those values show up on a notification:
These are scheduled as local notifications as soon as they are configured.
### Dynamic notification timing
Requires iOS SDK v4.10.7+ or Android SDK v2.6.6+.
The SDK automatically calculates the actual trial end date based on the product's introductory offer period from the app store. This means notifications are scheduled relative to when the trial **actually ends** — not when it starts.
For example, if you set a delay of 3 days:
| Product trial length | Notification fires on |
| -------------------- | ---------------------------- |
| 7-day trial | Day 4 (3 days before end) |
| 14-day trial | Day 11 (3 days before end) |
| 1-month trial | \~Day 27 (3 days before end) |
This ensures users receive trial-ending reminders at the right time — when the reminder is actually relevant to their subscription decision — regardless of the product's trial length.
On older SDK versions (pre-4.10.7 on iOS), the notification fires X days **after** the trial starts rather than X days **before** it ends. Upgrade to the latest SDK for accurate timing.
---
# Debugger
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-debugger
undefined
To view the paywall debugger, click the **Debugger** button from the **sidebar**
The debugger shows a raw representation of selected components. This is useful if you're trying to debug layouts or designs, since the CSS Superwall is generating will show here. It also will show what variables are applied and what they're specifically being evaluated to.
In this example, there is a variable called "Safe Area Top", set to 64 pixels. It's been set to the component's horiztonal padding for demonstration purposes:
When the component is selected, and the debugger is opened — you can confirm that variable is being applied to the component's padding:
If you're unsure of why a paywall has a design quirk or isn't displaying as you'd expect, open the debugger and take a look at the CSS.
---
# Slides
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-slides-component
Use Superwall's slides component to create a horizontal or vertical slide UX driven by a user's gesture.
### Adding a slides component
The slide component was built to make interactive slide designs easy. It's similar to a [carousel](/paywall-editor-carousel-component), except its meant to be driven by user gestures instead of automatically progressing through its contents. To use the slides component:
1. In the left sidebar, click **+** to add a new element.
2. Choose **Slides** under the "Layout" header.
The slides component requires an explicit `width` set. Generally, setting this to 100% of the viewport's width works well. This is also the default size set:
By default:
* The slides component is set to `Horizontal` scrolling.
* Scrolling indicators are created for you. Read below to see how you can customize these.
* A default height is assigned.
* The slides respond to gestures.
### Adding contents to slides
The slides component has a few demonstration items added to it by default. You can remove these and add your own content:
Here, the container stack determines the height. You can customize this as needed.
### Tracking or updating the displayed element in slides
When a slides element is added, Superwall automatically creates an element variable for it (accessed through the **[Variables](/paywall-editor-variables)** tab in the left sidebar, or the variables button in the **[floating toolbar](/paywall-editor-floating-toolbar)**). Its name will match whatever is in the element hierarchy in the left sidebar:
You can use its `Child Page Index` variable to change which slide is showing. You can use this to manually set which slide is showing. Here, the button progresses to the next slide by incrementing the slides `Child Page Index` variable:
The variable's name is derived by the node's unique identifier. You don't need to set or generally be aware of this value.
You can also reference this variable when using a [dynamic value](/paywall-editor-dynamic-values) to do things such as:
* Select a product based off of the index of the slide.
* Show custom paging indicators.
* Change text using [dynamic values](/paywall-editor-dynamic-values) based on the index.
* etc.
---
# Navigation
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-navigation-component
Use Superwall's navigation component to navigate through pages of content.
### Adding a navigation component
The navigation component was built to make paging, or navigating through paywall content, easy. To use the navigation component:
1. In the left sidebar, click **+** to add a new element.
2. Choose **Navigation** under the "Base Elements" header.
You'll see the navigation component in the element hierarchy. **In most cases, you'll want a navigation's width to be 100% of the viewport**:
From there, add in content to create pages using [stacks](/paywall-editor-stacks):
Similar to the parent navigation element, it helps to have the width of your stacks be 100% of the parent.
### Changing pages
When a navigation element is added, Superwall automatically creates an element variable for it (accessed through the **[Variables](/paywall-editor-variables)** tab in the left sidebar, or the variables button in the **[floating toolbar](/paywall-editor-floating-toolbar)**). Its name will match whatever is in the element hierarchy in the left sidebar:
Each top-level child within the navigation component represents a *current index* value, starting from 0. Changing this value will change which page is displayed. In this example, we add a [tap behavior](/paywall-editor-styling-elements#tap-behaviors) to the button, which increments the element variable's `current index` value:
The variable's name is derived by the node's unique identifier. You don't need to set or generally be aware of this value.
### Editing transitions
A navigation component has four different transitions to use. Edit them by **clicking** on the navigation component from the left sidebar, and then selecting a value in the trailing sidebar:
Available transitions are:
1. **No Transition:** No animation will occur during page changes.
2. **Push:** Each page is pushed on or off of the next page, similar to navigation stacks in iOS.
3. **Fade:** Each page change results in an opacity fade in or out.
4. **Slide:** Similar to push, but the animation results in a smooth transition between pages, much like scrolling through a carousel would look.
---
# Drawers
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-drawer-component
Use Superwall's drawer component to display content presented in response to a button tap or a variable changing.
### Adding a drawer component
The drawer component was built to make displaying contents from a bottom drawer easy, right out of the box. To use the drawer component:
1. In the left sidebar, click **+** to add a new element.
2. Choose **Drawer** under the "Base Elements" header.
Drawers will automatically show a dimming view behind them when presented. Tapping on it will dismiss the drawer. By default, they are interactive — meaning they can be dismissed via a drag gesture. You can also change this to be `manual`, letting you explicity control when it presents or dismisses. Toggle this under the `Dismissable` property:
### Presenting drawers
When a drawer element is added, Superwall automatically creates an element variable for it (accessed through the **[Variables](/paywall-editor-variables)** tab in the left sidebar, or the variables button in the **[floating toolbar](/paywall-editor-floating-toolbar)**). Its name will match whatever is in the element hierarchy in the left sidebar:
To toggle its open state, you can use a tap behavior on a button or another element. In this example, we add a [tap behavior](/paywall-editor-styling-elements#tap-behaviors) to the button, which toggles the element variable's `Is Open` value:
The variable's name is derived by the node's unique identifier. You don't need to set or generally be aware of this value.
### Adding content to drawers
By default, drawers have a minimum height set. This is a general size that works well, but in most cases you'll want to add a [stack](/paywall-editor-stacks) and have the drawer derive its height from that. Or, you can add a stack and set its height equal to the drawer's minimum height. Generally, that approach is not as flexible since you likely want the drawer's height to be determined by the content inside of it:
By default, there is a minimum height on the drawer. Here, we've removed that so that the inner stack will control its height:
Since the drawer's minimum height was cleared, now it'll derive its height from the stack inside of it:
---
# Styling Elements
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-styling-elements
undefined
Anytime you click on a component in the **Layout** tab, its editable properties will open on the right side of the editor window in the **component editor**. Here, you can see that clicking on the component in the layout tab opened its relevant properties in the component editor:
### Component Specific Properties
By default, when you select a component you'll see properties that are specific to it at the top of the component editor. For example, when you select a stack, you'll see stack-specific options. The same is true of text and any other component. Notice how the options change at the top-right here when a stack versus a text component are selected:
### Image generation
You can use A.I. to generate images. By selecting any image component, you can **click** on the **AI Tools** button to create an image based on the text and style you provide:
You are presented with two options:
1. **Generate Image:** Use this to create a brand new image, or regenerate an existing one.
2. **Remove Background:** This attempts to remove the background of the existing image element.
**Generating images:**
When the image generation editor modal is open, you can provide:
* **Image description:** A description of the image you'd like to generate. Generally speaking, the more detail you provide, the better the result will be. Instead of saying "Coffee up close", you might say "A close-up of a steaming cup of coffee with a heart-shaped foam design.""
* **Style:** The primary style of the image you're generating. Each one has several sub styles associated with it.
* **Sub-style:** A more specific style within the primary style you've chosen. For example, if you've chosen "Realistic Image", you might choose "Black and White" as a sub-style.
* **Remove background automatically:** Select this to have the image generator attempt to remove the background from the resulting image.
Here's an example prompt:
And, its result:
### Common component properties
Most components share similar properties related to things such as sizing, padding and more. Those are covered in more detail below.
Note that for any property that deals with editing a particular size, you can click on the disclosure arrow to choose a specific unit (such as `rems`):
Further, most values accept either an input amount or you can use a slider to set one. Some elements support hovering over them to reveal a slider, as well:
### Tap Behaviors
You can have a component trigger a specific action when it's tapped or clicked by adding a **tap behavior**. To add a tap behavior, **click** a component from either the Layout tab or the preview canvas, and in the **component editor** under under **Tap Behavior** click **+ Add Action**:
Available tap actions are:
* **Purchase:** Begin a purchasing flow of the selected product.
* **Set/Update Variable:** Sets or updates an existing variable's value. Options specific to the variable type will also be displayed. For example, a **Number** variable will have an option to choose an **Operation** such as Set, Increment or Decrement. Or, a **Boolean** variable's **Operation** will offer to either **Set** or **Toggle** the boolean value.
* **Set Attribute:** Sets a user attribute directly from the paywall. Enter a **Key** (e.g., `preferredPlan`, `onboardingComplete`) and a **Value** (e.g., `premium`, `true`). You can add multiple attributes per tap using **+ Add Attribute**. This behaves the same as calling `setUserAttributes()` in the SDK. Common use cases include capturing user preferences from paywall surveys, tracking paywall engagement, or segmenting users for A/B tests based on their choices. *Requires iOS SDK v4.10.7+.*
* **Select Product:** Puts the chosen product in a selected state. Useful for scenarios such as focusing a product in a paywall drawer, for example, when something is tapped or clicked.
* **Close:** Closes the paywall.
* **Restore:** Begins a purchase restore operation. Useful for restoring purchases someone may have made prior.
* **Open Url:** Opens the given URL via one of three different ways:
1. **In-app browser:** Attempts to open the link *inside* of the app using the platform's web browser control. For example, on iOS, this opens an instance of [`SFSafariViewController`](https://developer.apple.com/documentation/safariservices/sfsafariviewcontroller).
2. **External:** Attempts to open the link *outside* of the app using the platform's web browser app. For example, on iOS, this opens Safari. Please note that the paywall stays presented when the link is opened.
3. **Deep Link:** Similar to the **external** option, but it'll *close* the paywall before opening the URL. This is useful for internal navigation or when you are attempting to link to something in a web page and you'd like the paywall to close when doing so.
* **Request Review:** Requests a review for the given app storefront.
1. **Rating Prompt:** Attempts to display the system-level ratings prompt for the platform. On Android, you may use `useMockReviews` on `SuperwallOptions` to ensure a prompt shows while testing.
2. **Written Review:** This option deeplinks to the repspective App Store so the user can write a written review.
* **Custom Action:** Performs a custom action that you specify. Using custom actions, you can tie application logic to anything tapped or clicked on your paywall. Check out the docs [here](/custom-paywall-events).
* **Custom Placement:** Registers the placement you specify in the **Name** field. One common use-case is presenting another paywall from a currently opened one. Check out the example [here](/presenting-paywalls-from-one-another).
If a component has a tap action associated to it, you'll also see a **triangle** icon next to it within the sidebar:
### Component styling properties
The properties below are editable regardless of which kind of component you are editing. The most important thing to keep in mind is that all of the properties below will work the same as they would on a web page. When you change these properties, behind the scenes — Superwall is applying the corresponding CSS code to the paywall.
### Typography
Edit the text, size, color and more of a component's text:
If you've added a [custom font](/paywall-editor-custom-fonts), you can also select it here.
### Layer
Properties here edit the underlying layer of the component:
If you want a background fill, to toggle its overall opacity or other similar things — the layer is a great spot to do it.
### Size
Use size properties to set an explicitly width or height on the component:
Using the dropdown arrow, you can set a range of minimum and maximum values:
### Padding
Apply padding to the content within the component:
To have more granular control, expand each disclosure arrow to set only the top, bottom, left or right padding values:
### Margin
Apply spacing to the content outside of the component, further separating it from adjacent components:
### Corners
Applies a corner radius to the component:
Note that you may not see any change unless the component has some sort of background or layer fill. Further, if you'd like to adjust just one or more corners, click the dashed square icon to individually enter values:
### Borders
Set a border around the the component:
You can set its width, style (i.e. dashed, solid, etc) and more.
### Position
Specifies the position strategy used to place the component:
If you'd like to layer a component on top or below another component, the `Z Index` value is perfect here.
The most important value is what you use for `position`. Again, all of these options mirror their CSS counterpart. The available options are:
* **Normal:** The default option. The component will be positioned according to the normal flow of the paywall's hierarchy. This is analogous to `static` in CSS.
* **Relative:** Positions the component relative to its normal position, allowing you to move it with top, right, bottom, and left offsets *without* affecting the layout of surrounding components.
* **Absolute:** Removes the component from the normal paywall hierarchy flow and positions it relative to its nearest positioned component (which won't necessarily be a parent component).
* **Fixed:** Positions the component relative to the viewport, meaning it will stay in the same place even when the paywall is scrolled.
* **Sticky:** The component will behave as if it has a `normal` position *until* it teaches a certain point in the viewport. Then, it acts like it has a `fixed` position, sticking in place. This is great for sticky headers,footers or banners.
Mozilla has excellent developer docs over how the [position](https://developer.mozilla.org/en-US/docs/Web/CSS/position) CSS property works, along with interactive code samples. If you're having some issues getting things placed how you'd like, this is a great resource to check out.
### Effects
Applies CSS effects to the component:
If you're new to CSS transitions and animations, check out this interactive [reference](https://www.w3schools.com/css/css3_transitions.asp).
### Custom CSS
If you need to add some one-off custom CSS code, you can add them here. Just click **+ Add Property**:
From there, type in the CSS property you need and select it from our dropdown menu:
Here, you can see a manually set background value for the selected component:
Using the Custom CSS section should be your last step, and only if you absolutely cannot achieve
the design you need. For example, here we should simply use the `layer` section to set a
background color.
### CSS Output
As you make any changes to these properties, you can see the actual CSS that Superwall is applying by scrolling down in the component editor to the **CSS Output** section:
This can be useful for debugging or further refining your designs.
---
# Publishing
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-publishing
undefined
To set your paywall live, click the **Publish** button in the top-right side of the editor:
Setting your paywall live doesn't necessarily mean that users will see it. You'll first need to associate a paywall with a [campaign](/campaign). From there, either a user is matched to an audience filter or a [placement](/feature-gating) is evaluated which results in a paywall being presented.
Changes you make are saved locally, even if you haven't published the paywall. Refreshing won't
erase progress if you close the tab and come back later, unless you sign out.
---
# Paywall Localization
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-localization
undefined
To localize your paywall, **click** on the **Localization** button from the **sidebar**:
There are two ways to localize your paywall:
1. **Simple**: Here, you can use AI to localize your paywall into any language. You can manually refine each value at any point. Quick and accurate.
2. **Advanced**: User external .strings files to localize your paywall. This is ideal when you are using external localization services.
You can switch between the two methods at any time.
### Simple localization
Once enabled, a new side panel will present to help you localize you paywall:
You can control localization with the options at the top:
Here's what each options does, left-to-right:
| Name | Description |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Localization | Opens a menu with options to access AI localize settings, switch to advanced localizations, or clear all localizations. |
| Missing Only | Filters the list to show only keys that have no localized value. |
| Import/Export | Allows importing or exporting localization data as a `.csv` file. |
| AI Localize | Starts the AI-powered localization process for selected keys. |
| Add Language | Lets you specify a new language to add for localization. |
To start the AI localization process, **click** on the **Add Language** button. Then, choose **AI Localize**. Superwall will being to localize each value, while respecting the AI Localize settings in place:
Once finished, you'll see all localized values:
You can click on any value to edit it manually.
#### AI localization settings
You can customize how AI localization behaves by changing the settings in the **AI Localize Settings** menu:
The **Formality Style** lets you toggle between formal and informal language. Use the **Localization Style Guide** to provide specific instructions to your brand's voice accurately.
#### Managing languages
To remove or reset a language, **click** on the **three dotts** button next to the language:
To switch back and forth between languages, simply **click** the language at the top:
### Advanced localization
After opening the localization panel referenced above, **click** on the **Add Language** button. Choose the language identifier of the locale you're localizing for, and **click** on **Add**:
If there are any existing text components on your paywall, all of them with currently *unlocalized* strings will populate in the sidebar (in this example, we're localizing our text for Spanish speakers):
Click on the **Localize** button on any of them to enter in localized values. When you're done, click **Save**:
From there, go through and localize all of the values. Keep an eye on the progress bar at the top to see how far along you are. Remember to **click** on the **Publish** button at the top right of the editor to commit any localization edits.
When you are localizing strings, the editor will reflect the locale you're editing against so you
can see a live preview of how the text will appear.
#### Associating localized strings to new or existing text components
When you add new text components, or need to associate a different localization to an existing one — **click** the **Localize** button when the text component is selected. You can either use an existing localized string, or add a new one by clicking the plus button:
When a text component has a localized string attached to it, you'll see the localized string's key in place of the localize button:
You can use variables with localized strings, too. Simply use liquid syntax within your localized
string values to access any variable. Currently, variables themselves are not able to be
localized. Learn more about using variables [here](/paywall-editor-variables).
#### Using .strings files
You can download and import .strings files to speed up your translations. This is ideal when you are using external localization services or have a large number of strings to localize.
#### Exporting .strings files
Select **Localization** from the left sidebar, **click** on the **Import** button. Choose "Download template" and the .strings file will be downloaded with all of your currently localized strings:
#### Importing .strings files
Select **Localization** from the left sidebar, **click** on the **Import** button. Choose "Import Strings File" and select your local .strings file to upload. Then, all of the updated values will be reflected in the editor.
### Localizing period lengths
Superwall will automatically localize period lengths for products. Simply use any of the period-based variables in your text:
For example:
```liquid
Analyze the math of caffeine this {{ products.primary.period | locale: "en" }}
// English, French, and any or any other localized regions you support...
Analyze the math of caffeine this year
Analysez les chiffres de la caféine ce année
```
You can override and remove auto-localization on specific items by setting a `locale` filter:
```liquid
Analyze the math of caffeine this {{ products.primary.period | locale: “en” }}
// Now, it'll show in English in every language
Analysez les chiffres de la caféine ce year
```
### Testing localized strings
You can preview how localized strings will appear on device. To set this up:
1. Make sure you've got [in-app previews](/in-app-paywall-previews) configured.
2. Open the paywall editor and click "Preview":
3. When it opens, tap the menu located at the top left and choose "Localization":
4. Then, select the language to display and the preview will reload with it:
---
# Floating Toolbar
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-floating-toolbar
undefined
In the **device preview** area, there is a floating toolbar at the bottom:
Use it to better preview your paywall designs, and see what it'll look like at different sizes or orientations. Here's what the options do, from left-to-right:
### Device
Use the device toggle to switch between:
* **iPhone SE:** A generalized smaller iPhone device preview.
* **iPhone:** A generalized iPhone device preview.
* **iPhone XL:** A iPhone device preview reflecting the Max and Plus sized device families.
* **iPad:** A generalized iPad device preview.
* **Desktop:** A generalized desktop-sized preview.
### Orientation
Use the orientation button to switch between portrait and landscape:
### Zoom
Use the zoom slider to adjust the preview scale of the paywall preview:
### Refresh
You can manually refresh the paywall device preview with the circle arrow button. You won't lose any progress when clicking this, as your changes are always saved locally.
### Variables
Use the variable window to quickly reference or edit variables used across your paywall. You can toggle by variables in use, or all of them.
---
# Liquid
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-liquid
undefined
Liquid is a templating language that you can use to easily build text in your paywall. The simplest way to get started is simply by referencing a variable
with curly brackets. `{{ user.firstName }}` will output the user's first name. (Assuming you've called `setUserAttributes` with `firstName` previously in the SDK).
However, Liquid is much more flexible then simple curly brackets. It also offers "filters" which allow you to operate on the
variables before outputting them. Ex: `{{ 1 | plus: 3 }}` will output `4`. They work left to right and do not support order of
operations. (You can get around this limitation by using `assign`).
### Liquid syntax formatting
In text, you can use [Liquid filters](https://shopify.github.io/liquid/filters/abs/) to modify output. To use filters, add a pipe after the variable. Then, add in one or more filters:
```
// Results in 17, the absolute value of -17
{{ -17 | abs }}
```
For example, to capitalize a text variable, you would write:
```
// If the name was "jordan", this results in "JORDAN"
{{ user.name | upcase }}
```
## Working with Product Prices
When working with product prices in your paywall, you have two options depending on whether you need the raw numeric value or a pre-formatted price string.
### Formatted vs. Raw Prices
**Formatted Price (`{{ products.selected.price }}`)**
This provides a pre-formatted price string that includes the currency symbol and is formatted according to the user's locale with two decimal places.
```liquid
{{ products.selected.price }}
// Output -> "$0.99" (for US users)
// Output -> "€0.99" (for EU users)
// Output -> "¥99" (for Japanese users)
```
**Raw Price (`{{ products.selected.rawPrice }}`)**
This provides the raw numeric value without any formatting, which is useful when you need to perform mathematical operations.
```liquid
{{ products.selected.rawPrice }}
// Output -> 0.99
// Output -> 9.99
// Output -> 99
```
### Formatting Numbers to Two Decimal Places
If you're working with raw prices or performing calculations, you may need to format the result to show exactly two decimal places. You can use Liquid's `round` filter combined with number formatting:
```liquid
// Format a raw price to two decimal places
${{ products.selected.rawPrice | round: 2 }}
// Output -> "$0.99"
// Calculate a discount and format to two decimal places
{% assign discounted_price = products.selected.rawPrice | times: 0.8 %}
Sale Price: ${{ discounted_price | round: 2 }}
// Output -> "Sale Price: $0.79" (for a $0.99 product with 20% discount)
// Calculate savings and format to two decimal places
{% assign original_price = 9.99 %}
{% assign current_price = products.selected.rawPrice %}
{% assign savings = original_price | minus: current_price %}
You save: ${{ savings | round: 2 }}!
// Output -> "You save: $5.00!" (if current price is $4.99)
```
Use `{{ products.selected.price }}` when you want a properly formatted price string that respects the user's currency and locale. Use `{{ products.selected.rawPrice }}` when you need to perform calculations or custom formatting.
## Liquid inside Image URLs
You can use Liquid for any image URL in the Superwall editor. It can either be the entire URL, or interpolated with an existing one:
```javascript
// As the entire URL...
{{ user.profilePicture1 }}
// Or interpolated within one...
https://myApp.cdn.{{ events.activeEvent }}
```
You can access any variable available too ([including user created ones](https://superwall.com/docs/feature-gating#placement-parameters)), which makes it the right tool to display dynamic content for your images. Here are some examples:
* **User Profile Picture in a Dating App:** Display the profile image of a user that someone has tapped on:
`https://datingApp.cdn.{{ user.profilePicture1 }}`
* **Event-Specific Banners for Sports Apps:** Pull in images like team logos or event banners for ongoing or upcoming games: `https://sportsApp.cdn.{{ events.currentGame.teamLogo }}`
Here's an example:
## Custom Liquid filters
To make it easier to express dates & countdowns we've added several non-standard filters to our Liquid engine.
### `date_add`
Add a specified amount of time to a date.
**Usage**:
`[date string] | date_add: [number|ms string], (unit)`
There are two ways to specify the amount of time
to add:
1. By passing a number and a unit as arguments. The unit can be one of `seconds`, `minutes`, `hours`, `days`, `weeks`,
`months`, or `years`. For example, `{{ "2024-08-06T07:16:26.802Z" | date_add: 1, "days" }}` adds one day to the
date.
2. By using the ['ms'](https://github.com/vercel/ms?tab=readme-ov-file#ms) style of specifying a duration. This format is flexible
but generally you specify a number followed by a unit as part of a single string. Ex: `1d` (1 day), `2h` (2 hours), `30m` (30 minutes), etc.
For example, `{{ "2024-08-06T07:16:26.802Z" | date_add: "1d" }}` adds one day to the date.
You can chain multiple `date_add` and `date_subtract` filters together to add or subtract multiple units of time.
Ex: `{{ "2024-08-06T07:16:26.802Z" | date_add: 1, "days" | date_add: 2, "hours" }}` adds one day and two hours to the date.
**More Examples**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | date_add_minutes: 30 }}
// Output -> '2024-08-06T07:46:26.802Z'
```
### `date_subtract`
Subtract a specified amount of time from a date.
**Usage**:
`[date string] | date_subtract: [number|ms string], (unit)`
There are two ways to specify the amount of time
to subtract:
1. By passing a number and a unit as arguments. The unit can be one of `seconds`, `minutes`, `hours`, `days`, `weeks`,
`months`, or `years`. For example, `{{ "2024-08-06T07:16:26.802Z" | date_subtract: 1, "days" }}` subtracts one day from the
date.
2. By using the ['ms'](https://github.com/vercel/ms?tab=readme-ov-file#ms) style of specifying a duration. This format is flexible
but generally you specify a number followed by a unit as part of a single string. Ex: `1d` (1 day), `2h` (2 hours), `30m` (30 minutes), etc.
For example, `{{ "2024-08-06T07:16:26.802Z" | date_subtract: "1d" }}` subtracts one day to the date.
You can chain multiple `date_add` and `date_subtract` filters together to add or subtract multiple units of time.
Ex: `{{ "2024-08-06T07:16:26.802Z" | date_subtract: 1, "days" | date_subtract: 2, "hours" }}` subtracts one day and two hours from the date.
**More Examples**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | date_subtract_minutes: 30 }}
// Output -> '2024-08-06T06:46:26.802Z'
```
### `date`
Format a date in a specific way.
**Usage**:
`[date string] | date: [format string]`
The [`date`](https://liquidjs.com/filters/date.html) filter is a standard Liquid filter that formats a date. You can use it to format a date in any way that
Javascript's default date utility can parse. For example, `{{ "2024-08-06T07:16:26.802Z" | date: "%s" }}` formats the
date as a Unix timestamp. Here are some common date formats:
**Common Formats**
| Format | Example Output | Description |
| ------------------- | ------------------------- | ---------------------------------------------------------------------------- |
| `%s` | `1722929186` | Unix timestamp |
| `%Y-%m-%d %H:%M:%S` | `2024-08-06 07:16:26` | Year, month, day, hour, minute, second |
| `%a %b %e %T %Y` | `Sun Aug 6 07:16:26 2024` | Abbreviated day of the week, abbreviated month, day of the month, time, year |
| `%m/%d/%y` | `08/06/24` | Month, day, year (Common US Format) |
**Format Reference**
| Format | Example | Description |
| ------ | ---------- | --------------------------------------------- |
| %a | Tue | Shorthand day of the week |
| %A | Tuesday | Full day of the week |
| %b | Aug | Shorthand month |
| %B | August | Full month |
| %d | 06 | Zero padded day of the month |
| %H | 07 | Zero padded 24-hour hour |
| %I | 07 | Zero padded 12-hour hour |
| %j | 219 | Day of the year |
| %m | 08 | Zero padded month |
| %M | 16 | Zero padded minute |
| %p | AM | AM or PM |
| %S | 26 | Zero padded second |
| %U | 31 | Week number of the year, starting with Sunday |
| %W | 31 | Week number of the year, starting with Monday |
| %x | 8/6/2024 | Locale date |
| %X | 7:16:26 AM | Locale time |
| %y | 24 | Two digit year |
| %Y | 2024 | Four digit year |
| %z | +0000 | Timezone offset |
| %% | % | Literal % |
**More Examples**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | date: "%Y-%m-%d %H:%M" }}
// Output -> '2024-08-06 00:16'
{{ "2024-08-06T07:16:26.802Z" | date: "%B %d, %Y" }}
// Output -> 'August 06, 2024'
{{ "2024-08-06T07:16:26.802Z" | date: "%I:%M %p" }}
// Output -> '12:16 AM'
{{ "2024-08-06T07:16:26.802Z" | date: "%A, %B %d, %Y" }}
// Output -> 'Tuesday, August 06, 2024'
```
### `countdown_from`
Calculates and formats the difference between two dates as a countdown.
**Usage**:
`[end_date string] | countdown_from: [start_date string], (style), (max unit)`
* `end_date` (required): The end date of the countdown.
* `start_date` (required): The start date of the countdown. Almost always `state.now`.
* `style` (optional): The style of the countdown. Can be one of `digital`, `narrow`, `short`, `long`, `long_most_significant`. The default is `digital`.
* `digital`: Displays the countdown in the format `HH:MM:SS`.
* `narrow`: Displays the countdown in the format `1d 2h 3m 4s`.
* `short`: Displays the countdown in the format `2 hr, 3 min, 4 sec`.
* `long`: Displays the countdown in the format `2 hours, 3 minutes, 4 seconds`.
* `long_most_significant`: Displays the countdown in the format `2 hours, 3 minutes, 4 seconds`, but only shows the most significant unit. Ex: `2 hours` if the countdown is less than 1 day or `3 days` if the countdown is less than 1 month.
* `max unit` (optional): The maximum unit to display in the countdown. Can be one of `years`, `months`, `weeks`, `days`, `hours`, `minutes`, or `seconds`. The default is `hours`. This means for a digital countdown of 72 hours would be represented as `72:00:00`, rather than `3 days`.
* `column` (optional): The column to display in the countdown. Can be one of `years`, `months`, `weeks`, `days`, `hours`, `minutes`, or `seconds`. This means for a digital countdown with the column set to `minutes`, the countdown `47:12:03` would be represented as `12`.
**Common Usage**:
```liquid
// Simple countdown timer
{{ device.deviceInstalledAt | date_add: '3d' | countdown_from: state.now }}
// Output -> '03:00:19'
// Fixed end date, with a message
Our summer sale ends in {{ "2024-08-06T07:16:26.802Z" | countdown_from: state.now, "long_most_significant" }}!
// Output -> Our summer sales ends in 3 days!
// Countdown with a custom column
{{ "2024-08-06T07:16:26.802Z" | countdown_from: state.now, "long", "days", "minutes" }}
// Output -> 12
// One hour countdown timer, starting from the moment a paywall is opened, formatted with just the hour and minute, i.e. 59:36 for fifty-nine minutes, thirty-six seconds
{{ device.localDateTime | date_add: "60m" | countdown_from: state.now, "long", "days", "minutes" }}:{% assign seconds = device.localDateTime | date_add: "60m" | countdown_from: state.now, "long", "days", "seconds" %}{% if seconds < 10 %}0{{ seconds }}{% else %}{{ seconds }}{% endif %}
```
In practice you will almost always use `state.now` as the start date. This is a special variable
that represents the current time. Referencing it will ensure that the countdown re-renders every
second.
### `event_name`
You can add "event\_name" as a [variable](/dashboard/dashboard-creating-paywalls/paywall-editor-variables#custom-variables) to get the name of the placement (trigger event) that caused the paywall to be displayed:
Then, it will be available to use as a custom variable. Once created, it should be listed under the **left sidebar -> Variables -> Params -> Event Name**:
**Common Usage**:
You could display the value in any text element:
```liquid
Triggered by: {{ event_name }}
```
But, more commonly, you might use it with a [dynamic value](/dashboard/dashboard-creating-paywalls/paywall-editor-dynamic-values). Then, you can customize your paywall based on the event name:
---
# Renaming Paywalls
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-renaming-paywalls
undefined
To rename a paywall, click the **Pencil Icon** button in the top-left side of the editor:
Type in a name, and click **Save**:
---
# Surveys
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-surveys
undefined
To set up a survey to show users when they close a paywall or perform a purchase, click the **Surveys** button from the **sidebar**:
Every survey you've created for your app will be selectable in this section. Superwall's surveys display natively on the platform it's presented on. For example, on iOS, it will present as an action sheet.
### Close Survey
Select a **close survey** to present when a user closes a paywall and *does not* purchase a product or start a trial:
Ideally, you'd use these to discover why users aren't willing to pay or become a trialist. By default, Superwall's survey template is a good place to start.
### Post Purchase Survey
Select a **post purchase survey** to present after the user starts a trial or performs a purchase:
These are useful to hone in on what's working, or gain insights about the types of users who are paying.
### Creating or editing surveys
You can open the survey editor from the survey section by clicking **Editing Surveys**:
To learn more about creating a survey, view the [docs here](/surveys).
---
# Layout
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-layout
undefined
The **Layout** tab in the **sidebar** provides a visual outline of your paywall's components. Hovering over elements will highlight them in the device preview:
### Adding elements
Click the **+** in the left sidebar or in the **Layout** tab to select an element to add to your paywall. This will present our library of components along with any snippets you've made (along with some of our own stock recipes):
At the top, you can choose from our core, fundamental building blocks such as a stack, text and more.
Most of your layouts should probably start with a Stack component. From there, add child elements
to them to construct any layout.
Our stock components include:
* **Stack:** The foundation of any layout, it works like CSS Flexbox layout. Check out this [reference](https://flexbox.help) if you're new to Flexbox rules, alignment or just need a refresher.
* **Text:** Text components that can use [variables](/paywall-editor-variables), different font styles and more.
* **Image:** Add any image, or URL where it's located, to your paywall.
* **Video:** Add any video, or URL where it's located, to your paywall. You can choose to loop it, show or hide playback controls, mute it or toggle autoplay. We support most file formats but we do recommend keeping the file size around 2-5 megabytes.
* **Icon:** Superwall has over 1,000 searchable icons to available, along with the ability to edit their weight and color. You can browse them by category by clicking on the right hand side:
* **Lottie:** A [Lottie](https://airbnb.design/lottie/) file. Either point to a URL of where it's located at, or upload one yourself. You can also customize looping, playback speed and more.
* **Drawer:** A basic drawer which presents from the bottom that can be configured to dismiss via fluid gestures or manually.
* **Navigation:** A container to set up multi-page designs, complete with a transition style.
### Snippets
Snippets allow you to aggregate one or more components together to reuse. For example, if you have a stack component with an icon and a text label, you could group that together to use as a component either in the current paywall, or another one later.
To add a snippet, select the **component** you want to use for your snippet and click the **bookmark** icon:
Then, give your snippet a name and add a description. When you're finished, click **Save**:
From then on, you can reuse it when adding a new component to any paywall. You'll see your own snippets at the bottom. Here's an example of a few custom snippets:
Note that you can edit any snippet you add, it will *not* overwrite the original snippet. If you do want any edits you make to be used as a snippet, simply make another snippet with the one you've edited.
### Re-ordering components or adding them as children
To reorder components on your paywall, you can simply drag and drop them in the **Layout** tab:
1. **Hovering on** another component will add the current component you're dragging as a child of the other component.
2. **Hovering above or below** other components will reorder the component you're dragging either above or below the other component.
You'll see a box filled in when you're adding a component as a child component, or you'll see a thin line to indicate you're reordering components. In the image below, notice how "The second cool feature" should be listed in the middle. Simply dragging it above the component in the middle will correctly reorder it:
Reordering and adding components as children is all done via the **Layout** tab. It'll always represent the current hierarchy of your paywall's components.
### Deleting, renaming and copying elements
You can delete and copy components by selecting them in the **Layout** tab and then clicking on one of the following icons as seen in this image:
From left to right, here's what each icon does:
* **Trashcan:** Deletes the component.
* **Bookmark:** Creates a snippet from the component.
* **Square on Square:** Copies the component.
* **Plus sign:** Adds a new component.
You can also select a component directly in the **live preview canvas** and use `⌘+C` (Mac) or `Ctrl+C` (Windows) to copy it, then `⌘+V` or `Ctrl+V` to paste it.
To **rename** a component, **double click** on its current name to edit it.
### Context menu
You can also right-click on a component to open a context menu. It contains nearly all of the editing options you'll find in the component editor. In addition, this is a great way to see and learn the available keyboard shortcuts:
### Component editor
Any component you select will open its editable properties in the **component editor**, which is on the right side of the editor window. You can change padding, text and anything related to a component here. To learn more, check out the dedicated page over editing components [here](/paywall-editor-styling-elements).
### Editor toolbar
In the top right of the editor, you'll see a toolbar with a few icons:
From left to right, here's what each icon does:
* **Undo:** Undo the last action. You can also use the `command/control+Z` keyboard shortcut.
* **Redo:** Redo the last action.
* **Preview:** Preview the paywall on device. For more, read this [doc](/paywall-editor-previewing).
* **Duplicate:** Duplicate the current paywall within the current project, or into another one.
* **Share:** Allows you to share your paywall externally. See "Paywall sharing" below for more.
* **History:** View paywall edit history and revert to a previous version. See "Paywall history" below for more.
* **Publish:** Publish the current edits to your paywall and make them live.
### Paywall sharing
Clicking the share icon allows you to share your paywall externally. This is useful for sharing with your team or clients. Once you click on share, you'll be prompted to generate a link:
From there, you can share the link with anyone. When they open it, the paywall will be duplicated into their own Superwall project (though, without your existing products):
You'll know that a paywall has a share link available when the green banner at the top of the editor is present:
To make the paywall private again, simply click the **Share** button once more and **click** the **Make Private** option.
### Paywall history
All edits you make in the paywall editor are stored in the history view:
**Click** on any entry to rollback your paywall to that version. Additionally, you can rename and add more context about any entry by clicking the **pencil** icon:
Anytime you save a your paywall, a new entry will be created in the history.
To quickly see a snapshot in your history, you can click on an entry and it will show a live preview in the editor.
---
# Dynamic Values
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-dynamic-values
undefined
Dynamic Values allow you to create rules and control flow statements to conditionally apply variables. You can use it for things like:
* Changing the text of a component based on which product is selected.
* Hide and show a modal from a button click.
To open the dynamic values editor, **click** on either the gear icon in the **component editor**, or simply **click** on any property in the **component editor**. In the dropdown, choose **Dynamic**:
When the dynamic values editor shows, **click** on **Add Value** to get started.
Check out our introductory video covering [dynamic values on YouTube](https://youtu.be/bw9ve8d2rek?feature=shared).
### Assigning variables without conditions
**First off, to simply assign a variable *without* a condition, you still use the dynamic values editor.** For example, if you want some text component's color to match something you have in your [theme](paywall-editor-theme) — just select it and don't insert any rule.
Here, we set the text to the theme's primary color:
### Setting dynamic values
The dynamic values editor works like most control flow interfaces. You set a condition, and choose what should happen when it's met. You can chain multiple conditions together, too. Or, simply use an if/else format.
Check out this example:
Notice how you can use [variables](/paywall-editor-variables) within the dynamic values editor,
too.
It's saying:
1. When the product has an introductory offer (i.e. the condition)
2. Then set the text of the component to "Start \{\{ products.selected.trialPeriodText }} free trial" (i.e. what to do when a condition is met)
3. Otherwise, set it to "Subscribe for \{\{ products.selected.price }} / \{\{ products.selected.period }}."
You can also add rules within a group.
### Rules versus group
When you add a condition, you'll have the choice to either add a rule or a group:
Think about them like this:
* Use **rule** when you have one condition you're checking.
* Ex: If the user has a free trial available, do this.
* Use **group** when you need to aggregate several conditions together to check.
* Ex: If the user has a free trial available *and* they are in the United States, do this.
* Use **both** of them together to check complex conditions.
* Ex: If the user has a free trial available *and* they are in the United States, *and* they are on a certain version, do this.
In programming terms, it's a bit like this:
```swift
if user.hasPro && (user.isLegacy && user.isEligibleForProPlus) {
showUpsellToLegacyUsers()
}
```
The first part of that statement would be a **rule** and the second check that's grouped together would be a **group**.
You can add rules within groups, or more groups within an existing group.
### Free trial detection
A common use-case of dynamic values is to conditionally show or hide components, or change copy, based on whether or not the user is eligible for a free trial. To do this, set up a dynamic value as follows:
In short, use `products.hasIntroductoryOffer` to detect whether or not a free trial is available.
If a user has already claimed a free trial for any of the products within the subscription group,
this value will be `false`.
### Examples
This text component's color is to set to the theme's primary color without any condition (ie. it
should always be this color).
If the product has an introductory offer, the text component will read "Try for free".
Here, we set the text to be larger than it normally would be if the user an introductory offer
and they haven't seen a paywall in 3 days.
Here, some text is set if the user's app version is greater than `1.1.0` and they are on an
iPhone. If those are true, and they have an introductory offer — the text "Power up your iPhone
like never before" is used.
---
# Variables
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-variables
undefined
To add or edit variables, click the **Variables** button from the **sidebar**:
Variables allow you to reuse common values, adapt to the device's characteristics (such as size or color scheme), and do things like dynamically hide or how components. All of these scenarios can be achieved using variables in conjunction with our [dynamic values](/paywall-editor-dynamic-values) editor:
* Presenting or hiding a bottom sheet of products.
* Changing the padding of several elements based on the device's available width.
* Formatting the price of a product based on different parameters, such as trial availability.
By default, Superwall has three different type of variables for use:
* **Device:** Relates to the device, the app's install date, bundle ID and more.
* **Product:** Represents the products added to the paywall, and their properties. In addition, there are variables for the selected product in addition to the primary, secondary or tertiary product.
* **User:** User-specific values, such as their alias ID.
While those will allow you to cover several cases, you can also add your own custom variables too.
Variables dealing with any product period, such as `someProduct.period`, `someProduct.periodly`,
and other similar variables, can localize automatically now. Learn more [here](/paywall-editor-localization#localizing-period-lengths).
### Using Variables
You primarily use variables in the **component editor** and with [dynamic values](/paywall-editor-dynamic-values). When using a variable in text, follow the Liquid syntax to reference one: `{{ theVariable }}`. For example, to reference a variable in some text, you would:
1. Select the text component.
2. Under Text -> click "+ Add Variable".
3. Then, drill down or search for the variable or its corresponding property.
4. Click on it, and it'll be added to your text and correctly formatted.
To use a variable with a component property, **click** on the property and choose **Dynamic**:
The [dynamic values](/paywall-editor-dynamic-values) editor will appear. Next to **then:**, choose your variable and click **Save**:
Above, the "padding" variable was used. You can ignore the if/then rules above if you simply want to apply a variable, but to dynamically enable or disable them — you can set conditions accordingly. Read the docs over [dynamic values](/paywall-editor-dynamic-values) to learn more.
You can also hover a property and hold down the **Option/Alt** key to bring up the dynamic values
editor.
### Clearing variables
To remove a variable that's in use, **click** the property or gear icon (which will be purple when a variable is being used) and selected **Clear**.
### Stock variable documentation
Below are all of the stock variables and their types. You don't have to memorize any of these — when the variable picker shows, each of the correct liquid
syntax appears above every variable, and it be will auto-inserted for you when selected.
| Property | Type | Example |
| ------------------------------- | ------ | ------------------------------------------------------------------------------- |
| App Install Date | Text | 2024-04-11 02:40:44.918000 |
| App User Id | Text | $SuperwallAlias:2580915A-8A2A-40B6-A947-2BE75A42461E |
| App Version | Text | 1.0.2 |
| Bundle Id | Text | com.yourOrg.yourApp |
| Days Since Install | Number | 0 |
| Days Since Last Paywall View | Number | |
| Device Currency Code | Text | AED |
| Device Currency Symbol | Text | AED |
| Device Language Code | Text | en |
| Device Locale | Text | en\_AE |
| Device Model | Text | iPhone14 |
| Interface Style | Text | light |
| Interface Type | Text | iphone, ipad, mac. Returns "mac" for Mac Catalyst, "ipad" for iPad apps on mac. |
| Is Low Power Mode Enabled | Number | 0 |
| Is Mac | Number | 0 |
| Local Date | Text | 2024-05-02 |
| Local Date Time | Text | 2024-05-02T21:31:52 |
| Local Time | Text | 21:31:52 |
| Minutes Since Install | Number | 7 |
| Minutes Since Last Paywall View | Number | 1 |
| Orientation | String | "landscape" or "portrait" |
| Os Version | Text | 17.4.1 |
| Platform | Text | iOS |
| Public Api Key | Text | pk\_ccdfsriotuwiou23435 |
| Radio Type | Text | WiFi |
| Total Paywall Views | Number | 10 |
| Utc Date | Text | 2024-05-02 |
| Utc Date Time | Text | 2024-05-02T17:31:52 |
| Utc Time | Text | 17:31:52 |
| Vendor Id | Text | CC93GCD-ESB6-4DFF-A165-0963D0257221 |
| View Port Breakpoint | Text | X-Small/Small/Medium/Large/Extra Large/ Extra extra large |
| View Port Width | Number | 844 |
| View Port Height | Number | 390 |
Reference any of the variables above by using the `device` variable. For example, if you were creating a filter or dynamic value based off whether or not the device was a Mac, you'd write `{{ device.isMac }}`.
| Property | Type | Example |
| -------------------------- | ---- | -------------------- |
| Currency Code | Text | USD |
| Currency Symbol | Text | $ |
| Daily Price | Text | $0.26 |
| Identifier | Text | efc.1m799.3dt |
| Lanauge Code | Text | en |
| Locale | Text | en\_US\@currency=USD |
| Localized Period | Text | 1m |
| Monthly Price | Text | $10.00 |
| Period | Text | month |
| Period Alt | Text | 1m |
| Period Days | Text | 30 |
| Period Months | Text | 1 |
| Period Weeks | Text | 4 |
| Period Years | Text | 0 |
| Periodly | Text | monthly |
| Price | Text | $7.99 |
| Raw Price | Text | 7.99 |
| Raw Trial Period Price | Text | 0 |
| Trial Period Daily Price | Text | $0.00 |
| Trial Period Days | Text | 0 |
| Trial Period End Date | Text | May 2, 2024 |
| Trial Period Monthly Price | Text | $0.00 |
| Trial Period Months | Text | 0 |
| Trial Period Price | Text | $0.00 |
| Trial Period Text | Text | 7-days |
| Trial Period Weekly Price | Text | $1.00 |
| Trial Period Weeks | Text | 1 |
| Trial Period Yearly Price | Text | $0.00 |
| Trial Period Years | Text | 0 |
| Weekly Price | Text | $1.83 |
| Yearly Price | Text | $100.00 |
The values above apply to any referenced product. There is the notion of a **primary**, **secondary**, **tertiary** and **selected** product. Whichever you use, you can use any of the above variables with it.
For example, to reference the price of the selected product (i.e. one the user has clicked or tapped on within the paywall) — you could write `The selected product cost {{ products.selected.price }}`.
There are also two more stock variables which deal with products, but aren't a part of a single product variable itself. They are referenced via the `products` variable:
| Property | Type | Example |
| ---------------------- | ------ | ---------- |
| Has Introductory Offer | Bool | True/False |
| Selected Index | Number | 0 |
Use `products.hasIntroductoryOffer` to detect whether or not a user has a trial available. Further, `products.selectedIndex` represents the index of a selected products (i.e. primary would equal 0).
| Property | Type | Example |
| --------------------------- | ------ | ---------------------------------------------------- |
| Alias Id | Text | $SuperwallAlias:606Z8824-434B-2270-BBD9-F1DF3E994087 |
| Application Installed At Id | Text | 2024-04-15T04:59:31.163Z |
| Event Name | Text | custom\_value |
| Seed | Number | 0 |
Use any variable above by referencing the `user` variable first: `{{ user.seed }}`.
### Custom Variables
To create your own variable, click **+ Add Variable** in the **sidebar** under the **Variables** section:
The variable editor will be presented:
You'll be presented with four fields to fill out:
1. **Type:** The type of variable to create. Choose **State** if you'd like the variable to be mutated by [tap behaviors](/paywall-editor-styling-elements#tap-behaviors). **Parameter** variables are similar, but initial values can be passed in [from your app](/feature-gating#register-everything).
2. **Name:** How you will reference the variable. Any name will autocorrect to camel case, i.e. "Cool Variable" will be `coolVariable`.
3. **Value Type:** The variable type. Choose from `text`, `number`, or `boolean`.
4. **Initial Value:** The initial value of the variable. This only displays once a variable type has been chosen.
Once you have everything entered, click **Save**. Your variable will show up in a section in the **sidebar** under **Variables** called **Params**:
From there, they are able to be referenced the same way as any other variable:
### Liquid syntax formatting
In text, you can use [Liquid filters](https://shopify.github.io/liquid/filters/abs/) to modify output. To use filters, add a pipe after the variable. Then, add in one or more filters:
```
// Results in 17, the absolute value of -17
{{ -17 | abs }}
```
For example, to capitalize a text variable, you would write:
```
// If the name was "jordan", this results in "JORDAN"
{{ user.name | upcase }}
```
### Custom Liquid filters
To make it easier to express dates & countdowns we've added several non-standard filters to our Liquid engine.
#### `date_add_*` and `date_subtract_*`
These filters add or subtract a specified amount of time to/from a date.
| Filter | Description |
| ----------------------- | ----------------------------------------------------- |
| `date_add_seconds` | Adds the specified number of seconds to a date |
| `date_add_minutes` | Adds the specified number of minutes to a date |
| `date_add_hours` | Adds the specified number of hours to a date |
| `date_add_days` | Adds the specified number of days to a date |
| `date_add_weeks` | Adds the specified number of weeks to a date |
| `date_add_months` | Adds the specified number of months to a date |
| `date_add_years` | Adds the specified number of years to a date |
| `date_subtract_seconds` | Subtracts the specified number of seconds from a date |
| `date_subtract_minutes` | Subtracts the specified number of minutes from a date |
| `date_subtract_hours` | Subtracts the specified number of hours from a date |
| `date_subtract_days` | Subtracts the specified number of days from a date |
| `date_subtract_weeks` | Subtracts the specified number of weeks from a date |
| `date_subtract_months` | Subtracts the specified number of months from a date |
| `date_subtract_years` | Subtracts the specified number of years from a date |
**Example Usage**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | date_add_minutes: 30 | date: "%s" }}
```
Output: `1722929186`
#### `countdown_*_partial`
These filters calculate the partial difference between two dates in various units. This is usefull for
formatting a countdown timer by exach segment.
| Filter | Description |
| --------------------------- | ----------------------------------------------------------------------------- |
| `countdown_minutes_partial` | Returns the remaining minutes in the current hour |
| `countdown_hours_partial` | Returns the remaining hours in the current day |
| `countdown_days_partial` | Returns the remaining days in the current week |
| `countdown_weeks_partial` | Returns the remaining weeks in the current month (assuming 4 weeks per month) |
| `countdown_months_partial` | Returns the remaining months in the current year |
| `countdown_years` | Returns the full number of years between the two dates |
**Example Usage**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | countdown_hours_partial: "2024-08-06T15:30:00.000Z" }}:{{ "2024-08-06T07:16:26.802Z" | countdown_minutes_partial: "2024-08-06T15:30:00.000Z" }}
```
Output: `8:33`
#### `countdown_*_total`
These filters calculate the total difference between two dates in various units.
| Filter | Description |
| ------------------------- | ----------------------------------------------------- |
| `countdown_minutes_total` | Returns the total number of minutes between two dates |
| `countdown_hours_total` | Returns the total number of hours between two dates |
| `countdown_days_total` | Returns the total number of days between two dates |
| `countdown_weeks_total` | Returns the total number of weeks between two dates |
| `countdown_months_total` | Returns the total number of months between two dates |
| `countdown_years_total` | Returns the total number of years between two dates |
**Example Usage**:
```liquid
{{ "2024-08-06T07:16:26.802Z" | countdown_days_total: "2024-08-16T07:16:26.802Z" }}
```
Output: `10`
All these filters expect date strings as arguments. Anything that Javascript's default date
utility can parse will work. For countdown filters, the first argument is the starting date, and
the second argument (where applicable) is the end date.
The `countdown_*_total` filters calculate the total difference, while the `countdown_*_partial`
filters calculate the remainder after dividing by the next larger unit (except for years).
For `countdown_months_total` and `countdown_years_total`, the calculations account for varying
month lengths and leap years.
All countdown filters assume that the end date is later than the start date. If this isn't always
the case in your application, you may need to handle this scenario separately.
### Snippets with variables
If you create a group of components built off of variables and conditions, save it as a [snippet](/paywall-editor-layout#snippets) to reuse. There are several stock snippets built this way. For example the **Product Selector** snippet:
Adding this snippet shows your products in a vertical stack:
When one is selected, the checkmark next to it is filled in. This is achieved with stock variables (i.e. the selected product) and then changing layer opacity based on if the checkmark's corresponding product is selected or not:
### Testing and handling different states
Often times, you'll want to test things like introductory or trial offers, a certain page within a paging design, or keep a modal drawer open to tweak its contents or look. To do that, simply change the variable's value in the editor. On the left sidebar, click **Variables** and then search for the one you're after and set its value.
Here are some common examples:
1. **Testing introductory offers:** To test trial or introductory offer states, change the `products.hasIntroductoryOffer` to `true` or `false`. In the example below, the text on the paywall changes based on whether or not a trial is available. To easily test it, you can toggle `products.hasIntroductoryOffer`:
2. **Testing a particular page in a paging paywall:** In this design, there are three distinct pages:
By default, the first one is showing. Though, if you needed to easily edit the second or third page, start by finding the variable that is controlling which page is shown. Typically, it'll be a state variable. Here, it's `changeScreen`:
By changing it, you can easily pull up each individual page and edit it as needed:
---
# Getting Started with the Paywall Editor
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-overview
Use Superwall's best-in-class editor to bring virtually any paywall design to life, complete with advanced U.X. patterns. Or, browse our growing list of paywall templates to get started quickly.
There are two primary ways to create a paywall:
1. Using our editor from scratch.
2. Or, start with a [template](https://superwall.com/applications/\:app/templates) and edit it to fit your needs.
### Using the Editor
On the Superwall dashboard under **Paywalls**, click **+ New Paywall** and select **From Scratch**:
The Paywall Editor consists of 3 sections:
1. **Sidebar -** General paywall settings, designs and products to show on the paywall. You can toggle through its sections using keyboard shortcuts such as `command/control 1/2/3`, etc.
2. **[Device Preview](/paywall-editor-previewing) -** An interactive preview of your paywall on a mock device.
3. **Component Editor -** Fully customize components, use variables and more on your paywall.
### Starting with a Template
On the Superwall dashboard under **Paywalls**, click **+ New Paywall** and select **Use Template**:
This will redirect you to the templates page where you can browse different types of paywall templates. Clicking on one will allow you to preview it:
Click **Use Template**, and it will open in our editor ready to customize:
### Request a Design
If you have an existing design in Figma, Sketch or something similar, you can ask Superwall to create it for you in our editor. Please allow about five business days from the date of your request (give or take). Once it's finished, it'll be uploaded to your Superwall account.
To request one, on the Superwall dashboard under **Paywalls**, click **+ New Paywall** and select **Request a Template**:
### Legacy Editor
If you're still using our legacy editor, you can still access those docs [here](/configuring-a-paywall). If you're not sure which editor you're using, any legacy editor will have a `v3` or lower in the URL:
---
# Stacks
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-stacks
undefined
From a component standpoint, stacks are the foundation of every layout. Most components and snippets will start with a stack. Under the hood, they mimic a flexbox layout.
If you are new to CSS Flexbox, try out this interactive [tool](https://flexbox.help). Or, simply change the properties in the editor to see realtime changes.
### Stack Specific Properties
Stacks have unique properties:
* **Axis**: Determines the arrangement of items within the stack.
1. `Horizontal`: Items are arranged left to right.
2. `Vertical`: Items are arranged top to bottom.
3. `Layered`: Items are stacked on top of each other.
* **Vertical**: Controls the vertical alignment of the items within the stack.
1. `Top`: Aligns items to the top of the container.
2. `Center`: Aligns items vertically in the center of the container.
3. `Bottom`: Aligns items to the bottom of the container.
4. `Stretch`: Stretches items to fill the vertical space of the container.
5. `Baseline`: Aligns items according to their baseline.
* **Horizontal**: Controls the horizontal alignment of the items within the stack.
1. `Left`: Aligns items to the left of the container.
2. `Center`: Aligns items horizontally in the center of the container.
3. `Right`: Aligns items to the right of the container.
4. `Fill Equally`: Distributes items evenly across the container, filling the space equally.
5. `Space Evenly`: Distributes items with equal space around them.
6. `Space Around`: Distributes items with space around them, with half-size space on the edges.
7. `Space Between`: Distributes items with space only between them, with no space at the edges.
* **Spacing**: Defines the amount of space between items within the stack, measured in pixels by default.
* **Wrap**: Specifies how items within the stack should behave when they exceed the container's width.
1. `Don't Wrap`: Items remain in a single line and do not wrap onto a new line.
2. `Wrap`: Items wrap onto the next line when they exceed the container's width.
3. `Wrap Reverse`: Items wrap onto the previous line in reverse order.
* **Scroll**: Determines the scrolling behavior of the stack.
1. `None`: Disables scrolling within the stack.
2. `Normal`: Enables standard scrolling behavior.
3. `Paging`: Enables paginated scrolling, allowing users to swipe through pages of items. See "Creating Carousels" below.
4. `Infinite`: Endless scrolling, items clone and repeat themselves once they reach the end.
* **Snap Position**: Defines the position at which items snap into place during paging. Only relevant if `Scroll` is set to `Paging`.
1. `Start`: Items snap to the start of the container.
2. `Center`: Items snap to the center of the container.
3. `End`: Items snap to the end of the container.
* **Auto Paging**: Controls whether a carousel's contents should automatically page between items. Only relevant if `Scroll` is set to `Paging`.
1. `Disabled`: Auto paging is turned off, and items page via user interaction.
2. `Enabled`: Auto paging is turned on and items will automatically page according to the paging delay.
* **Paging Delay**: The duration to automatically advance the slides. Only relevant if `Scroll` is set to `Paging` and `Auto Paging` is set to `Enabled`.
* **Infinite Scroll Speed**: The amount of pixels per frame that the carousel should advance. Only relevant if `Scroll` is set to `Infinite`.
To see how to use stacks for common designs, check out these pages:
* [Carousel](/paywall-editor-carousel-component)
* [Autoscrolling](/paywall-editor-autoscroll-component)
* [Slides](/paywall-editor-slides-component)
* [Navigation](/paywall-editor-navigation-component)
---
# Theme
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-theme
undefined
To configure a paywall's theme, click the **Theme** button in the **sidebar**:
The theme options let you control the overall styling of your paywall. For example, you can change the background color, your primary color, and more. In addition, you can add your own variables to a theme to reference throughout your paywall's components.
A great place to start is to set the `primary` color to your brand's prominent color.
For example, notice how the entire background of the paywall changes when the `background` theme is changed from black to white:
Remember, these are *variables*, so while some of them like `background` immediately reflect their changes, most of them will be referenced by you within a component. For example, if you wanted to reference the default **padding** variable under the "Device size" section, you would:
1. Select a component.
2. Hover over the padding value you want to change (i.e. horizontal, vertical, individual values, etc.)
3. Hold the `option` or `alt` key and click **Edit**.
4. Select **padding** to apply it.
Here's what that example would look like:
Notice how the "padding" button now displays as purple, indicating it's referencing a variable.
There are three main theme groups for variables:
* **Interface:** These variables change automatically depending on the interface style of the device.
* **Device size:** These variables change automatically depending on the device size.
* **Theme:** Variables added here are static, and by default there is variable for a font choice.
### Interface
Use the **Interface** toggle to have your theme values be reflected in either light or dark mode. Any values you set will only apply when the device's interface theme matches the selected choice (i.e. light or dark).
**By default, Superwall has all of your theme apply to both light and dark mode.** But, if you click the **+** icon you can add dark mode specific values, too:
Superwall will copy all of your theme values over to the dark interface style, and from there you can customize them specifically for dark mode.
Superwall provides three interface theme variables out of the box:
* **Background:** The fill color of the paywall's background.
* **Primary:** The fill color of core component layers, like a button.
* **Text:** The text color.
However, you are free to add as many different theme variables as you need. Read below under "Creating theme variables" for more.
### Device Size
You can tailor variables to react to a device size. There are a total three different device sizes:
* **Small:** Typical iPhone device size in portrait.
* **Medium:** Typical iPhone device size in landscape, or a tablet in portrait or landscape.
* **Large:** Devices such as a desktop or laptop.
You can see the device preview change size as you toggle through the sizes:
By default, Superwall uses the **small** device size. Simply click the **+** button to add more. By default, Superwall provides a padding device size variable:
* **Padding:** A default padding of 16 pixels you can apply to components by referencing this variable.
### Theme static values
Variables you add here are static, meaning they don't react to device parameters and update their values. This is useful for thing you likely want to stay the same, regardless if light or dark mode is on, no matter the size of the device, etc.
Superwall provides a **font** static variable. Use it to set a default font to use for any text component.
### Custom fonts
Using the default **font** variable, you can also add a custom font. Click the **+** button in the font variable to add one:
Additionally, you can add a custom font by **selecting** a text component, and under the **Typography** section in the component editor, click the **+** button:
### Creating theme variables
To add your own theme variable, click **+ Add Theme Variable**:
There are three different types you can add, all of which use CSS under the hood:
1. **Color:** Set up a color variable using a color picker.
2. **Length:** Set up a length variable using a value of either pixels, a percent, viewport values and more.
3. **Font:** Set up a font variable using the font picker.
Once you've given it a name, value type and initial value, click **Create** to begin using it:
---
# Carousel
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-carousel-component
Use Superwall's carousel component to have items automatically progress through slides.
### Adding a carousel component
The carousel component was built to make progressing slide designs easy. It's similar to a [slides component](/paywall-editor-slides-component), except it automatically progresses through its contents instead of being primarily gesture driven. To use the carousel component:
1. In the left sidebar, click **+** to add a new element.
2. Choose **Carousel** under the "Layout" header.
The carousel component requires an explicit `width` set. Generally, setting this to 100% of the viewport's width works well. This is also the default size set:
By default:
* The carousel `Scroll` property is set to `Paging`. Required.
* It's `Wrap` property is set to `Don't Wrap`. Required.
* The `Snap Position` property is set to `Center`. Editable.
* `Auto Paging` is set to `Enabled`. Editable.
* Finally, `Paging Delay` is intentionally set low to help with designing its content. Set it to a higher value to see the carousel in action.
### Adding contents to carousels
The carousel component has a few demonstration items added to it by default. You can remove these and add your own content:
### Tracking or updating the displayed element in a carousel
When a carousel element is added, Superwall automatically creates an element variable for it (accessed through the **[Variables](/paywall-editor-variables)** tab in the left sidebar, or the variables button in the **[floating toolbar](/paywall-editor-floating-toolbar)**). Its name will match whatever is in the element hierarchy in the left sidebar:
You can use this to:
* Select a product based off of the index of the carousel.
* Have a button progress to the next slide.
* Change text using [dynamic values](/paywall-editor-dynamic-values) based on the index.
* etc.
The variable's name is derived by the node's unique identifier. You don't need to set or generally
be aware of this value.
For example, here the button progresses to the next slide by incrementing the slides `Child Page Index` variable:
As another example, we could change the text to represent the different product periods we've set up for our fictional products of weekly, monthly and annual. By using a dynamic value, we can simply check which carousel index is showing and change the text accordingly:
---
# Duplicating Paywalls
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-duplicating-paywalls
undefined
To duplicate a paywall live, click the **Duplicate** button in the top-right side of the editor:
You can choose to duplicate the paywall into the current project, or into another one. If you choose to duplicate it into another project, you'll be prompted to select which app you want to duplicate it into:
Additionally, you can duplicate a paywall by opening the **Paywalls** view from the left-hand sidebar for any app you have. Below any paywall to duplicate, click the **Duplicate** button at the bottom:
---
# Products
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-products
undefined
To add products to your paywall, click the **Products** button from the **sidebar**:
If you haven't added products to your app, do that first. Check out this [doc](/products) for
more.
### Choosing products
You can display as many products as you see fit on your paywall. Superwall will automatically fill in a name for the first three added ("primary", "secondary", and "tertiary") but you're free to name them anything else. Regardless, the name is used to reference them using Liquid Syntax in the editor. For example, `products.primary.price`.
It's important to remember that *you* retain full control over which of your products show in a paywall, and how. For example, use them along with [dynamic values](/paywall-editor-dynamic-values) to hide or show them to create any U.X. your design calls for.
### Web Checkout Locations
When using web checkout products (Stripe products), you can control how the checkout experience is presented to users. This setting determines where the web checkout interface appears:
There are three web checkout location options:
* **Payment Sheet** (Recommended): Opens an in-app payment sheet that appears as a modal covering about half the screen height. This provides the smoothest user experience by keeping users within your app context.
* **In App Browser**: Opens the checkout flow in an in-app web browser (like Safari View Controller on iOS). This keeps users within your app while providing full web functionality.
* **External**: Opens the system's default web browser for checkout. This takes users completely out of your app but may be necessary for certain compliance requirements.
The Payment Sheet option is recommended as it provides the best user experience with minimal disruption to your app flow. Users can complete their purchase without feeling like they've left your app.
### Understanding the selected product and selected product index variables
The `products.selected` variable will always represent any product the user has selected on your paywall. By default, it will be the *first* product you've added. In addition, the `products.selectedIndex` variable will also be updated as products are selected. This opens up many patterns to use, such as customizing copy, images, videos, or anything else based on which product the user has tapped on.
Many of our [built-in elements](/paywall-editor-layout#adding-elements) which display products will update these values. If you wish to add a custom element which selects a product, **click** on the element and add a **[tap behavior](/paywall-editor-styling-elements#tap-behaviors)** to choose a product (the selected index will update automatically as a result).
### Customizing pricing copy
In my most cases, Superwall will format your product's price in a localized manner. For example, look at this paywall from left-to-right:
1. The primary product is displayed in the button.
2. Below it, the call-to-action button formats its text as `Subscribe for {{ products.selected.price }} / {{ products.selected.period }} `.
3. That means any selected product's price will display with a similar pattern in the call-to-action button.
You can use [Liquid syntax](https://shopify.github.io/liquid/) to format prices in several different ways. For example, if you wanted to show an annual price differently, you could write `Subscribe for only {{ products.primary.monthlyPrice }} / month.` to display the localized price in monthly terms. If a product cost $120.00 a year, then the text would read as "Subscribe for only $10.00 / month."
Copy like this is achieved by using variables. To learn more about them, visit this [page](/paywall-editor-variables).
### Offer pricing copy
A common use-case is showing copy that reflects the selected product's trial or offer terms. Consider this example product:
| Product Identifier | Trial | Trial Price | Price | Period |
| ---------------------- | ------ | ----------- | ------ | ------ |
| myapp.annual40.1wkFree | 1 week | Free | $39.99 | 1 year |
In Superwall, all data for the one-week free trial is found in the `trial` liquid variables, which are a part of a `product`. Below, critical details about its duration, offer price and more are shown in the example paywall. Take note of the text box on the right, which shows how these variables can be used:
### Products missing App Store Connect API
When using Apple-based products, Superwall will automatically fetch the product information from App Store Connect. However, if you haven't set up the App Store Connect API, you may see a message indicating that the product information is missing:
To resolve this, follow the steps in our [App Store Connect API setup guide](/overview-settings-revenue-tracking#app-store-connect-api).
---
# Autoscroll
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-autoscroll-component
Use Superwall's autoscroll component to create marquee-like content that automatically scrolls.
### Adding an autoscroll component
The autoscroll component was built to make creating marquee-like content easy. To use the autoscroll component:
1. In the left sidebar, click **+** to add a new element.
2. Choose **Autoscroll** under the "Layout" header.
The autoscroll component requires an explicit `width` set. Generally, setting this to 100% of the viewport's width works well. This is also the default size set:
### Adding contents to autoscroll
The autoscroll component has a few demonstration items added to it by default. You can remove these and add your own content:
### Controlling scroll speed
To control the scrolling speed, change the `Infinite Scroll Speed` property when the autoscroll component is selected. When it's first added, this value is intentionally set low so you can configure the component first. Change this to a higher value to see its content scroll:
---
# Previewing
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-previewing
undefined
To preview a paywall on device, click **Preview** in the top-right side of the editor:
To enable this functionality, you'll need to use deep links.
#### Adding a Custom URL Scheme (iOS)
To handle deep links on iOS, you'll need to add a custom URL scheme for your app.
Open **Xcode**. In your **info.plist**, add a row called **URL Types**. Expand the automatically created **Item 0**, and inside the **URL identifier** value field, type your **Bundle ID**, e.g., **com.superwall.Superwall-SwiftUI**. Add another row to **Item 0** called **URL Schemes** and set its **Item 0** to a URL scheme you'd like to use for your app, e.g., **exampleapp**. Your structure should look like this:
With this example, the app will open in response to a deep link with the format **exampleapp\://**. You can [view Apple's documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) to learn more about custom URL schemes.
#### Adding a Custom Intent Filter (Android)
For Android, add the following to your `AndroidManifest.xml` file:
```xml
```
This configuration allows your app to open in response to a deep link with the format `exampleapp://` from your `MainActivity` class.
#### Handling Deep Links (iOS)
Depending on whether your app uses a SceneDelegate, AppDelegate, or is written in SwiftUI, there are different ways to tell Superwall that a deep link has been opened.
Be sure to click the tab that corresponds to your architecture:
```swift AppDelegate.swift
import SuperwallKit
class AppDelegate: UIResponder, UIApplicationDelegate {
// NOTE: if your app uses a SceneDelegate, this will NOT work!
func application(\_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return Superwall.shared.handleDeepLink(url)
}
}
```
```swift SceneDelegate.swift
import SuperwallKit
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
// for cold launches
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
if let url = connectionOptions.urlContexts.first?.url {
Superwall.shared.handleDeepLink(url)
}
}
// for when your app is already running
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
if let url = URLContexts.first?.url {
Superwall.shared.handleDeepLink(url)
}
}
}
```
```swift SwiftUI
import SuperwallKit
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
ContentView()
.onOpenURL { url in
Superwall.shared.handleDeepLink(url) // handle your deep link
}
}
}
}
```
```swift Objective-C
// In your SceneDelegate.m
#import "SceneDelegate.h"
@import SuperwallKit;
@interface SceneDelegate ()
@end
@implementation SceneDelegate
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
[self handleURLContexts:connectionOptions.URLContexts];
}
- (void)scene:(UIScene *)scene openURLContexts:(NSSet *)URLContexts {
[self handleURLContexts:URLContexts];
}
#pragma mark - Deep linking
- (void)handleURLContexts:(NSSet *)URLContexts {
[URLContexts enumerateObjectsUsingBlock:^(UIOpenURLContext * _Nonnull context, BOOL * _Nonnull stop) {
[[Superwall sharedInstance] handleDeepLink:context.URL];
}];
}
@end
```
#### Handling Deep Links (Android)
In your `MainActivity` (or the activity specified in your intent-filter), add the following Kotlin code to handle deep links:
```kotlin Kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Respond to deep links
respondToDeepLinks()
}
private fun respondToDeepLinks() {
intent?.data?.let { uri ->
Superwall.instance.handleDeepLink(uri)
}
}
}
```
### Previewing Paywalls
Next, build and run your app on your phone.
Then, head to the Superwall Dashboard. Click on **Settings** from the Dashboard panel on the left, then select **General**:
With the **General** tab selected, type your custom URL scheme, without slashes, into the **Apple Custom URL Scheme** field:
Next, open your paywall from the dashboard and click **Preview**. You'll see a QR code appear in a pop-up:
On your device, scan this QR code. You can do this via Apple's Camera app. This will take you to a paywall viewer within your app, where you can preview all your paywalls in different configurations.
```
```
---
# Settings
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-settings
undefined
To configure settings for your paywall, click the **Settings** button from the **sidebar**:
You have four primary properties of your paywall to configure here, all are set with default values.
### Presentation Style
Toggle the presentation style of your paywall. Available options are:
1. **Fullscreen:** The paywall will cover the entire device screen.
2. **Push:** The paywall will push onto a hierarchy, such as a `UINavigationController` on iOS.
3. **Modal:** The paywall presents with the platform's default modal API.
4. **No Animation:** The paywall presents modally, but without any animation.
5. **Drawer:** The paywall presents from a bottom drawer with customizable height and corner radius.
6. **Popup:** The paywall presents as a modal popup with customizable width, height, and corner radius from the center of the screen.
#### Drawer Configuration
When using the **Drawer** presentation style, you can configure:
* **Height:** Set the height of the drawer as a percentage of the screen (default: 70%).
* **Corner Radius:** Set the corner radius for the drawer corners (default: 15px).
* **Scrolling:** Enable or disable scrolling within the drawer.
#### Popup Configuration
When using the **Popup** presentation style, you can configure:
* **Width:** Set the width of the popup as a percentage of the screen (default: 80%).
* **Height:** Set the height of the popup as a percentage of the screen (default: 60%).
* **Corner Radius:** Set the corner radius for the popup corners (default: 15px).
Popup style requires iOS SDK v4.8.0+
### Scrolling
Toggle the scrolling behavior of your paywall. Available options are:
1. **Enabled (Default):** The paywall can scroll its contents when presented on a device.
2. **Disabled:** Disables all scrolling behavior on the paywall.
Requires iOS SDK v3.11.2+ and Android SDK v1.4.0+
### Game Controller Support
Toggle game controller support for paywalls — obviously, ideal for paywalls shown in games where controllers may be in use. Available options are:
1. **Enabled:** The paywall can scroll its contents when presented on a device.
2. **Disabled (Default):** Disables all scrolling behavior on the paywall.
Learn more about game controller support [here](/game-controller-support#game-controller-support).
### Feature Gating
Feature gating allows you to control whether or not [placements](/campaigns-placements) should restrict access to features. Using either method, the paywall will still be presented if a user isn't subscribed:
1. **Non Gated:** Placements *will always* fire your feature block. Specifically, once the paywall is dismissed.
2. **Gated:** Placements *will only* fire your feature block if the user is subscribed. Note that if they are subscribed, the paywall will *not* be presented.
For example:
```swift
// With non gated - `logCaffeine()` is still invoked
Superwall.shared.register(placement: "caffeineLogged") {
logCaffeine()
}
// With gated - `logCaffeine()` is invoked only if the user is subscribed
Superwall.shared.register(placement: "caffeineLogged") {
logCaffeine()
}
```
This is useful to dynamically change what is paywalled in production without an app update. For example, in a caffeine tracking app — perhaps you might run a weekend campaign where logging caffeine is free. You'd simply change the paywall to be **Non Gated**. Then, the paywall would still be presented, but users would be able to continue and log caffeine.
For information on how this behaves when offline, view this [section](/feature-gating#handling-network-issues).
Feature gating does not apply if you are manually presenting a paywall via `getPaywall`.
### Cache on Device
If enabled, Superwall's SDK will cache the paywall on device. This can be useful if you have a paywall that could take a few seconds to fetch and present (i.e. if there is a video as part of your design). On-device caching can lead to quicker presentation.
Device caching is currently only available on iOS.
### Identifier
The identifier for the paywall. Non-editable.
### Present Paywall
This is now deprecated in iOS SDK version 4 and above, and version 2 and above for all other SDKs. Instead, use the [entitlements](/campaigns-audience#matching-to-entitlements) feature when creating campaign filters.
You can have a paywall present under two different conditions when a [placement](/campaigns-placements) is matched:
1. **Check User Subscription:** Present the paywall only if the user's subscription is not active.
2. **Always:** Present the paywall regardless of the user's subscription status.
### Reroute back button
If enabled, allows you to run custom logic on back button press and consuming the event.
To use it, once the option has been enabled, use the `PaywallOptions.onBackPressed` and return true to consume the back press event or false to let the SDK handle it.
Back button rerouting is currently only supported on Android SDK 2.5.6 or higher
---
# Creating Projects
Source: https://superwall.com/docs/dashboard/creating-applications
Projects are how Superwall groups the same app together across platforms.
Projects can contain one or more applications. For example, a project for one "app" could have an iOS, Android and web checkout app in the same project. To create a new project, follow these steps:
Open the menu by selecting your existing project from the top-level side of
the sidebar
*You may need to scroll down if you have many apps*
From there, name your app and choose the platform you're building for. You can always add more platforms later.
Superwall can prefill existing iOS apps live on the App Store. If you haven't launched yet, simply choose "Not released yet" and you'll be good to go.
Once you're all done, you should be able to see your new project and its app and switch between
them using the project switcher on the top left that we used to get started! 🎉
---
# Presenting Paywalls from One Another
Source: https://superwall.com/docs/dashboard/guides/presenting-paywalls-from-one-another
Learn how to present a different paywall from one that's already presented.
It's possible to present another paywall from one already showing. This can be useful if you want to highlight a special discount, offer, or emphasize another feature more effectively using a different paywall. Check out the example here:
* A [placement](/campaigns-placements) is evaluated when the button is tapped. Superwall sees that the user isn't subscribed, so a paywall is shown.
* Next, the user taps the "Custom Icons Too 👀" button.
* The current paywall dismisses, and then presents the icons-centric paywall.
You can extend this technique to be used with several other interesting standard placements. For
example, presenting a paywall when the user abandons a transaction, responds to a survey and more.
Check out the examples [here](/campaigns-standard-placements#standard-placements).
There are two different ways you can do this, with [custom placements](/paywall-editor-styling-elements#tap-behaviors) or by using [deep links](/in-app-paywall-previews). We recommend using custom placements, as the setup is a little easier.
Custom placements minimum SDK requirements are 3.7.3 for iOS, 1.2.4 for Android, 1.2.2 for
flutter, and 1.2.6 for React Native.
They both have the same idea, though. You create a new campaign specifically for this purpose, attach a paywall and either add a filter (for deep linking) or a new placement (for custom placements) to match users to it.
While it's not *required* to make a new campaign, it is best practice. Then, if you later have
other paywalls you wish to open in the same manner, you can simply add a new
[audience](/campaigns-audience) for them in the campaign you make from the steps below.
### Use Custom Placements
Select a component on your paywall and add a **Custom Placement** Tap Behavior, and name it whatever you wish (i.e. showIconPaywall).
Finally, be sure to click **Publish** at the top of the editor to push your changes live
Create a new [campaign](/campaigns) specifically for this purpose, here — it's called "Custom Placement Example":
In your new campaign, [add a new placement](/campaigns-placements#adding-a-placement) that matches the name of your custom action you added in step one. For us, that's `showIconPaywall`:
Finally, choose a paywall that should present by **clicking** on the **Paywalls** button at the top:
### Use Deep Links
You'll need [deep links](/in-app-paywall-previews) set up for your app. This is how Superwall
will query parameters and later launch your desired paywall.
Choose the paywall you want to open another paywall from. Then, click the element (a button, text, etc.) that should open the new paywall:
1. In its component properties on the right-hand side, add a **Tap Behavior**.
2. Set its **Action** to **Open Url**.
3. For the URL, use your deep link scheme from step one, and then append a parameter which will represent which other paywall to present. This is specific to your app, but here — `offer` is the key and `icons` is the value. Your resulting URL should be constructed like this: `deepLinkScheme://?someKey=someValue`.
4. Set its **Type** to **Deep Link**.
5. Click **Done**.
Here's what it should look like (again, with your own values here):
Finally, be sure to click **Publish** at the top of the editor to push your changes live.
Create a new [campaign](/campaigns) specifically for this purpose, here — it's called "Deeplink Example":
In your new campaign, [add a placement](/campaigns-placements#adding-a-placement) for the `deepLink_open` standard placement:
Edit the default audience's filter to match `params.[whatever-you-named-the-parameter]`. Recall that in our example, the parameter was `offer` and the value was `icons`. So here, we'd type `params.offer` and **click** the **+** button:
Superwall will ask what type of new parameter this is — choose **Placement** and enter the parameter name once more (i.e. "offer"). Click **Save**:
Finally, choose the **is** operator and type in the value of your parameter (in our case, "icons"). Then, **click** the **+ Add Filter** button. Here's what it should look like:
Finally, choose a paywall that should present by **clicking** on the **Paywalls** button at the top:
### Test Opens
After following the steps above for either method, be sure to test out your presentation. Open the relevant paywall on a device and tap on whichever button should trigger the logic. The currently presented paywall should dismiss, and then immediately after — the other paywall will show.
---
# Custom Actions
Source: https://superwall.com/docs/dashboard/guides/tips-using-custom-actions
Learn how to use custom actions.
### What
Use [custom actions](/custom-paywall-events#custom-paywall-actions) to trigger application-specific functionality or logic from within your app.
### Why
Custom actions allow you to fire any arbitrary logic inside your app, allowing you to navigate to certain places or trigger platform-specific APIs (such as playing haptic feedback when tapping on a button on iOS).
### How
---
# Abandoned Transaction Paywalls
Source: https://superwall.com/docs/dashboard/guides/tips-abandoned-transaction-paywall
Learn how to present a a paywall when a user starts to convert, but then cancels the transaction.
### What
Transaction abandon discounts can boost revenue by offering discounts to users who start, but don't complete, in-app purchases. We've seen 25-40% of revenue come from this method in a few of our own apps, and it can be implemented in Superwall without an app update.
### Why
Somewhere around only 50% of users complete in-app purchases once they start. Offering discounts to those who showed interest, but hesitated, can convert them into paying customers.
### How
---
# Using Stripe's New Payment Sheet Checkout In-App
Source: https://superwall.com/docs/dashboard/guides/using-stripe-bottom-sheet-checkout-in-app
undefined
For users in the United States, you can offer Stripe checkout inside of your app's experience. For more information on how to configure Stripe checkout, review the documentation [here](/web-checkout-direct-stripe-checkout). This specific guide shows you how to use Stripe's new bottom sheet checkout flow.
Superwall will prioritize showing Apple Pay when available as the first payment option.
This process works by attaching the Stripe product to a purchase tap behavior. Once the user checks out, the [web redemption flow](/web-checkout-direct-stripe-checkout) will occur.
---
# Using Superwall for Onboarding Flows
Source: https://superwall.com/docs/dashboard/guides/using-superwall-for-onboarding-flows
Due to the flexible nature of our paywalls and SDK, you can easily use Superwall for onboarding flows.
Superwall's flexible paywall system can be used for building engaging onboarding experiences. With multi-page paywalls, dynamic content, and powerful targeting rules, you can create interactive onboarding flows without shipping app updates. Here's a quick guide on how to get up and running.
## Creating an onboarding campaign
Start by creating a [campaign](/campaigns) specifically for onboarding:
1. Navigate to **Campaigns** in the dashboard sidebar
2. Click **+ New Campaign**
3. Name it something like "User Onboarding"
4. Add a [placement](/campaigns-placements) to trigger your onboarding flow
## Triggering onboarding automatically
There are two main approaches to triggering onboarding:
### Using the `app_install` placement
The [`app_install`](/campaigns-standard-placements) standard placement fires automatically when a user first installs your app. This is ideal for showing onboarding since it only fires once:
1. Add `app_install` as a [placement](/campaigns-placements) to your onboarding campaign
2. Optionally, in your [audience filters](/dashboard/dashboard-campaigns/campaigns-audience#using-user-properties-or-placement-parameters), add a condition like `user.totalPaywallViews` equals `0` to ensure it only shows to brand new users
Since `app_install` only fires once per install, you don't need additional logic to prevent it from showing multiple times. However, if users complete onboarding and you want to track that for other purposes, you can still [set a user attribute](/sdk/quickstart/setting-user-properties):
```swift iOS
// Swift
Superwall.shared.setUserAttributes(["hasCompletedOnboarding": true])
// Android
Superwall.instance.setUserAttributes(mapOf("hasCompletedOnboarding" to true))
// Flutter
Superwall.instance.setUserAttributes({
"hasCompletedOnboarding": true
});
// React Native / Expo
await Superwall.shared.setUserAttributes({ hasCompletedOnboarding: true });
```
### Using a custom placement
For more control over when onboarding appears, create a custom placement and register it manually:
```swift iOS
// Swift
Superwall.shared.register(event: "start_onboarding")
// Android
Superwall.instance.register("start_onboarding")
// Flutter
Superwall.instance.register("start_onboarding");
// React Native / Expo
await Superwall.shared.register({ placement: "start_onboarding" });
```
This approach lets you trigger onboarding based on specific user actions, like completing account setup or reaching a certain screen.
## Building multi-page onboarding paywalls
Superwall's [Navigation component](/paywall-editor-navigation-component) is perfect for creating multi-page onboarding experiences. Check out our [Simple Onboarding](https://superwall.com/templates?templateId=119147) template to see this in action.
To create a multi-page onboarding paywall:
1. In the paywall editor, click **+** to add a new element
2. Select **Navigation** under the "Base Elements" section
3. Add your onboarding content pages using [stacks](/paywall-editor-stacks)
4. Add buttons with tap behaviors to navigate between pages, or use transitions like Push, Fade, or Slide
You can also use the [Slides component](/paywall-editor-slides-component) if you want gesture-driven navigation or the [Carousel component](/paywall-editor-carousel-component) if you want slides that auto-advance.
## Personalizing content with dynamic values
Use [variables](/paywall-editor-variables) and [dynamic values](/paywall-editor-dynamic-values) to show different content based on user attributes, device properties, or actions:
**Show different messages based on device type:**
```
if device.interfaceType is "ipad"
then "Welcome to the best iPad experience"
else
then "Welcome to your new favorite app"
```
**Display personalized content using user attributes:**
```
if user.accountType is "premium"
then "Unlock your premium features"
else
then "Discover what you can do"
```
This means you can go to certain pages based off a button they tapped showing a survey, change wording, which products to show, and more. Rely on dynamic values and variables to completely customize flows.
**Adjust layout based on onboarding progress:**
Track which slide users are on using the [slides element variable](/paywall-editor-slides-component#tracking-or-updating-the-displayed-element-in-slides) and conditionally show/hide elements or change copy accordingly.
## Tracking onboarding analytics
To track onboarding metrics, you can use these [Superwall events](/tracking-analytics) and can they can also be sent to your own analytics service. Additionally, you can also use [custom paywall actions](/sdk/guides/advanced/custom-paywall-actions) to trigger specific tracking events when users interact with buttons or elements in your onboarding flow, giving you detailed insights into user behavior and drop-off points.
## Best practices
* **Length:** 3-10 pages is usually optimal for onboarding
* **Use user attributes:** Track onboarding completion and progress to avoid showing it repeatedly
* **Test variations:** Create multiple audiences to A/B test different onboarding flows
* **Make it dismissible:** Consider adding a skip option for returning users
* **Track analytics:** Monitor your onboarding completion rates in the campaign metrics
Remember, since everything is managed through the dashboard, you can iterate on your onboarding experience without shipping app updates.
## Going forward
Superwall is currently building out more tools for onboarding, such as text boxes and text entry, and will be available soon.
---
# Showing Unique Paywalls
Source: https://superwall.com/docs/dashboard/guides/tips-paywalls-based-on-placement
Learn how to present a unique paywall based on the audience that was matched within a campaign.
### What
Using [audiences](campaigns-audience) within a campaign, you can:
1. Show unique paywalls for each one.
2. And, within an audience, you can show multiple paywalls based on a [percentage](/campaigns-audience#paywalls).
### Why
Our data clearly demonstrates that showing the right paywall, to the right user, and at the right time dramatically affects revenue. There is rarely a one-size-fits all paywall, so you should be testing different variations of them often.
### How
---
# RevenueCat Migration Guide
Source: https://superwall.com/docs/dashboard/guides/migrating-from-revenuecat-to-superwall
A guide to migrating from RevenueCat to Superwall.
If you're looking to migrate off RevenueCat and use Superwall, here's what you'll need to do along with a few considerations. Your setup can look a little different depending on how you're using RevenueCat, so we'll break it down into a few different sections. Jump to the one that fits your current architecture.
### If you're currently using RevenueCat and not Superwall
If you've not installed or shipped the Superwall SDK, and are only using RevenueCat — then it's a matter of removing one SDK and adding the other:
1. Remove the RevenueCat SDK from your project.
2. Install the Superwall SDK by following the [installation guide](/installation).
3. Update any local data models to correlate purchase status.
For step 3, you might've been doing something similar to this to see if a user was subscribed:
```swift
// In RevenueCat's SDK
let customerInfo = try? await Purchases.shared.customerInfo()
return customerInfo.entitlements.active["Pro"]?.isActive ?? false
```
In Superwall, the concept is similar. You query active entitlements:
```swift
switch Superwall.shared.subscriptionStatus {
case .active(let entitlements):
logger.info("User has active entitlements: \(entitlements)")
handler(true)
case .inactive:
logger.info("User is free plan.")
handler(false)
case .unknown:
logger.info("User is inactive.")
handler(false)
}
```
Or, if you're only dealing with one entitlement, you can simplify the above to:
```swift
if Superwall.shared.subscriptionStatus.isActive {
// The user has an active entitlement
}
```
### If you're using a [PurchaseController](/advanced-configuration) with Superwall and RevenueCat
In this case, it's mostly a matter of removing the `PurchaseController` implementation. Remember, a purchase controller is for manually assigning a subscription state to a user and performing purchase logic. Superwall's SDK does all of that out of the box without any code from you:
```swift
// Remove the `PurchaseController` implementation from your app.
// Change this code...
let purchaseController = RCPurchaseController()
Superwall.configure(
apiKey: "MY_API_KEY",
purchaseController: purchaseController
)
// To this...
Superwall.configure(apiKey: "MY_API_KEY")
```
Now, when Superwall is configured without a purchase controller, the SDK takes over all purchasing, restoring and entitlement management.
### If you're using observer mode
If you're using RevenueCat today just with [observer mode](/using-revenuecat#using-purchasesarecompletedby) — you're free to continue to do so. Simply install the Superwall SDK and continue on.
### Considerations
1. **Paywalls:** RevenueCat's paywalls can be displayed if an entitlement isn't active, manually, or by providing custom logic. Superwall can do all of those presentation methods as well. The core difference is with Superwall, typically users [register a placement](/feature-gating) at the call site instead of looking at an entitlement. This means you can show a paywall based on one or several conditions, not just whether or not a user has an entitlement.
2. **Purchases:** Superwall uses the relevant app storefront (App Store or Google Play) to check for a source of truth for purchases. This is tied to the account logged into the device. For example, if a user is logged into the same Apple ID across an iPad, Mac and iPhone — any subscription they buy in-app will work on all of those devices too. RevenueCat uses a similar approach, so there typically isn't much you need to do. If any subscription status issues arise, typically restoring the user's purchases puts things into place.
Even if you're using [web checkout](/web-checkout-overview) with either platform, Superwall allows you to manually assign a subscription state to a user via [a `PurchaseController`](/advanced-configuration).
3. **Platform differences:** Like all products, Superwall and RevenueCat bring different features to the table, even though there are a lot of similarities. While both offer subscription SDKs, paywalls, and analytics - it helps to familiarize yourself with how Superwall is different. Superwall works on the foundations of registering placements and filtering users who activate them into audiences. Superwall groups those concepts together into [campaigns](/campaigns). This means that you're ready from day one to run all sorts of price tests, paywall experiments, and more.
In terms of reporting, RevenueCat currently offers some metrics like LTV and MRR that you may still need. If so, you can continue using RevenueCat alongside Superwall in [observer mode](/using-revenuecat#using-purchasesarecompletedby) and all of your dashboard analytics should work as they always have.
***
Whatever your setup, Superwall is ready to meet you where you're at. Whether you want to go all-in with Superwall, use it with RevenueCat or any other approach, our SDK is flexible enough to support you.
---
# Pre-Launch Checklist
Source: https://superwall.com/docs/dashboard/guides/pre-launch-checklist
Ready to ship your app with Superwall? Here is a last minute checklist to give you confidence that you're ready to ship without issue.
In your Superwall account, make sure you've got a card on file to avoid any service disruptions.
Go to `Settings->Billing` in your Superwall account to add one if you haven't yet.
Set up your products in their respective storefront first, whether that's App Store Connect or
Google Play. Once you've done that, add them into Superwall. All of their respective identifiers
should match what they are in each storefront. For more details, refer to this
[page](/products).
Each paywall should display one or more of those previously added products. You can associate
them easily on the left hand side of the paywall editor.
Be sure your paywall presents and our SDK is configured in your app. If you need to double check
things, check out the [docs for the relevant platform](/configuring-the-sdk).
Next, after your paywall shows in Testflight and beta builds, make sure you can successfully
purchase a product, start a trial or kick off a subscription. If you run into an issue, try
these steps in our [troubleshooting guide](/troubleshooting). They solve a majority of the
common problems.
Finally, make sure that your subscriptions have been approved in each storefront. On App Store
Connect, for example, you'll have to send off each one individually for review. If this is your
initial launch, you can have them approved alongside the first build of your app.
If everything looks good here, you should be ready to launch with Superwall.
### Bonus Steps
These aren't essential, but they are good to think about to make sure you're leveraging all Superwall has to offer.
No matter how much you optimize flows, designs or copy — the truth is that, statistically speaking, the majority of users will not convert. Finding out why is key, and you can do that with our surveys that you can attach to any paywall.
Once a user closes a paywall, we'll present the survey attached to it. See how to set them up [here](/surveys).
If you're new to Superwall, it might be tempting to use one, do-it-all placement — like `showPaywall` or something similar. We don't recommend this, please use an individual placement for each action or scenario that could possibly trigger a paywall. The more placements you have, the more flexible you can be. It opens up things like:
1. Showing a particular paywall based on a placement. For example, in a caffeine tracking app, two of them might be `caffeineLogged` and `viewedCharts`. Later, you could tailor the paywall based on which placement was fired.
2. You can dynamically make some placements "Pro" or temporarily free to test feature gating without submitting app updates.
3. In your campaign view, you can see which placements resulted in conversions. This helps you see what particular features users might value the most.
The easy advice is to simply create a placement for each action that might be paywalled. For a quick video on how to use placements, check out this [YouTube Short](https://youtube.com/shorts/lZx8fAL8Nvw?feature=shared).
Audiences are how Superwall can segment users by filtering by several different values such as the time of day, app version and more. This lets you target different paywalls to certain audiences. To see an example of how you might set up an advanced example, see this video:
---
# Feature Gating
Source: https://superwall.com/docs/dashboard/guides/tips-paywalls-feature-gating
Learn how to toggle feature gating in a paywall.
### What
Toggle [feature gating](/paywall-editor-settings#feature-gating) on a paywall to change whether or not a placement restricts access to features.
### Why
When you use "non-gated", it means users will still see a paywall *but* will have access to whatever feature is behind that paywall. This can be useful to allow access to pro features for a limited time — which hopefully will lead to more conversions later on down the road.
### How
---
# First Touch Paywalls
Source: https://superwall.com/docs/dashboard/guides/tips-first-touch-paywall
Learn how to present a paywall the moment users interact with your app.
### What
App installs to paywall views is one of the most critical metrics you can track. Using the first touch event to present a paywall is a great way to boost it.
### Why
Showing a paywall from the user's first touch can be an effective alternative to showing one simply after the app launches. This way, it feels less "in the way" and much less like a popup a user had no control over — while still ensuring users view your products.
### How
---
# Subscription Management
Source: https://superwall.com/docs/dashboard/subscription-management
See how Superwall manages subscription states end-to-end, surface that data in the dashboard, and distribute updates across your stack.
## Overview
* **One source of truth:** Superwall ingests purchase lifecycle events from the App Store, Play Store, and Stripe-powered web checkout flows. The platform reconciles those events into user entitlements that power paywall targeting, analytics, and access gates.
* **Entitlements-first:** Products attach to entitlements that represent access tiers. Learn more about configuring them in [Adding Products → Entitlements](/dashboard/products#entitlements).
* **Real-time syncing:** When an event (purchase, renewal, cancellation, refund) lands, Superwall updates the user profile and campaign eligibility automatically.
## Dashboard
### Users Page
The Users page gives you a per-customer timeline that includes subscription events, paywall impressions, and entitlement snapshots. See [Users](/dashboard/overview-users) for the full walkthrough.
* Confirm active entitlements and their expiration.
* Review recent renewals, cancellations, and billing issues.
* See paywall views, SDK events, and other analytics-style activity for that user.
### Audience Filters & Campaign Targeting
Campaigns can check entitlements directly, letting you show different paywalls or post-purchase experiences to subscribers vs. trials. See [Campaign Audience Filters](/dashboard/dashboard-campaigns/campaigns-audience) for details on the filter capabilities.
## Web checkout
Web checkout purchases follow the same entitlement pipeline as native stores and surface throughout the dashboard:
* **Checkout and campaigns** – Configure Stripe credentials and connect campaigns that present web paywalls with [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings) and [Creating Campaigns to Show Paywalls](/web-checkout/web-checkout-creating-campaigns-to-show-paywalls).
* **Redemption** – After purchase, users receive a redemption email. Validate the flow using [Testing Purchases](/web-checkout/web-checkout-testing-purchases) and share the manage URL pattern (`https://{your-domain}.superwall.app/manage`) for manual redemption.
* **Manage page** – Customers update billing, cancel, or request new redemption links from the manage portal documented in [Managing Memberships](/web-checkout/web-checkout-managing-memberships).
* **Settings** – Brand the manage page and configure support contact info in **Settings → General → For Stripe apps**. See [General Settings](/dashboard/dashboard-settings/overview-settings) for field descriptions.
## Integrations
Superwall emits webhook events for every subscription lifecycle change. Connect these via the Integrations page to power downstream systems:
* **Webhooks** – Review payloads and event types in [Integrations](/integrations). Common uses include syncing CRM subscription status, triggering feature flags, or updating internal billing systems.
* **Slack** – Route high-value events into a revenue channel by enabling the [Slack integration](/integrations/slack).
* **Analytics tools** – Send proceeds and lifecycle events into [Mixpanel](/integrations/mixpanel) or other analytics tooling to correlate subscription momentum with product usage.
## SDK
Superwall's SDK tracks subscription status automatically based on your dashboard setup, so adding new products or entitlements does not require code changes. For platform-specific details, start with [Tracking Subscription State](/docs/sdk/quickstart/tracking-subscription-state).
---
# Charts
Source: https://superwall.com/docs/dashboard/charts
View charts detailing important metrics about your app's subscription performance, paywalls and more.
To view charts breaking down your app's performance, click the **Charts** button in the **sidebar**:
Check out a video overview of our charts on [YouTube](https://youtu.be/7UIO99LSvTQ).
### Chart types
Choose between different charts by making a selection from the left sidebar:
You can also toggle which charts are showing by using the chevrons on the left-hand side.
Currently, we offer the following charts:
#### Revenue Charts
* **Proceeds:** Revenue after refunds, store fees, and taxes.
* **Sales:** Revenue before refunds, taxes, and fees.
* **Cohorted Proceeds:** Net proceeds cohorted by Install Date, after refunds, taxes, and fees. Usually used in comparison to Ad Spend. Only includes revenue generated by Superwall.
* **ARR:** Normalized revenue from subscriptions to an annual period until their expiration. Doesn't factor in auto renew status.
* **MRR:** Normalized revenue from subscriptions to a monthly period until their expiration. Doesn't factor in auto renew status.
* **ARPU:** Average revenue per user, cohorted by install date.
* **Realized LTV:** Realized fifetime value, cohorted by install date.
#### Subscription Charts
* **Active Subscriptions:** Count of unexpired, paid subscriptions. Doesn't factor in auto renew status. Shows how many users have access to your product at a point in time.
* **Paid Conversion:** Percent of installs who became paying users.
* **New Trials:** Trial starts, cohorted by trial start date.
* **Trial Conversion:** Percentage of trials that converted to paid subscriptions.
* **New Subscriptions:** New subscriptions, cohorted by subscription start date.
* **Auto Renew Status:** How much of your MRR is set to renew vs churn.
#### Paywall Charts
* **Initial Conversion:** Percent of new users who converted on a paywall.
* **Paywalled Users:** Count of unique users who opened paywalls.
* **Paywall Rate:** Percent of new users who opened paywalls.
* **Paywall Conversion:** Percent of users who converted on a paywall.
* **Conversions:** Count of paywall conversions (i.e. a completed transaction).
* **Checkout Conversion:** Percentage of users who converted after starting checkout.
#### User Charts
* **New Users:** Count of new users.
* **Active Users:** Count of active users.
#### Refund & Churn Charts
* **Refund Rate:** Ratio of refunds to gross proceeds, cohorted by first purchase date.
### Filtering chart data
To filter data on a chart, **click** the **Filter** button at the top right:
Filter data by choosing a filter type and **clicking** on **+ Add Filter** to apply it. You can add one, or several, filters:
When you're done, **click** on the **Apply** button, and the chart will refresh with the data filtered by your selections:
To remove an individual filter, **click** on the **trash can** icon on the trailing side of it:
To remove an individual component that's part of a filter (i.e. breaking down by "Application" and removing one of the included apps), **click** on the **X** button on its trailing side:
To remove all filters, **click** on the **Clear Filters** button:
### Breaking down chart data
To break down data in a chart, **click** the **Breakdown** toggle at the top right:
The breakdowns available are tailored to the type of chart you have selected. After you apply a selection, the chart will automatically update. At the bottom of the chart, the data displayed will also be updated according to your breakdown selection:
Breaking down a **Proceeds** chart by **Placements** is a powerful way to directly correlate features you make (or similar things you've paywalled) to your app's revenue growth.
### Selecting time ranges
To customize the time span and level of detail of the data displayed on the chart, use the two date toggles at the top right:
These controls adjust the chart's view interval and data range:
**Display Interval (First Dropdown):** Sets the interval at which data is displayed on the chart. Choose options like Hourly, Daily, Weekly, etc., to adjust how granular the data appears. Selecting "Auto" automatically optimizes the interval based on the selected date range.
**Data Fetch Range (Second Dropdown):** Defines the total date range from which data is fetched and displayed on the chart. Options include Yesterday, Last 7 Days, Last 30 Days, and more. The selected range determines the period of data used to populate the chart, regardless of the display interval setting.
You can also use natural language to set a data fetch range. For example, "last month", "two weeks ago", etc.
### Changing chart formats
Each chart type can display its data in different chart formats. To change the default display, **click** on the **Chart** button found at the top right:
You can toggle the chart format between **Stacked Area**, **Line**, **Stacked Bar**, or **Bar**. Here is the same chart data in each format:
Additionally, you can hover any chart element to see more details about the data point:
### Exporting chart data
You can export any chart data as a `.csv` file. Just **click** the **Export** button at the bottom-right of any chart:
---
# Paywalls
Source: https://superwall.com/docs/dashboard/paywalls
Create or edit paywalls across all of your campaigns in one place.
View the **Paywalls** section from the **sidebar** to view all of the paywalls you've created for the selected app, along with critical metrics:
Below each paywall, you can also **Preview**, **Duplicate** or **Archive** it.
Archived paywalls can be restored at any point.
Looking for a beginner walkthrough of the paywall editor? Check out this video:
### Viewing paywalls by date
You can toggle which paywalls are showing by using the **date toggle**, located above your paywalls towards the top-right:
Choose **Custom** to select any arbitrary date range to filter by.
The date toggle works when you are viewing your paywalls as a
[**list**](#viewing-paywall-metrics).
### Viewing paywalls by status
To view a paywall by its status, click any of the options above the paywalls:
Here's what each status means:
Each paywall displayed corresponds to the currently selected app, located at the top-left of the
page.
| Property | Description |
| -------- | --------------------------------------------------------------------------------------------------------------------------- |
| All | Displays every paywall created, regardless of its status. |
| Active | Paywalls that are currently being displayed and are live. |
| Inactive | Paywalls which are not being displayed. They are not associated with any active campaign, or their rollout percentage is 0. |
| Archived | Paywalls that have been archived. These can be restored if needed. |
| Search | Perform a search across all of the app's paywalls, regardless of its status. |
### Viewing paywalls as a table or list
To toggle between viewing your paywalls by either a table or list, click the toggle buttons at the top:
When viewing them as a **list**, Superwall also displays additional metrics.
### Viewing paywall metrics
Choose the **list** view to see high-level metrics about each paywall:
Each metric displays the data in the time frame that's selected from the date toggle. Here's what each metric represents:
| Property | Description |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| Status | The current status of the paywall (i.e. active, archived, etc). |
| Products | All of the products in use on the paywall. |
| Time Spent | How much time the paywall has spent being presented. |
| Inst Churn | Represents the percentage of users who closed the app while a paywall was presented, and the paywall was not manually closed prior. |
| Opens/User | The percentage per user of how many times the paywall was presented. |
| Opens | The total number of paywall opens. |
| Users | The total number of users who've interacted with the paywall. |
| Conversions | The total number of conversions for the paywall. |
| Conv Rate | The conversion rate of the paywall. |
| Updated | The date when the paywall was last updated. |
| Created | The date when the paywall was initially created or copied. |
Click on any of these values at the top of the list to order the data by that metric, either
ascending or descending.
### Creating a new paywall
To create a new paywall, click **+ New Paywall** at the top-right. For more on creating paywalls, check out this [doc](/paywall-editor-overview#using-the-editor).
---
# Surveys
Source: https://superwall.com/docs/dashboard/surveys
Adding a paywall exit or post-purchase survey is a great way to boost conversion and get feedback on why users declined or purchased from your paywall. Once you've configured a survey, it can be attached to multiple paywalls. A user will only ever see a specific survey once unless you reset its responses.
To attach a survey to a paywall, edit one or manage existing surveys, **click** the **Survey** button found on the sidebar:
Once selected, you'll see an overview of all of the surveys you've created:
There are two types of surveys you can present:
* **Close Survey:** When a user declines to transact with a paywall or closes it.
* **Post-Purchase Survey:** When a user successfully transacts with a paywall.
No matter the type, each one is bound to present within the presentation percentages you set for it (more on that below).
Our surveys present using the native controls for the given platform (i.e. on iOS, a
`UIActionSheet`).
### Creating a new survey or editing existing ones
To create a new survey, click the **+ New Survey** button:
If you already have existing surveys, **click** the **+ Add Survey** button located at the top-right to make another one.
The survey editor will appear, and here you can edit all of the data for existing ones, or change the default options for a new one:
Superwall will provide sensible defaults for a new survey. If you're not quite sure what kind of
questions to ask, the default options are a great place to start and will yield insightful data.
All of the edits you make will be reflected in the preview on the right-hand side.
**Title**
The title of the survey, which will appear at the top.
**Message**
The message displays below the title, and you can use it to provide more context about the survey.
**Response options**
Each option you add here will be a response the user can choose. You'll see data about which one was selected once the survey is live. You can remove an option by using the trash icon on the right side of the text field. To add another option, **click** the **Add Option** button at the bottom of the existing options.
All survey options are shuffled for each user. This helps combat any ordering bias. However, the
"Other" button will always appear last.
**Using the "Other" button**
The "Other" button lets users type in a free text field. This is useful if users are willing to provide more context about why they declined (or purchased from) the paywall. If this is used, it will always display as the *last* option in the survey.
**Using the "Close" button**
You can also provide a "Close" button. Here, the user can exit the survey without providing a response. If you omit it, the user can only dismiss the survey by choosing a response.
**Toggling presentation percentages**
Use the percentage field to control how many users should receive the survey, from 0%-100%.
When you're done editing your survey, **click** the **Save** button at the top-right:
### Attach a survey to a paywall
Creating a survey *does not* mean it will start appearing. Instead, you choose which paywalls should present the survey. To attach a survey to a paywall, **click** the **Connect Paywall +** button in the bottom right of the survey editor:
Then, in the modal that's presented, select the paywall you wish to attach it to:
After you've selected a paywall, **click** the **Connect** button and you're all set. From there, each user will only see the survey **once** per paywall.
You can also attach surveys from the paywall editor itself. This is also where you specify whether
you want a close or post-purchase survey. Read how in this [doc](/paywall-editor-surveys).
### Managing surveys
**Deleting surveys**
To delete a survey, **click** the **Survey** button on the sidebar. Then, for the survey you wish to delete, click the **trashcan** icon:
**Duplicating surveys**
To duplicate a survey, **click** the **Duplicate** button at the top-right when inside the survey editor:
### Viewing survey stats and results
To see the results for any survey, click on one and then **click**
the **Stats** button at the top-right:
From there, you'll see the survey responses:
**Viewing "Other" responses**
If you've included the "Other" button in your survey, you can view the responses from users by **clicking** the **"View "Other" Responses"** button:
**Resetting survey stats**
Finally, if you wish to reset the survey results, **click** the **Reset Responses** button underneath the results:
Keep in mind that when you reset survey data, it also means that it will present to everyone once
again (within your presentation percentages).
### Tip: showing a paywall based off of a survey response
One particularly useful technique to use with surveys is to show a paywall with a discounted price if the user indicated the pricing was too expensive in their response. You can easily do this using a [standard placement](/campaigns-standard-placements) — and we have a step-by-step guide on how to do exactly this right [here](/campaigns-standard-placements#using-the-survey-response-event).
---
# Templates
Source: https://superwall.com/docs/dashboard/templates
Use our template library to jump-start your paywall design process. Either plug in your products, switch them up to fit your needs, or remix them altogether.
Click **Templates** from the **sidebar** to start your paywall design process with one of our templates:
We hand-select the paywalls these templates are based on, and each one is from a high-performing segment on the App Store or Google Play Store. We recommend picking one that matches your design goals the best, and then tweaking them to fit your branding and needs from there.
Each template can be easily changed to support as many products as you need.
### Requesting a template
Superwall offers a complimentary white glove paywall design service for all users. Supply Superwall with either an existing paywall in production, a Figma link, Sketch file or anything else for Superwall's designers to use as a reference.
To get started, simply click **Request a Template** at the top, and fill out the form:
Turnaround is typically about 3-4 business days, but can also be up to a week depending on demand. Rest assured that Superwall's designers take the time to get these done right.
### Sorting paywall templates
To sort available templates by date (either newest to oldest, or vice-versa) or by recently updated — **click** the toggle in the top right and make a selection:
Superwall frequently updates existing templates, as well as adding new ones. Check back often!
---
# Welcome
Source: https://superwall.com/docs/dashboard
Welcome to the Superwall Dashboard documentation
Get up and running with the Superwall Dashboard
Learn to use the Paywall Editor
Learn to setup and use Campaigns
Integrate Web Checkout with your app
Documentation for the Superwall SDK
## Feedback
We are always improving our documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
---
# Using the Presentation Handler
Source: https://superwall.com/docs/using-the-presentation-handler
When and how to use per-presentation handlers for paywalls, and how they differ from global delegates.
Use a presentation handler when you need fine‑grained callbacks for a single paywall presentation. For global events across your app, use the platform’s delegate instead.
* iOS: see [`PaywallPresentationHandler`](/ios/sdk-reference/PaywallPresentationHandler) and [`SuperwallDelegate`](/ios/sdk-reference/SuperwallDelegate)
* Flutter: see [`PaywallPresentationHandler`](/flutter/sdk-reference/PaywallPresentationHandler) and [`SuperwallDelegate`](/flutter/sdk-reference/SuperwallDelegate)
Typical use cases:
* Show custom loading/placeholder UI while a specific paywall is presented
* Gate navigation based on that presentation’s result only
* Capture metrics tied to one presentation without implementing a global delegate
For end‑to‑end presenting patterns (registering or retrieving a paywall yourself), see:
* iOS: [`Presenting paywalls`](/ios/guides/advanced/presenting-paywalls)
* Android: [`Presenting paywalls`](/android/guides/advanced/presenting-paywalls)
* Flutter: [`Presenting paywalls`](/flutter/guides/advanced/presenting-paywalls)
* Expo: [`Presenting paywalls`](/expo/guides/advanced/presenting-paywalls)
---
# Stripe Setup
Source: https://superwall.com/docs/web-checkout/web-checkout-configuring-stripe-keys-and-settings
Connect Superwall to Stripe using the official Stripe app and configure your settings.
Once you've created a [Stripe app](/web-checkout-creating-an-app), you'll need to connect it with Stripe and fill in a few settings. This is a one-time setup that connects Superwall to Stripe. The easiest way to get started is to click on the link in your overview page, which will take you to your app's [Settings](/overview-settings) page:
### Application settings
Fill out metadata about your iOS app in this section.
1. **Icon:** An icon to represent your app, we recommend using the same one that your iOS app does. This will appear on the checkout and subscription management pages.
2. **Application Name:** The name of your app, we recommend using the same name as your iOS app.
3. **Support URL:** A URL to your support page. This will be shown on the checkout and subscription management pages.
4. **Support Email:** An email you provide customers for support questions and general reach out
5. **Redeemable on Desktop:** If your app is an iPad app on Mac, enable this option so that users can redeem products on their Mac. If you aren't using iPads Apps on the Mac, you can disable this. If this is disabled, Superwall enforces redemption on an iOS device.
Once you've filled out this information, **click** on the **Update Application** button.
### Post-Purchase Behavior
Configure what happens after a user completes a purchase on the web:
**Redeem (Default)**: Superwall manages the entire redemption flow. Users are automatically deep linked to your app with a redemption code, with fallback to the App Store/Play Store if the app isn't installed. This is recommended for most apps.
**Redirect**: Redirect users to your own custom URL with purchase information passed as query parameters. Use this when you need to:
* Show a custom success or onboarding page
* Perform additional verification or actions before redemption
* Integrate with your own deep linking infrastructure
When using Redirect mode, you'll need to provide a **Redirect URL** (must start with `https://`). Purchase data will be appended as query parameters:
* `app_user_id` - User's app identifier
* `email` - User's email address
* `stripe_subscription_id` - Stripe subscription ID
* Any custom placement parameters you've set
Learn more about [post-checkout redirecting](/sdk/guides/web-checkout/post-checkout-redirecting).
### Web Paywall Domain
This is the domain your paywalls will be shown from. This was set when the Stripe app was created, and cannot be changed.
### Stripe Live Configuration
To connect Stripe with Superwall, you'll use the official Superwall Stripe app:
#### Step 1: Visit the Stripe Marketplace
Visit the [Superwall app on Stripe Marketplace](https://marketplace.stripe.com/apps/superwall):
#### Step 2: Install the App
Click **Install app** to begin the authorization flow:
#### Step 3: Continue Installation
Click **Continue** to proceed with the installation:
#### Step 4: Generate API Keys
Click **Generate keys** to create your API keys:
#### Step 5: Confirm Key Generation
Click **Generate keys** again to confirm:
#### Step 6: Copy Your Keys
After installation, you'll receive a **Publishable Key** and a **Restricted Secret Key** with the proper permissions already configured. Copy both keys:
#### Step 7: Configure Superwall
Paste the keys into the corresponding fields in Superwall:
* **Publishable Key**: Your Stripe publishable key from the app
* **Secret Key**: The restricted secret key provided by the app
Then **click** on **Update Configuration** to save your changes.
This section should say "Configured" at the top right if setup was successful:
### Stripe Sandbox Configuration
The Superwall Stripe app provides both live and test mode keys. Make sure you're in the correct mode in your Stripe dashboard when copying keys.
For sandbox/test mode, switch to **Test mode** in your Stripe dashboard (toggle in the top-right corner), then follow these steps:
#### Step 1: Access the Superwall App
Navigate to the Superwall app in your Stripe dashboard. If already installed, find it under **Apps**:
#### Step 2: Install in Test Mode
If you haven't installed the app in test mode yet, click **Install app**:
#### Step 3: Continue Installation
Click **Continue** to proceed:
#### Step 4: Reveal Your API Keys
Click **Reveal test key** to view your test mode API keys:
#### Step 5: Copy Your Test Keys
Copy both the **Publishable Key** and **Secret Key**:
#### Step 6: Configure Superwall
Paste both keys into the Sandbox Configuration fields in Superwall, then **click** on the **Update Configuration** button.
This section should say "Configured" at the top right if setup was successful.
### iOS configuration
Superwall uses the details here to handle deep links back to your app after a purchase occurs. **All of this information is required.**
1. **Apple Custom URL Scheme:** Add your app's custom URL scheme. If you haven't set on up, read [here for instructions](/in-app-paywall-previews).
2. **Apple App ID:** Your iOS app's ID. If you're unsure of your app's ID, you find it in **[App Store Connect](https://appstoreconnect.apple.com) -> Select your App -> General -> App Information -> Apple ID**:
3. **Bundle ID:** Your iOS app's bundle ID. You can find this in Xcode -> Targets -> General -> Identity -> Bundle Identifier.
4. **Team ID:** The team ID that your iOS app belongs to. To find this, visit **[Apple Developer](https://developer.apple.com) -> Account -> Membership details -> Team ID**. It's obscured here, but it'll be where the arrow points in the image below:
### Confirm setup
Once you've filled out all of these fields, you should see **Configured** for each section:
Next, you'll need to create some products in Stripe.
---
# App2Web
Source: https://superwall.com/docs/web-checkout/web-checkout-direct-stripe-checkout
Offer Stripe products directly from your iOS paywalls and perform checkout flows.
For customers in the United States, you can offer Stripe products directly from your iOS paywalls. This is a great way to streamline the checkout process and make it easier for users to purchase your products.
First, follow the [web checkout setup guide](/web-checkout-overview#getting-setup) to create a Stripe app and configure your web checkout settings. Specifically, you'll need to complete the first three steps. This includes installing the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) and setting up your app's settings.
Select a paywall and add a Stripe product to it. This will allow users to purchase the product directly from the paywall. Stripe products are prepended with "stripe" in the product selector:
You can control whether or not Stripe checkout opens in your app via Safari, or externally in the Safari app:
Since the ruling only applies to customers in the United States, you can easily create a campaign filter that will match to those customers. Just create a filter where `storeFrontCountryCode` matches `USA`, like this:
From there, the flow works the same way as it would for web checkout. Once the payment succeeds, the [Superwall delegate](/using-the-superwall-delegate) functions `willRedeemLink()` and `didRedeemLink(result:)` will be called. You can use these functions to handle the deep link in your app if you need to show any specific UI as described in our [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting) docs.
Additionally, the subscription status will be updated automatically and the delegate callback `func subscriptionStatusDidChange(from oldValue: SubscriptionStatus, to newValue: SubscriptionStatus)` will be called. If you're using a `PurchaseController`, refer to [the docs here](/web-checkout-linking-membership-to-iOS-app#using-a-purchasecontroller).
If you need to test checkout, learn how [here](/web-checkout-testing-purchases).
### Prefill customer information
When starting checkout from an iOS paywall (App2Web), you can prefill customer information in two ways:
#### Email
Stripe will automatically prefill the email field if you set the user's `email` as a [User Attribute](/sdk/quickstart/setting-user-properties) in your app before initiating checkout.
#### Stripe Customer ID
If you already have a Stripe customer ID for your user, you can set it as the `stripe_customer_id` user attribute. This will associate the checkout session with the existing Stripe customer, automatically prefilling their saved information and payment methods:
```swift
Superwall.shared.setUserAttributes([
"email": user.email,
"stripe_customer_id": user.stripeCustomerId
])
```
When both `stripe_customer_id` and `email` are provided, the Stripe customer ID takes precedence. The checkout session will use the existing customer's information rather than creating a new customer.
---
# Web Checkout Links
Source: https://superwall.com/docs/web-checkout/web-checkout-creating-campaigns-to-show-paywalls
Learn how to use campaigns and placements to present web paywalls using Superwall's web checkout links.
Once you've [created a Stripe app](/web-checkout-creating-an-app), [configured Stripe with Superwall](web-checkout-configuring-stripe-keys-and-settings) via the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) and have [created Stripe products](web-checkout-adding-a-stripe-product) — you're ready to configure a campaign to show a web paywall.
Before you proceed, recall that web checkout has all of the advantages of the Superwall platform. If you are unfamiliar with how to create campaigns or what a placement is — we recommend you read through the [introduction](/home) documentation and [campaigns doc](/campaigns) first.
### Understanding placements in web checkout
There are two primary differences between web checkout and the typical Superwall campaign flow:
1. **Placements become unique URLs** which, in turn, show your paywall. These are called *web checkout links*.
2. **User variables** are not available in audience filtering.
Other than that, everything operates as a normal Superwall campaign would. For example:
Here, the placement `black-friday-promo` presents a paywall. If the app's URL in [settings](/web-checkout-configuring-stripe-keys-and-settings) is `caffeinepal`, then the URL for this placement would be `https://caffeinepal.superwall.app/black-friday-promo`. Visiting that web checkout link presents a paywall:
Conceptually, you can think of these web checkout links performing a similar function as registering a placement does in our mobile SDK:
```swift
Superwall.shared.register(placement:"black-friday-promo") { _ in }
```
This means that you now can use web checkout with all of the same powerful features that Superwall offers, such as A/B testing, paywall targeting and more. Again, these work just like any other campaign would in Superwall. The interface is the same, so now you create placements, start creating audience filters and more:
Also, remember to create responsive paywalls. Users can view your checkout page on a laptop, phone and other varying sized viewports. For some quick tips, check out this blog post over adapting paywalls to look great on [iPad](https://superwall.com/blog/how-to-create-adaptable-paywalls-for-iphone-and-ipad-using-superwall).
### A note on the `$home` placement
Every campaign has a `$home` placement out of the box. This placement acts a "default" link, and isn't required to be part of the URL as other placements are. For example:
```plaintext
// This works
https://caffeinepal.superwall.app/$home
// And this also works, even though `$home` isn't in the URL
https://caffeinepal.superwall.app/
```
This is useful so that even if a user visits your web checkout link, and there isn't a placement in the URL — they'll still see a paywall.
### How query string parameters work
You can attach query string parameters to any web checkout link by appending them to the URL:
```html
https://caffeinepal.superwall.app/black-friday-promo?name=jordan
```
This will pass the `name` parameter to the placement, and you can use it in your audience filters. For example, you could create a filter that only shows the paywall if the `name` parameter is equal to `jordan`:
Or, you could access them in your paywall using the same flow as you would for [placement parameters](/sdk/guides/advanced/using-placement-parameters):
1. In the paywall editor, add a variable.
2. Make it a `parameter` type. Match the `name` to the query string parameter key (here, that would be `name`).
3. Set the value type, then click **Create**.
4. Now, you can use that variable in your paywall:
This makes it easy to show in your paywall:
Then, if the URL is visited, the audience filter matches from above — and we can see the value on the paywall, too:
Of course, this is a simplistic example — but this is useful for personalization, seasonal events, influencer campaigns and more. Any query string parameter you pass can be used in the paywall, and in audience filters.
### Automatically populating user emails in checkout flows
This section is Web2App only (starting from a web link). For App2Web (starting from an iOS paywall), see [App2Web](/web-checkout-direct-stripe-checkout#prefill-email).
There is a special query string parameter you can use to automatically populate the user's email in the checkout flow. This is useful for pre-filling the email field in the checkout form, so that users don't have to enter it manually. Simply add `email` and set the value to the user's email address:
```html
https://caffeinepal.superwall.app/black-friday-promo?email=myemail@yahoo.com
```
When the Stripe checkout flow launches, the email is now filled out automatically:
### Automatically populating appUserId in checkout flows
There is a set of special query string parameters which will set the appUserId for the subscription. This overrides the default behavior where Superwall will automatically assign an anonymous identifier. You may pass `uid`, `user`, or `app_user_id` to override the default.
```html
https://caffeinepal.superwall.app/black-friday-promo?app_user_id=my-custom-id
```
This identifier will show up in Stripe metadata & webhooks. The app\_user\_id will be put into the `client_reference_id` field on a Stripe Checkout Session and will be included on the subscription metadata under `_sw_app_user_id`
---
# Creating Products
Source: https://superwall.com/docs/web-checkout/web-checkout-adding-a-stripe-product
Create products in Stripe to show on your web paywalls.
### Adding products
Once your app is configured with Stripe, you can create products to show on your web paywalls. To get started, **click** on **Products** from the overview page:
Complete your Stripe setup first by following the steps in [Configuring Stripe Keys and Settings](/web-checkout/web-checkout-configuring-stripe-keys-and-settings).
Next, **click** on the **+ Import Products** button in the top right corner:
You'll be given a choice to add either a:
1. **Live Product:** These are for production purchases and flows.
2. **Sandbox Product:** These are for testing purchases and flows.
Superwall supports both sandbox and live products. To learn more about their differences, here's a
good overview from [Stripe's documentation](https://docs.stripe.com/test-mode).
### Using Stripe products
If you've already created products in Stripe, you can import them into Superwall now. All you need to do is select the "Product" and the rest of the fields should automatically populate with its data when you select them. You will need to choose which entitlement or entitlements a product should grant a user access to:
Once you're done **click** on the **Save** button and your product is ready to be used in a paywall.
### Creating new products in Stripe
To create new products, **click** on the **Create Product in Stripe** link:
{" "}
From there, fill in all of the fields presented to you in Stripe:
1. **Name:** The product name, i.e. "Pro", "Premium", etc.
2. **Description:** A description of the product, this will show up in checkout.
3. **Image:** An image representing the product, this will show up in checkout. Optional.
4. **Product tax code:** The tax code classification for the product. Refer to your territories tax codes for more information.
5. **Recurring vs One-off:** For subscriptions, choose "Recurring", whereas one time purchases or consumables should be "one-off" products.
6. **Amount:** The price of your product, and what it will renew at if it's recurring.
7. **Billing period:** The billing period for the product, i.e. "Monthly", "Yearly", etc.
Once you've finished filling out pricing details, product name and all other metadata, **click** on the **Add product** button at the bottom right of the form. You should be redirected to your Stripe products page:
Now, when you return to Superwall, select your product from the **Products** drop down, and when you select the other fields, Superwall will pull in the data for you (aside from trials, which you choose when adding a Stripe product). Here, the new "Scores Annual" product created in Stripe shows up in the products menu now:
Be sure to associate the correct entitlement to the product as well.
### Adding products to paywalls
Adding Stripe products to web paywalls works the exact same way as it does for mobile paywalls. Check out the docs [here](/paywall-editor-products). For a quick overview:
1. Open the paywall editor.
2. On the left sidebar click on **Products**.
3. Choose the products to add, as in the image below:
Keep in mind that to test products, it's as simple as adding a test product to a paywall and performing the checkout flow. For more information, please refer to [Testing purchases](/web-checkout/web-checkout-testing-purchases).
### Sandbox products
Sandbox products are used to test purchases. When you create one, you can add it to any web paywall to test check out flows. You create sandbox products the same you create other products, just choose "Sandbox Product" when creating a product. You'll see a sandbox banner at the top of Stripe when you create these types of products:
Once you've created a sandbox product in Stripe, import them to Superwall the same way as you would a normal product, and then they are ready for use in a paywall. Within the products page, Superwall will show which environment each product belongs to:
When testing with sandbox products, you can see their details in the Overview page. **For this to work, all products on a paywall must be test products.** Put differently, the sandbox metrics won't show here if you mixed and matched live and sandbox products on the same paywall when testing:
### Free trials
Trials are controlled by Superwall, they are not set up in Stripe. When you go to add a product, you choose the terms. You can also reuse the same product ID multiple times to create different trial lengths. This is a powerful capability, as it avoids the need to create a similar product over and over just to offer different trial terms. For example, you can use the same product ID with a one week trial, no trial, 3 day trial, and any other terms you need — these will all be represented as individual products you can add to paywalls.
---
# Creating an App
Source: https://superwall.com/docs/web-checkout/web-checkout-creating-an-app
Add a Stripe app to an existing project within Superwall.
### Adding a Stripe app to Superwall
Web checkout is represented in Superwall as a Stripe app. To create one, open any existing project and click on the Stripe logo at the top left:
Right now, web checkout is only available for iOS apps. Android support is coming soon.
You'll be presented with three fields to fill out:
1. **Platform:** This will default to Stripe — leave this unchanged.
2. **App Name:** Shown at checkout, we recommend using the same name as your app.
3. **Domain:** The URL your paywall will be shown from, and `superwall.app` will be appended to it. You cannot edit this once your app is created.
Once you've filled these out, **click** on **Add App ->**. You'll automatically be taken to your app's [overview](/overview-metrics) page. Next, it's time to [configure your app with Stripe](/web-checkout-configuring-stripe-keys-and-settings).
---
# Web-Only Checkout
Source: https://superwall.com/docs/web-checkout/web-checkout-web-only
Use web checkout without a mobile app for web apps, websites, or any non-App-Store product.
You can use Superwall's [web checkout links](/docs/web-checkout/web-checkout-creating-campaigns-to-show-paywalls) without an iOS or Android app. It's suitable for things like a web app, SaaS products, or any scenario where you want to handle the post-purchase flow yourself.
All that's required is creating a web app in Superwall. Then, for its post-purchase behavior use **Redirect mode** instead of *Redeem* mode:
After a user completes checkout from a paywall, they get redirected to your URL with purchase data as query parameters:
For example, if your redirect URL is `https://amazingwebproduct.com/welcome`, then after a successful purchase the redirect URL would be the following:
```javascript
https://amazingwebproduct.com/welcome?
app_user_id=user_123&
email=user@example.com&
stripe_subscription_id=sub_1234567890
```
## Setup
### 1. Create a Superwall Web App
Create a new app in Superwall for your web product in a new or existing project. Follow the steps in [Creating an App](/web-checkout-creating-an-app).
### 2. Configure Your Payment Provider
Set up Stripe by following the [Stripe Setup](/web-checkout-configuring-stripe-keys-and-settings) guide.
You can skip any iOS/Android related configuration sections since you won't be using a mobile app.
### 3. Enable Redirect Mode
In your app's settings under **Post-Purchase Behavior**, select **Redirect** and enter your custom URL.
Your URL will receive the following query parameters after checkout:
| Parameter | Description |
| ------------------------ | -------------------------------------- |
| `app_user_id` | The user's identifier (if you set one) |
| `email` | User's email from checkout |
| `stripe_subscription_id` | The Stripe subscription ID |
| Custom parameters | Any placement parameters you set |
**Example redirect:**
```javascript
https://amazingwebproduct.com/welcome?
app_user_id=user_123&
email=user@example.com&
stripe_subscription_id=sub_1234567890
```
### 4. Handle the Redirect
When users land on your redirect URL, use the query parameters to:
* Verify the purchase with your backend.
* Create or update the user's account.
* Grant access to your product.
* Show a success or onboarding page.
## What's Next
* [Creating Products](/web-checkout-adding-a-stripe-product) to add products to your checkout.
* [Creating Campaigns](/web-checkout-creating-campaigns-to-show-paywalls) to show paywalls via web checkout links. Remember, you use these URLs in any way you wish, but the checkout link itself is derived from two things:
1. The web paywall domain you created for the web app (found in Settings -> General).
2. And, the placement which is housed in a campaign.
---
# Web Checkout FAQ
Source: https://superwall.com/docs/web-checkout/web-checkout-faq
Frequently asked questions about web checkout.
### How does restoring memberships work on iOS when you've purchased via web checkout?
When the user taps on the restore link in the paywall, we'll do the normal restore flow for on-device subscriptions. However, if you've enabled web checkout and the restored
entitlements don't match the entitlements belonging to the products on the paywall, we'll present an alert asking the user if they'd like to check for subscriptions on the web. This will
take them out of your app to the [plan management screen](/web-checkout-managing-memberships) where they can get a redemption link to restore their subscriptions.
### Does Superwall email customers after checkout?
Yes. By default, Superwall emails the address used during checkout with instructions and a redemption link to activate the subscription in your iOS app. The email is sent from `Your app name ` with the subject `Your activation link from your app name`.
To turn these off, use the "Disable Superwall Emails" setting in your Stripe app settings — see [how to disable the activation link email](/support/web-checkout/3969573187-how-do-i-disable-the-activation-link-email-for-web-checkout).
### What happens if a user taps the redemption link multiple times or shares it?
Redemption codes are single-use and tied to a specific device. Once a code has been redeemed, it cannot be used again on a different device.
However, users can visit the manage page and request a new redemption link. This generates a new code that can be used to activate access on another device.
#### Without accounts (`identify` not called)
If you're not using accounts with Superwall (i.e. you never call `identify`), we allow up to **five active devices** per user. When a sixth device redeems a code, the **first device** to have redeemed a code will automatically lose access. This helps prevent abuse while still supporting reasonable multi-device usage.
#### With accounts (`identify` called)
If you are using accounts with Superwall (i.e. you call `identify` with an `appUserId` when someone logs in), then entitlements are tied to the user ID, not the individual device.
* If two different `appUserIds` redeem codes, **only the most recently identified user will retain access**.
* If the **same `appUserId` is used across multiple devices**, all those devices will **automatically share access** without needing to redeem again.
This system ensures flexibility while protecting against unauthorized sharing of redemption codes.
### How do I associate a web checkout purchase with a user in my app?
The short answer — use Superwall's [user identification APIs](/identity-management#identified-users). When you configure Superwall, or a user signs in or out, you can always associate their login status to Superwall's SDK:
```swift
Superwall.shared.identify(userId: user.id)
```
This will ensure that the user is associated with the web checkout purchase.
### A user paid on the web and can't access their subscription in the app. What should I do?
Direct them to your app's plan management page so they can retrieve their redemption link or manage billing. For example: `http://yourapp.superwall.app/manage`
### When should I use Redirect mode instead of Redeem mode?
Use **Redirect mode** when you need to:
* Show a custom success or onboarding page after purchase
* Perform additional verification or collect more information before granting access
* Integrate with your own deep linking or authentication infrastructure
* Track conversions in your own analytics before redemption
Use **Redeem mode** (the default) when:
* You want Superwall to handle the entire redemption flow automatically
* You don't need custom post-purchase logic
* You want the simplest integration
Most apps should use Redeem mode. You can always switch between modes in your [Application Settings](/web-checkout-configuring-stripe-keys-and-settings#post-purchase-behavior).
### What data is passed to my redirect URL in Redirect mode?
When using Redirect mode, the following query parameters are automatically appended to your custom URL:
**Standard parameters**:
* `app_user_id` - The user's identifier from your app (if you called `identify`)
* `email` - The user's email address from checkout
* `stripe_subscription_id` - The Stripe subscription ID
**Custom parameters**: Any placement parameters you set when creating the web checkout link will also be included.
**Example redirect**:
```
https://yourapp.com/success?
app_user_id=user_123&
email=user@example.com&
stripe_subscription_id=sub_1234567890&
campaign_id=summer_sale
```
You can use this data to verify the purchase, link it to your user account, or perform custom onboarding. Learn more about [post-checkout redirecting](/sdk/guides/web-checkout/post-checkout-redirecting).
---
# Overview
Source: https://superwall.com/docs/web-checkout/web-checkout-overview
Let customers purchase products online via Stripe, then link them to your iOS app with one seamless flow. No authentication required.
Superwall's web checkout integration makes it easy to set up purchasing funnels for your app via the web. Web checkout is powered by Stripe. Once an online purchase is complete, the customer will be redirected back to your app with a deep link that can be used to unlock content or features in your app via any associated [entitlement](/products#entitlements).
Web checkout requires the Superwall iOS SDK 4.2.0 or later.
Visual learner? Go watch our web checkout tour over on YouTube
[here](https://youtu.be/eUSIySsN1ZU).
## How it works
Superwall presents paywalls via the concept of [campaigns](/campaigns), and each campaign has one or more [placements](/campaigns-placements). A paywall is shown in a campaign when a placement is triggered after your [audience filters](/campaigns-audience) are evaluated. This setup is Superwall's foundation, and the web checkout flow works the exact same way.
The core difference? Each placement becomes a unique URL that you can share, send or email to present a user with a paywall that leads to a Stripe checkout flow. And just like with Superwall on apps, you can create experiments, try out different paywalls, run price tests and more.
## Overall flow
Refer to the individual pages below to get started, but for a quick, high-level overview — here's how web checkout works from beginning to end:
1. A Web Checkout app is added to an existing iOS project in Superwall.
2. Your checkout provider is configured with Superwall.
3. iOS app details and post-purchase behavior are configured in the provider's settings page (within Superwall).
4. Products are created *in* your payment provider, and imported into Superwall.
5. Within a campaign (a default one is provided), you attach those products to a paywall.
6. A user visits a placement URL, and performs the checkout flow.
7. After a successful purchase, the user is redirected based on your [post-purchase behavior setting](/web-checkout-configuring-stripe-keys-and-settings#post-purchase-behavior):
* **Redeem mode** (default): User is directed to download the app and click the redemption link
* **Redirect mode**: User is redirected to your custom URL with purchase data
8. For Redeem mode: *On the device that they downloaded the app*, they click the redemption link.
9. Your iOS app is opened via a deep link (which means it must be set up with Superwall deep links, [docs here](/in-app-paywall-previews)).
10. In the `SuperwallDelegate`, `willRedeemLink()` is called, and then once it's fetched — `didRedeemLink(result:)` is called with the result of the redemption.
11. Finally, this user's account and details are managed via a link they find in their [email receipt or by visiting a URL manually](/web-checkout-managing-memberships).
## Getting setup
Before you start, you'll need to have a Superwall account and a Stripe account. You can create a Stripe account [here](https://dashboard.stripe.com/register).
1. **[Creating an app](/web-checkout-creating-an-app):** First, you'll add a Web Checkout app to an existing project within Superwall.
2. **[Stripe setup](/web-checkout-configuring-stripe-keys-and-settings):** Install the [Superwall Stripe app](https://marketplace.stripe.com/apps/superwall) for automatic configuration.
3. **[Managing products](/web-checkout-adding-a-stripe-product):** Create or import products to add to your web paywalls.
### Creating paywalls and campaigns
4. **[Presenting paywalls](/web-checkout-creating-campaigns-to-show-paywalls):** Set up a campaign, create some placements and add paywalls to begin showing them to customers.
### Associating entitlements to your iOS apps
5. **[Linking purchases to your iOS app](/web-checkout-linking-membership-to-iOS-app):** Once a purchase occurs, the user will be prompted to download your app and click on a redemption link.
6. **[Managing memberships](/web-checkout-managing-memberships):** Users can cancel, update or manage their memberships via Stripe.
### Testing purchases
7. **[Testing purchases](/web-checkout-testing-purchases):** Test your web checkout flow with test purchases.
### App to Web
8. **[App to Web Checkout](/web-checkout-direct-stripe-checkout):** For customers in the United States, you can offer Stripe products directly from your iOS paywalls.
## Troubleshooting
If a user has issues accessing their subscription in your app after paying via web checkout, direct them to your plan management page to retrieve their subscription link or manage billing. For example: `http://yourapp.superwall.app/manage`
---
# Restoring & Managing Purchases
Source: https://superwall.com/docs/web-checkout/web-checkout-managing-memberships
Learn how users can manage their subscriptions from purchases made via the web.
When users purchase a subscription via the web, they can can access their account details via a plan management page. This url is included in their receipt which is sent to their email upon a successful purchase. To retrieve the link, users must enter in their email that was used during checkout. Otherwise, to offer this link manually you can use the following URL format:
```plaintext
https://{your URL in settings}.superwall.app/manage
```
By default, after a successful checkout, Superwall emails the address used at checkout with instructions and a redemption link to activate the subscription in your iOS app. The email is sent from `Your app name ` with the subject `Your activation link from your app name`.
If you want to disable these emails, use the "Disable Superwall Emails" setting in your Stripe app settings — see [how to disable the activation link email](/support/web-checkout/3969573187-how-do-i-disable-the-activation-link-email-for-web-checkout).
When this page is visited, users enter in their email that used during checkout to receive a link to manage their subscription:
For the above example, the URL would be `https://caffeinepal.superwall.app/manage`. After entering their email, they will receive a link to manage their subscription, update payment methods, view their billing history, and more:
For situations where a user needs to restore their purchases, check out the answer in this [F.A.Q](/web-checkout-faq).
---
# Sandbox Purchases
Source: https://superwall.com/docs/web-checkout/web-checkout-testing-purchases
Test with your web paywalls by using sandbox products.
### Purchase flow overview
When a user clicks on a button to purchase a product, the process will switch over to Stripe's checkout flow:
Once the purchase goes through successfully, they'll be taken to a page where Superwall prompts them to:
1. Download the app.
2. Click the redemption link.
Users should click the redemption link *on the device where the app is installed*. If the setting for "Redeemable on Desktop" is diabled, they'll be prompted to continue on an iOS device.
From there, the [redemption flow](/web-checkout-linking-membership-to-iOS-app) occurs.
### Testing a purchase
To test a purchase:
1. Add a [sandbox product](/web-checkout-adding-a-stripe-product#creating-sandbox-products-to-test-with) to a paywall.
2. Visit the paywall URL and checkout.
3. Choose "Card" for the payment method.
4. For the card number, use `4242 4242 4242 4242` with any expiration date later than today, any CVC and fill out the name and zip code.
This will allow you to checkout and go through the entire flow to debug issues, test it out on a device and more.
---
# Using New SDK Features
Source: https://superwall.com/docs/getting-started-with-our-sdks
Superwall's recent SDK updates bring several new improvements and features. Here's how to get started quickly.
With our latest iOS SDK (version 4) and updates for Android, Flutter, and React Native (version 2), plus recent product enhancements, Superwall delivers several improvements to the overall experience:
1. **Cross-platform entitlements:** Segment product offerings by tiers of service across your product suite.
2. **Entitlements in campaign filters:** Use powerful new campaign filtering capabilities, such as leveraging entitlements in filters.
3. **New product management:** Easily set up products and associate them to tiers of service using entitlements.
4. **StoreKit 2:** Finally, our iOS SDK uses [StoreKit 2](https://developer.apple.com/storekit/) by default (unless you're using Objective-C).
To see migration information, check out these guides for all of our SDKs:
* [iOS](/migrating-to-v4)
* [Android](/migrating-to-v2-android)
* [React Native](/migrating-to-v2-react-native)
* [Flutter](/migrating-to-v2-flutter)
### Entitlements
Products are now attached to an entitlement. By default, we provide an entitlement out of the box — and products can use one or more of them. If you are not using a [purchase controller](/advanced-configuration) or tiered services, then you don't have to think much about them. From an SDK standpoint, tracking subscription state worked similar to this:
```swift
if Superwall.shared.subscriptionState == .active/inactive {
// Some paid feature
}
```
Whereas now, you still look at `subscriptionStatus`, except it's no longer `.active`. Now, the `.active` case includes the active *entitlements*:
```swift
switch Superwall.shared.subscriptionStatus {
case .active(let entitlements):
print("Active entitlements: \(entitlements)")
case .inactive:
print("Inactive")
case .unknown:
print("Unknown")
}
```
Or, if you only have one entitlement you use to represent "pro" access, you can simplify your check:
```swift
// If you're only using one entitlement...
if Superwall.shared.subscriptionStatus.isActive{
// Has an active entitlement
}
```
Also, common [delegate](/using-superwall-delegate) methods have changed as well. As the migration guides above call out, `event` has been renamed to `placement`, so you'll see that reflected across our product and SDKs.
With entitlements, the paywall editor setting "Present Paywall" is now deprecated. Entitlements
replace them in the audience filter.
### Entitlements in campaign filters
Campaign filters now filter more operators, like `and` and `or`, and they also have access to product entitlements:
Using entitlements in campaign filtering opens up scenarios where you could filter down to tiers of service, such as "Match users who have the Silver entitlement active, but not Platinum.", etc.
### New product management
As mentioned above, products are now associated to an entitlement. When adding products, you can choose one or more entitlements that belong to it. For any previously added products, Superwall associates a default entitlement (`pro`) to them automatically.
For more, check out our docs on [adding products](/products).
### StoreKit 2
Finally, our iOS SDK defaults to using StoreKit 2 in most cases. Refer to the migration guide above for our iOS SDK to learn more. StoreKit 2 support also opened up other enhancements for our SDK. You can now use Superwall to make purchases directly, like this:
```swift
// StoreKit 1 Products
let result = await Superwall.shared.purchase(sk1Product)
// StoreKit 2 Products
let result = await Superwall.shared.purchase(product)
// Superwall's abstraction over products
let result = await Superwall.shared.purchase(storeProduct)
```
The ability to make purchases directly along with [observer mode](/observer-mode) means that you can:
* Have Superwall handle all purchase logic.
* Track your revenue
* And enable metrics, charts and other data
...all for free.
---
# Layout Tab
Source: https://superwall.com/docs/layout-tab
undefined
The legacy editor is deprecated. Please visit the docs covering our new
[editor](/paywall-editor-overview).
If you want to customise the layout of your paywall, you can use the Layout tab:
This allows you to add, delete, move, customize, and duplicate paywall elements. Using this tab, you can build any kind of paywall you want.
---
# Capacitor
Source: https://superwall.com/docs/community/capacitor
Superwall plugin for Capacitor by Capawesome
**Community SDK**
This SDK is developed and maintained by [Capawesome](https://capawesome.io), not by Superwall. For support, please visit the [official documentation](https://capawesome.io/plugins/superwall/).
The [Capacitor Superwall plugin](https://capawesome.io/plugins/superwall/) by [Capawesome](https://capawesome.io) enables you to integrate Superwall into your Capacitor apps for iOS and Android.
## Installation
Install the plugin via npm:
```bash
npm install @capawesome/capacitor-superwall
npx cap sync
```
## Android Setup
Add the following activities to your `AndroidManifest.xml` inside the `` tag:
```xml
```
## Configuration
Initialize the SDK with your API key:
```typescript
import { Superwall } from '@capawesome/capacitor-superwall';
await Superwall.configure({
apiKey: 'YOUR_API_KEY',
options: {
paywalls: {
shouldPreload: true,
automaticallyDismiss: true
},
logging: {
level: 'WARN',
scopes: ['ALL']
}
}
});
```
## Core Methods
| Method | Description |
| ------------------------- | ----------------------------------------- |
| `configure()` | Initialize the SDK with your API key |
| `register()` | Present a paywall for a placement |
| `getPresentationResult()` | Check if a paywall would display |
| `identify()` | Associate a user ID with the current user |
| `reset()` | Clear user identity on logout |
| `setUserAttributes()` | Set custom user attributes |
| `getSubscriptionStatus()` | Get the current subscription status |
## Event Listeners
The plugin supports the following event listeners:
* `superwallEvent` - Analytics events
* `subscriptionStatusDidChange` - Subscription status changes
* `paywallPresented` - Paywall displayed
* `paywallWillDismiss` - Before paywall closes
* `paywallDismissed` - After paywall closes
* `customPaywallAction` - Custom paywall element interactions
## Full Documentation
View the complete API reference and detailed documentation on capawesome.io
---
# Community SDKs
Source: https://superwall.com/docs/community
Community-maintained Superwall SDKs
**Community SDKs**
These SDKs are developed and maintained by the community, not by Superwall. For support, please contact the SDK maintainer or visit their official documentation.
## Available SDKs
Superwall plugin for Capacitor apps by Capawesome. Supports iOS and Android.
---
# Superwall
Source: https://superwall.com/docs/react-native/sdk-reference/Superwall
The shared instance of Superwall that provides access to all SDK features.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
You must call [`configure()`](/react-native/sdk-reference/configure) before accessing `Superwall.shared`, otherwise your app may crash or behave unexpectedly.
## Purpose
Provides access to the configured Superwall instance after calling [`configure()`](/react-native/sdk-reference/configure).
## Signature
```typescript
static get shared(): Superwall
```
## Parameters
This is a static property with no parameters.
## Returns / State
Returns the shared `Superwall` instance that was configured via [`configure()`](/react-native/sdk-reference/configure).
## Usage
Configure first (typically in your app's entry point):
```typescript
import Superwall from "@superwall/react-native-superwall"
await Superwall.configure({
apiKey: "pk_your_api_key"
})
```
Then access throughout your app:
```typescript
Superwall.shared.register({
placement: "feature_access",
feature: () => {
// Feature code here
}
})
```
Set user identity and attributes:
```typescript
await Superwall.shared.identify({
userId: "user123"
})
await Superwall.shared.setUserAttributes({
plan: "premium",
signUpDate: new Date()
})
```
Reset the user:
```typescript
await Superwall.shared.reset()
```
Avoid calling `Superwall.shared.reset()` repeatedly. Resetting rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download configuration state. Only trigger a reset when a user explicitly logs out or you intentionally need to forget their identity.
Set delegate:
```typescript
import { SuperwallDelegate } from "@superwall/react-native-superwall"
class MyDelegate extends SuperwallDelegate {
subscriptionStatusDidChange(from, to) {
console.log(`Subscription status changed from ${from} to ${to}`)
}
}
await Superwall.shared.setDelegate(new MyDelegate())
```
## Main Methods
* [`register()`](/react-native/sdk-reference/register) - Register a placement to trigger paywalls
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user
* [`getUserAttributes()`](/react-native/sdk-reference/getUserAttributes) - Get user attributes
* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes
* [`handleDeepLink()`](/react-native/sdk-reference/handleDeepLink) - Handle deep links
* [`getSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Get subscription status
* [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Set subscription status
---
# PurchaseController
Source: https://superwall.com/docs/react-native/sdk-reference/PurchaseController
An abstract class that defines the contract for a purchase controller.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Abstract class that defines the contract for a purchase controller. This is used for custom purchase handling when you want to manage all subscription-related logic yourself.
## Signature
```typescript
export abstract class PurchaseController {
abstract purchaseFromAppStore(productId: string): Promise
abstract purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise
abstract restorePurchases(): Promise
}
```
## Methods
| Name | Type | Description | Required |
| ---------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- |
| purchaseFromAppStore | productId: string | Purchase a product from the App Store. Returns a Promise that resolves with the result of the purchase logic. | yes |
| purchaseFromGooglePlay | productId: string, basePlanId?: string, offerId?: string | Purchase a product from Google Play. Returns a Promise that resolves with the result of the purchase logic. | yes |
| restorePurchases | None | Restore purchases. Returns a Promise that resolves with the restoration result. | yes |
## Usage
Implement the `PurchaseController` class:
```typescript
import { PurchaseController, PurchaseResult, RestorationResult, PurchaseResultCancelled, PurchaseResultFailed, PurchaseResultPurchased } from "@superwall/react-native-superwall"
class MyPurchaseController extends PurchaseController {
async purchaseFromAppStore(productId: string): Promise {
try {
// Your iOS purchase logic here
// For example, using RevenueCat:
const purchase = await Purchases.purchaseProduct(productId)
if (purchase.customerInfo.entitlements.active["pro"]) {
return new PurchaseResultPurchased()
} else {
return new PurchaseResultFailed("Purchase completed but entitlement not active")
}
} catch (error) {
if (error.userCancelled) {
return new PurchaseResultCancelled()
}
return new PurchaseResultFailed(error.message)
}
}
async purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise {
try {
// Your Android purchase logic here
// For example, using RevenueCat:
const purchase = await Purchases.purchaseProduct(productId)
if (purchase.customerInfo.entitlements.active["pro"]) {
return new PurchaseResultPurchased()
} else {
return new PurchaseResultFailed("Purchase completed but entitlement not active")
}
} catch (error) {
if (error.userCancelled) {
return new PurchaseResultCancelled()
}
return new PurchaseResultFailed(error.message)
}
}
async restorePurchases(): Promise {
try {
// Your restore logic here
// For example, using RevenueCat:
const customerInfo = await Purchases.restorePurchases()
if (customerInfo.entitlements.active["pro"]) {
return RestorationResult.restored()
} else {
return RestorationResult.failed("No active subscription found")
}
} catch (error) {
return RestorationResult.failed(error.message)
}
}
}
```
Configure Superwall with your purchase controller:
```typescript
await Superwall.configure({
apiKey: "pk_your_api_key",
purchaseController: new MyPurchaseController()
})
```
## Important Notes
* When using a `PurchaseController`, you must call [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) whenever the user's entitlements change.
* The purchase controller is responsible for handling all purchase and restore logic.
* You can use third-party services like RevenueCat, Stripe, or your own backend to handle purchases.
## Related
* [`setSubscriptionStatus()`](/react-native/sdk-reference/subscriptionStatus) - Update subscription status after purchases
* [`SuperwallDelegate.subscriptionStatusDidChange`](/react-native/sdk-reference/SuperwallDelegate) - Receive subscription status change notifications
---
# PaywallOptions
Source: https://superwall.com/docs/react-native/sdk-reference/PaywallOptions
Options for configuring the appearance and behavior of paywalls.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Options for configuring the appearance and behavior of paywalls. Use this to customize how paywalls are presented and how purchase failures are handled.
`PaywallOptions` (and its `RestoreFailed` helper) do not take constructor arguments. Create an instance, then set properties directly.
## Signature
```typescript
export class PaywallOptions {
isHapticFeedbackEnabled = true
restoreFailed: RestoreFailed = new RestoreFailed()
shouldShowPurchaseFailureAlert = true
shouldPreload = false
automaticallyDismiss = true
transactionBackgroundView: TransactionBackgroundView = TransactionBackgroundView.spinner
}
```
## Properties
| Name | Type | Description | Default | Required |
| ------------------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| isHapticFeedbackEnabled | boolean | Whether haptic feedback is enabled when interacting with paywalls. | true | no |
| restoreFailed | RestoreFailed | Configuration for the alert shown when restore purchases fails. | | yes |
| shouldShowPurchaseFailureAlert | boolean | Whether to show an alert when a purchase fails. | true | no |
| shouldPreload | boolean | Whether paywalls should be preloaded. If \`false\`, you can manually preload using \`preloadAllPaywalls()\` or \`preloadPaywalls()\`. | false | no |
| automaticallyDismiss | boolean | Whether paywalls should automatically dismiss after a successful purchase. | true | no |
| transactionBackgroundView | TransactionBackgroundView | The view to show behind Apple's payment sheet during a transaction. Options: \`spinner\`, \`none\`. | spinner | no |
## Usage
Create paywall options:
```typescript
import { PaywallOptions, TransactionBackgroundView, RestoreFailed } from "@superwall/react-native-superwall"
const paywallOptions = new PaywallOptions()
paywallOptions.isHapticFeedbackEnabled = true
paywallOptions.shouldShowPurchaseFailureAlert = false
paywallOptions.shouldPreload = true
paywallOptions.automaticallyDismiss = true
paywallOptions.transactionBackgroundView = TransactionBackgroundView.spinner
const restoreFailed = new RestoreFailed()
restoreFailed.title = "No Subscription Found"
restoreFailed.message = "We couldn't find an active subscription for your account."
restoreFailed.closeButtonTitle = "Okay"
paywallOptions.restoreFailed = restoreFailed
const superwallOptions = new SuperwallOptions({
paywalls: paywallOptions
})
await Superwall.configure({
apiKey: "pk_your_api_key",
options: superwallOptions
})
```
## RestoreFailed
Customize the alert shown when restore purchases fails:
```typescript
const restoreFailed = new RestoreFailed()
restoreFailed.title = "No Subscription Found"
restoreFailed.message = "We couldn't find an active subscription for your account."
restoreFailed.closeButtonTitle = "Okay"
const paywallOptions = new PaywallOptions()
paywallOptions.restoreFailed = restoreFailed
```
## Transaction Background View
Control what appears behind Apple's payment sheet:
```typescript
// Show a spinner (default)
const options1 = new PaywallOptions({
transactionBackgroundView: TransactionBackgroundView.spinner
})
// Show nothing
const options2 = new PaywallOptions({
transactionBackgroundView: TransactionBackgroundView.none
})
```
## Related
* [`SuperwallOptions`](/react-native/sdk-reference/SuperwallOptions) - Main SDK configuration options
* [`preloadAllPaywalls()`](/react-native/sdk-reference/Superwall) - Manually preload all paywalls
* [`preloadPaywalls()`](/react-native/sdk-reference/Superwall) - Manually preload specific paywalls
---
# register()
Source: https://superwall.com/docs/react-native/sdk-reference/register
A function that registers a placement that can be remotely configured to show a paywall and gate feature access.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Registers a placement so that when it's added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature.
## Signature
```typescript
async register(params: {
placement: string
params?: Map | Record
handler?: PaywallPresentationHandler
feature?: () => void
}): Promise
```
## Parameters
| Name | Type | Description | Default | Required |
| --------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- |
| placement | string | The name of the placement you wish to register. | | yes |
| params | Map\ \| Record\? | Optional parameters to pass with your placement. These can be referenced within audience filters in your campaign. Keys beginning with \`$\` are reserved for Superwall and will be dropped. Arrays and dictionaries as values are not supported and will be omitted. | undefined | no |
| handler | PaywallPresentationHandler? | A handler whose functions provide status updates for the paywall lifecycle. | undefined | no |
| feature | (() => void)? | An optional completion callback representing the gated feature. It is executed based on the paywall's gating mode: called immediately for \*\*Non-Gated\*\*, called after the user subscribes or if already subscribed for \*\*Gated\*\*. If not provided, you can chain a \`.then()\` block to the returned promise. | | no |
## Returns / State
Returns a Promise that resolves when registration completes. If you supply a `feature` callback, it will be executed according to the paywall's gating configuration, as described above.
## Usage
With feature callback:
```typescript
Superwall.shared.register({
placement: "premium_feature",
params: {
source: "onboarding"
},
feature: () => {
// Code that unlocks the premium feature
openPremiumScreen()
}
})
```
Using promise chaining:
```typescript
await Superwall.shared.register({
placement: "premium_feature",
params: {
source: "onboarding"
}
}).then(() => {
// Code that unlocks the premium feature
openPremiumScreen()
})
```
With presentation handler:
```typescript
import { PaywallPresentationHandler } from "@superwall/react-native-superwall"
const handler = new PaywallPresentationHandler()
handler.onPresent((info) => {
console.log("Paywall presented:", info.name)
})
handler.onDismiss((info, result) => {
console.log("Paywall dismissed:", result)
})
Superwall.shared.register({
placement: "onboarding_complete",
params: {
source: "onboarding"
},
handler: handler
})
```
## Behavior
This behavior is remotely configurable via the Superwall Dashboard:
* For **Non-Gated** paywalls, the feature callback is executed when the paywall is dismissed or if the user is already paying.
* For **Gated** paywalls, the feature callback is executed only if the user is already paying or if they begin paying.
* If no paywall is configured, the feature callback is executed immediately.
* If no feature callback is provided, the returned promise resolves when registration completes.
* If a feature callback is provided, the returned promise always resolves after the feature callback is executed.
Note: The feature callback will not be executed if an error occurs during registration. Such errors can be detected via the `handler`.
---
# Subscription Status
Source: https://superwall.com/docs/react-native/sdk-reference/subscriptionStatus
Methods for getting and setting the user's subscription status.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Methods for managing the user's subscription status. When using a `PurchaseController`, you must call `setSubscriptionStatus()` to update the user's subscription status whenever entitlements change.
## Methods
### getSubscriptionStatus()
Retrieves the current subscription status of the user.
**Signature:**
```typescript
async getSubscriptionStatus(): Promise
```
**Returns:** A Promise that resolves to the current `SubscriptionStatus`.
**Usage:**
```typescript
const status = await Superwall.shared.getSubscriptionStatus()
console.log("Subscription status:", status)
```
### setSubscriptionStatus()
Sets the subscription status of the user. When using a `PurchaseController`, you must call this method to update the user's subscription status. Alternatively, you can implement the [`SuperwallDelegate.subscriptionStatusDidChange`](/react-native/sdk-reference/SuperwallDelegate) delegate callback to receive notifications whenever the subscription status changes.
**Signature:**
```typescript
async setSubscriptionStatus(status: SubscriptionStatus): Promise
```
**Parameters:**
| Name | Type | Description | Required |
| ------ | ------------------ | ---------------------------- | -------- |
| status | SubscriptionStatus | The new subscription status. | yes |
**Returns:** A Promise that resolves once the subscription status has been updated.
**Usage:**
```typescript
import { SubscriptionStatus } from "@superwall/react-native-superwall"
// Set active subscription with entitlements
const activeStatus = SubscriptionStatus.Active(["pro"])
await Superwall.shared.setSubscriptionStatus(activeStatus)
// Set inactive subscription
const inactiveStatus = SubscriptionStatus.Inactive()
await Superwall.shared.setSubscriptionStatus(inactiveStatus)
```
## SubscriptionStatus Type
The `SubscriptionStatus` type represents the user's subscription state:
* `SubscriptionStatus.Active(entitlements: string[] \| Entitlement[])` - User has an active subscription with the specified entitlements
* `SubscriptionStatus.Inactive()` - User does not have an active subscription
* `SubscriptionStatus.Unknown()` - Subscription status is unknown
## When to Update
* After a successful purchase
* After a purchase restoration
* When a subscription expires
* When a subscription is cancelled
* On app launch (to sync with your backend)
## Related
* [`PurchaseController`](/react-native/sdk-reference/PurchaseController) - Handle purchases and update subscription status
* [`SuperwallDelegate`](/react-native/sdk-reference/SuperwallDelegate) - Receive subscription status change notifications
---
# identify()
Source: https://superwall.com/docs/react-native/sdk-reference/identify
Creates an account with Superwall by linking the provided userId to Superwall's automatically generated alias.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Creates an account with Superwall by linking the provided `userId` to Superwall's automatically generated alias. Call this function as soon as you have a valid `userId`.
## Signature
```typescript
async identify({
userId,
options,
}: {
userId: string
options?: IdentityOptions
}): Promise
```
## Parameters
| Name | Type | Description | Default | Required |
| ------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- |
| userId | string | Your user's unique identifier as defined by your backend system. | | yes |
| options | IdentityOptions? | An optional \`IdentityOptions\` object. You can set the \`restorePaywallAssignments\` property to \`true\` to instruct the SDK to wait to restore paywall assignments from the server before presenting any paywalls. This option should be used only in advanced cases (e.g., when users frequently switch accounts or reinstall the app). | undefined | no |
## Returns / State
Returns a Promise that resolves once the identification process is complete.
## Usage
Basic identification:
```typescript
await Superwall.shared.identify({
userId: "user123"
})
```
With options to restore paywall assignments:
```typescript
import { IdentityOptions } from "@superwall/react-native-superwall"
const options = new IdentityOptions()
options.restorePaywallAssignments = true
await Superwall.shared.identify({
userId: "user123",
options: options
})
```
## When to Call
Call `identify()` as soon as you have a valid `userId` in your app. This is typically:
* After user login
* After user registration
* When restoring a previous session
* On app launch if the user is already logged in
## Related
* [`reset()`](/react-native/sdk-reference/Superwall) - Reset the user identity
* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes after identification
---
# configure()
Source: https://superwall.com/docs/react-native/sdk-reference/configure
A static function that configures a shared instance of Superwall for use throughout your app.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
This is a static method called on the `Superwall` class itself, not on the shared instance.
## Purpose
Configures the shared instance of Superwall with your API key and optional configurations, making it ready for use throughout your app.
## Signature
```typescript
static async configure({
apiKey,
options,
purchaseController,
completion,
}: {
apiKey: string
options?: SuperwallOptions
purchaseController?: PurchaseController
completion?: () => void
}): Promise
```
## Parameters
| Name | Type | Description | Default | Required |
| ------------------ | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | --------- | -------- |
| apiKey | string | Your Public API Key from the Superwall dashboard settings. | | yes |
| options | SuperwallOptions? (see /react-native/sdk-reference/SuperwallOptions) | Optional configuration object for customizing paywall appearance and behavior. | undefined | no |
| purchaseController | PurchaseController? | Optional object for handling all subscription-related logic yourself. If omitted, Superwall handles subscription logic. | undefined | no |
| completion | (() => void)? | Optional completion handler called when Superwall finishes configuring. | undefined | no |
## Returns / State
Returns a Promise that resolves to the configured `Superwall` instance. The instance is also accessible via [`Superwall.shared`](/react-native/sdk-reference/Superwall).
## Usage
Basic configuration:
```typescript
import Superwall from "@superwall/react-native-superwall"
await Superwall.configure({
apiKey: "pk_your_api_key"
})
```
With custom options:
```typescript
import Superwall, { SuperwallOptions } from "@superwall/react-native-superwall"
const options = new SuperwallOptions({
paywalls: {
shouldShowPurchaseFailureAlert: false
}
})
await Superwall.configure({
apiKey: "pk_your_api_key",
options: options,
completion: () => {
console.log("Superwall configured successfully")
}
})
```
With custom purchase controller:
```typescript
import Superwall, { PurchaseController } from "@superwall/react-native-superwall"
class MyPurchaseController extends PurchaseController {
async purchaseFromAppStore(productId: string): Promise {
// Your purchase logic
}
async purchaseFromGooglePlay(productId: string, basePlanId?: string, offerId?: string): Promise {
// Your purchase logic
}
async restorePurchases(): Promise {
// Your restore logic
}
}
await Superwall.configure({
apiKey: "pk_your_api_key",
purchaseController: new MyPurchaseController()
})
```
---
# PaywallPresentationHandler
Source: https://superwall.com/docs/react-native/sdk-reference/PaywallPresentationHandler
Handles events related to paywall presentation.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Handles events related to paywall presentation. Use this to receive callbacks about the paywall lifecycle when registering a placement.
## Signature
```typescript
export class PaywallPresentationHandler {
onPresentHandler?: (info: PaywallInfo) => void
onDismissHandler?: (info: PaywallInfo, result: PaywallResult) => void
onErrorHandler?: (error: string) => void
onSkipHandler?: (reason: PaywallSkippedReason) => void
onPresent(handler: (info: PaywallInfo) => void): void
onDismiss(handler: (info: PaywallInfo, result: PaywallResult) => void): void
onError(handler: (error: string) => void): void
onSkip(handler: (reason: PaywallSkippedReason) => void): void
}
```
## Methods
| Name | Type | Description | Required |
| --------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------- | -------- |
| onPresent | handler: (info: PaywallInfo) => void | Sets a handler that is called when a paywall is presented. | yes |
| onDismiss | handler: (info: PaywallInfo, result: PaywallResult) => void | Sets a handler that is called when a paywall is dismissed. | yes |
| onError | handler: (error: string) => void | Sets a handler that is called when an error occurs during paywall presentation. | yes |
| onSkip | handler: (reason: PaywallSkippedReason) => void | Sets a handler that is called when a paywall is skipped (not shown). | yes |
## Usage
Create a handler and use it when registering a placement:
```typescript
import { PaywallPresentationHandler, PaywallResult, PaywallSkippedReason } from "@superwall/react-native-superwall"
const handler = new PaywallPresentationHandler()
handler.onPresent((info) => {
console.log("Paywall presented:", info.name)
// Pause video, hide UI, etc.
pauseBackgroundTasks()
})
handler.onDismiss((info, result: PaywallResult) => {
console.log("Paywall dismissed with result:", result.type)
// Resume video, show UI, etc.
resumeBackgroundTasks()
if (result.type === "purchased") {
console.log("User purchased!")
} else if (result.type === "declined") {
console.log("User dismissed without purchasing")
} else if (result.type === "restored") {
console.log("User restored a purchase")
}
})
handler.onError((error) => {
console.error("Paywall error:", error)
// Handle error
})
handler.onSkip((reason) => {
console.log("Paywall skipped:", reason)
// Handle skip reason
})
// Use the handler when registering
Superwall.shared.register({
placement: "premium_feature",
handler: handler,
feature: () => {
// Feature code
}
})
```
## Handler Callbacks
* **onPresent**: Called when a paywall is successfully presented to the user.
* **onDismiss**: Called when a paywall is dismissed. The `result` parameter has a `type` of `purchased`, `declined`, or `restored`.
* **onError**: Called when an error occurs during paywall presentation or loading.
* **onSkip**: Called when a paywall is skipped (not shown) for various reasons (user already subscribed, no audience match, etc.).
## Related
* [`register()`](/react-native/sdk-reference/register) - Register a placement with a handler
* [`PaywallResult`](/react-native/sdk-reference/types) - Result types for paywall dismissal
* [`PaywallSkippedReason`](/react-native/sdk-reference/types) - Reasons why a paywall might be skipped
---
# handleDeepLink()
Source: https://superwall.com/docs/react-native/sdk-reference/handleDeepLink
Handles a deep link.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Handles a deep link that may be related to Superwall functionality (e.g., promotional links, paywall deep links).
## Signature
```typescript
async handleDeepLink(url: string): Promise
```
## Parameters
| Name | Type | Description | Required |
| ---- | ------ | ---------------------------- | -------- |
| url | string | The deep link URL to handle. | yes |
## Returns / State
Returns a Promise that resolves to a boolean indicating whether the deep link was handled by Superwall. Returns `true` if Superwall handled the link, `false` otherwise.
## Usage
```typescript
// In your deep link handler
const url = "https://your-app.com/paywall?placement=onboarding"
const wasHandled = await Superwall.shared.handleDeepLink(url)
if (!wasHandled) {
// Handle other deep links in your app
handleOtherDeepLink(url)
}
```
## Integration
Typically, you'll call this method from your app's deep link handler:
```typescript
import { Linking } from "react-native"
// Handle initial URL (if app was opened via deep link)
Linking.getInitialURL().then((url) => {
if (url) {
Superwall.shared.handleDeepLink(url)
}
})
// Handle deep links while app is running
Linking.addEventListener("url", (event) => {
Superwall.shared.handleDeepLink(event.url)
})
```
## Related
* [`SuperwallDelegate.paywallWillOpenDeepLink`](/react-native/sdk-reference/SuperwallDelegate) - Delegate method called before opening a deep link
---
# Types and Enums
Source: https://superwall.com/docs/react-native/sdk-reference/types
Reference for types, enums, and result objects used in the React Native SDK.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Overview
This page provides reference documentation for types, enums, and result objects used throughout the React Native SDK.
## SubscriptionStatus
Represents the subscription status of a user.
```typescript
type SubscriptionStatus =
| SubscriptionStatus.Active
| SubscriptionStatus.Inactive
| SubscriptionStatus.Unknown
// Create instances
const active = SubscriptionStatus.Active(["pro", "premium"])
const inactive = SubscriptionStatus.Inactive()
const unknown = SubscriptionStatus.Unknown()
```
* **Active**: `status: "ACTIVE"` and an `entitlements` array (string IDs or `Entitlement` objects)
* **Inactive**: `status: "INACTIVE"`
* **Unknown**: `status: "UNKNOWN"`
## PaywallResult
Result of a paywall presentation.
```typescript
type PaywallResult =
| { type: "purchased"; productId: string }
| { type: "declined" }
| { type: "restored" }
```
* **purchased**: User successfully purchased (includes `productId`)
* **declined**: User dismissed/declined the paywall
* **restored**: User restored a previous purchase
## PresentationResult
Result of checking whether a placement will present a paywall.
```typescript
type PresentationResult =
| PresentationResultPaywall // contains an Experiment
| PresentationResultHoldout // contains an Experiment
| PresentationResultNoAudienceMatch
| PresentationResultPlacementNotFound
| PresentationResultUserIsSubscribed
| PresentationResultPaywallNotAvailable
```
* Use `PresentationResult.fromJson(...)` to materialize instances returned from the native bridge.
* Holdout/Paywall results include the associated `Experiment`.
## TriggerResult
Result of registering a placement.
```typescript
enum TriggerResultType {
placementNotFound,
noAudienceMatch,
paywall,
holdout,
error,
}
class TriggerResult {
type: TriggerResultType
experiment?: Experiment
error?: string
}
```
* Use `TriggerResult.fromJson(...)` to parse responses.
## ConfigurationStatus
Status of SDK configuration.
```typescript
enum ConfigurationStatus {
PENDING = "PENDING",
CONFIGURED = "CONFIGURED",
FAILED = "FAILED"
}
```
* **PENDING**: Configuration is in progress
* **CONFIGURED**: Configuration completed successfully
* **FAILED**: Configuration failed
## EntitlementsInfo
Information about user entitlements.
```typescript
interface EntitlementsInfo {
status: SubscriptionStatus
active: Entitlement[]
all: Entitlement[]
inactive: Entitlement[]
}
```
## PaywallInfo
Information about a paywall.
```typescript
interface PaywallInfo {
identifier: string
name: string
url: string
experiment?: Experiment
products: Product[]
productIds: string[]
// ...additional timing and metadata fields
}
```
## PaywallSkippedReason
Reason why a paywall was skipped.
```typescript
type PaywallSkippedReason =
| PaywallSkippedReasonHoldout // includes Experiment
| PaywallSkippedReasonNoAudienceMatch
| PaywallSkippedReasonPlacementNotFound
| PaywallSkippedReasonUserIsSubscribed
```
* Holdout and paywall decisions include the associated `Experiment` instance.
## PurchaseResult
Result of a purchase attempt.
```typescript
class PurchaseResult { type: string; error?: string }
class PurchaseResultPurchased extends PurchaseResult {}
class PurchaseResultCancelled extends PurchaseResult {}
class PurchaseResultFailed extends PurchaseResult { error: string }
class PurchaseResultPending extends PurchaseResult {}
```
## RestorationResult
Result of a restore purchases attempt.
```typescript
abstract class RestorationResult {
static restored(): RestorationResult
static failed(error?: Error): RestorationResult
}
```
* `RestorationResult.restored()` when purchases are restored
* `RestorationResult.failed(error?)` when restoration fails
## RedemptionResults
Result of redeeming a promotional link.
```typescript
type RedemptionResult =
| { status: "SUCCESS"; code: string; redemptionInfo: RedemptionInfo }
| { status: "ERROR"; code: string; error: { message: string } }
| { status: "CODE_EXPIRED"; code: string; expired: { resent: boolean; obfuscatedEmail?: string } }
| { status: "INVALID_CODE"; code: string }
| { status: "EXPIRED_SUBSCRIPTION"; code: string; redemptionInfo: RedemptionInfo }
```
## LogLevel
Logging level.
```typescript
enum LogLevel {
Debug = "debug",
Info = "info",
Warn = "warn",
Error = "error",
None = "none"
}
```
## LogScope
Logging scope.
```typescript
enum LogScope {
LocalizationManager = "localizationManager",
BounceButton = "bounceButton",
CoreData = "coreData",
ConfigManager = "configManager",
IdentityManager = "identityManager",
DebugManager = "debugManager",
DebugViewController = "debugViewController",
LocalizationViewController = "localizationViewController",
GameControllerManager = "gameControllerManager",
Device = "device",
Network = "network",
PaywallEvents = "paywallEvents",
ProductsManager = "productsManager",
StoreKitManager = "storeKitManager",
Placements = "placements",
Receipts = "receipts",
SuperwallCore = "superwallCore",
PaywallPresentation = "paywallPresentation",
PaywallTransactions = "paywallTransactions",
PaywallViewController = "paywallViewController",
Cache = "cache",
All = "all",
}
```
## InterfaceStyle
Interface style preference.
```typescript
enum InterfaceStyle {
LIGHT = "LIGHT",
DARK = "DARK"
}
```
## NetworkEnvironment
Network environment.
```typescript
enum NetworkEnvironment {
Release = "release",
ReleaseCandidate = "releaseCandidate",
Developer = "developer"
}
```
## TransactionBackgroundView
View to show behind Apple's payment sheet.
```typescript
enum TransactionBackgroundView {
spinner = "spinner",
none = "none"
}
```
## Related
* [`SubscriptionStatus` methods](/react-native/sdk-reference/subscriptionStatus) - Getting and setting subscription status
* [`PaywallResult` usage](/react-native/sdk-reference/PaywallPresentationHandler) - Handling paywall results
---
# SuperwallDelegate
Source: https://superwall.com/docs/react-native/sdk-reference/SuperwallDelegate
A class that handles Superwall lifecycle events and analytics.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
Set the delegate using `Superwall.shared.setDelegate(delegate)` to receive these callbacks.
Use `handleSuperwallEvent(eventInfo)` to track Superwall analytics events in your own analytics platform for a complete view of user behavior.
`SuperwallDelegate` is an abstract class—all methods are required. Provide no-op implementations for callbacks you do not use.
## Purpose
Provides callbacks for Superwall lifecycle events, analytics tracking, and custom paywall interactions.
## Signature
```typescript
export abstract class SuperwallDelegate {
abstract subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus): void
abstract willRedeemLink(): void
abstract didRedeemLink(result: RedemptionResult): void
abstract handleSuperwallEvent(eventInfo: SuperwallEventInfo): void
abstract handleCustomPaywallAction(name: string): void
abstract willDismissPaywall(paywallInfo: PaywallInfo): void
abstract willPresentPaywall(paywallInfo: PaywallInfo): void
abstract didDismissPaywall(paywallInfo: PaywallInfo): void
abstract didPresentPaywall(paywallInfo: PaywallInfo): void
abstract paywallWillOpenURL(url: URL): void
abstract paywallWillOpenDeepLink(url: URL): void
abstract handleLog(
level: string,
scope: string,
message?: string,
info?: Map,
error?: string
): void
}
```
## Methods
All methods must be implemented (you can provide empty bodies). Key methods include:
| Name | Type | Description | Required |
| --------------------------- | ---------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | -------- |
| subscriptionStatusDidChange | from: SubscriptionStatus, to: SubscriptionStatus | Called when subscription status changes. | yes |
| handleSuperwallEvent | eventInfo: SuperwallEventInfo | Called for all internal analytics events. Use for tracking in your own analytics. | yes |
| handleCustomPaywallAction | name: string | Called when user taps elements with \`data-pw-custom\` tags. | yes |
| willPresentPaywall | paywallInfo: PaywallInfo | Called before paywall presentation. | yes |
| didPresentPaywall | paywallInfo: PaywallInfo | Called after paywall presentation. | yes |
| willDismissPaywall | paywallInfo: PaywallInfo | Called before paywall dismissal. | yes |
| didDismissPaywall | paywallInfo: PaywallInfo | Called after paywall dismissal. | yes |
| paywallWillOpenURL | url: URL | Called when paywall attempts to open a URL. | yes |
| paywallWillOpenDeepLink | url: URL | Called when paywall attempts to open a deep link. | yes |
| handleLog | level: string, scope: string, message?: string, info?: Map\, error?: string | Called for logging messages from the SDK. | yes |
| willRedeemLink | None | Called before the SDK attempts to redeem a promotional link. | yes |
| didRedeemLink | result: RedemptionResult | Called after the SDK has attempted to redeem a promotional link. | yes |
## Usage
Basic delegate setup:
```typescript
import { SuperwallDelegate, PaywallInfo, SubscriptionStatus } from "@superwall/react-native-superwall"
class MyDelegate extends SuperwallDelegate {
subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus) {
console.log(`Subscription changed from ${from.status} to ${to.status}`)
// update UI here
}
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
// Track in your analytics
Analytics.track("superwall_event", {
event: eventInfo.event.type,
paywall_id: eventInfo.paywallInfo?.id
})
}
handleCustomPaywallAction(name: string) {
switch (name) {
case "help":
this.presentHelpScreen()
break
case "contact":
this.presentContactForm()
break
}
}
willPresentPaywall(paywallInfo: PaywallInfo) {
// Pause video, hide UI, etc.
this.pauseBackgroundTasks()
}
didDismissPaywall(paywallInfo: PaywallInfo) {
// Resume video, show UI, etc.
this.resumeBackgroundTasks()
}
// Required methods you might not use
willRedeemLink() {}
didRedeemLink() {}
handleCustomPaywallAction() {}
willPresentPaywall() {}
didPresentPaywall() {}
paywallWillOpenURL() {}
paywallWillOpenDeepLink() {}
handleLog() {}
}
// Set the delegate
await Superwall.shared.setDelegate(new MyDelegate())
```
Track subscription status changes:
```typescript
subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus) {
console.log("Subscription changed from", from, "to", to)
this.updateUI(for: to)
}
```
Forward analytics events:
```typescript
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
switch (eventInfo.event.type) {
case EventType.paywallOpen:
Analytics.track("paywall_opened", {
paywall_id: eventInfo.paywallInfo?.id,
placement: eventInfo.placement
})
break
case EventType.transactionComplete:
Analytics.track("subscription_purchased", {
product_id: eventInfo.product?.id,
paywall_id: eventInfo.paywallInfo?.id
})
break
}
}
```
---
# getUserAttributes()
Source: https://superwall.com/docs/react-native/sdk-reference/getUserAttributes
Retrieves the user attributes, set using setUserAttributes.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Retrieves the user attributes that were previously set using [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes).
## Signature
```typescript
async getUserAttributes(): Promise
```
## Parameters
This method takes no parameters.
## Returns / State
Returns a Promise that resolves with an object representing the user's attributes. The object has string keys and values can be any JSON-encodable value, URLs, or Dates.
## Usage
```typescript
const attributes = await Superwall.shared.getUserAttributes()
console.log("User attributes:", attributes)
// Example output: { name: "John", email: "john@example.com", plan: "premium" }
```
## Related
* [`setUserAttributes()`](/react-native/sdk-reference/setUserAttributes) - Set user attributes
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user
---
# setUserAttributes()
Source: https://superwall.com/docs/react-native/sdk-reference/setUserAttributes
Sets user attributes for use in paywalls and on the Superwall dashboard.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Sets user attributes for use in paywalls and on the Superwall dashboard. If an attribute already exists, its value will be overwritten while other attributes remain unchanged. This is useful for analytics and campaign audience filters you may define in the Superwall Dashboard.
**Note:** These attributes should not be used as a source of truth for sensitive information.
## Signature
```typescript
async setUserAttributes(userAttributes: UserAttributes): Promise
```
## Parameters
| Name | Type | Description |
| -------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| userAttributes | UserAttributes | An object containing custom attributes to store for the user. Values can be any JSON-encodable value, URLs, or Dates. Keys beginning with \`$\` are reserved for Superwall and will be dropped. Arrays and dictionaries as values are not supported and will be omitted. |
## Returns / State
Returns a Promise that resolves once the user attributes have been updated.
## Usage
```typescript
await Superwall.shared.setUserAttributes({
name: user.name,
email: user.email,
username: user.username,
profilePic: user.profilePicUrl,
plan: "premium",
signUpDate: new Date()
})
```
## Best Practices
* Set user attributes after calling [`identify()`](/react-native/sdk-reference/identify)
* Update attributes whenever relevant user information changes
* Use attributes in campaign audience filters on the Superwall Dashboard
* Don't store sensitive information (passwords, tokens, etc.) as user attributes
## Related
* [`getUserAttributes()`](/react-native/sdk-reference/getUserAttributes) - Get user attributes
* [`identify()`](/react-native/sdk-reference/identify) - Identify a user
---
# SuperwallOptions
Source: https://superwall.com/docs/react-native/sdk-reference/SuperwallOptions
Options for configuring the Superwall SDK.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Purpose
Options for configuring the Superwall SDK. Use this to customize the appearance and behavior of paywalls, logging, and other SDK features.
## Signature
```typescript
export class SuperwallOptions {
paywalls: PaywallOptions = new PaywallOptions()
networkEnvironment: NetworkEnvironment = NetworkEnvironment.Release
isExternalDataCollectionEnabled = true
localeIdentifier?: string
isGameControllerEnabled = false
logging: LoggingOptions = new LoggingOptions()
collectAdServicesAttribution = false
passIdentifiersToPlayStore = false
storeKitVersion?: "STOREKIT1" | "STOREKIT2"
enableExperimentalDeviceVariables = false
}
```
## Properties
| Name | Type | Description | Default | Required |
| --------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------- | -------- |
| paywalls | PaywallOptions (see /react-native/sdk-reference/PaywallOptions) | Options for configuring paywall appearance and behavior. | | yes |
| networkEnvironment | NetworkEnvironment | The network environment to use. Options: \`Release\`, \`ReleaseCandidate\`, \`Developer\`. | Release | no |
| isExternalDataCollectionEnabled | boolean | Whether external data collection is enabled. | true | no |
| localeIdentifier | string? | The locale identifier to use. If not set, the system locale is used. | | no |
| isGameControllerEnabled | boolean | Whether game controller support is enabled. | false | no |
| logging | LoggingOptions | Options for configuring logging behavior. \*\*Must be an instance of \`LoggingOptions\` so \`toJson()\` is available.\*\* | | yes |
| collectAdServicesAttribution | boolean | Whether to collect AdServices attribution data. | false | no |
| passIdentifiersToPlayStore | boolean | Whether to pass identifiers to Play Store. | false | no |
| storeKitVersion | "STOREKIT1" \| "STOREKIT2"? | The StoreKit version to use (iOS only). | \`undefined\` (auto-detect) | no |
| enableExperimentalDeviceVariables | boolean | Whether to enable experimental device variables. | false | no |
## Usage
Create options when configuring the SDK:
```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
})
```
## Network Environment
Use different network environments for different build configurations:
```typescript
// Development builds
const devOptions = new SuperwallOptions({
networkEnvironment: NetworkEnvironment.Developer
})
// Release candidate builds
const rcOptions = new SuperwallOptions({
networkEnvironment: NetworkEnvironment.ReleaseCandidate
})
// Production builds
const prodOptions = new SuperwallOptions({
networkEnvironment: NetworkEnvironment.Release
})
```
## Related
* [`PaywallOptions`](/react-native/sdk-reference/PaywallOptions) - Paywall-specific options
* [`configure()`](/react-native/sdk-reference/configure) - Configure the SDK with options
---
# Overview
Source: https://superwall.com/docs/react-native/sdk-reference
Reference documentation for the Superwall React Native SDK.
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Welcome to the Superwall React Native SDK Reference
This reference documentation covers the legacy React Native SDK (`react-native-superwall`).
You can find the source code for the SDK [on GitHub](https://github.com/superwall/react-native-superwall).
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
---
# Changelog
Source: https://superwall.com/docs/react-native/changelog
Release notes for the Superwall React Native SDK
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## 2.1.7
### Fixes
* Fixes issue with `enableExperimentalDeviceVariables`.
## 2.1.6
### Enhancements
* Upgrades iOS SDK to 4.5.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.5.0).
### Fixes
* Fixes issue with `enableExperimentalDeviceVariables`.
## 2.1.5
### Enhancements
* Exposes the `enableExperimentalDeviceVariables` `SuperwallOption`.
## 2.1.4
### Enhancements
* Upgrades iOS SDK to 4.4.1 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.4.1).
* Upgrades Android SDK to 2.1.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.2).
## 2.1.3
### Fixes
* Fixes issue when building for iOS.
## 2.1.2
### Fixes
* Upgrades iOS SDK to 4.4.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.4.0).
## 2.1.1
### Enhancements
* Upgrades Android SDK to 2.1.0 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.0).
## 2.1.0
### Fixes
* Upgrades iOS SDK to 4.3.9 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.9).
### Enhancements
* Adds support for `storeKitVersion` in `SuperwallOptions`.
* Fixes an issue preventing `SuperwallDelegate.didRedeemLink` from getting
called when a Web Checkout link was redeemed.
* Adds `didRedeem` and `willRedeem` to support web checkout
## 2.1.0 (Beta 3)
### Fixes
* Adds support for `storeKitVersion` in `SuperwallOptions`.
## 2.1.0 (Beta 2)
### Fixes
* Fixes an issue preventing `SuperwallDelegate.didRedeemLink` from getting called when a Web Checkout link was redeemed.
## 2.1.0 (Beta 1)
### Enhancements
* Adds `didRedeem` and `willRedeem` to support web checkout
* Upgrades iOS SDK to 4.3.7 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.7).
## 2.0.14
### Enhancements
* Upgrades iOS SDK to 4.3.5 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.5).
## 2.0.13
### Enhancements
* Adds `getAssignments`.
* Upgrades iOS SDK to 4.3.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.0).
## 2.0.12
### Enhancements
* Adds `setLogLevel`.
* Upgrades Android SDK to 2.0.6 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.6).
### Fixes
* Bug fixes for running the example app on Xcode 16.4.
## 2.0.11
### Enhancements
* Upgrades iOS SDK to 4.2.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.2.0).
### Fixes
* Fixes an issue preventing `RestorationResult.failed` from deserializing, which caused failed Restore Purchases attempts to get stuck with the loading indicator shown.
## 2.0.10
### Enhancements
* Upgrades iOS SDK to 4.0.6 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.6).
### Fixes
* Fixes `productId` not being available in the `PurchaseResult` on iOS.
* Fixes issues for Kotlin 2.0 users on Android
## 2.0.9
### Fixes
* Fixes issue with `getSubscriptionStatus` on iOS.
## 2.0.8
### Enhancements
* Upgrades Android SDK to 2.0.5 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.5).
* Upgrades iOS SDK to 4.0.5 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.5).
* Adds back `getSubscriptonStatus`
## 2.0.7
## Fixes
* Fixes issue when hanling deep links
## 2.0.6
### Enhancements
* Upgrades Android SDK to 2.0.3 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.3).
* Upgrades Android SDK to 4.0.3 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.3).
* Updates `SuperwallPlacement` naming to `SuperwallEvent`
## 2.0.5
### Enhancements
* Upgrades Android SDK to 2.0.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.2).
## 2.0.4
### Enhancements
* Upgrades iOS SDK to 4.0.1 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.1).
## 2.0.3
### Enhancements
* Updates `SubscriptionStatus.Active` to accept either a list of strings or a list of `Entitlement` objects.
* Updates how feature block is passed in and used in `register` call
* Removes the need for params to be a `Map`, the parameter now supports a `Record`
* Upgrades Android SDK to `2.0.1` [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/2.0.1)
### Fixes
* Example project fixes.
## 2.0.2
### Fixes
* Readds `handleDeepLink(url:)` to `Superwall`.
## 2.0.1
### Fixes
* Fixes the issue `TypeError: SuperwallReactNative.observeSubscriptionStatus is not a function`.
## 2.0.0
### Breaking Changes
* Updated API for `Superwall.shared.configure` to now receive an object
* Updated API for `Superwall.shared.register` to now receive an object
* Updated API for `Superwall.shared.setSubscriptionStatus` to now receive a `SubscriptionStatus` type with an `Entitlements` array in case of `SubscriptionStatus.Active`
* Added a `subscriptionStatusEmitter` you can subscribe to using the `change`listener
* Upgrades iOS SDK to 4.0.0 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/4.0.0).
* Upgrades Android SDK to 2.0.0 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/2.0.0)
* View more changes in our [migration guide](https://superwall.com/docs/migrating-to-v2-react-native)
## 1.4.7
### Enhancements
* Upgrades iOS SDK to 3.12.4 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.4).
## 1.4.6
### Enhancements
* Upgrades iOS SDK to 3.12.3 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.3).
## 1.4.5
### Fixes
* Removes unnecessary date comparison from PurchaseController example code.
* Adds a StoreKit configuration file to the iOS expo example app.
## 1.4.4
### Enhancements
* Upgrades iOS SDK to 3.12.1 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.1)
## 1.4.3
### Enhancements
* Upgrades Android SDK to 1.5.1 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.5.1)
* Upgrades iOS SDK to 3.12.0 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.0)
### Fixes
* Fixes issue where accessing configuration state before configuring would cause a crash.
## 1.4.2
### Fixes
* Fixes an issue where params that were passed with `getPresentationResult(event:params:)` were being dropped.
## 1.4.1
### Enhancements
* Exposes `getPresentationResult(event:params:)`. This returns a `PresentationResult`, which preemptively gets the result of registering an event. This helps you determine whether a particular event will present a paywall in the future.
## 1.4.0
### Enhancements
* Adds `setInterfaceStyle(style:)` to Superwall, which you can use to set the interface style as `LIGHT` or `DARK`.
## 1.3.5
### Fixes
* Fixes issue where the `PurchaseController` functions wouldn't get called on hot restart of the app.
* Fixes issue with configuration status serialization on Android.
* Fixes issue with preloading paywalls on Android.
## 1.3.4
### Enhancements
* Upgrades Android SDK to 1.3.1 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.3.1)
* Upgrades iOS SDK to 3.11.1 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.11.1)
* Adds `preloadAllPaywalls` and `preloadPaywalls(eventNames: Set)` method to `Superwall` which preloads all paywalls or paywalls for the event names passed in the argument.
### Fixes
* Fixes issue with the `Experiment` inside `PaywallInfo` being `null` in the `handleSuperwallEvent` delegate for iOS.
## 1.3.3
### Enhancements
* Upgrades Android SDK to 1.3.0 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.3.0)
* Upgrades iOS SDK to 3.10.1 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.10.1)
* Adds `passIdentifiersToPlayStore` to `SuperwallOptions` which allows you to pass user identifiers to the Play Store purchases as account identifiers. This is useful for tracking user purchases in the Play Store console.
* Adds `confirmAllAssignments` method to `Superwall` which confirms assignments for all placements and returns an array of all confirmed experiment assignments. Note that the assignments may be different when a placement is registered due to changes in user, placement, or device parameters used in audience filters.
### Fixes
* Fixes issue with the `Experiment` inside `PaywallInfo` being `null` in the `handleSuperwallEvent` delegate for iOS.
## 1.3.2
### Enhancements
* Upgrades iOS SDK to 3.10.0 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.10.0)
* Upgrades Android SDK to 1.2.9 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.9)
## 1.3.1
### Enhancements
* Upgrades Android SDK to 1.2.8 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.8)
## 1.3.0
### Enhancements
* Upgrades iOS SDK to 3.9.1. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.9.1)
* Upgrades Android SDK to 1.2.7 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.7)
* Exposes the `SuperwallOption` `collectAdServicesAttribution` for iOS. When `true`, this collects the AdServices attribute token, which will be process by our backend. This adds `adServicesTokenRequest_start`, `adServicesTokenRequest_complete`, and `adServicesTokenRequest_fail` events.
* Exposes `getConfigurationStatus()`. This returns either `PENDING`, `CONFIGURED`, or `FAILED`.
## 1.2.7
### Fixes
// TODO: Update iOS to latest version before releasing.
* Fixes issue where the `paywallWillOpenURL` wasn't being called.
## 1.2.6
### Enhancements
* Adds an expo example project.
* Upgrades iOS SDK to 3.7.3. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.7.3)
* Upgrades Android SDK to 1.2.4. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.4)
## 1.2.5
### Fixes
* Fixes `Switch must be exhaustive` error caused by the upgrade of the iOS SDK.
## 1.2.4
### Enhancements
* Upgrades iOS SDK to 3.7.0. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.7.0)
### Fixes
* Fixes an error `Invalid LocalNotificationType value`.
## 1.2.3
### Enhancements
* Adds `Superwall.shared.dismiss()` to be able to dismiss a paywall programmatically.
* Upgrades Android SDK to 1.2.1. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.1)
## 1.2.2
### Enhancements
* Upgrades iOS SDK to 3.6.6. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.6)
* Upgrades Android SDK to 1.1.7. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.7)
### Fixes
* Makes sure the iOS SDK is pinned to a specific version, rather than a minimum version.
## 1.2.1
### Enhancements
* Upgrades Android SDK to 1.1.6. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.6)
## 1.2.0
### Enhancements
* Adds `handleDeepLink(url:)`.
* Adds `setUserAttributes(userAttributes:)` and `getUserAttributes()`.
* Upgrades iOS SDK to 3.6.5. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.5)
### Fixes
* Transaction error alerts now display the intended error message rather than a generic `PurchaseResultError`.
## 1.1.3
### Enhancements
* Upgrades Android SDK to 1.1.5. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.5)
## 1.1.2
### Enhancements
* Upgrades Android SDK to 1.1.4. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.4)
* Upgrades iOS SDK to 3.6.2. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.2)
### Fixes
* Fixes issue where the React Native `SuperwallEvent` hadn't been updated to include `identityAlias`.
## 1.1.1
### Enhancements
* Upgrades Android SDK to 1.1.2. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.2)
* Upgrades iOS SDK to 3.6.1. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.1)
## 1.1.0
### Enhancements
* Upgrades Android SDK to 1.1.1. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.1)
* Upgrades iOS SDK to 3.6.0. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.0)
### Fixes
* Fixes issue with restoration on iOS.
* Fixes issue with presenting surveys.
## 1.0.5
### Fixes
* Fixes issue where params sent via register were being dropped.
## 1.0.4
### Enhancements
* Upgrades Android SDK to 1.0.2. [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/1.0.2)
## 1.0.3
### Fixes
* Providing your own `PurchaseController` now works as expected.
* Publicly exposes `EventType`, `PurchaseResultCancelled`, `PurchaseResultFailed`, `PurchaseResultPending`, `PurchaseResultPurchased`, `PurchaseResultRestored`, `TransactionBackgroundView`.
## 1.0.2
### Enhancements
* Upgrades Android SDK to 1.0.0. [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/1.0.0)
* Upgrades iOS SDK to 3.5.0. [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/3.5.0)
---
# Welcome
Source: https://superwall.com/docs/react-native
Welcome to the Superwall React Native SDK documentation
**Deprecated SDK**
We strongly recommend migrating to the new [Superwall Expo SDK](/expo), see our [migration guide](/expo/guides/migrating-react-native) for details.
## Quick Links
Reference the Superwall React Native SDK
Step-by-step migration guide to the new Expo SDK
Documentation for the recommended Expo SDK
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
---
# Using Referral or Promo Codes with Superwall
Source: https://superwall.com/docs/using-referral-or-promo-codes-with-superwall
Learn how to use referral or promo codes with Superwall.
There are two primary ways to use referral codes or promo codes with Superwall:
1. **Using Superwall's Mobile SDKs**: By using [custom actions](/custom-paywall-events) along with a [campaign](/campaigns) for referrals, you can create a flow to handle referral codes and see their resulting conversions and other data. You create the products that each referral should unlock within the respective app storefront.
2. **Web Checkout**: Here, you can use Superwall's [web checkout](/web-checkout-overview) feature to easily offer referrals. With this approach, you could create a [checkout link](/web-checkout-creating-campaigns-to-show-paywalls) for each referral you need. Unlike the previous option, you create the [products in Stripe](/web-checkout-adding-a-stripe-product).
### Understanding Superwall's role
Before you continue, it's critical to understand Superwall's role in this process. Most referral flows usually call for two things:
1. A way to enter in a referral code and validate it.
2. And, a resulting discounted offer that the user can redeem.
**Your app must provide the referral code entry and validation.** In addition, you'll want to create discounted products in either App Store Connect, Google Play Console, or Stripe. Superwall offers products from these sources on paywalls. Remember, Superwall does *not* create or manage the products — it shows the ones you've imported from one of those places.
### Referral flows
Given that information, here is how most referral flows can work:
```mermaid
flowchart TD
A([Paywall is shown]) --> B[Referral Code claim button is tapped]
B --> C[Custom Action is fired from button tap]
C --> D[Responding in your Superwall Delegate, you present your own referral UI over the existing paywall]
D --> E{Code is valid?}
E -- NO --> F[Dismiss referral UI, existing paywall is still presented]
E -- YES --> G[Dismiss referral UI, dismiss existing paywall. Register placement for the referral code.]
G --> H[Present new paywall with discounted product. In Superwall, you can use campaign data to attribute conversions, trials, etc.]
```
Now, let's go through each step in detail. We'll assume that you're triggering this flow from a paywall that's already presented, but if that's not the case — just skip to the step where you present your referral entry UI (step four):
Create a campaign for your referrals. Here, you'd add the discounted product(s) you've made to a paywall. You can add in as many placements as you need. Maybe there's one for each influencer, or seasonal discount offer, etc. You'll register one of these placements later on if the referral code entry was successful.
A paywall is shown. On it, this button that reads "Referral Code" has a custom tap action called "showPromoRedeem" which gets tapped:
This app has a [`SuperwallDelegate`](/using-superwall-delegate):
```swift
@main
struct Caffeine_PalApp: App {
@State private var delegate: SWDelegate = .init()
init() {
Superwall.configure(apiKey: "api_key")
// Delegate configured here
Superwall.shared.delegate = delegate
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
Using the [`SuperwallDelegate`](/using-superwall-delegate), the app responds to the custom action. It presents a customized referral redemption interface *on top* of the existing paywall. This is optional, but presenting over the paywall means that the user will be taken back to it if the redemption code entry fails:
```swift
@Observable
class SWDelegate: SuperwallDelegate {
enum CustomActions: String, Identifiable {
case showPromoRedeem
var id: Self { self }
}
func handleCustomPaywallAction(withName name: String) {
guard let action: CustomActions = .init(rawValue: name) else {
print("Unexpected custom action: \(name)")
return
}
switch action {
case .showPromoRedeem:
let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
// TODO: Implement placement on success
}))
if let paywallVC = Superwall.shared.presentedViewController {
paywallVC.present(referralUI, animated: true)
} else {
// Present either using SwiftUI .sheet or other means
}
}
}
}
```
Now that your referral interface is showing, you'd validate the code on your server or by some other means.
Now, if the code succeeds, you'd dismiss the referral UI and the existing paywall. In our callback, we...
1. Dismiss the existing views.
2. And, we register a placement that corresponds to a campaign you've setup for referral codes:
```swift
// This...
let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
// TODO: Implement placement on success
}))
// Might look similar to this...
let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
// Dismiss the referral UI
referralUI.dismiss(animated: true)
// Dismiss the existing paywall
Superwall.shared.presentedViewController?.dismiss(animated: true)
// This shows the paywall with the discounted product.
// It should be gated, which means the closure only fires if they convert.
Superwall.shared.register(placement: "referral",
params: ["influencer":"Jordan"]) {
MyAnalyticsService.shared.log("referral_code_redeemed",
properties: ["referral_code": "Jordan", "result": "trial_started"])
}
}))
```
Finally, your paywall and discounted product that you setup in step #1 is shown. If they convert, you'll see all of the details in your campaign that you built for referrals, just like you would any other campaign. You can also forward events to your third party analytics service as well, as shown in the previous step.
And that's it! It's a matter of creating discounted products, using them in a campaign, showing a referral UI and validating it, and then registering a placement to show those paywalls within a campaign.
The flow on web checkout is considerably easier, and that's primarily because you aren't navigating app storefronts for products and have a direct link to payments. And, just like with mobile, you can use your own referral entry system if you've got one to reveal web checkout links and their paywalls. Here's how it works:
Create a campaign for your referrals. Here, you'd add the discounted product(s) you've made to a paywall that were created in Stripe. You can add in as many placements as you need. Maybe there's one for each influencer, or seasonal discount offer, etc.
Next, simply send out the [web checkout](/web-checkout-creating-campaigns-to-show-paywalls) links to your users. You can create a link for each referral code, or you can use the same link for all of them.
Remember that with Superwall's web checkout feature, each placement you add becomes its own web checkout link.
When the user clicks the link, they are taken to a web checkout page that has the discounted product you created in Stripe. They can enter their payment information and complete the purchase.
And that's it! It's a matter of creating discounted products in Stripe, using them in a campaign, and then sending out the web checkout links to your users. You'll see all of the details in your campaign that you built for referrals, just like you would any other campaign, so you can track conversions, trial starts, and more.
---
# Superwall
Source: https://superwall.com/docs/android/sdk-reference/Superwall
The shared instance of Superwall that provides access to all SDK features.
You must call [`configure()`](/android/sdk-reference/configure) before accessing `Superwall.instance`, otherwise your app will crash.
## Purpose
Provides access to the configured Superwall instance after calling [`configure()`](/android/sdk-reference/configure).
## Signature
```kotlin
companion object {
val instance: Superwall
}
```
```java
// Java
public static Superwall getInstance()
```
## Parameters
This is a companion object property with no parameters.
## Returns / State
Returns the shared `Superwall` instance that was configured via [`configure()`](/android/sdk-reference/configure).
## Usage
Configure first (typically in Application class):
```kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(
application = this,
apiKey = "pk_your_api_key"
)
}
}
```
Then access throughout your app:
```kotlin
Superwall.instance.register("feature_access") {
// Feature code here
}
```
Set user identity and attributes:
```kotlin
Superwall.instance.identify("user123")
Superwall.instance.setUserAttributes(mapOf(
"plan" to "premium",
"signUpDate" to System.currentTimeMillis()
))
```
Reset the user:
```kotlin
Superwall.instance.reset()
```
Avoid calling `Superwall.instance.reset()` repeatedly. Resetting rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download configuration state. Only trigger a reset when a user explicitly logs out or you intentionally need to forget their identity. See [User Management](/android/quickstart/user-management) for more guidance.
Set delegate:
```kotlin
Superwall.instance.delegate = this
```
Consume a purchase (2.6.2+):
```kotlin
// Using coroutines
lifecycleScope.launch {
val result = Superwall.instance.consume(purchaseToken)
result.fold(
onSuccess = { token ->
println("Purchase consumed: $token")
},
onFailure = { error ->
println("Failed to consume: ${error.message}")
}
)
}
// Using callback
Superwall.instance.consume(purchaseToken) { result ->
result.fold(
onSuccess = { token ->
println("Purchase consumed: $token")
},
onFailure = { error ->
println("Failed to consume: ${error.message}")
}
)
}
```
Show an alert over the current paywall (2.5.3+):
```kotlin
Superwall.instance.showAlert(
title = "Important Notice",
message = "Your subscription will renew soon",
actionTitle = "View Details",
closeActionTitle = "Dismiss",
action = {
// Handle action button tap
navigateToSubscriptionSettings()
},
onClose = {
// Handle close/dismiss
println("Alert dismissed")
}
)
```
Set integration attributes for analytics (2.5.3+):
```kotlin
import com.superwall.sdk.models.attribution.AttributionProvider
Superwall.instance.setIntegrationAttributes(
mapOf(
AttributionProvider.ADJUST to "adjust_user_id_123",
AttributionProvider.MIXPANEL to "mixpanel_distinct_id_456",
AttributionProvider.META to "meta_user_id_789"
)
)
```
Java usage:
```java
// Access the instance
Superwall.getInstance().register("feature_access", () -> {
// Feature code here
});
// Set user identity
Superwall.getInstance().identify("user123");
```
---
# PurchaseController
Source: https://superwall.com/docs/android/sdk-reference/PurchaseController
An interface for handling Superwall's subscription-related logic with your own purchase implementation.
**This interface is not required.** By default, Superwall handles all subscription-related logic automatically using Google Play Billing.
When implementing PurchaseController, you must manually update [`subscriptionStatus`](/android/sdk-reference/subscriptionStatus) whenever the user's entitlements change.
## Purpose
Use this interface only if you want complete control over purchase handling, such as when using RevenueCat or other third-party purchase frameworks.
## Signature
```kotlin
interface PurchaseController {
suspend fun purchase(
activity: Activity,
product: StoreProduct
): PurchaseResult
suspend fun restorePurchases(): RestorationResult
}
```
```java
// Java
public interface PurchaseController {
CompletableFuture purchase(
Activity activity,
StoreProduct product
);
CompletableFuture restorePurchases();
}
```
## Parameters
| Name | Type | Description | Required |
| ---------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| purchase | activity: Activity, product: StoreProduct | Called when user initiates purchasing. Implement your purchase logic here. Activity is needed for Google Play Billing. Returns \`PurchaseResult\`. | yes |
| restorePurchases | None | Called when user initiates restore. Implement your restore logic here. Returns \`RestorationResult\`. | yes |
## Returns / State
* `purchase()` returns a `PurchaseResult` (`.Purchased`, `.Failed(Throwable)`, `.Cancelled`, or `.Pending`)
* `restorePurchases()` returns a `RestorationResult` (`.Restored` or `.Failed(Throwable?)`)
When using a PurchaseController, you must also manage [`subscriptionStatus`](/android/sdk-reference/subscriptionStatus) yourself.
## Usage
For implementation examples and detailed guidance, see [Using RevenueCat](/android/guides/using-revenuecat).
---
# PaywallOptions
Source: https://superwall.com/docs/android/sdk-reference/PaywallOptions
Configuration for paywall presentation and behavior in the Superwall Android SDK.
`PaywallOptions` is provided via the `paywalls` property on [`SuperwallOptions`](/android/sdk-reference/SuperwallOptions) and is passed to the SDK when you call [`configure`](/android/sdk-reference/configure).
## Purpose
Customize how paywalls look and behave, including preload behavior, alerts, dismissal, and haptics.
## Signature
```kotlin
class PaywallOptions {
var isHapticFeedbackEnabled: Boolean = true
class RestoreFailed {
var title: String = "No Subscription Found"
var message: String = "We couldn't find an active subscription for your account."
var closeButtonTitle: String = "Okay"
}
var restoreFailed: RestoreFailed = RestoreFailed()
var shouldShowPurchaseFailureAlert: Boolean = true
var shouldPreload: Boolean = true
var useCachedTemplates: Boolean = false
var automaticallyDismiss: Boolean = true
enum class TransactionBackgroundView { SPINNER }
var transactionBackgroundView: TransactionBackgroundView? = TransactionBackgroundView.SPINNER
var overrideProductsByName: Map = emptyMap()
var optimisticLoading: Boolean = false
var onBackPressed: ((PaywallInfo?) -> Boolean)? = null
}
```
## Parameters
| Name | Type | Description | Default | Required |
| ------------------------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | -------- |
| isHapticFeedbackEnabled | Boolean | Enables haptic feedback when users purchase/restore, open links, or close the paywall. | true | no |
| restoreFailed | RestoreFailed | Messaging for the restore-failed alert. | | yes |
| restoreFailed.title | String | Title for restore-failed alert. | No Subscription Found | no |
| restoreFailed.message | String | Message for restore-failed alert. | We couldn't find an active subscription for your account. | no |
| restoreFailed.closeButtonTitle | String | Close button title for restore-failed alert. | Okay | no |
| shouldShowPurchaseFailureAlert | Boolean | Shows an alert after a purchase fails. Set to \`false\` if you handle failures via a \`PurchaseController\`. | true | no |
| shouldPreload | Boolean | Preloads and caches trigger paywalls and products during SDK initialization. Set to \`false\` for just-in-time loading. | true | no |
| useCachedTemplates | Boolean | Loads paywall template websites from disk when available. | false | no |
| automaticallyDismiss | Boolean | Automatically dismisses the paywall on successful purchase or restore. | true | no |
| transactionBackgroundView | TransactionBackgroundView? | View shown behind the system payment sheet during a transaction. Use \`null\` for no view. | .SPINNER | no |
| overrideProductsByName | Map\ | Overrides products on all paywalls using name→identifier mapping (e.g., \`"primary"\` → \`"com.example.premium\_monthly"\`). | | yes |
| optimisticLoading | Boolean | Hides shimmer optimistically. | false | no |
| onBackPressed | ((PaywallInfo?) -> Boolean)? | Callback invoked when back button is pressed (requires \`reroute\_back\_button\` enabled in paywall settings). Return \`true\` to consume the back press, \`false\` to use SDK default behavior. | null | no |
## Usage
```kotlin
val paywallOptions = PaywallOptions().apply {
isHapticFeedbackEnabled = true
shouldShowPurchaseFailureAlert = false
shouldPreload = true
useCachedTemplates = false
automaticallyDismiss = true
transactionBackgroundView = PaywallOptions.TransactionBackgroundView.SPINNER
overrideProductsByName = mapOf(
"primary" to "com.example.premium_monthly",
"tertiary" to "com.example.premium_annual",
)
optimisticLoading = false
onBackPressed = { paywallInfo ->
// Custom back button handling
// Return true to consume the back press, false to use SDK default
false
}
}
val options = SuperwallOptions().apply {
paywalls = paywallOptions
}
Superwall.configure(
application = this,
apiKey = "pk_your_api_key",
options = options,
)
```
## Related
* [`SuperwallOptions`](/android/sdk-reference/SuperwallOptions)
---
# register()
Source: https://superwall.com/docs/android/sdk-reference/register
A function that registers a placement that can be remotely configured to show a paywall and gate feature access.
## Purpose
Registers a placement so that when it's added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature.
## Signature
```kotlin
fun Superwall.register(
placement: String,
params: Map? = null,
handler: PaywallPresentationHandler? = null,
feature: () -> Unit,
)
```
```kotlin
fun Superwall.register(
placement: String,
params: Map? = null,
handler: PaywallPresentationHandler? = null,
)
```
## Parameters
| Name | Type | Description | Default | Required |
| --------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| placement | String | The name of the placement you wish to register. | | yes |
| params | Map\? | Optional parameters to pass with your placement. These can be referenced within campaign rules. Keys beginning with \`$\` are reserved for Superwall and will be dropped. Arrays and nested maps are currently unsupported and will be ignored. | null | no |
| handler | PaywallPresentationHandler? | A handler whose functions provide status updates for the paywall lifecycle. | null | no |
| feature | () -> Unit | A completion block representing the gated feature. It is executed based on the paywall's gating mode: called immediately for \*\*Non-Gated\*\*, called after the user subscribes or if already subscribed for \*\*Gated\*\*. | | yes |
## Returns / State
This function returns `Unit`. If you supply a `feature` lambda, it will be executed according to the paywall's gating configuration, as described above.
## Usage
```swift iOS
func pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.register(placement: "StartWorkout") {
navigation.startWorkout()
}
}
```
```kotlin Android
fun pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.instance.register("StartWorkout") {
navigation.startWorkout()
}
}
```
```dart Flutter
void pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.registerPlacement('StartWorkout', feature: () {
navigation.startWorkout();
});
}
```
```typescript React Native
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.register({
placement: 'StartWorkout',
feature: () => {
navigation.navigate('LaunchedFeature', {
value: 'Non-gated feature launched',
});
}
});
```
Register without feature gating:
```kotlin
Superwall.instance.register(
placement = "onboarding_complete",
params = mapOf("source" to "onboarding"),
handler = this
)
```
---
# subscriptionStatus
Source: https://superwall.com/docs/android/sdk-reference/subscriptionStatus
A StateFlow property that indicates the subscription status of the user.
If you're using a custom [`PurchaseController`](/android/sdk-reference/PurchaseController), you must update this property whenever the user's entitlements change.
You can also observe changes via the [`SuperwallDelegate`](/android/sdk-reference/SuperwallDelegate) method `subscriptionStatusDidChange(from, to)`.
## Purpose
Indicates the current subscription status of the user and can be observed for changes using Kotlin StateFlow.
## Signature
```kotlin
val subscriptionStatus: StateFlow
// For setting the status (when using custom PurchaseController)
fun setSubscriptionStatus(status: SubscriptionStatus)
```
```java
// Java
public StateFlow getSubscriptionStatus()
public void setSubscriptionStatus(SubscriptionStatus status)
```
## Parameters
This property accepts a `SubscriptionStatus` sealed class value:
* `SubscriptionStatus.Unknown` - Status is not yet determined
* `SubscriptionStatus.Active(Set)` - User has active entitlements (set of entitlement identifiers)
* `SubscriptionStatus.Inactive` - User has no active entitlements
## Returns / State
Returns a `StateFlow` that emits the current subscription status. When using a [`PurchaseController`](/android/sdk-reference/PurchaseController), you must set this property yourself using `setSubscriptionStatus()`. Otherwise, Superwall manages it automatically.
## Usage
Set subscription status (when using PurchaseController):
```kotlin
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(setOf("premium", "pro_features"))
)
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
```
Get current subscription status:
```kotlin
val status = Superwall.instance.subscriptionStatus.value
when (status) {
is SubscriptionStatus.Unknown ->
println("Subscription status unknown")
is SubscriptionStatus.Active ->
println("User has active entitlements: ${status.entitlements}")
is SubscriptionStatus.Inactive ->
println("User has no active subscription")
}
```
Observe changes with StateFlow:
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
lifecycleScope.launch {
Superwall.instance.subscriptionStatus.collect { status ->
updateUI(status)
}
}
}
private fun updateUI(status: SubscriptionStatus) {
when (status) {
is SubscriptionStatus.Active -> showPremiumContent()
is SubscriptionStatus.Inactive -> showFreeContent()
is SubscriptionStatus.Unknown -> showLoadingState()
}
}
}
```
Jetpack Compose observation:
```kotlin
@Composable
fun ContentScreen() {
val subscriptionStatus by Superwall.instance.subscriptionStatus
.collectAsState()
Column {
when (subscriptionStatus) {
is SubscriptionStatus.Active -> {
Text("Premium user with: ${subscriptionStatus.entitlements.joinToString()}")
}
is SubscriptionStatus.Inactive -> {
Text("Free user")
}
is SubscriptionStatus.Unknown -> {
Text("Loading...")
}
}
}
}
```
Java usage:
```java
// Get current status
SubscriptionStatus status = Superwall.getInstance()
.getSubscriptionStatus().getValue();
// Observe changes
Superwall.getInstance().getSubscriptionStatus()
.observe(this, status -> {
updateUI(status);
});
// Set status (when using PurchaseController)
Superwall.getInstance().setSubscriptionStatus(
new SubscriptionStatus.Active(Set.of("premium"))
);
```
---
# setSubscriptionStatus()
Source: https://superwall.com/docs/android/sdk-reference/advanced/setSubscriptionStatus
A function that manually sets the subscription status when using a custom PurchaseController.
This function should only be used when implementing a custom [`PurchaseController`](/android/sdk-reference/PurchaseController). When using Superwall's built-in purchase handling, the subscription status is managed automatically.
You must call this function whenever the user's entitlements change to keep Superwall's subscription status synchronized with your purchase system.
## Purpose
Manually updates the subscription status when using a custom [`PurchaseController`](/android/sdk-reference/PurchaseController) to ensure paywall gating and analytics work correctly.
## Signature
```kotlin
fun Superwall.setSubscriptionStatus(status: SubscriptionStatus)
```
```java
// Java
public void setSubscriptionStatus(SubscriptionStatus status)
```
## Parameters
| Name | Type | Description | Required |
| ------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| status | SubscriptionStatus | The subscription status to set. Can be \`SubscriptionStatus.Unknown\`, \`SubscriptionStatus.Active(entitlements)\`, or \`SubscriptionStatus.Inactive\`. | yes |
## Returns / State
This function returns `Unit`. The new status will be reflected in the [`subscriptionStatus`](/android/sdk-reference/subscriptionStatus) StateFlow and will trigger the [`SuperwallDelegate.subscriptionStatusDidChange`](/android/sdk-reference/SuperwallDelegate) callback.
## Usage
Set active subscription with entitlements:
```kotlin
// User purchased premium subscription
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(setOf("premium", "pro_features"))
)
```
Set inactive subscription:
```kotlin
// User's subscription expired or was cancelled
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
```
Set unknown status during initialization:
```kotlin
// While checking subscription status on app launch
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Unknown)
```
Usage with RevenueCat:
```kotlin
class RevenueCatPurchaseController : PurchaseController {
override suspend fun purchase(
activity: Activity,
product: StoreProduct
): PurchaseResult {
return try {
val result = Purchases.sharedInstance.purchase(activity, product.sku)
// Update Superwall subscription status based on RevenueCat result
if (result.isSuccessful) {
val entitlements = result.customerInfo.entitlements.active.keys
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(entitlements)
)
PurchaseResult.Purchased
} else {
PurchaseResult.Failed(Exception("Purchase failed"))
}
} catch (e: Exception) {
PurchaseResult.Failed(e)
}
}
override suspend fun restorePurchases(): RestorationResult {
return try {
val customerInfo = Purchases.sharedInstance.restorePurchases()
val activeEntitlements = customerInfo.entitlements.active.keys
if (activeEntitlements.isNotEmpty()) {
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(activeEntitlements)
)
} else {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
}
RestorationResult.Restored
} catch (e: Exception) {
RestorationResult.Failed(e)
}
}
}
```
Listen for external subscription changes:
```kotlin
class SubscriptionManager {
fun onSubscriptionStatusChanged(isActive: Boolean, entitlements: Set) {
val status = if (isActive) {
SubscriptionStatus.Active(entitlements)
} else {
SubscriptionStatus.Inactive
}
// Update Superwall whenever subscription status changes externally
Superwall.instance.setSubscriptionStatus(status)
}
}
```
Java usage:
```java
// Set active subscription
Set entitlements = Set.of("premium", "pro_features");
Superwall.getInstance().setSubscriptionStatus(
new SubscriptionStatus.Active(entitlements)
);
// Set inactive subscription
Superwall.getInstance().setSubscriptionStatus(
SubscriptionStatus.Inactive.INSTANCE
);
```
---
# PaywallBuilder
Source: https://superwall.com/docs/android/sdk-reference/advanced/PaywallBuilder
A builder class for creating custom PaywallView instances for advanced presentation.
You're responsible for managing the lifecycle of the returned PaywallView. Do not use the same PaywallView instance in multiple places simultaneously.
The remotely configured presentation style is ignored when using this method. You must handle presentation styling programmatically.
## Purpose
Creates a PaywallView that you can present however you want, bypassing Superwall's automatic presentation logic.
## Signature
```kotlin
class PaywallBuilder(private val placement: String) {
fun params(params: Map?): PaywallBuilder
fun overrides(overrides: PaywallOverrides?): PaywallBuilder
fun delegate(delegate: PaywallViewCallback): PaywallBuilder
fun activity(activity: Activity): PaywallBuilder
suspend fun build(): Result
fun buildSync(): PaywallView
fun build(onSuccess: (PaywallView) -> Unit, onError: (Throwable) -> Unit)
}
```
## Parameters
| Name | Type | Description | Required |
| --------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -------- |
| placement | String | The name of the placement as defined on the Superwall dashboard. | yes |
| params | Map\? | Optional parameters to pass with your placement for audience filters. Keys beginning with \`$\` are reserved and will be dropped. | no |
| overrides | PaywallOverrides? | Optional overrides for products and presentation style. | no |
| delegate | PaywallViewCallback | A delegate to handle user interactions with the retrieved PaywallView. | yes |
| activity | Activity | The activity context required for the PaywallView. | yes |
## Returns / State
Returns a `Result` that you can add to your view hierarchy. If presentation should be skipped, returns a failure result.
## Usage
Using with coroutines:
```kotlin
lifecycleScope.launch {
val result = PaywallBuilder("premium_feature")
.params(mapOf("source" to "settings"))
.delegate(object : PaywallViewCallback {
override fun onFinished(
paywall: PaywallView,
result: PaywallResult,
shouldDismiss: Boolean
) {
// Handle paywall completion
}
})
.activity(this@MainActivity)
.build()
result.fold(
onSuccess = { paywallView ->
binding.container.addView(paywallView)
},
onFailure = { error ->
println("Error creating paywall: ${error.message}")
}
)
}
```
Jetpack Compose integration:
```kotlin
@Composable
fun PaywallScreen() {
PaywallComposable(
placement = "premium_feature",
params = mapOf("source" to "settings"),
delegate = object : PaywallViewCallback {
override fun onFinished(
paywall: PaywallView,
result: PaywallResult,
shouldDismiss: Boolean
) {
// Handle completion
}
},
errorComposable = { error ->
Text("Failed to load paywall: ${error.message}")
},
loadingComposable = {
CircularProgressIndicator()
}
)
}
```
---
# userId
Source: https://superwall.com/docs/android/sdk-reference/userId
A property on Superwall.instance that returns the current user's ID.
The anonymous user ID is automatically generated and persisted to disk, so it remains consistent across app launches until the user is identified.
## Purpose
Returns the current user's unique identifier, either from a previous call to [`identify()`](/android/sdk-reference/identify) or an anonymous ID if not identified.
## Signature
```kotlin
// Accessed via Superwall.instance
val userId: String
```
```java
// Java
public String getUserId()
```
## Parameters
This is a read-only property on the [`Superwall.instance`](/android/sdk-reference/Superwall) with no parameters.
## Returns / State
Returns a `String` representing the user's ID. If [`identify()`](/android/sdk-reference/identify) has been called, returns that user ID. Otherwise, returns an automatically generated anonymous user ID that is cached to disk.
## Usage
Get the current user ID:
```kotlin
val currentUserId = Superwall.instance.userId
println("User ID: $currentUserId")
```
Check if user is identified:
```kotlin
if (Superwall.instance.isLoggedIn) {
println("User is identified with ID: ${Superwall.instance.userId}")
} else {
println("User is anonymous with ID: ${Superwall.instance.userId}")
}
```
Example usage in analytics:
```kotlin
fun trackAnalyticsEvent() {
val userId = Superwall.instance.userId
Analytics.track("feature_used", mapOf(
"user_id" to userId,
"timestamp" to System.currentTimeMillis()
))
}
```
Example usage in custom logging:
```kotlin
fun logError(error: Throwable) {
Logger.log("Error for user ${Superwall.instance.userId}: ${error.message}")
}
```
Java usage:
```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());
}
```
---
# identify()
Source: https://superwall.com/docs/android/sdk-reference/identify
A function that creates an account with Superwall by linking a userId to the automatically generated alias.
Call this as soon as you have a user ID, typically after login or when the user's identity becomes available.
## Purpose
Links a user ID to Superwall's automatically generated alias, creating an account for analytics and personalization.
## Signature
```kotlin
fun Superwall.identify(
userId: String,
options: IdentityOptions? = null
)
```
```java
// Java
public void identify(
String userId,
@Nullable IdentityOptions options
)
```
## Parameters
| Name | Type | Description | Default | Required |
| ------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| userId | String | Your user's unique identifier, as defined by your backend system. | | yes |
| options | IdentityOptions? | Optional configuration for identity behavior. Set \`restorePaywallAssignments\` to \`true\` to wait for paywall assignments from the server. Use only in advanced cases where users frequently switch accounts. | null | no |
## Returns / State
This function returns `Unit`. After calling, [`isLoggedIn`](/android/sdk-reference/userId) will return `true` and [`userId`](/android/sdk-reference/userId) will return the provided user ID.
## Usage
Basic identification:
```kotlin
Superwall.instance.identify("user_12345")
```
With options for account switching scenarios:
```kotlin
val options = IdentityOptions().apply {
restorePaywallAssignments = true
}
Superwall.instance.identify(
userId = "returning_user_67890",
options = options
)
```
Call as soon as you have a user ID:
```kotlin
fun userDidLogin(user: User) {
Superwall.instance.identify(user.id)
// Set additional user attributes
Superwall.instance.setUserAttributes(mapOf(
"email" to user.email,
"plan" to user.subscriptionPlan,
"signUpDate" to user.createdAt
))
}
```
Java usage:
```java
// Basic identification
Superwall.getInstance().identify("user_12345");
// With options
IdentityOptions options = new IdentityOptions();
options.setRestorePaywallAssignments(true);
Superwall.getInstance().identify("returning_user_67890", options);
```
---
# SuperwallEvent
Source: https://superwall.com/docs/android/sdk-reference/SuperwallEvent
A sealed class representing analytical events that are automatically tracked by Superwall.
These events provide comprehensive analytics about user behavior and paywall performance. Use them to track conversion funnels, user engagement, and revenue metrics in your analytics platform.
Common events to track for conversion analysis include `TriggerFire`, `PaywallOpen`, `TransactionStart`, and `TransactionComplete`.
## Purpose
Represents internal analytics events tracked by Superwall and sent to the [`SuperwallDelegate`](/android/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform.
## Signature
```kotlin
sealed class SuperwallEvent {
// User lifecycle events
object FirstSeen : SuperwallEvent()
object AppOpen : SuperwallEvent()
object AppLaunch : SuperwallEvent()
object AppClose : SuperwallEvent()
object SessionStart : SuperwallEvent()
object IdentityAlias : SuperwallEvent()
object AppInstall : SuperwallEvent()
// Deep linking
data class DeepLink(val url: String) : SuperwallEvent()
// Paywall events
data class TriggerFire(
val placementName: String,
val result: TriggerResult
) : SuperwallEvent()
data class PaywallOpen(val paywallInfo: PaywallInfo) : SuperwallEvent()
data class PaywallClose(val paywallInfo: PaywallInfo) : SuperwallEvent()
data class PaywallDecline(val paywallInfo: PaywallInfo) : SuperwallEvent()
// Transaction events
data class TransactionStart(
val product: StoreProduct,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class TransactionComplete(
val transaction: StoreTransaction?,
val product: StoreProduct,
val type: TransactionType,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class TransactionFail(
val error: TransactionError,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class TransactionAbandon(
val product: StoreProduct,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class TransactionRestore(
val restoreType: RestoreType,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class TransactionTimeout(val paywallInfo: PaywallInfo) : SuperwallEvent()
// Subscription events
data class SubscriptionStart(
val product: StoreProduct,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
data class FreeTrialStart(
val product: StoreProduct,
val paywallInfo: PaywallInfo
) : SuperwallEvent()
object SubscriptionStatusDidChange : SuperwallEvent()
// System events
data class DeviceAttributes(val attributes: Map) : SuperwallEvent()
// And more...
}
```
```java
// Java - SuperwallEvent is a sealed class hierarchy
// Access via pattern matching or instanceof checks
```
## Parameters
Each event contains associated values with relevant information for that event type. Common parameters include:
* `paywallInfo: PaywallInfo` - Information about the paywall
* `product: StoreProduct` - The product involved in transactions
* `url: String` - Deep link URLs
* `attributes: Map` - Device or user attributes
## Returns / State
This is a sealed class that represents different event types. Events are received via [`SuperwallDelegate.handleSuperwallEvent(eventInfo)`](/android/sdk-reference/SuperwallDelegate).
## Usage
These events are received via [`SuperwallDelegate.handleSuperwallEvent(eventInfo)`](/android/sdk-reference/SuperwallDelegate) for forwarding to your analytics platform.
---
# getPresentationResult()
Source: https://superwall.com/docs/android/sdk-reference/getPresentationResult
Check the outcome of a placement without presenting a paywall.
## Purpose
Retrieves the presentation result for a placement without presenting the paywall. Call this when you need to know whether a placement would show a paywall, send the user to a holdout, or fail due to missing configuration before you decide how to render UI.
## Signature
```kotlin
suspend fun Superwall.getPresentationResult(
placement: String,
params: Map? = null,
): Result
```
```kotlin
fun Superwall.getPresentationResultSync(
placement: String,
params: Map? = null,
): Result
```
`getPresentationResultSync` blocks the calling thread. Prefer the suspend function inside a coroutine whenever possible.
## Parameters
| Name | Type | Description | Default | Required |
| --------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| placement | String | The placement to evaluate. | | yes |
| params | Map\? | Optional custom parameters that feed audience filters. Keys starting with \`$\` are dropped by the SDK. Nested maps or lists are ignored. | null | no |
## Returns / State
Returns a Kotlin `Result`.
* On success, the wrapped `PresentationResult` can be:
* `PresentationResult.PlacementNotFound` – Placement is missing from any live campaign.
* `PresentationResult.NoAudienceMatch` – No audience matched, so nothing would show.
* `PresentationResult.Paywall(experiment)` – A paywall would be presented; inspect the `experiment`.
* `PresentationResult.Holdout(experiment)` – The user is in a holdout group for that experiment.
* `PresentationResult.PaywallNotAvailable` – The SDK could not present (no activity, already showing, offline, etc.).
* On failure, the `Result` contains the thrown exception (for example, the SDK is not configured yet). Inspect it with `exceptionOrNull()` or `onFailure`.
## Usage
```kotlin
lifecycleScope.launch {
val result = Superwall.instance.getPresentationResult(
placement = "premium_feature",
params = mapOf("source" to "settings")
)
result
.onSuccess { presentation ->
when (presentation) {
is PresentationResult.Paywall -> {
logExperiment(presentation.experiment)
showLockedState()
}
is PresentationResult.Holdout -> showHoldoutBanner()
is PresentationResult.NoAudienceMatch -> unlockFeature()
is PresentationResult.PlacementNotFound -> Timber.w("Missing placement configuration")
is PresentationResult.PaywallNotAvailable -> showOfflineMessage()
}
}
.onFailure { error ->
Timber.e(error, "Unable to fetch presentation result")
}
}
```
```kotlin
// Blocking usage (for example, inside a worker)
val result = Superwall.instance.getPresentationResultSync("premium_feature")
val presentation = result.getOrNull() ?: return
```
## Related
* [`register()`](/android/sdk-reference/register) – Registers a placement and may present a paywall.
* [`SuperwallDelegate`](/android/sdk-reference/SuperwallDelegate) – Receive callbacks when paywalls are presented.
---
# configure()
Source: https://superwall.com/docs/android/sdk-reference/configure
A static function that configures a shared instance of Superwall for use throughout your app.
This is a static method called on the `Superwall` class itself, not on the shared instance. The Android SDK requires an Application context for initialization.
## Purpose
Configures the shared instance of Superwall with your API key and optional configurations, making it ready for use throughout your Android app.
```kotlin Android
public fun configure(
applicationContext: Application,
apiKey: String,
purchaseController: PurchaseController? = null,
options: SuperwallOptions? = null,
activityProvider: ActivityProvider? = null,
completion: ((Result) -> Unit)? = null
)
```
## Parameters
| Name | Type | Description | Default | Required |
| ------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| applicationContext | Application | Your Android Application instance, required for SDK initialization and lifecycle management. | | yes |
| apiKey | String | Your Public API Key from the Superwall dashboard settings. | | yes |
| purchaseController | PurchaseController? | Optional object for handling all subscription-related logic yourself. If \`null\`, Superwall handles subscription logic. | null | no |
| options | SuperwallOptions? (see /android/sdk-reference/SuperwallOptions) | Optional configuration object for customizing paywall appearance and behavior. | null | no |
| activityProvider | ActivityProvider? | Optional provider that supplies the current Activity when needed by the SDK. | null | no |
| completion | ((Result\) -> Unit)? | Optional completion handler called when Superwall finishes configuring. Result contains success or failure. | null | no |
## Returns / State
Configures the Superwall instance which is accessible via [`Superwall.instance`](/android/sdk-reference/Superwall).
```kotlin Android
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(
applicationContext = this,
apiKey = "pk_your_api_key"
)
}
}
```
With custom options:
```kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
val options = SuperwallOptions().apply {
paywalls.shouldShowPurchaseFailureAlert = false
}
Superwall.configure(
applicationContext = this,
apiKey = "pk_your_api_key",
options = options
) {
println("Superwall configured successfully")
}
}
}
```
---
# handleDeepLink()
Source: https://superwall.com/docs/android/sdk-reference/handleDeepLink
A function that handles deep links and triggers paywalls based on configured campaigns.
Configure deep link campaigns on the Superwall dashboard by adding the `deepLink` event to a campaign trigger.
Deep link events are also tracked via [`SuperwallEvent.DeepLink`](/android/sdk-reference/SuperwallEvent) and sent to your [`SuperwallDelegate`](/android/sdk-reference/SuperwallDelegate).
## Purpose
Processes a deep link URL and triggers any associated paywall campaigns configured on the Superwall dashboard.
## Signature
```kotlin
fun Superwall.handleDeepLink(url: String)
```
```java
// Java
public void handleDeepLink(String url)
```
## Parameters
| Name | Type | Description | Required |
| ---- | ------ | -------------------------------------------------- | -------- |
| url | String | The deep link URL to process for paywall triggers. | yes |
## Returns / State
This function returns `Unit`. If the URL matches a campaign configured on the dashboard, it may trigger a paywall presentation.
## Usage
In your Activity:
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Handle deep link on app launch
intent?.let { handleIntent(it) }
}
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
intent?.let { handleIntent(it) }
}
private fun handleIntent(intent: Intent) {
val action = intent.action
val data = intent.data
if (Intent.ACTION_VIEW == action && data != null) {
val url = data.toString()
// Handle the deep link with Superwall
Superwall.instance.handleDeepLink(url)
// Continue with your app's deep link handling
handleAppDeepLink(url)
}
}
}
```
In your manifest (declare your deep link schemes):
```xml
```
Handle deep links in different scenarios:
```kotlin
fun handleDeepLinkFromNotification(url: String) {
// Handle deep link from push notification
Superwall.instance.handleDeepLink(url)
navigateToContent(url)
}
fun handleDeepLinkFromWebView(url: String) {
// Handle deep link from web view or external browser
Superwall.instance.handleDeepLink(url)
processWebViewDeepLink(url)
}
```
Java usage:
```java
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Intent intent = getIntent();
handleIntent(intent);
}
@Override
protected void onNewIntent(Intent intent) {
super.onNewIntent(intent);
handleIntent(intent);
}
private void handleIntent(Intent intent) {
String action = intent.getAction();
Uri data = intent.getData();
if (Intent.ACTION_VIEW.equals(action) && data != null) {
String url = data.toString();
// Handle the deep link with Superwall
Superwall.getInstance().handleDeepLink(url);
// Continue with your app's deep link handling
handleAppDeepLink(url);
}
}
}
```
Example deep link campaign setup:
```kotlin
// When users click a deep link like "myapp://premium-feature"
// The dashboard campaign can be configured to:
// 1. Track the deepLink event
// 2. Show a paywall if user is not subscribed
// 3. Direct to premium content if user is subscribed
Superwall.instance.handleDeepLink("myapp://premium-feature?source=email")
```
---
# SuperwallDelegate
Source: https://superwall.com/docs/android/sdk-reference/SuperwallDelegate
An interface that handles Superwall lifecycle events and analytics.
Set the delegate using `Superwall.instance.delegate = this` to receive these callbacks. For Java, use `setJavaDelegate()` for better Java interop.
Use `handleSuperwallEvent(eventInfo)` to track Superwall analytics events in your own analytics platform for a complete view of user behavior.
## Purpose
Provides callbacks for Superwall lifecycle events, analytics tracking, and custom paywall interactions.
## Signature
```kotlin
interface SuperwallDelegate {
fun subscriptionStatusDidChange(
from: SubscriptionStatus,
to: SubscriptionStatus
) {}
fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {}
fun handleCustomPaywallAction(name: String) {}
fun willDismissPaywall(paywallInfo: PaywallInfo) {}
fun willPresentPaywall(paywallInfo: PaywallInfo) {}
fun didDismissPaywall(paywallInfo: PaywallInfo) {}
fun didPresentPaywall(paywallInfo: PaywallInfo) {}
fun paywallWillOpenURL(url: String) {}
fun paywallWillOpenDeepLink(url: String) {}
fun handleLog(
level: LogLevel,
scope: LogScope,
message: String,
info: Map?,
error: Throwable?
) {}
fun userAttributesDidChange(newAttributes: Map) {}
}
```
```java
// Java - Use SuperwallDelegateJava for better Java interop
public interface SuperwallDelegateJava {
default void subscriptionStatusDidChange(
SubscriptionStatus from,
SubscriptionStatus to
) {}
default void handleSuperwallEvent(SuperwallEventInfo eventInfo) {}
default void handleCustomPaywallAction(String name) {}
// ... other methods
}
```
## Parameters
All methods are optional to implement. Key methods include:
| Name | Type | Description | Required |
| --------------------------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- | -------- |
| subscriptionStatusDidChange | from: SubscriptionStatus, to: SubscriptionStatus | Called when subscription status changes. | yes |
| handleSuperwallEvent | eventInfo: SuperwallEventInfo | Called for all internal analytics events. Use for tracking in your own analytics. | yes |
| handleCustomPaywallAction | name: String | Called when user taps elements with \`data-pw-custom\` tags. | yes |
| willPresentPaywall | paywallInfo: PaywallInfo | Called before paywall presentation. | yes |
| didPresentPaywall | paywallInfo: PaywallInfo | Called after paywall presentation. | yes |
| willDismissPaywall | paywallInfo: PaywallInfo | Called before paywall dismissal. | yes |
| didDismissPaywall | paywallInfo: PaywallInfo | Called after paywall dismissal. | yes |
| userAttributesDidChange | newAttributes: Map\ | Called when user attributes change outside your app (for example via the \`Set Attribute\` paywall action). | yes |
## Returns / State
All delegate methods return `Unit`. They provide information about Superwall events and state changes.
## Usage
Basic delegate setup:
```kotlin
class MainActivity : AppCompatActivity(), SuperwallDelegate {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
Superwall.instance.delegate = this
}
}
```
Track subscription status changes:
```kotlin
override fun subscriptionStatusDidChange(
from: SubscriptionStatus,
to: SubscriptionStatus
) {
println("Subscription changed from $from to $to")
updateUI(to)
}
```
Forward analytics events:
```kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when (val event = eventInfo.event) {
is SuperwallEvent.PaywallOpen -> {
Analytics.track("paywall_opened", mapOf(
"paywall_id" to event.paywallInfo.id,
"placement" to event.paywallInfo.placement
))
}
is SuperwallEvent.TransactionComplete -> {
Analytics.track("subscription_purchased", mapOf(
"product_id" to event.product.id,
"paywall_id" to event.paywallInfo.id
))
}
else -> {
// Handle other events
}
}
}
```
Handle custom paywall actions:
```kotlin
override fun handleCustomPaywallAction(name: String) {
when (name) {
"help" -> presentHelpScreen()
"contact" -> presentContactForm()
else -> println("Unknown custom action: $name")
}
}
```
Handle paywall lifecycle:
```kotlin
override fun willPresentPaywall(paywallInfo: PaywallInfo) {
// Pause video, hide UI, etc.
pauseBackgroundTasks()
}
override fun didDismissPaywall(paywallInfo: PaywallInfo) {
// Resume video, show UI, etc.
resumeBackgroundTasks()
}
```
Handle user attributes changes:
```kotlin
override fun userAttributesDidChange(newAttributes: Map) {
// React to paywall-triggered attribute updates
println("User attributes updated: $newAttributes")
refreshProfileUI(newAttributes)
}
```
Java usage:
```java
public class MainActivity extends AppCompatActivity implements SuperwallDelegateJava {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Superwall.getInstance().setJavaDelegate(this);
}
@Override
public void subscriptionStatusDidChange(
SubscriptionStatus from,
SubscriptionStatus to
) {
System.out.println("Subscription changed from " + from + " to " + to);
updateUI(to);
}
}
```
---
# setUserAttributes()
Source: https://superwall.com/docs/android/sdk-reference/setUserAttributes
A function that sets user attributes for use in paywalls and analytics on the Superwall dashboard.
These attributes should not be used as a source of truth for sensitive information.
Keys beginning with `$` are reserved for Superwall internal use and will be ignored. Arrays and nested maps are not supported as values.
## Purpose
Sets custom user attributes that can be used in paywall personalization, audience filters, and analytics on the Superwall dashboard.
## Signature
```kotlin
fun Superwall.setUserAttributes(attributes: Map)
```
```java
// Java
public void setUserAttributes(Map attributes)
```
## Parameters
| Name | Type | Description | Required |
| ---------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| attributes | Map\ | A map of custom attributes to store for the user. Values can be any JSON encodable value, including strings, numbers, booleans, URLs, or timestamps. | yes |
## Returns / State
This function returns `Unit`. If an attribute already exists, its value will be overwritten while other attributes remain unchanged.
## Usage
Set multiple user attributes:
```kotlin
val attributes = mapOf(
"name" to "John Doe",
"email" to "john@example.com",
"plan" to "premium",
"signUpDate" to System.currentTimeMillis(),
"profilePicUrl" to "https://example.com/pic.jpg",
"isVip" to true,
"loginCount" to 42
)
Superwall.instance.setUserAttributes(attributes)
```
Set individual attributes over time:
```kotlin
Superwall.instance.setUserAttributes(mapOf("lastActiveDate" to System.currentTimeMillis()))
Superwall.instance.setUserAttributes(mapOf("featureUsageCount" to 15))
```
Remove an attribute by setting it to null:
```kotlin
Superwall.instance.setUserAttributes(mapOf("temporaryFlag" to null))
```
Real-world example after user updates profile:
```kotlin
fun updateUserProfile(user: User) {
Superwall.instance.setUserAttributes(mapOf(
"name" to user.displayName,
"avatar" to user.avatarURL,
"preferences" to user.notificationPreferences,
"lastUpdated" to System.currentTimeMillis()
))
}
```
Java usage:
```java
// Set multiple attributes
Map attributes = new HashMap<>();
attributes.put("name", "John Doe");
attributes.put("email", "john@example.com");
attributes.put("plan", "premium");
attributes.put("loginCount", 42);
Superwall.getInstance().setUserAttributes(attributes);
```
---
# SuperwallOptions
Source: https://superwall.com/docs/android/sdk-reference/SuperwallOptions
A configuration class for customizing paywall appearance and behavior.
Only modify `networkEnvironment` if explicitly instructed by the Superwall team. Use `.RELEASE` (default) for production apps.
Use different `SuperwallOptions` configurations for debug and release builds to optimize logging, purchasing behavior, and Google Play settings for each environment.
## Purpose
Configures paywall presentation, logging, Google Play purchase behavior, and other global SDK settings. Pass an instance in to [`Superwall.configure`](/android/sdk-reference/configure).
## Signature
```kotlin
class SuperwallOptions {
var paywalls: PaywallOptions = PaywallOptions()
var shouldObservePurchases: Boolean = false
var networkEnvironment: NetworkEnvironment = NetworkEnvironment.Release()
var isExternalDataCollectionEnabled: Boolean = true
var localeIdentifier: String? = null
var isGameControllerEnabled: Boolean = false
var passIdentifiersToPlayStore: Boolean = false
var enableExperimentalDeviceVariables: Boolean = false
var logging: Logging = Logging()
var useMockReviews: Boolean = false
}
```
```java
// Java
public class SuperwallOptions {
public PaywallOptions paywalls = new PaywallOptions();
public boolean shouldObservePurchases = false;
public NetworkEnvironment networkEnvironment = new NetworkEnvironment.Release();
public boolean isExternalDataCollectionEnabled = true;
public @Nullable String localeIdentifier = null;
public boolean isGameControllerEnabled = false;
public boolean passIdentifiersToPlayStore = false;
public boolean enableExperimentalDeviceVariables = false;
public Logging logging = new Logging();
public boolean useMockReviews = false;
}
```
## Parameters
| Name | Type | Description | Default | Required |
| --------------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------- | -------- |
| paywalls | PaywallOptions (see /android/sdk-reference/PaywallOptions) | Controls paywall presentation, preload, and alert behavior. | | yes |
| shouldObservePurchases | Boolean | Set to \`true\` to have Superwall observe Google Play purchases you make outside the SDK. | | yes |
| networkEnvironment | NetworkEnvironment | Overrides the API environment. \*\*Only change if instructed by Superwall.\*\* | | yes |
| isExternalDataCollectionEnabled | Boolean | Allows Superwall to send non-paywall analytics events to the backend. | true | no |
| localeIdentifier | String? | Overrides the locale used for rule evaluation (e.g., \`"en\_GB"\`). | | no |
| isGameControllerEnabled | Boolean | Forwards game controller events to paywalls. | | yes |
| passIdentifiersToPlayStore | Boolean | When \`true\`, Google Play receives the raw \`userId\` as \`obfuscatedExternalAccountId\`; otherwise Superwall sends a SHA-256 hash. | | yes |
| enableExperimentalDeviceVariables | Boolean | Enables experimental device variables (subject to change). | | yes |
| logging | Logging | Sets log level and scopes printed to Logcat. | | yes |
| useMockReviews | Boolean | Shows mock Google Play review dialogs for testing. | | yes |
## How `passIdentifiersToPlayStore` affects Google Play
Superwall always calls `BillingFlowParams.Builder.setObfuscatedAccountId(Superwall.instance.externalAccountId)` when launching a billing flow.
* **Default (`false`)** – `externalAccountId` is a SHA-256 hash of the `userId`. Google Play displays the hashed value as `obfuscatedExternalAccountId`, and the same hash is sent back to your servers.
* **Enabled (`true`)** – Superwall forwards the exact `appUserId` you passed to [`identify()`](/android/sdk-reference/identify). This makes it easier to correlate Google Play purchases with your users, but the value must comply with [Google's policy](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId) and must not contain PII.
Configure it as part of your application startup:
```kotlin
val options = SuperwallOptions().apply {
passIdentifiersToPlayStore = true
logging.level = LogLevel.info
}
Superwall.configure(
application = this,
apiKey = "pk_your_api_key",
options = options
)
```
## Related
* [`PaywallOptions`](/android/sdk-reference/PaywallOptions)
---
# Overview
Source: https://superwall.com/docs/android/sdk-reference
Reference documentation for the Superwall Android SDK.
## Welcome to the Superwall Android SDK Reference
You can find the source code for the SDK [on GitHub](https://github.com/superwall/Superwall-Android) along with our [example app](https://github.com/superwall/Superwall-Android/tree/develop/example).
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-android/issues).
---
# Tracking Subscription State
Source: https://superwall.com/docs/android/quickstart/tracking-subscription-state
Here's how to view whether or not a user is on a paid plan in Android.
Superwall tracks the subscription state of a user for you. However, there are times in your app where you need to know if a user is on a paid plan or not. For example, you might want to conditionally show certain UI elements or enable premium features based on their subscription status.
## Using subscriptionStatus
The easiest way to track subscription status in Android is by accessing the `subscriptionStatus` StateFlow:
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Get current status
val status = Superwall.instance.subscriptionStatus.value
when (status) {
is SubscriptionStatus.Active -> {
Log.d("Superwall", "User has active entitlements: ${status.entitlements}")
showPremiumContent()
}
is SubscriptionStatus.Inactive -> {
Log.d("Superwall", "User is on free plan")
showFreeContent()
}
is SubscriptionStatus.Unknown -> {
Log.d("Superwall", "Subscription status unknown")
showLoadingState()
}
}
}
}
```
The `SubscriptionStatus` sealed class has three possible states:
* `SubscriptionStatus.Unknown` - Status is not yet determined
* `SubscriptionStatus.Active(Set)` - User has active entitlements (set of entitlement identifiers)
* `SubscriptionStatus.Inactive` - User has no active entitlements
## Observing subscription status changes
You can observe real-time subscription status changes using Kotlin's StateFlow:
```kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
lifecycleScope.launch {
Superwall.instance.subscriptionStatus.collect { status ->
when (status) {
is SubscriptionStatus.Active -> {
Log.d("Superwall", "User upgraded to pro!")
updateUiForPremiumUser()
}
is SubscriptionStatus.Inactive -> {
Log.d("Superwall", "User is on free plan")
updateUiForFreeUser()
}
is SubscriptionStatus.Unknown -> {
Log.d("Superwall", "Loading subscription status...")
showLoadingState()
}
}
}
}
}
}
```
## Using with Jetpack Compose
If you're using Jetpack Compose, you can observe subscription status reactively:
```kotlin
@Composable
fun ContentScreen() {
val subscriptionStatus by Superwall.instance.subscriptionStatus
.collectAsState()
Column {
when (subscriptionStatus) {
is SubscriptionStatus.Active -> {
val entitlements = (subscriptionStatus as SubscriptionStatus.Active).entitlements
Text("Premium user with: ${entitlements.joinToString()}")
PremiumContent()
}
is SubscriptionStatus.Inactive -> {
Text("Free user")
FreeContent()
}
is SubscriptionStatus.Unknown -> {
Text("Loading...")
LoadingIndicator()
}
}
}
}
```
## Checking for specific entitlements
If your app has multiple subscription tiers (e.g., Bronze, Silver, Gold), you can check for specific entitlements:
```kotlin
val status = Superwall.instance.subscriptionStatus.value
when (status) {
is SubscriptionStatus.Active -> {
if (status.entitlements.contains("gold")) {
// Show gold-tier features
showGoldFeatures()
} else if (status.entitlements.contains("silver")) {
// Show silver-tier features
showSilverFeatures()
}
}
else -> showFreeFeatures()
}
```
## Setting subscription status
When using Superwall with a custom purchase controller or third-party billing service, you need to manually update the subscription status. Here's how to sync with RevenueCat:
```kotlin
class RevenueCatPurchaseController : PurchaseController {
override suspend fun purchase(
activity: Activity,
product: StoreProduct
): PurchaseResult {
return try {
val result = Purchases.sharedInstance.purchase(activity, product.sku)
// Update Superwall subscription status based on RevenueCat result
if (result.isSuccessful) {
val entitlements = result.customerInfo.entitlements.active.keys
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(entitlements)
)
PurchaseResult.Purchased
} else {
PurchaseResult.Failed(Exception("Purchase failed"))
}
} catch (e: Exception) {
PurchaseResult.Failed(e)
}
}
override suspend fun restorePurchases(): RestorationResult {
return try {
val customerInfo = Purchases.sharedInstance.restorePurchases()
val activeEntitlements = customerInfo.entitlements.active.keys
if (activeEntitlements.isNotEmpty()) {
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(activeEntitlements)
)
} else {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
}
RestorationResult.Restored
} catch (e: Exception) {
RestorationResult.Failed(e)
}
}
}
```
You can also listen for subscription changes from your billing service:
```kotlin
class SubscriptionManager {
fun syncSubscriptionStatus() {
Purchases.sharedInstance.getCustomerInfoWith { customerInfo ->
val activeEntitlements = customerInfo.entitlements.active.keys
if (activeEntitlements.isNotEmpty()) {
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(activeEntitlements)
)
} else {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
}
}
}
}
```
## Using SuperwallDelegate
You can also listen for subscription status changes using the `SuperwallDelegate`:
```kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(
applicationContext = this,
apiKey = "YOUR_API_KEY",
options = SuperwallOptions().apply {
delegate = object : SuperwallDelegate() {
override fun subscriptionStatusDidChange(
from: SubscriptionStatus,
to: SubscriptionStatus
) {
when (to) {
is SubscriptionStatus.Active -> {
Log.d("Superwall", "User is now premium")
}
is SubscriptionStatus.Inactive -> {
Log.d("Superwall", "User is now free")
}
is SubscriptionStatus.Unknown -> {
Log.d("Superwall", "Status unknown")
}
}
}
}
}
)
}
}
```
## Superwall checks subscription status for you
Remember that the Superwall SDK uses its [audience filters](/campaigns-audience#matching-to-entitlements) for determining when to show paywalls. You generally don't need to wrap your calls to register placements with subscription status checks:
```kotlin
// ❌ Unnecessary
if (Superwall.instance.subscriptionStatus.value !is SubscriptionStatus.Active) {
Superwall.instance.register("campaign_trigger")
}
// ✅ Just register the placement
Superwall.instance.register("campaign_trigger")
```
In your [audience filters](/campaigns-audience#matching-to-entitlements), you can specify whether the subscription state should be considered, which keeps your codebase cleaner and puts the "Should this paywall show?" logic where it belongs—in the Superwall dashboard.
---
# Setting User Attributes
Source: https://superwall.com/docs/android/quickstart/setting-user-properties
undefined
By setting user attributes, you can display information about the user on the paywall. You can also define [audiences](/campaigns-audience) in a campaign to determine which paywall to show to a user, based on their user attributes.
If a paywall uses the **Set user attributes** action, the merged attributes are sent back to your app via `SuperwallDelegate.userAttributesDidChange(newAttributes:)`.
You do this by passing a `[String: Any?]` dictionary of attributes to `Superwall.shared.setUserAttributes(_:)`:
:::android
```kotlin Kotlin
val attributes = mapOf(
"name" to user.name,
"apnsToken" to user.apnsTokenString,
"email" to user.email,
"username" to user.username,
"profilePic" to user.profilePicUrl,
"stripe_customer_id" to user.stripeCustomerId // Optional: For Stripe checkout prefilling
)
Superwall.instance.setUserAttributes(attributes) // (merges existing attributes)
```
:::
## Usage
This is a merge operation, such that if the existing user attributes dictionary
already has a value for a given property, the old value is overwritten. Other
existing properties will not be affected. To unset/delete a value, you can pass `nil`
for the value.
You can reference user attributes in [audience filters](/campaigns-audience) to help decide when to display your paywall. When you configure your paywall, you can also reference the user attributes in its text variables. For more information on how to that, see [Configuring a Paywall](/paywall-editor-overview).
---
# Presenting Paywalls
Source: https://superwall.com/docs/android/quickstart/feature-gating
Control access to premium features with Superwall placements.
This allows you to register a [placement](/campaigns-placements) to access a feature that may or may not be paywalled later in time. It also allows you to choose whether the user can access the feature even if they don't make a purchase.
Here's an example.
#### With Superwall
:::android
```kotlin Kotlin
fun pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.instance.register("StartWorkout") {
navigation.startWorkout()
}
}
```
:::
#### Without Superwall
:::android
```kotlin Kotlin
fun pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout()
} else {
navigation.presentPaywall { result ->
if (result) {
navigation.startWorkout()
} else {
// user didn't pay, developer decides what to do
}
}
}
}
```
:::
### How registering placements presents paywalls
You can configure `"StartWorkout"` to present a paywall by [creating a campaign, adding the placement, and adding a paywall to an audience](/campaigns) in the dashboard.
1. The SDK retrieves your campaign settings from the dashboard on app launch.
2. When a placement is called that belongs to a campaign, audiences are evaluated ***on device*** and the user enters an experiment — this means there's no delay between registering a placement and presenting a paywall.
3. If it's the first time a user is entering an experiment, a paywall is decided for the user based on the percentages you set in the dashboard
4. Once a user is assigned a paywall for an audience, they will continue to see that paywall until you remove the paywall from the audience or reset assignments to the paywall.
5. After the paywall is closed, the Superwall SDK looks at the *Feature Gating* value associated with your paywall, configurable from the paywall editor under General > Feature Gating (more on this below)
1. If the paywall is set to ***Non Gated***, the `feature:` closure on `register(placement: ...)` gets called when the paywall is dismissed (whether they paid or not)
2. If the paywall is set to ***Gated***, the `feature:` closure on `register(placement: ...)` gets called only if the user is already paying or if they begin paying.
6. If no paywall is configured, the feature gets executed immediately without any additional network calls.
Given the low cost nature of how register works, we strongly recommend registering **all core functionality** in order to remotely configure which features you want to gate – **without an app update**.
:::android
```kotlin 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()
}
}
```
:::
### Automatically Registered Placements
The SDK [automatically registers](/tracking-analytics) some internal placements which can be used to present paywalls:
### Register. Everything.
To provide your team with ultimate flexibility, we recommend registering *all* of your analytics events, even if you don't pass feature blocks through. This way you can retroactively add a paywall almost anywhere – **without an app update**!
If you're already set up with an analytics provider, you'll typically have an `Analytics.swift` singleton (or similar) to disperse all your events from. Here's how that file might look:
### Getting a presentation result
Use `getPresentationResult(forPlacement:params:)` when you need to ask the SDK what would happen when registering a placement — without actually showing a paywall. Superwall evaluates the placement and its audience filters then returns a `PresentationResult`. You can use this to adapt your app's behavior based on the outcome (such as showing a lock icon next to a pro feature if they aren't subscribed).
In short, this lets you peek at the outcome first and decide how your app should respond:
---
# Configure the SDK
Source: https://superwall.com/docs/android/quickstart/configure
undefined
As soon as your app launches, you need to configure the SDK with your **Public API Key**. You'll retrieve this from the Superwall settings page.
### Sign Up & Grab Keys
If you haven't already, [sign up for a free account](https://superwall.com/sign-up) on Superwall. Then, when you're through to the Dashboard, click **Settings** from the panel on the left, click **Keys** and copy your **Public API Key**:
### Initialize Superwall in your app
Begin by editing your main Application entrypoint. Depending on the
platform this could be `AppDelegate.swift` or `SceneDelegate.swift` for iOS,
`MainApplication.kt` for Android, `main.dart` in Flutter, or `App.tsx` for React Native:
:::android
```kotlin Kotlin
// MainApplication.kt
class MainApplication : android.app.Application(), SuperwallDelegate {
override fun onCreate() {
super.onCreate()
// Setup
Superwall.configure(this, "MY_API_KEY")
// OR using the DSL
configureSuperwall("MY_API_KEY") {
purchaseController = MyPurchaseController(this@MainApplication)
}
}
}
```
:::
This configures a shared instance of `Superwall`, the primary class for interacting with the SDK's API. Make sure to replace `MY_API_KEY` with your public API key that you just retrieved.
By default, Superwall handles basic subscription-related logic for you. However, if you’d like
greater control over this process (e.g. if you’re using RevenueCat), you’ll want to pass in a
`PurchaseController` to your configuration call and manually set the `subscriptionStatus`. You can
also pass in `SuperwallOptions` to customize the appearance and behavior of the SDK. See
[Purchases and Subscription Status](/advanced-configuration) for more.
You've now configured Superwall!
:::android
For further help, check out our [Android example apps](https://github.com/superwall/Superwall-Android/tree/master/Examples) for working examples of implementing the Superwall SDK.
:::
---
# User Management
Source: https://superwall.com/docs/android/quickstart/user-management
undefined
### Anonymous Users
Superwall automatically generates a random user ID that persists internally until the user deletes/reinstalls your app.
You can call `Superwall.shared.reset()` to reset this ID and clear any paywall assignments.
### Identified Users
If you use your own user management system, call `identify(userId:options:)` when you have a user's identity. This will alias your `userId` with the anonymous Superwall ID enabling us to load the user’s assigned paywalls.
Calling `Superwall.shared.reset()` will reset the on-device userId to a random ID and clear the paywall assignments.
:::android
Google Play receives the identifier you pass to `BillingFlowParams.Builder.setObfuscatedAccountId` as both the **`obfuscatedExternalAccountId`** and the `externalAccountId` we forward to your Superwall backend. By default we SHA-256 hash your `userId` before sending it. If you want the raw `appUserId` to appear in Play Console and downstream server events, set `SuperwallOptions().passIdentifiersToPlayStore = true` before configuring the SDK. Make sure the value complies with [Google's policies](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId)—it must not contain personally identifiable information.
:::
:::android
```kotlin Kotlin
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.instance.identify(user.id)
// When the user signs out
Superwall.instance.reset()
```
:::
**Advanced Use Case**
You can supply an `IdentityOptions` object, whose property `restorePaywallAssignments` you can set to `true`. This tells the SDK to wait to restore paywall assignments from the server before presenting any paywalls. This should only be used in advanced use cases. If you expect users of your app to switch accounts or delete/reinstall a lot, you'd set this when users log in to an existing account.
### Best Practices for a Unique User ID
* Do NOT make your User IDs guessable – they are public facing.
* Do NOT set emails as User IDs – this isn't GDPR compliant.
* Do NOT set IDFA or DeviceIds as User IDs – these are device specific / easily rotated by the operating system.
* Do NOT hardcode strings as User IDs – this will cause every user to be treated as the same user by Superwall.
### Identifying users from App Store server events
On iOS, Superwall always supplies an [`appAccountToken`](https://developer.apple.com/documentation/storekit/product/purchaseoption/3749440-appaccounttoken) with every StoreKit 2 transaction:
| Scenario | Value used for `appAccountToken` |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| You’ve called `Superwall.shared.identify(userId:)` | The exact `userId` you passed |
| You *haven’t* called `identify` yet | The UUID automatically generated for the anonymous user (the **alias ID**), **without** the `$SuperwallAlias:` prefix |
| You passed a non‑UUID `userId` to `identify` | StoreKit rejects it; Superwall falls back to the alias UUID |
Because the SDK falls back to the alias UUID, purchase notifications sent to your server always include a stable, unique identifier—even before the user signs in.
```swift
// Generate and use a UUID user ID in Swift
let userId = UUID().uuidString
Superwall.shared.identify(userId: userId)
```
---
# Install the SDK
Source: https://superwall.com/docs/android/quickstart/install
Install the Superwall Android SDK via Gradle.
## Overview
To see the latest release, [check out the repository](https://github.com/superwall/Superwall-Android)
## Install via Gradle
[Gradle](https://developer.android.com/build/releases/gradle-plugin) is the
preferred way to install Superwall for Android.
In your `build.gradle` or `build.gradle.kts` add the latest Superwall SDK. You
can find the [latest release here](https://github.com/superwall/Superwall-Android/releases).
```groovy build.gradle
implementation "com.superwall.sdk:superwall-android:2.6.5"
```
```kotlin build.gradle.kts
implementation("com.superwall.sdk:superwall-android:2.6.5")
```
```toml libs.version.toml
[libraries]
superwall-android = { group = "com.superwall.sdk", name = "superwall-android", version = "2.6.5" }
// And in your build.gradle.kts
dependencies {
implementation(libs.superwall.android)
}
```
Make sure to run **Sync Now** to force Android Studio to update.
Go to your `AndroidManifest.xml` and add the following permissions:
```xml AndroidManifest.xml
```
Then add our Activity to your `AndroidManifest.xml`:
```xml AndroidManifest.xml
```
Set your app's theme in the `android:theme` section.
When choosing a device or emulator to run on make sure that it has the Play Store app and that you are signed in to your Google account on the Play Store.
**And you're done!** Now you're ready to configure the SDK 👇
---
# Handling Deep Links
Source: https://superwall.com/docs/android/quickstart/in-app-paywall-previews
undefined
1. Previewing paywalls on your device before going live.
2. Deep linking to specific [campaigns](/campaigns).
3. Web Checkout [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting)
## Setup
:::android
The way to deep link into your app is URL Schemes.
:::
### Adding a Custom URL Scheme
:::android
Add the following to your `AndroidManifest.xml` file:
```xml
```
This configuration allows your app to open in response to a deep link with the format `exampleapp://` from your `MainActivity` class.
:::
### Handling Deep Links
:::android
In your `MainActivity` (or the activity specified in your intent-filter), add the following Kotlin code to handle deep links:
```kotlin Kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Respond to deep links
respondToDeepLinks()
}
private fun respondToDeepLinks() {
intent?.data?.let { uri ->
Superwall.instance.handleDeepLink(uri)
}
}
}
```
:::
::::android
### Handling App Links
## Adding app links
Android App links enable seamless integration between the Web checkout and your app,
enabling users to redeem the purchase automatically.
To allow Android app links to open your app, you will need to follow these steps:
## 1. Add your app's fingerprint and schema to Stripe settings
To verify that the request to open the app is legitimate, Android requires your app's keystore SHA256 fingerprint, with at least one for your development keystore and one for your release keystore. You can obtain these fingerprints in the following way:
#### Development fingerprints
If you're using Android studio or have Android components installed, you can obtain your debug key by running the following command in your terminal:
`keytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass android -keypass android`
And then copying the outputted SHA256 fingerprint.
#### Release fingerprints
To obtain the release fingerprints, you'll need your own keystore file (the one you use to sign the final application package before publishing).
You can do this by running the following command in your terminal:
`keytool -list -v -keystore -alias `
And then copying the outputted SHA256 fingerprint.
#### Adding the fingerprints to the project
To add the fingerprints to Superwall, open the Settings tab of your Superwall Stripe application.
Under the `Android Configuration` title, you should see three fields:
* Package schema - this allows us to know which schema your app uses to open and parse deep links
* Package name - your app's package name, i.e. `com.mydomain.myapp`
* App fingerprints - One or more of your app's fingerprints, comma separated
Once added, click the `Update Configuration` button which will ensure the application asset links are properly generated for Google to verify.
### 2. Add the schema to your app's Android Manifest
For this, you'll need to copy the domain from your Superwall Stripe settings.
Then, open your `AndroidManifest.xml` and inside the `` tag declaring your deep link handling activity, add the following, replacing the domain with the one from the settings:
```xml
```
### 3. Handle incoming deep links using Superwall SDK
In the same activity as in step #2, you'll need to pass deeplinks along to Superwall SDK.
You can do this by overriding your Activity's `onCreate` and `onNewIntent` methods and passing along the intent data to Superwall using `Superwall.handleDeepLinks()` method. The method returns a `kotlin.Result` indicating if the deep link will be handled by Superwall SDK.
```kotlin
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// your onCreate code
intent?.data?.let { uri ->
Superwall.handleDeepLink(uri)
}
}
override fun onNewIntent(intent: Intent, caller: ComponentCaller) {
super.onNewIntent(intent, caller)
// ... Your onNewIntent code
intent?.data?.let { uri ->
Superwall.handleDeepLink(uri)
}
}
```
### 4. Handling links while testing
If you are running your app using Android Studio, you need to be aware that it won't automatically allow verified links to be opened using the app, but you will need to enable it in settings yourself. This is not the case when installing from Play Store, and all the links will be handled automatically.
To do that, once you install the app on your device, open:
`Settings > Apps > Your Application Name > Open By Default`
Under there, the `Open supported links` should be enabled.
Tap `Add Links` button and selected the available links.
### Testing & more details
For details regarding testing and setup, you can refer to [Android's guide for verifying app links](https://developer.android.com/training/app-links/verify-android-applinks).
Note - Superwall generates the assetlinks.json for you. To check the file, you can use the subdomain from your Superwall stripe configuation:
`https://my-app.superwall.app/.well-known/assetlinks.json`
:::android
:::
::::
## Previewing Paywalls
Next, build and run your app on your phone.
Then, head to the Superwall Dashboard. Click on **Settings** from the Dashboard panel on the left, then select **General**:
With the **General** tab selected, type your custom URL scheme, without slashes, into the **Apple Custom URL Scheme** field:
Next, open your paywall from the dashboard and click **Preview**. You'll see a QR code appear in a pop-up:
On your device, scan this QR code. You can do this via Apple's Camera app. This will take you to a paywall viewer within your app, where you can preview all your paywalls in different configurations.
## Using Deep Links to Present Paywalls
Deep links can also be used as a placement in a campaign to present paywalls. Simply add `deepLink_open` as an placement, and the URL parameters of the deep link can be used as parameters! You can also use custom placements for this purpose. [Read this doc](/presenting-paywalls-from-one-another) for examples of both.
---
# Post-Checkout Redirecting
Source: https://superwall.com/docs/android/guides/web-checkout/post-checkout-redirecting
Learn how to handle users redirecting back to your app after a web purchase.
After a user completes a web purchase, Superwall needs to redirect them back to your app. You can configure this behavior in two ways:
## Post-Purchase Behavior Modes
You can configure how users are redirected after checkout in your [Application Settings](/web-checkout-configuring-stripe-keys-and-settings#post-purchase-behavior):
### Redeem Mode (Default)
Superwall manages the entire redemption experience:
* Users are automatically deep linked to your app with a redemption code
* Fallback to App Store/Play Store if the app isn't installed
* Redemption emails are sent automatically
* The SDK handles redemption via delegate methods (detailed below)
This is the recommended mode for most apps.
### Redirect Mode
Redirect users to your own custom URL with purchase information:
* **When to use**: You want to show a custom success page, perform additional actions before redemption, or have your own deep linking infrastructure
* **What you receive**: Purchase data is passed as query parameters to your URL
**Query Parameters Included**:
* `app_user_id` - The user's identifier from your app
* `email` - User's email address
* `stripe_subscription_id` - The Stripe subscription ID
* Any custom placement parameters you set
**Example**:
```
https://yourapp.com/success?
app_user_id=user_123&
email=user@example.com&
stripe_subscription_id=sub_1234567890&
campaign_id=summer_sale
```
You'll need to implement your own logic to handle the redirect and deep link users into your app.
***
## Setting Up Deep Links
Whether you're showing a checkout page in a browser or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app.
#### Prerequisites
1. [Configuring Stripe Keys and Settings](/web-checkout-configuring-stripe-keys-and-settings)
2. [Deep Links](/in-app-paywall-previews)
If you're not using Superwall to handle purchases, then you'll need to follow extra steps to redeem the web purchase in your app.
* [Using RevenueCat](/web-checkout-using-revenuecat)
* [Using a PurchaseController](/web-checkout-linking-membership-to-iOS-app#using-a-purchasecontroller)
***
## Handling Redemption (Redeem Mode)
When using Redeem mode (the default), handle the user experience when they're redirected back to your app using `SuperwallDelegate` methods:
### willRedeemLink
When your app opens via the deep link, we will call the delegate method `willRedeemLink()` before making a network call to redeem the code.
At this point, you might wish to display a loading indicator in your app so the user knows that the purchase is being redeemed.
```kotlin
class SWDelegate : SuperwallDelegate {
override fun willRedeemLink() {
// Show a loading indicator to the user
showToast("Activating your purchase...")
}
}
```
You can manually dismiss the paywall at this point if needed, but note that the paywall will be dismissed automatically when the `didRedeemLink` method is called.
### didRedeemLink
After receiving a response from the network, we will call `didRedeemLink(result:)` with the result of redeeming the code. This result can be one of the following:
* `RedemptionResult.Success`: The redemption succeeded and contains information about the redeemed code.
* `RedemptionResult.Error`: An error occurred while redeeming. You can check the error message via the error parameter.
* `RedemptionResult.ExpiredCode`: The code expired and contains information about whether a redemption email has been resent and an optional obfuscated email address.
* `RedemptionResult.InvalidCode`: The code that was redeemed was invalid.
* `RedemptionResult.ExpiredSubscription`: The subscription that the code redeemed has expired.
On network failure, the SDK will retry up to 6 times before returning an `Error` `RedemptionResult` in `didRedeemLink(result:)`.
Here, you should remove any loading UI you added in `willRedeemLink` and show a message to the user based on the result. If a paywall is presented, it will be dismissed automatically.
```kotlin
class SWDelegate : SuperwallDelegate {
override fun didRedeemLink(result: RedemptionResult) {
when (result) {
is RedemptionResult.ExpiredCode -> {
showToast("Expired Link")
Log.d("Superwall", "Code expired: ${result.code}, ${result.expiredInfo}")
}
is RedemptionResult.Error -> {
showToast(result.error.message)
Log.d("Superwall", "Error: ${result.code}, ${result.error}")
}
is RedemptionResult.ExpiredSubscription -> {
showToast("Expired Subscription")
Log.d("Superwall", "Expired subscription: ${result.code}, ${result.redemptionInfo}")
}
is RedemptionResult.InvalidCode -> {
showToast("Invalid Link")
Log.d("Superwall", "Invalid code: ${result.code}")
}
is RedemptionResult.Success -> {
val email = result.redemptionInfo.purchaserInfo.email
val productIdentifier = result.redemptionInfo.paywallInfo?.productIdentifier
if (email != null) {
Superwall.instance.setUserAttributes(mapOf("email" to email))
showToast("Welcome, $email!")
} else {
showToast("Welcome!")
}
// Access the product identifier if available (2.6.3+)
productIdentifier?.let {
Log.d("Superwall", "Redeemed product: $it")
}
}
}
}
}
```
---
# Redeeming In-App
Source: https://superwall.com/docs/android/guides/web-checkout/linking-membership-to-iOS-app
Handle a deep link in your app and use the delegate methods.
After purchasing from a web paywall, the user will be redirected to your app by a deep link to redeem their purchase on device.
Please follow our [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting) guide to handle this user experience.
If you're using Superwall to handle purchases, then you don't need to do anything here.
If you're using your own `PurchaseController`, you will need to update the subscription status with the redeemed web entitlements. If you're using RevenueCat, you should follow our [Using RevenueCat](/web-checkout-using-revenuecat) guide.
### Using a PurchaseController
If you're using Google Play Billing in your PurchaseController, you'll need to merge the web entitlements with the device entitlements before setting the subscription status.
Here's an example of how you might do this:
```kotlin
import com.android.billingclient.api.BillingClient
import com.android.billingclient.api.Purchase
import com.android.billingclient.api.QueryPurchasesParams
import com.superwall.sdk.Superwall
import com.superwall.sdk.models.entitlements.SubscriptionStatus
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
suspend fun syncSubscriptionStatus(billingClient: BillingClient) {
withContext(Dispatchers.IO) {
val productIds = mutableSetOf()
// Get the device entitlements from Google Play Billing
val params = QueryPurchasesParams.newBuilder()
.setProductType(BillingClient.ProductType.SUBS)
.build()
val purchasesResult = billingClient.queryPurchasesAsync(params)
// Collect purchased product IDs
purchasesResult.purchasesList.forEach { purchase ->
if (purchase.purchaseState == Purchase.PurchaseState.PURCHASED) {
purchase.products.forEach { productId ->
productIds.add(productId)
}
}
}
// Get products from Superwall and extract their entitlements
val storeProducts = Superwall.instance.getProducts(productIds)
val deviceEntitlements = storeProducts.flatMap { it.entitlements }.toSet()
// Get the web entitlements from Superwall
val webEntitlements = Superwall.instance.entitlements.web
// Merge the two sets of entitlements
val allEntitlements = deviceEntitlements + webEntitlements
// Update subscription status on the main thread
withContext(Dispatchers.Main) {
if (allEntitlements.isNotEmpty()) {
Superwall.instance.setSubscriptionStatus(
SubscriptionStatus.Active(allEntitlements)
)
} else {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive)
}
}
}
}
```
In addition to syncing the subscription status when purchasing and restoring, you'll need to sync it whenever `didRedeemLink(result:)` is called:
```kotlin
import com.superwall.sdk.delegate.SuperwallDelegate
import com.superwall.sdk.models.redemption.RedemptionResult
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
class SWDelegate(private val billingClient: BillingClient) : SuperwallDelegate {
private val coroutineScope = CoroutineScope(Dispatchers.Main)
override fun didRedeemLink(result: RedemptionResult) {
coroutineScope.launch {
syncSubscriptionStatus(billingClient)
}
}
}
```
### Refreshing of web entitlements
If you aren't using a Purchase Controller, the SDK will refresh the web entitlements every 24 hours.
### Redeeming while a paywall is open
If a redeem event occurs when a paywall is open, the SDK will track that as a restore event and the paywall will close.
---
# Using RevenueCat
Source: https://superwall.com/docs/android/guides/web-checkout/using-revenuecat
Handle a deep link in your app and use the delegate methods to link web checkouts with RevenueCat.
After purchasing from a web paywall, the user will be redirected to your app by a deep link to redeem their purchase on device. Please follow our [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting) guide to handle this user experience.
If you're using Superwall to handle purchases, then you don't need to do anything here.
You only need to use a `PurchaseController` if you want end-to-end control of the purchasing pipeline. The recommended way to use RevenueCat with Superwall is by putting it in observer mode.
If you're using your own `PurchaseController`, you should follow our [Redeeming In-App](/web-checkout-linking-membership-to-iOS-app) guide.
### Using a PurchaseController with RevenueCat
If you're using RevenueCat, you'll need to follow [steps 1 to 4 in their guide](https://www.revenuecat.com/docs/web/integrations/stripe) to set up Stripe with RevenueCat. Then, you'll need to
associate the RevenueCat customer with the Stripe subscription IDs returned from redeeming the code. You can do this by extracting the ids from the `RedemptionResult` and sending them to RevenueCat's API
by using the `didRedeemLink(result:)` delegate method:
```kotlin
import com.revenuecat.purchases.Purchases
import com.superwall.sdk.Superwall
import com.superwall.sdk.delegate.SuperwallDelegate
import com.superwall.sdk.models.redemption.RedemptionResult
import kotlinx.coroutines.CoroutineScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import okhttp3.MediaType.Companion.toMediaType
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import org.json.JSONObject
import java.io.IOException
class SWDelegate : SuperwallDelegate {
private val client = OkHttpClient()
private val coroutineScope = CoroutineScope(Dispatchers.IO)
// The user tapped on a deep link to redeem a code
override fun willRedeemLink() {
Log.d("Superwall", "[!] willRedeemLink")
// Optionally show a loading indicator here
}
// Superwall received a redemption result and validated the purchase with Stripe.
override fun didRedeemLink(result: RedemptionResult) {
Log.d("Superwall", "[!] didRedeemLink: $result")
// Send Stripe IDs to RevenueCat to link purchases to the customer
// Get a list of subscription ids tied to the customer.
val stripeSubscriptionIds = when (result) {
is RedemptionResult.Success -> result.stripeSubscriptionIds
else -> null
} ?: return
val revenueCatStripePublicAPIKey = "strp....." // replace with your RevenueCat Stripe Public API Key
val appUserId = Purchases.sharedInstance.appUserID
// In the background using coroutines...
coroutineScope.launch {
// For each subscription id, link it to the user in RevenueCat
stripeSubscriptionIds.forEach { stripeSubscriptionId ->
try {
val json = JSONObject().apply {
put("app_user_id", appUserId)
put("fetch_token", stripeSubscriptionId)
}
val requestBody = json.toString()
.toRequestBody("application/json".toMediaType())
val request = Request.Builder()
.url("https://api.revenuecat.com/v1/receipts")
.post(requestBody)
.addHeader("Content-Type", "application/json")
.addHeader("Accept", "application/json")
.addHeader("X-Platform", "stripe")
.addHeader("Authorization", "Bearer $revenueCatStripePublicAPIKey")
.build()
client.newCall(request).execute().use { response ->
val responseBody = response.body?.string().orEmpty()
if (!response.isSuccessful) {
throw IOException("RevenueCat responded with ${response.code}: $responseBody")
}
Log.d("Superwall", "[!] Success: linked $stripeSubscriptionId to user $appUserId: $responseBody")
}
} catch (e: Exception) {
Log.e("Superwall", "[!] Error: unable to link $stripeSubscriptionId to user $appUserId", e)
}
}
/// After all network calls complete, invalidate the cache
Purchases.sharedInstance.getCustomerInfo(
onSuccess = { customerInfo ->
/// If you're using RevenueCat's `UpdatedCustomerInfoListener`, or keeping Superwall Entitlements in sync
/// via RevenueCat's listener methods, you don't need to do anything here. Those methods will be
/// called automatically when this call fetches the most up to date customer info, ignoring any local caches.
/// Otherwise, if you're manually calling `Purchases.sharedInstance.getCustomerInfo` to keep Superwall's entitlements
/// in sync, you should use the newly updated customer info here to do so.
/// You could always access web entitlements here as well
/// val webEntitlements = Superwall.instance.entitlements.web
},
onError = { error ->
Log.e("Superwall", "Error getting customer info", error)
}
)
// After all network calls complete, update UI on the main thread
withContext(Dispatchers.Main) {
// Perform UI updates on the main thread, like letting the user know their subscription was redeemed
}
}
}
}
```
The example surfaces non-200 responses and network exceptions so you can add retries, user messaging,
or monitoring. Customize the error handling to fit your production logging and UX.
If you call `logIn` from RevenueCat's SDK, then you need to call the logic you've implemented
inside `didRedeemLink(result:)` again. For example, that means if `logIn` was invoked from
RevenueCat, you'd either abstract out this logic above into a function to call again, or simply
call this function directly.
The web entitlements will be returned along with other existing entitlements in the `CustomerInfo` object accessible via RevenueCat's SDK.
If you're logging in and out of RevenueCat, make sure to resend the Stripe subscription IDs to RevenueCat's endpoint after logging in.
---
# Web Checkout
Source: https://superwall.com/docs/android/guides/web-checkout
Integrate Superwall web checkout with your iOS app for seamless cross-platform subscriptions
## Dashboard Setup
1. [Set up Web Checkout in the dashboard](/web-checkout/web-checkout-overview)
2. [Add web products to your paywall](/web-checkout/web-checkout-direct-stripe-checkout)
## SDK Setup
1. [Set up deep links](/sdk/quickstart/in-app-paywall-previews)
2. [Handle Post-Checkout redirecting](/sdk/guides/web-checkout/post-checkout-redirecting)
3. **Only if you're using RevenueCat:** [Using RevenueCat](/sdk/guides/web-checkout/using-revenuecat)
4. **Only if you're using your own PurchaseController:** [Redeeming In-App](/sdk/guides/web-checkout/linking-membership-to-iOS-app)
## Testing
1. [Testing Purchases](/web-checkout/web-checkout-testing-purchases)
2. [Managing Memberships](/web-checkout/web-checkout-managing-memberships)
## Troubleshooting
If a user has issues accessing their subscription in your app after paying via web checkout, direct them to your plan management page to retrieve their subscription link or manage billing:
For example: `http://yourapp.superwall.app/manage`
## FAQ
[Web Checkout FAQ](/web-checkout/web-checkout-faq)
---
# Migrating from v1 to v2 - Android
Source: https://superwall.com/docs/android/guides/migrations/migrating-to-v2
SuperwallKit 2.0 is a major release of Superwall's Android SDK. This introduces breaking changes.
## Migration steps
## 1. Update code references
### 1.1 Rename references from `event` to `placement`
In some most cases, the updates are simple and consist of renaming `events` to `placements` where necessary, for others, you'll need to run through this list to manually update your code.
| Before | After |
| ------------------------------------ | ---------------------------------------- |
| fun register(event:) | fun register(placement:) |
| fun preloadPaywalls(forEvents:) | fun preloadPaywalls(forPlacements:) |
| fun getPaywall(forEvent:) | fun getPaywall(forPlacement:) |
| fun getPresentationResult(forEvent:) | fun getPresentationResult(forPlacement:) |
| TriggerResult.EventNotFound | TriggerResult.PlacementNotFound |
| TriggerResult.NoRuleMatch | TriggerResult.NoAudienceMatch |
### 1.2 If using Compose and Paywall Composable
The `PaywallComposable` has been removed from the main Superwall SDK and moved into an optional `superwall-compose` library.
To use it, besides including the main superwall library, you'll now need to also include a `superwall-compose` artifact
```groovy gradle
implementation "com.superwall.sdk:superwall-compose:2.6.5"
```
## 2. Replacing getPaywall with PaywallBuilder
The default method for retrieving a paywall to display it yourself is changing to use the Builder pattern, allowing you more flexibility
in both retrieving and displaying paywalls. The builder allows for improved customisation of your paywall experience, allowing you to pass
in both custom Shimmer and Loading views by implementing proper interfaces.
Usage example:
```kotlin Android
val paywallView = PaywallBuilder("placement_name")
.params(mapOf("key" to "value"))
.overrides(PaywallOverrides())
.delegate(mySuperwallDelegate)
.shimmerView(MyShimmerView(context))
.purchaseLoadingView(MyPurchaseLoadingView(context))
.activity(activity)
.build()
```
### 3. Getting the purchased product
The `onDismiss` block of the `PaywallPresentationHandler` now accepts both a `PaywallInfo` object and a `PaywallResult` object. This allows you to easily access
the purchased product from the result when the paywall dismisses.
### 4. Entitlements
The `subscriptionStatus` has been changed to accept a set of `Entitlement` objects. This allows you to give access to entitlements based on products purchased.
For example, in your app you might have Bronze, Silver, and Gold subscription tiers, i.e. entitlements, which entitle a user to access a certain set of features within your app.
Every subscription product must be associated with one or more entitlements, which is controlled via the dashboard. Superwall will already have associated all your
products with a default entitlement. If you don't use more than one entitlement tier within your app and you only use subscription products, you don't need to do anything extra.
However, if you use one-time purchases or multiple entitlements, you should review your products and their entitlements. In general, consumables should not be associated with an
entitlement, whereas non-consumables should be. Check your products [here](https://superwall.com/applications/\:app/products/v2).
If you're using a `PurchaseController`, you'll need to set the `entitlements` with the `subscriptionStatus`:
| Before | After |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Superwall.shared.setSubscriptionStatus(SubscriptionStatus.ACTIVE) | Superwall.shared.setSubscriptionStatus(SubscriptionStatus.Active(entitlements)) |
You can get the `ProductDetails` and their associated entitlements from Superwall by calling the method `products(for:)`. Here is an example of how you'd sync your subscription
status with Superwall using these methods:
```kotlin With Play Billing
suspend fun syncSubscriptionStatus() {
// We await for configuration to be set so our entitlements are available
Superwall.instance.configurationStateListener.first { it is ConfigurationStatus.Configured }
// Query purchases from your BillingClient
val subscriptionPurchases = queryPurchasesOfType(BillingClient.ProductType.SUBS)
val inAppPurchases = queryPurchasesOfType(BillingClient.ProductType.INAPP)
val allPurchases = subscriptionPurchases + inAppPurchases
val hasActivePurchaseOrSubscription =
allPurchases.any { it.purchaseState == Purchase.PurchaseState.PURCHASED }
val status: SubscriptionStatus =
if (hasActivePurchaseOrSubscription) {
subscriptionPurchases
.flatMap {
// Extract the productId
it.products
}.toSet() // Ensure uniqueness
.flatMap {
// Receive entitlements
val res = entitlementsInfo.byProductId(it)
res
}.toSet()
.let { entitlements ->
if (entitlements.isNotEmpty()) {
SubscriptionStatus.Active(entitlements)
} else {
SubscriptionStatus.Inactive
}
}
} else {
SubscriptionStatus.Inactive
}
Superwall.instance.setSubscriptionStatus(status)
}
```
```kotlin with RevenueCat
fun syncSubscriptionStatus() {
Purchases.sharedInstance.getCustomerInfoWith {
if (hasAnyActiveEntitlements(it)) {
setSubscriptionStatus(
SubscriptionStatus.Active(
it.entitlements.active
.map {
Entitlement(it.key, Entitlement.Type.SERVICE_LEVEL)
}.toSet(),
),
)
} else {
setSubscriptionStatus(SubscriptionStatus.Inactive)
}
}
}
```
You can listen to the flowable property `Superwall.instance.subscriptionStatus` to be notified when the subscriptionStatus changes. Or you can use the `SuperwallDelegate`
method `subscriptionStatusDidChange(from:to:)`, which replaces `subscriptionStatusDidChange(to:)`.
### 5. Paywall Presentation Condition
In the Paywall Editor you can choose whether to always present a paywall or ask the SDK to check the user subscription before presenting a paywall.
For users on v2 of the SDK, this is replaced with a check on the entitlements within the audience filter. As you migrate your users from v1 to v2 of the
SDK, you'll need to make sure you set both the entitlements check and the paywall presentation condition in the paywall editor.
## 6. Check out the full change log
You can view this on [our GitHub page](https://github.com/superwall/Superwall-Android/blob/develop/CHANGELOG.md).
## 7. Check out our updated example apps
All of our [example apps](https://github.com/superwall/Superwall-Android/tree/develop/example) have been updated to use the latest SDK. We now only have two apps: Basic and Advanced. Basic shows you the basic integration of Superwall
without needing a purchase controller or multiple entitlements. Advanced has multiple flavors, showing you how to use entitlements within your app as well as optionally using a purchase controller with Play Billing or RevenueCat.
---
# Using the Presentation Handler
Source: https://superwall.com/docs/android/guides/advanced/using-the-presentation-handler
undefined
You can provide a `PaywallPresentationHandler` to `register`, whose functions provide status updates for a paywall:
* `onDismiss`: Called when the paywall is dismissed. Accepts a `PaywallInfo` object containing info about the dismissed paywall, and there is a `PaywallResult` informing you of any transaction.
* `onPresent`: Called when the paywall did present. Accepts a `PaywallInfo` object containing info about the presented paywall.
* `onError`: Called when an error occurred when trying to present a paywall. Accepts an `Error` indicating why the paywall could not present.
* `onSkip`: Called when a paywall is skipped. Accepts a `PaywallSkippedReason` enum indicating why the paywall was skipped.
```swift Swift
let handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result in
print("The paywall dismissed. PaywallInfo: \(paywallInfo). Result: \(result)")
}
handler.onPresent { paywallInfo in
print("The paywall presented. PaywallInfo:", paywallInfo)
}
handler.onError { error in
print("The paywall presentation failed with error \(error)")
}
handler.onSkip { reason in
switch reason {
case .holdout(let experiment):
print("Paywall not shown because user is in a holdout group in Experiment: \(experiment.id)")
case .noAudienceMatch:
print("Paywall not shown because user doesn't match any audiences.")
case .placementNotFound:
print("Paywall not shown because this placement isn't part of a campaign.")
}
}
Superwall.shared.register(placement: "campaign_trigger", handler: handler) {
// Feature launched
}
```
```swift Objective-C
SWKPaywallPresentationHandler *handler = [[SWKPaywallPresentationHandler alloc] init];
[handler onDismiss:^(SWKPaywallInfo * _Nonnull paywallInfo,
enum SWKPaywallResult result,
SWKStoreProduct * _Nullable product) {
NSLog(@"The paywall presented. PaywallInfo: %@ - result: %ld", paywallInfo, (long)result);
}];
[handler onPresent:^(SWKPaywallInfo * _Nonnull paywallInfo) {
NSLog(@"The paywall presented. PaywallInfo: %@", paywallInfo);
}];
[handler onError:^(NSError * _Nonnull error) {
NSLog(@"The paywall presentation failed with error %@", error);
}];
[handler onSkip:^(enum SWKPaywallSkippedReason reason) {
switch (reason) {
case SWKPaywallSkippedReasonUserIsSubscribed:
NSLog(@"Paywall not shown because user is subscribed.");
break;
case SWKPaywallSkippedReasonHoldout:
NSLog(@"Paywall not shown because user is in a holdout group.");
break;
case SWKPaywallSkippedReasonNoAudienceMatch:
NSLog(@"Paywall not shown because user doesn't match any audiences.");
break;
case SWKPaywallSkippedReasonPlacementNotFound:
NSLog(@"Paywall not shown because this placement isn't part of a campaign.");
break;
case SWKPaywallSkippedReasonNone:
// The paywall wasn't skipped.
break;
}
}];
[[Superwall sharedInstance] registerWithPlacement:@"campaign_trigger" params:nil handler:handler feature:^{
// Feature launched.
}];
```
```kotlin Kotlin
val handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result ->
println("The paywall dismissed. PaywallInfo: ${it}")
}
handler.onPresent {
println("The paywall presented. PaywallInfo: ${it}")
}
handler.onError {
println("The paywall errored. Error: ${it}")
}
handler.onSkip {
when (it) {
is PaywallSkippedReason.PlacementNotFound -> {
println("The paywall was skipped because the placement was not found.")
}
is PaywallSkippedReason.Holdout -> {
println("The paywall was skipped because the user is in a holdout group.")
}
is PaywallSkippedReason.NoAudienceMatch -> {
println("The paywall was skipped because no audience matched.")
}
}
}
Superwall.instance.register(placement = "campaign_trigger", handler = handler) {
// Feature launched
}
```
```dart Flutter
PaywallPresentationHandler handler = PaywallPresentationHandler();
handler.onPresent((paywallInfo) async {
String name = await paywallInfo.name;
print("Handler (onPresent): $name");
});
handler.onDismiss((paywallInfo, paywallResult) async {
String name = await paywallInfo.name;
print("Handler (onDismiss): $name");
});
handler.onError((error) {
print("Handler (onError): ${error}");
});
handler.onSkip((skipReason) async {
String description = await skipReason.description;
if (skipReason is PaywallSkippedReasonHoldout) {
print("Handler (onSkip): $description");
final experiment = await skipReason.experiment;
final experimentId = await experiment.id;
print("Holdout with experiment: ${experimentId}");
} else if (skipReason is PaywallSkippedReasonNoAudienceMatch) {
print("Handler (onSkip): $description");
} else if (skipReason is PaywallSkippedReasonPlacementNotFound) {
print("Handler (onSkip): $description");
} else {
print("Handler (onSkip): Unknown skip reason");
}
});
Superwall.shared.registerPlacement("campaign_trigger", handler: handler, feature: () {
// Feature launched
});
```
```typescript React Native
const handler = new PaywallPresentationHandler()
handler.onPresent((paywallInfo) => {
const name = paywallInfo.name
console.log(`Handler (onPresent): ${name}`)
})
handler.onDismiss((paywallInfo, paywallResult) => {
const name = paywallInfo.name
console.log(`Handler (onDismiss): ${name}`)
})
handler.onError((error) => {
console.log(`Handler (onError): ${error}`)
})
handler.onSkip((skipReason) => {
const description = skipReason.description
if (skipReason instanceof PaywallSkippedReasonHoldout) {
console.log(`Handler (onSkip): ${description}`)
const experiment = skipReason.experiment
const experimentId = experiment.id
console.log(`Holdout with experiment: ${experimentId}`)
} else if (skipReason instanceof PaywallSkippedReasonNoAudienceMatch) {
console.log(`Handler (onSkip): ${description}`)
} else if (skipReason instanceof PaywallSkippedReasonPlacementNotFound) {
console.log(`Handler (onSkip): ${description}`)
} else {
console.log(`Handler (onSkip): Unknown skip reason`)
}
})
Superwall.shared.register({
placement: 'campaign_trigger',
handler: handler,
feature: () => {
// Feature launched
}
});
```
Wanting to see which product was just purchased from a paywall? Use `onDismiss` and the `result`
parameter. Or, you can use the
[SuperwallDelegate](/3rd-party-analytics#using-events-to-see-purchased-products).
---
# Observer Mode
Source: https://superwall.com/docs/android/guides/advanced/observer-mode
undefined
If you wish to make purchases outside of Superwall's SDK and paywalls, you can use **observer mode** to report purchases that will appear in the Superwall dashboard, such as transactions:
This is useful if you are using Superwall solely for revenue tracking, and you're making purchases using frameworks like StoreKit or Google Play Billing Library directly. Observer mode will also properly link user identifiers to transactions. To enable observer mode, set it using `SuperwallOptions` when configuring the SDK:
:::android
```kotlin Android (Automatic)
val options = SuperwallOptions()
options.shouldObservePurchases = true
Superwall.configure(this, "your_api_key", options = options)
// In your purchase methods, replace Google's billing code with Superwall's proxy
val productDetailsParams =
SuperwallBillingFlowParams.ProductDetailsParams
.newBuilder()
.setOfferToken("test_offer_token")
.setProductDetails(mockProductDetails)
.build()
val params =
SuperwallBillingFlowParams
.newBuilder()
.setIsOfferPersonalized(true)
.setObfuscatedAccountId(...)
.setObfuscatedProfileId(...)
.setProductDetailsParamsList(listOf(productDetailsParams))
.build()
billingClient.launchBillingFlowWithSuperwall()
```
```kotlin Android (Manual)
val options = SuperwallOptions()
options.shouldObservePurchases = true
Superwall.configure(this, "your_api_key", options = options)
// In your purchase methods, begin by tracking the purchase start
Superwall.instance.observePurchaseStart(productDetails)
// On succesful purchase
Superwall.instance.observePurchaseResult(billingResult, purchases)
// On purchase error
Superwall.instance.observePurchaseError(productDetails, error)
```
:::
There are a few things to keep in mind when using observer mode:
1. On iOS, if you're using StoreKit 2, then Superwall solely reports transaction completions. If you're using StoreKit 1, then Superwall will report transaction starts, abandons, and completions.
2. When using observer mode, you can't make purchases using our SDK — such as `Superwall.shared.purchase(aProduct)`.
For more on setting up revenue tracking, check out this [doc](/overview-settings-revenue-tracking).
---
# Viewing Purchased Products
Source: https://superwall.com/docs/android/guides/advanced/viewing-purchased-products
undefined
When a paywall is presenting and a user converts, you can view the purchased products in several different ways.
### Use the `PaywallPresentationHandler`
Arguably the easiest of the options — simply pass in a presentation handler and check out the product within the `onDismiss` block.
```swift Swift
let handler = PaywallPresentationHandler()
handler.onDismiss { _, result in
switch result {
case .declined:
print("No purchased occurred.")
case .purchased(let product):
print("Purchased \(product.productIdentifier)")
case .restored:
print("Restored purchases.")
}
}
Superwall.shared.register(placement: "caffeineLogged", handler: handler) {
logCaffeine()
}
```
```swift Objective-C
SWKPaywallPresentationHandler *handler = [SWKPaywallPresentationHandler new];
[handler onDismiss:^(SWKPaywallInfo * _Nonnull info,
enum SWKPaywallResult result,
SWKStoreProduct * _Nullable product) {
switch (result) {
case SWKPaywallResultPurchased:
NSLog(@"Purchased %@", product.productIdentifier);
default:
NSLog(@"Unhandled event.");
}
}];
[[Superwall sharedInstance] registerWithPlacement:@"caffeineLogged"
params:@{}
handler:handler
feature:^{
[self logCaffeine];
}];
```
```kotlin Android
val handler = PaywallPresentationHandler()
handler.onDismiss { _, paywallResult ->
when (paywallResult) {
is PaywallResult.Purchased -> {
// The user made a purchase!
val purchasedProductId = paywallResult.productId
println("User purchased product: $purchasedProductId")
// ... do something with the purchased product ID ...
}
is PaywallResult.Declined -> {
// The user declined to make a purchase.
println("User declined to make a purchase.")
// ... handle the declined case ...
}
is PaywallResult.Restored -> {
// The user restored a purchase.
println("User restored a purchase.")
// ... handle the restored case ...
}
}
}
Superwall.instance.register(placement = "caffeineLogged", handler = handler) {
logCaffeine()
}
```
```dart Flutter
PaywallPresentationHandler handler = PaywallPresentationHandler();
handler.onDismiss((paywallInfo, paywallResult) async {
String name = await paywallInfo.name;
print("Handler (onDismiss): $name");
switch (paywallResult) {
case PurchasedPaywallResult(productId: var id):
// The user made a purchase!
print('User purchased product: $id');
// ... do something with the purchased product ID ...
break;
case DeclinedPaywallResult():
// The user declined to make a purchase.
print('User declined the paywall.');
// ... handle the declined case ...
break;
case RestoredPaywallResult():
// The user restored a purchase.
print('User restored a previous purchase.');
// ... handle the restored case ...
break;
}
});
Superwall.shared.registerPlacement(
"caffeineLogged", handler: handler, feature: () {
logCaffeine();
});
```
```typescript React Native
import * as React from "react"
import Superwall from "../../src"
import { PaywallPresentationHandler, PaywallInfo } from "../../src"
import type { PaywallResult } from "../../src/public/PaywallResult"
const Home = () => {
const navigation = useNavigation()
const presentationHandler: PaywallPresentationHandler = {
onDismiss: (handler: (info: PaywallInfo, result: PaywallResult) => void) => {
handler = (info, result) => {
console.log("Paywall dismissed with info:", info, "and result:", result)
if (result.type === "purchased") {
console.log("Product purchased with ID:", result.productId)
}
}
},
onPresent: (handler: (info: PaywallInfo) => void) => {
handler = (info) => {
console.log("Paywall presented with info:", info)
// Add logic for when the paywall is presented
}
},
onError: (handler: (error: string) => void) => {
handler = (error) => {
console.error("Error presenting paywall:", error)
// Handle any errors that occur during presentation
}
},
onSkip: () => {
console.log("Paywall presentation skipped")
// Handle the case where the paywall presentation is skipped
},
}
const nonGated = () => {
Superwall.shared.register({ placement: "non_gated", handler: presentationHandler, feature: () => {
navigation.navigate("caffeineLogged", {
value: "Go for caffeine logging",
})
});
}
return // Your view code here
}
```
### Use `SuperwallDelegate`
Next, the [SuperwallDelegate](/using-superwall-delegate) offers up much more information, and can inform you of virtually any Superwall event that occurred:
```swift Swift
class SWDelegate: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case .transactionComplete(_, let product, _, _):
print("Transaction complete: product: \(product.productIdentifier)")
case .subscriptionStart(let product, _):
print("Subscription start: product: \(product.productIdentifier)")
case .freeTrialStart(let product, _):
print("Free trial start: product: \(product.productIdentifier)")
case .transactionRestore(_, _):
print("Transaction restored")
case .nonRecurringProductPurchase(let product, _):
print("Consumable product purchased: \(product.id)")
default:
print("Unhandled event.")
}
}
}
@main
struct Caffeine_PalApp: App {
@State private var swDelegate: SWDelegate = .init()
init() {
Superwall.configure(apiKey: "my_api_key")
Superwall.shared.delegate = swDelegate
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
```swift Objective-C
// SWDelegate.h...
#import
@import SuperwallKit;
NS_ASSUME_NONNULL_BEGIN
@interface SWDelegate : NSObject
@end
NS_ASSUME_NONNULL_END
// SWDelegate.m...
@implementation SWDelegate
- (void)handleSuperwallEventWithInfo:(SWKSuperwallEventInfo *)eventInfo {
switch(eventInfo.event) {
case SWKSuperwallEventTransactionComplete:
NSLog(@"Transaction complete: %@", eventInfo.params[@"primary_product_id"]);
}
}
// In AppDelegate.m...
#import "AppDelegate.h"
#import "SWDelegate.h"
@import SuperwallKit;
@interface AppDelegate ()
@property (strong, nonatomic) SWDelegate *delegate;
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
self.delegate = [SWDelegate new];
[Superwall configureWithApiKey:@"my_api_key"];
[Superwall sharedInstance].delegate = self.delegate;
return YES;
}
```
```kotlin Android
class SWDelegate : SuperwallDelegate {
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when (eventInfo.event) {
is SuperwallPlacement.TransactionComplete -> {
val transaction = (eventInfo.event as SuperwallPlacement.TransactionComplete).transaction
val product = (eventInfo.event as SuperwallPlacement.TransactionComplete).product
val paywallInfo = (eventInfo.event as SuperwallPlacement.TransactionComplete).paywallInfo
println("Transaction Complete: $transaction, Product: $product, Paywall Info: $paywallInfo")
}
else -> {
// Handle other cases
}
}
}
}
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "my_api_key")
Superwall.instance.delegate = SWDelegate()
}
}
```
```dart Flutter
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart';
class _MyAppState extends State implements SuperwallDelegate {
final logging = Logging();
@override
void initState() {
super.initState();
configureSuperwall(useRevenueCat);
}
Future configureSuperwall(bool useRevenueCat) async {
try {
final apiKey = Platform.isIOS
? 'ios_api_project_key'
: 'android_api_project_key';
final logging = Logging();
logging.level = LogLevel.warn;
logging.scopes = {LogScope.all};
final options = SuperwallOptions();
options.paywalls.shouldPreload = false;
options.logging = logging;
Superwall.configure(apiKey,
purchaseController: null,
options: options, completion: () {
logging.info('Executing Superwall configure completion block');
});
Superwall.shared.setDelegate(this);
} catch (e) {
// Handle any errors that occur during configuration
logging.error('Failed to configure Superwall:', e);
}
}
@override
Future handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
switch (eventInfo.event.type) {
case PlacementType.transactionComplete:
final product = eventInfo.params?['product'];
logging.info('Transaction complete event received with product: $product');
// Add any additional logic you need to handle the transaction complete event
break;
// Handle other events if necessary
default:
logging.info('Unhandled event type: ${eventInfo.event.type}');
break;
}
}
}
```
```typescript React Native
import {
PaywallInfo,
SubscriptionStatus,
SuperwallDelegate,
SuperwallPlacementInfo,
PlacementType,
} from '../../src';
export class MySuperwallDelegate extends SuperwallDelegate {
handleSuperwallPlacement(placementInfo: SuperwallPlacementInfo) {
console.log('Handling Superwall placement:', placementInfo);
switch (placementInfo.placement.type) {
case PlacementType.transactionComplete:
const product = placementInfo.params?.["product"];
if (product) {
console.log(`Product: ${product}`);
} else {
console.log("Product not found in params.");
}
break;
default:
break;
}
}
}
export default function App() {
const delegate = new MySuperwallDelegate();
React.useEffect(() => {
const setupSuperwall = async () => {
const apiKey =
Platform.OS === 'ios'
? 'ios_api_project_key'
: 'android_api_project_key';
Superwall.configure({
apiKey: apiKey,
});
Superwall.shared.setDelegate(delegate);
};
}
}
```
### Use a purchase controller
If you are controlling the purchasing pipeline yourself via a [purchase controller](/advanced-configuration), then naturally the purchased product is available:
```swift Swift
final class MyPurchaseController: PurchaseController {
func purchase(product: StoreProduct) async -> PurchaseResult {
print("Kicking off purchase of \(product.productIdentifier)")
do {
let result = try await MyPurchaseLogic.purchase(product: product)
return .purchased // .cancelled, .pending, .failed(Error)
} catch {
return .failed(error)
}
}
// 2
func restorePurchases() async -> RestorationResult {
print("Restoring purchases")
return .restored // false
}
}
@main
struct Caffeine_PalApp: App {
private let pc: MyPurchaseController = .init()
init() {
Superwall.configure(apiKey: "my_api_key", purchaseController: pc)
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
```swift Objective-C
// In MyPurchaseController.h...
#import
@import SuperwallKit;
@import StoreKit;
NS_ASSUME_NONNULL_BEGIN
@interface MyPurchaseController : NSObject
+ (instancetype)sharedInstance;
@end
NS_ASSUME_NONNULL_END
// In MyPurchaseController.m...
#import "MyPurchaseController.h"
@implementation MyPurchaseController
+ (instancetype)sharedInstance
{
static MyPurchaseController *sharedInstance = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
sharedInstance = [MyPurchaseController new];
});
return sharedInstance;
}
- (void)purchaseWithProduct:(SWKStoreProduct * _Nonnull)product
completion:(void (^ _Nonnull)(enum SWKPurchaseResult, NSError * _Nullable))completion {
NSLog(@"Kicking off purchase of %@", product.productIdentifier);
// Do purchase logic here
completion(SWKPurchaseResultPurchased, nil);
}
- (void)restorePurchasesWithCompletion:(void (^ _Nonnull)(enum SWKRestorationResult, NSError * _Nullable))completion {
// Do restore logic here
completion(SWKRestorationResultRestored, nil);
}
@end
// In AppDelegate.m...
#import "AppDelegate.h"
#import "MyPurchaseController.h"
@import SuperwallKit;
@interface AppDelegate ()
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
[Superwall configureWithApiKey:@"my_api_key"
purchaseController:[MyPurchaseController sharedInstance]
options:nil
completion:^{
}];
return YES;
}
```
```kotlin Android
class MyPurchaseController(val context: Context): PurchaseController {
override suspend fun purchase(
activity: Activity,
productDetails: ProductDetails,
basePlanId: String?,
offerId: String?
): PurchaseResult {
println("Kicking off purchase of $basePlanId")
return PurchaseResult.Purchased()
}
override suspend fun restorePurchases(): RestorationResult {
TODO("Not yet implemented")
}
}
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "my_api_key", purchaseController = MyPurchaseController(this))
}
}
```
```dart Flutter
class MyPurchaseController extends PurchaseController {
// 1
@override
Future purchaseFromAppStore(String productId) async {
print('Attempting to purchase product with ID: $productId');
// Do purchase logic
return PurchaseResult.purchased;
}
@override
Future purchaseFromGooglePlay(
String productId,
String? basePlanId,
String? offerId
) async {
print('Attempting to purchase product with ID: $productId and basePlanId: $basePlanId');
// Do purchase logic
return PurchaseResult.purchased;
}
@override
Future restorePurchases() async {
// Do resture logic
}
}
```
```typescript React Native
export class MyPurchaseController extends PurchaseController {
// 1
async purchaseFromAppStore(productId: string): Promise {
console.log("Kicking off purchase of ", productId)
// Purchase logic
return await this._purchaseStoreProduct(storeProduct)
}
async purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise {
console.log("Kicking off purchase of ", productId, " base plan ID", basePlanId)
// Purchase logic
return await this._purchaseStoreProduct(storeProduct)
}
// 2
async restorePurchases(): Promise {
// TODO
// ----
// Restore purchases and return true if successful.
}
}
```
### SwiftUI - Use `PaywallView`
The `PaywallView` allows you to show a paywall by sending it a placement. It also has a dismiss handler where the purchased product will be vended:
```swift
@main
struct Caffeine_PalApp: App {
@State private var presentPaywall: Bool = false
init() {
Superwall.configure(apiKey: "my_api_key")
}
var body: some Scene {
WindowGroup {
Button("Log") {
presentPaywall.toggle()
}
.sheet(isPresented: $presentPaywall) {
PaywallView(placement: "caffeineLogged", params: nil, paywallOverrides: nil) { info, result in
switch result {
case .declined:
print("No purchased occurred.")
case .purchased(let product):
print("Purchased \(product.productIdentifier)")
case .restored:
print("Restored purchases.")
}
} feature: {
print("Converted")
presentPaywall.toggle()
}
}
}
}
}
```
---
# Custom Paywall Actions
Source: https://superwall.com/docs/android/guides/advanced/custom-paywall-actions
undefined
For example, adding a custom action called `help_center` to a button in your paywall gives you the opportunity to present a help center whenever that button is pressed. To set this up, implement `handleCustomPaywallAction(withName:)` in your `SuperwallDelegate`:
:::android
```kotlin
override fun handleCustomPaywallAction(name: String) {
if (name == "help_center") {
HelpCenterManager.present()
}
}
```
:::
Remember to set `Superwall.shared.delegate`! For implementation details, see the [Superwall Delegate](/using-superwall-delegate) guide.
---
# Device Tier Targeting
Source: https://superwall.com/docs/android/guides/advanced/using-device-tiers-on-android
Target users based on their device performance capabilities to optimize paywall experiences across different hardware tiers.
The `deviceTier` variable allows you to create targeted audiences based on device performance capabilities. This helps optimize paywall experiences by showing resource-appropriate content to different device types. You can reference this in campaign filters, dynamic values, or in paywall text via the `device.deviceTier` variable.
Device tier targeting is available starting in Android SDK version `2.2.3`. Make sure you're using this version or later to access this feature.
## How device tier works
Device tier classification is based on several hardware factors:
* CPU performance
* Available RAM
* 4K/2K codec support
* Display quality
This automatic classification helps you deliver paywalls that perform well across the full spectrum of Android devices.
### Matching device ranges
When creating device tier filters, you can use `contains` or `equals` for narrower matching:
* **`contains`** - Broader matching that includes partial matches. For example, `deviceTier contains high` matches both `high` and `ultra_high` devices.
* **`equals`** - Exact matching for precise targeting. For example, `deviceTier equals high` matches only `high` tier devices, not `ultra_high`.
Use `contains` when you want to target a range of similar device capabilities, and `equals` when you need precise control over which specific tier to target.
## Device tier values
The `device.deviceTier` attribute returns one of these values:
* **`ultraLow`** - Entry-level devices with limited resources.
* **`low`** - Budget devices with basic performance capabilities.
* **`mid`** - Mid-range devices with moderate performance.
* **`high`** - Premium devices with strong performance.
* **`ultra_high`** - Flagship devices with top-tier specifications.
* **`unknown`** - Device tier couldn't be determined.
## Creating device tier audiences
To target users by device tier, create an audience using the `device.deviceTier` attribute:
1. Navigate to **Campaigns** in your dashboard.
2. Click on the campaign you want to target.
3. Edit, or create, a new audience.
4. Add a filter where `device.deviceTier` contains your target tier(s).
5. Save your audience.
You can target multiple tiers in a single audience. For example, use `deviceTier contains LOW` to target both `ultraLow` and `low` tier devices.
### Optimizing for lower-end devices
Create lightweight paywalls for devices that may struggle with resource-intensive content:
```
device.deviceTier contains ultraLow OR device.deviceTier contains low
```
Show these users paywalls with:
* Static images instead of videos.
* Compressed media files.
* Simplified animations.
---
# Purchasing Products Outside of a Paywall
Source: https://superwall.com/docs/android/guides/advanced/direct-purchasing
undefined
If you're using Superwall for revenue tracking, but want a hand with making purchases in your implementation, you can use our `purchase` methods:
:::android
```kotlin Android
// Purchase product with first available baseplan
Superwall.instance.purchase("my_product_id")
// Purchase product with base plan and cheapest/free offer
Superwall.instance.purchase("my_product_id:base_plan:sw-auto")
// Purchase product with a specified offer
Superwall.instance.purchase("my_product_id:base_plan:offer")
// Purchase product with no offer
Superwall.instance.purchase("my_product_id:base_plan:sw-none")
```
:::
For iOS, the `purchase()` method supports StoreKit 1, 2 and Superwall's abstraction over a product, `StoreProduct`. You can fetch the products you've added to Superwall via the `products(for:)` method. Similarly, in Android, you can fetch a product using a product identifier — and the first base plan will be selected:
:::android
```kotlin Android
val products = Superwall.instance.getProducts("id1", "id2")
```
:::
If you already have your own product fetching code, simply pass the product representation to these methods. For example, in StoreKit 1 — an `SKProduct` instance, in StoreKit 2, `Product`, etc. Each `purchase()` implementation returns a `PurchaseResult`, which informs you of the transaction's resolution:
* `.cancelled`: The purchase was cancelled.
* `.purchased`: The product was purchased.
* `.pending`: The purchase is pending/deferred and requires action from the developer.
* `.failed(Error)`: The purchase failed for a reason other than the user cancelling or the payment pending.
---
# Retrieving and Presenting a Paywall Yourself
Source: https://superwall.com/docs/android/guides/advanced/presenting-paywalls
undefined
If you want complete control over the paywall presentation process, you can use `getPaywall(forPlacement:params:paywallOverrides:delegate:)`. This returns the `UIViewController` subclass `PaywallViewController`, which you can then present however you like. Or, you can use a SwiftUI `View` via `PaywallView`. The following is code is how you'd mimic [register](/docs/feature-gating):
```swift Swift
final class MyViewController: UIViewController {
private func presentPaywall() async {
do {
// 1
let paywallVc = try await Superwall.shared.getPaywall(
forPlacement: "campaign_trigger",
delegate: self
)
self.present(paywallVc, animated: true)
} catch let skippedReason as PaywallSkippedReason {
// 2
switch skippedReason {
case .holdout,
.noAudienceMatch,
.placementNotFound:
break
}
} catch {
// 3
print(error)
}
}
private func launchFeature() {
// Insert code to launch a feature that's behind your paywall.
}
}
// 4
extension MyViewController: PaywallViewControllerDelegate {
func paywall(
_ paywall: PaywallViewController,
didFinishWith result: PaywallResult,
shouldDismiss: Bool
) {
if shouldDismiss {
paywall.dismiss(animated: true)
}
switch result {
case .purchased,
.restored:
launchFeature()
case .declined:
let closeReason = paywall.info.closeReason
let featureGating = paywall.info.featureGatingBehavior
if closeReason != .forNextPaywall && featureGating == .nonGated {
launchFeature()
}
}
}
}
```
```swift Objective-C
@interface MyViewController : UIViewController
- (void)presentPaywall;
@end
@interface MyViewController ()
@end
@implementation MyViewController
- (void)presentPaywall {
// 1
[[Superwall sharedInstance] getPaywallForEvent:@"campaign_trigger" params:nil paywallOverrides:nil delegate:self completion:^(SWKGetPaywallResult * _Nonnull result) {
if (result.paywall != nil) {
[self presentViewController:result.paywall animated:YES completion:nil];
} else if (result.skippedReason != SWKPaywallSkippedReasonNone) {
switch (result.skippedReason) {
// 2
case SWKPaywallSkippedReasonHoldout:
case SWKPaywallSkippedReasonUserIsSubscribed:
case SWKPaywallSkippedReasonEventNotFound:
case SWKPaywallSkippedReasonNoRuleMatch:
case SWKPaywallSkippedReasonNone:
break;
};
} else if (result.error) {
// 3
NSLog(@"%@", result.error);
}
}];
}
-(void)launchFeature {
// Insert code to launch a feature that's behind your paywall.
}
// 4
- (void)paywall:(SWKPaywallViewController *)paywall didFinishWithResult:(enum SWKPaywallResult)result shouldDismiss:(BOOL)shouldDismiss {
if (shouldDismiss) {
[paywall dismissViewControllerAnimated:true completion:nil];
}
SWKPaywallCloseReason closeReason;
SWKFeatureGatingBehavior featureGating;
switch (result) {
case SWKPaywallResultPurchased:
case SWKPaywallResultRestored:
[self launchFeature];
break;
case SWKPaywallResultDeclined:
closeReason = paywall.info.closeReason;
featureGating = paywall.info.featureGatingBehavior;
if (closeReason != SWKPaywallCloseReasonForNextPaywall && featureGating == SWKFeatureGatingBehaviorNonGated) {
[self launchFeature];
}
break;
}
}
@end
```
```swift SwiftUI
import SuperwallKit
struct MyAwesomeApp: App {
@State var store: AppStore = .init()
init() {
Superwall.configure(apiKey: "MyAPIKey")
}
var body: some Scene {
WindowGroup {
ContentView()
.fullScreenCover(isPresented: $store.showPaywall) {
// You can just use 'placement' at a minimum. The 'feature'
// Closure fires if they convert
PaywallView(placement: "a_placement", onSkippedView: { skip in
switch skip {
case .userIsSubscribed,
.holdout(_),
.noRuleMatch,
.eventNotFound:
MySkipView()
}
}, onErrorView: { error in
MyErrorView()
}, feature: {
// User is subscribed as a result of the paywall purchase
// Or they already were (which would happen in `onSkippedView`)
})
}
}
}
}
```
```kotlin Kotlin
// This is an example of how to use `getPaywall` to use a composable`
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.viewinterop.AndroidView
import com.superwall.sdk.Superwall
import com.superwall.sdk.paywall.presentation.get_paywall.getPaywall
import com.superwall.sdk.paywall.presentation.internal.request.PaywallOverrides
import com.superwall.sdk.paywall.vc.PaywallView
import com.superwall.sdk.paywall.vc.delegate.PaywallViewCallback
@Composable
fun PaywallComposable(
event: String,
params: Map? = null,
paywallOverrides: PaywallOverrides? = null,
callback: PaywallViewCallback,
errorComposable: @Composable ((Throwable) -> Unit) = { error: Throwable ->
// Default error composable
Text(text = "No paywall to display")
},
loadingComposable: @Composable (() -> Unit) = {
// Default loading composable
Box(modifier = Modifier.fillMaxSize()) {
Column(
modifier = Modifier.align(Alignment.Center),
verticalArrangement = Arrangement.Center,
horizontalAlignment = Alignment.CenterHorizontally
) {
CircularProgressIndicator()
}
}
}
) {
val viewState = remember { mutableStateOf(null) }
val errorState = remember { mutableStateOf(null) }
val context = LocalContext.current
LaunchedEffect(Unit) {
PaywallBuilder(event)
.params(params)
.overrides(paywallOverrides)
.delegate(delegate)
.activity(context as Activity)
.build()
.fold(onSuccess = {
viewState.value = it
}, onFailure = {
errorState.value = it
})
}
when {
viewState.value != null -> {
viewState.value?.let { viewToRender ->
DisposableEffect(viewToRender) {
viewToRender.onViewCreated()
onDispose {
viewToRender.beforeOnDestroy()
viewToRender.encapsulatingActivity = null
CoroutineScope(Dispatchers.Main).launch {
viewToRender.destroyed()
}
}
}
AndroidView(
factory = { context ->
viewToRender
}
)
}
}
errorState.value != null -> {
errorComposable(errorState.value!!)
}
else -> {
loadingComposable()
}
}
}
```
This does the following:
1. Gets the paywall view controller.
2. Handles the cases where the paywall was skipped.
3. Catches any presentation errors.
4. Implements the delegate. This is called when the user is finished with the paywall. First, it checks `shouldDismiss`. If this is true then is dismissed the paywall from view before launching any features. This may depend on the `result` depending on how you first presented your view. Then, it switches over the `result`. If the result is `purchased` or `restored` the feature can be launched. However, if the result is `declined`, it checks that the the `featureGating` property of `paywall.info` is `nonGated` and that the `closeReason` isn't `.forNextPaywall`.
### Best practices
1. **Make sure to prevent a paywall from being accessed after a purchase has occurred**.
If a user purchases from a paywall, it is your responsibility to make sure that the user can't access that paywall again. For example, if after successful purchase you decide to push a new view on to the navigation stack, you should make sure that the user can't go back to access the paywall.
2. **Make sure the paywall view controller deallocates before presenting it elsewhere**.
If you have a paywall view controller presented somewhere and you try to present
the same view controller elsewhere, you will get a crash. For example, you may
have a paywall in a tab bar controller, and then you also try to present it
modally. We plan on improving this, but currently it's your responsibility to
ensure this doesn't happen.
---
# Game Controller Support
Source: https://superwall.com/docs/android/guides/advanced/game-controller-support
undefined
:::android
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```kotlin
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
:::flutter
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```dart
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
:::expo
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```typescript
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
---
# Experimental Flags
Source: https://superwall.com/docs/android/guides/experimental-flags
undefined
Support for Experimental Flags in Android is not yet available.
---
# Advanced Purchasing
Source: https://superwall.com/docs/android/guides/advanced-configuration
If you need fine-grain control over the purchasing pipeline, use a purchase controller to manually handle purchases and subscription status.
Using a `PurchaseController` is only recommended for **advanced** use cases. By default, Superwall handles all
subscription-related logic and purchasing operations for you out of the box.
By default, Superwall handles basic subscription-related logic for you:
1. **Purchasing**: When the user initiates a checkout on a paywall.
2. **Restoring**: When the user restores previously purchased products.
3. **Subscription Status**: When the user's subscription status changes to active or expired (by checking the local receipt).
However, if you want more control, you can pass in a `PurchaseController` when configuring the SDK via `configure(apiKey:purchaseController:options:)` and manually set `Superwall.shared.subscriptionStatus` to take over this responsibility.
### Step 1: Creating a `PurchaseController`
A `PurchaseController` handles purchasing and restoring via protocol methods that you implement.
:::android
```kotlin Kotlin
// MyPurchaseController.kt
class MyPurchaseController(val context: Context): PurchaseController {
// 1
override suspend fun purchase(
activity: Activity,
productDetails: ProductDetails,
basePlanId: String?,
offerId: String?
): PurchaseResult {
// TODO
// ----
// Purchase via GoogleBilling, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.Purchased()
}
// 2
override suspend fun restorePurchases(): RestorationResult {
// TODO
// ----
// Restore purchases and return true if successful.
return RestorationResult.Success()
}
}
```
:::
Here’s what each method is responsible for:
1. Purchasing a given product. In here, enter your code that you use to purchase a product. Then, return the result of the purchase as a `PurchaseResult`. For Flutter, this is separated into purchasing from the App Store and Google Play. This is an enum that contains the following cases, all of which must be handled:
1. `.cancelled`: The purchase was cancelled.
2. `.purchased`: The product was purchased.
3. `.pending`: The purchase is pending/deferred and requires action from the developer.
4. `.failed(Error)`: The purchase failed for a reason other than the user cancelling or the payment pending.
2. Restoring purchases. Here, you restore purchases and return a `RestorationResult` indicating whether the restoration was successful or not. If it was, return `.restore`, or `failed` along with the error reason.
### Step 2: Configuring the SDK With Your `PurchaseController`
Pass your purchase controller to the `configure(apiKey:purchaseController:options:)` method:
:::android
```kotlin Kotlin
// MainApplication.kt
class MainApplication : android.app.Application(), SuperwallDelegate {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "MY_API_KEY", MyPurchaseController(this))
// OR using the DSL
configureSuperwall("MY_API_KEY") {
purchaseController = MyPurchaseController(this@MainApplication)
}
}
}
```
:::
### Step 3: Keeping `subscriptionStatus` Up-To-Date
You **must** set `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise the SDK won't know who to show a paywall to. This is an enum that has three possible cases:
1. **`.unknown`**: This is the default value. In this state, paywalls will not show and their presentation will be ***automatically delayed*** until `subscriptionStatus` changes to a different value.
2. **`.active(let entitlements)`**: Indicates that the user has an active entitlement. Paywalls will not show in this state unless you remotely set the paywall to ignore subscription status. A user can have one or more active entitlement.
3. **`.inactive`**: Indicates that the user doesn't have an active entitlement. Paywalls can show in this state.
Here's how you might do this:
:::android
```kotlin Kotlin
// When a subscription is purchased, restored, validated, expired, etc...
myService.subscriptionStatusDidChange {
if (it.hasActiveSubscription) {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Active(entitlements))
} else {
Superwall.instance.setSubscriptionStatus(SubscriptionStatus.Inactive(entitlements))
}
}
```
:::
`subscriptionStatus`
is cached between app launches
### Listening for subscription status changes
If you need a simple way to observe when a user's subscription status changes, on iOS you can use the `Publisher` for it. Here's an example:
:::android
```kotlin Kotlin
Superwall.instance.subscriptionStatus.collect { status: SubscriptionStatus ->
// React to changes
}
```
:::
You can do similar tasks with the `SuperwallDelegate`, such as [viewing which product was purchased from a paywall](/3rd-party-analytics#using-events-to-see-purchased-products).
### Product Overrides
Product overrides allow you to dynamically substitute products on paywalls without modifying the paywall design in the Superwall dashboard.
When using a `PurchaseController`, you may want to override specific products shown on your paywalls. This is useful for:
* A/B testing different subscription tiers
* Showing region-specific products
* Dynamically changing products based on user segments
* Testing promotional pricing without modifying paywalls
**How Product Overrides Work:**
1. Product names (e.g., "primary", "secondary") must match exactly as defined in the Superwall dashboard's Paywall Editor
2. The SDK substitutes the original product IDs with your override IDs before fetching from the App Store
3. The paywall maintains its visual design while showing the substituted products
4. Your `PurchaseController` will receive the overridden products when `purchase(product:)` is called
Product overrides only affect the products shown on paywalls. They don't change your subscription logic or entitlement validation.
---
# Cohorting in 3rd Party Tools
Source: https://superwall.com/docs/android/guides/3rd-party-analytics/cohorting-in-3rd-party-tools
To easily view Superwall cohorts in 3rd party tools, we recommend you set user attributes based on the experiments that users are included in. You can also use custom placements for creating analytics events for actions such as interacting with an element on a paywall.
:::android
```kotlin Kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when(eventInfo.event) {
is SuperwallEvent.TriggerFire -> {
MyAnalyticsService.shared.setUserAttributes(
mapOf(
"sw_experiment_${eventInfo.params.get("experiment_id").toString()}" to true,
"sw_variant_${eventInfo.params.get("variant_id").toString()}" to true
)
)
}
else -> {}
}
}
```
:::
:::flutter
```dart Flutter
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
final experimentId = eventInfo.params?['experiment_id'];
final variantId = eventInfo.params?['variant_id'];
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
"sw_experiment_$experimentId": true,
"sw_variant_$variantId": true
});
break;
default:
break;
}
}
```
:::
:::expo
```typescript React Native
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
const experimentId = eventInfo.params?['experiment_id']
const variantId = eventInfo.params?['variant_id']
if (!experimentId || !variantId) {
return
}
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
`sw_experiment_${experimentId}`: true,
`sw_variant_${variantId}`: true
});
break;
default:
break;
}
}
```
:::
Once you've set this up, you can easily ask for all users who have an attribute `sw_experiment_1234` and breakdown by both variants to see how users in a Superwall experiment behave in other areas of your app.
---
# Custom Paywall Analytics
Source: https://superwall.com/docs/android/guides/3rd-party-analytics/custom-paywall-analytics
Learn how to log events from paywalls, such as a button tap or product change, to forward to your analytics service.
You can create customized analytics tracking for any paywall event by using custom placements. With them, you can get callbacks for actions such as interacting with an element on a paywall sent to your [Superwall delegate](/using-superwall-delegate). This can be useful for tracking how users interact with your paywall and how that affects their behavior in other areas of your app.
For example, in the paywall below, perhaps you're interested in tracking when people switch the plan from "Standard" and "Pro":
You could create a custom placement [tap behavior](/paywall-editor-styling-elements#tap-behaviors) which fires when a segment is tapped:
Then, you can listen for this placement and forward it to your analytics service:
```swift Swift
extension SuperwallService: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case let .customPlacement(name, params, paywallInfo):
// Prints out didTapPro or didTapStandard
print("\(name) - \(params) - \(paywallInfo)")
MyAnalyticsService.shared.send(event: name, params: params)
default:
print("Default event: \(eventInfo.event.description)")
}
}
}
```
For a walkthrough example, check out this [video on YouTube](https://youtu.be/4rM1rGRqDL0).
---
# Superwall Events
Source: https://superwall.com/docs/android/guides/3rd-party-analytics/tracking-analytics
The SDK automatically tracks some events, which power the charts in the dashboard.
We encourage you to track them in your own analytics as described in [3rd Party Analytics](/3rd-party-analytics).
The following Superwall events can be used as placements to present paywalls:
* `app_install`
* `app_launch`
* `deepLink_open`
* `session_start`
* `paywall_decline`
* `transaction_fail`
* `transaction_abandon`
* `survey_response`
For more info about how to use these, check out [how to add them using a Placement](/campaigns-placements#adding-a-placement).
The full list of events is as follows:
| **Event Name** | **Action** | **Parameters** |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `adServicesTokenRequestComplete` | When the AdServices token request finishes. | `["token": String]` |
| `adServicesTokenRequestFail` | When the AdServices token request fails. | `["error": Error]` |
| `adServicesTokenRequestStart` | When the AdServices token request starts. | None |
| `app_close` | Anytime the app leaves the foreground. | Same as `app_install` |
| `app_install` | When the SDK is configured for the first time. | `["is_superwall": true, "app_session_id": String, "using_purchase_controller": Bool]` |
| `app_launch` | When the app is launched from a cold start. | Same as `app_install` |
| `app_open` | Anytime the app enters the foreground. | Same as `app_install` |
| `configAttributes` | When the attributes affecting Superwall's configuration are set or changed. | None |
| `configFail` | When the Superwall configuration fails to be retrieved. | None |
| `configRefresh` | When the Superwall configuration is refreshed. | None |
| `confirmAllAssignments` | When all experiment assignments are confirmed. | None |
| `customPlacement` | When the user taps on an element in the paywall that has a `custom_placement` action. | `["name": String, "params": [String: Any], "paywallInfo": PaywallInfo]` |
| [`deepLink_open`](/campaigns-standard-placements#using-the-deeplink-open-event) | When a user opens the app via a deep link. | `["url": String, "path": String", "pathExtension": String, "lastPathComponent": String, "host": String, "query": String, "fragment": String]` + any query parameters in the deep link URL |
| `device_attributes` | When device attributes are sent to the backend every session. | Includes `app_session_id`, `app_version`, `os_version`, `device_model`, `device_locale`, and various hardware/software details. |
| `first_seen` | When the user is first seen in the app, regardless of login status. | Same as `app_install` |
| `freeTrial_start` | When a user completes a transaction for a subscription product with an introductory offer. | Same as `subscription_start` |
| `identityAlias` | When the user's identity aliases after calling `identify`. | None |
| `nonRecurringProduct_purchase` | When the user purchases a non-recurring product. | Same as `subscription_start` |
| `paywall_close` | When a paywall is closed (either manually or after a transaction succeeds). | \[“paywall\_webview\_load\_complete\_time”: String?, “paywall\_url”: String, “paywall\_response\_load\_start\_time”: String?, “paywall\_products\_load\_fail\_time”: String?, “secondary\_product\_id”: String, “feature\_gating”: Int, “paywall\_response\_load\_complete\_time”: String?, “is\_free\_trial\_available”: Bool, “is\_superwall”: true, “presented\_by”: String, “paywall\_name”: String, “paywall\_response\_load\_duration”: String?, “paywall\_identifier”: String, “paywall\_webview\_load\_start\_time”: String?, “paywall\_products\_load\_complete\_time”: String?, “paywall\_product\_ids”: String, “tertiary\_product\_id”: String, “paywall\_id”: String, “app\_session\_id”: String, “paywall\_products\_load\_start\_time”: String?, “primary\_product\_id”: String, “survey\_attached”: Bool, “survey\_presentation”: String?] |
| [`paywall_decline`](/campaigns-standard-placements#using-the-paywall-decline-event) | When a user manually dismisses a paywall. | Same as `paywall_close` |
| `paywall_open` | When a paywall is opened. | Same as `paywall_close` |
| `paywallPresentationRequest` | When something happened during the paywall presentation, whether a success or failure. | `[“source_event_name”: String, “status”: String, “is_superwall”: true, “app_session_id”: String, “pipeline_type”: String, “status_reason”: String]` |
| `paywallProductsLoad_complete` | When the request to load a paywall's products completes. | Same as `paywallResponseLoad_start` |
| `paywallProductsLoad_fail` | When the request to load a paywall's products fails. | Same as `paywallResponseLoad_start` |
| `paywallProductsLoad_retry` | When the request to load a paywall's products fails and is being retried. | `["triggeredPlacementName": String?, "paywallInfo": PaywallInfo, "attempt": Int]` |
| `paywallProductsLoad_start` | When the request to load a paywall's products starts. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_complete` | When a paywall request to Superwall's servers completes. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_fail` | When a paywall request to Superwall's servers fails. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_notFound` | When a paywall request returns a 404 error. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_start` | When a paywall request to Superwall's servers has started. | Same as `app_install` + `["is_triggered_from_event": Bool]` |
| `paywallWebviewLoad_complete` | When a paywall's webpage completes loading. | Same as `paywall_close` |
| `paywallWebviewLoad_fail` | When a paywall's webpage fails to load. | Same as `paywall_close` |
| `paywallWebviewLoad_fallback` | When a paywall's webpage fails and loads a fallback version. | Same as `paywall_close` |
| `paywallWebviewLoad_start` | When a paywall's webpage begins to load. | Same as `paywall_close` |
| `paywallWebviewLoad_processTerminated` | When the paywall's web view content process terminates. | Same as `paywall_close` |
| `reset` | When `Superwall.reset()` is called. | None |
| `restoreComplete` | When a restore completes successfully. | None |
| `restoreFail` | When a restore fails. | `["message": String]` |
| `restoreStart` | When a restore is initiated. | None |
| `session_start` | When the app is opened after at least 60 minutes since last `app_close`. | Same as `app_install` |
| `shimmerViewComplete` | When the shimmer view stops showing. | None |
| `shimmerViewStart` | When the shimmer view starts showing. | None |
| `subscription_start` | When a user completes a transaction for a subscription product without an introductory offer. | \[“product\_period\_days”: String, “product\_price”: String, “presentation\_source\_type”: String?, “paywall\_response\_load\_complete\_time”: String?, “product\_language\_code”: String, “product\_trial\_period\_monthly\_price”: String, “paywall\_products\_load\_duration”: String?, “product\_currency\_symbol”: String, “is\_superwall”: true, “app\_session\_id”: String, “product\_period\_months”: String, “presented\_by\_event\_id”: String?, “product\_id”: String, “trigger\_session\_id”: String, “paywall\_webview\_load\_complete\_time”: String?, “paywall\_response\_load\_start\_time”: String?, “product\_raw\_trial\_period\_price”: String, “feature\_gating”: Int, “paywall\_id”: String, “product\_trial\_period\_daily\_price”: String, “product\_period\_years”: String, “presented\_by”: String, “product\_period”: String, “paywall\_url”: String, “paywall\_name”: String, “paywall\_identifier”: String, “paywall\_products\_load\_start\_time”: String?, “product\_trial\_period\_months”: String, “product\_currency\_code”: String, “product\_period\_weeks”: String, “product\_periodly”: String, “product\_trial\_period\_text”: String, “paywall\_webview\_load\_start\_time”: String?, “paywall\_products\_load\_complete\_time”: String?, “primary\_product\_id”: String, “product\_trial\_period\_yearly\_price”: String, “paywalljs\_version”: String?, “product\_trial\_period\_years”: String, “tertiary\_product\_id”: String, “paywall\_products\_load\_fail\_time”: String?, “product\_trial\_period\_end\_date”: String, “product\_weekly\_price”: String, “variant\_id”: String, “presented\_by\_event\_timestamp”: String?, “paywall\_response\_load\_duration”: String?, “secondary\_product\_id”: String, “product\_trial\_period\_days”: String, “product\_monthly\_price”: String, “paywall\_product\_ids”: String, “product\_locale”: String, “product\_daily\_price”: String, “product\_raw\_price”: String, “product\_yearly\_price”: String, “product\_trial\_period\_price”: String, “product\_localized\_period”: String, “product\_identifier”: String, “experiment\_id”: String, “is\_free\_trial\_available”: Bool, “product\_trial\_period\_weeks”: String, “paywall\_webview\_load\_duration”: String?, “product\_period\_alt”: String, “product\_trial\_period\_weekly\_price”: String, “presented\_by\_event\_name”: String?] |
| `subscriptionStatus_didChange` | When a user's subscription status changes. | `["is_superwall": true, "app_session_id": String, "subscription_status": String]` |
| `surveyClose` | When the user chooses to close a survey instead of responding. | None |
| [`survey_response`](/campaigns-standard-placements#using-the-survey-response-event) | When a user responds to a paywall survey. | `["survey_selected_option_title": String, "survey_custom_response": String, "survey_id": String, "survey_assignment_key": String, "survey_selected_option_id": String]` |
| `touches_began` | When the user touches the app's UIWindow for the first time (if tracked by a campaign). | Same as `app_install` |
| `transaction_abandon` | When the user cancels a transaction. | Same as `subscription_start` |
| `transaction_complete` | When the user completes checkout and any product is purchased. | Same as subscription\_start + \[“web\_order\_line\_item\_id”: String, “app\_bundle\_id”: String, “config\_request\_id”: String, “state”: String, “subscription\_group\_id”: String, “is\_upgraded”: String, “expiration\_date”: String, “trigger\_session\_id”: String, “original\_transaction\_identifier”: String, “id”: String, “transaction\_date”: String, “is\_superwall”: true, “store\_transaction\_id”: String, “original\_transaction\_date”: String, “app\_session\_id”: String] |
| `transaction_fail` | When the payment sheet fails to complete a transaction (ignores user cancellation). | Same as `subscription_start` + `["message": String]` |
| `transaction_restore` | When the user successfully restores their purchases. | Same as `subscription_start` |
| `transaction_start` | When the payment sheet is displayed to the user. | Same as `subscription_start` |
| `transaction_timeout` | When the transaction takes longer than 5 seconds to display the payment sheet. | `["paywallInfo": PaywallInfo]` |
| `trigger_fire` | When a registered placement triggers a paywall. | `[“trigger_name”: String, “trigger_session_id”: String, “variant_id”: String?, “experiment_id”: String?, “paywall_identifier”: String?, “result”: String, “unmatched_rule_”: “”]. unmatched_rule_ indicates why a rule (with a specfiic experiment id) didn’t match. It will only exist if the result is no_rule_match. Its outcome will either be OCCURRENCE, referring to the limit applied to a rule, or EXPRESSION.` |
| `user_attributes` | When the user attributes are set. | `[“aliasId”: String, “seed”: Int, “app_session_id”: String, “applicationInstalledAt”: String, “is_superwall”: true, “application_installed_at”: String] + provided attributes` |
---
# 3rd Party Analytics
Source: https://superwall.com/docs/android/guides/3rd-party-analytics
undefined
### Hooking up Superwall events to 3rd party tools
SuperwallKit automatically tracks some internal events. You can [view the list of events here](/tracking-analytics). We encourage you to also track them in your own analytics by implementing the [Superwall delegate](/using-superwall-delegate). Using the `handleSuperwallEvent(withInfo:)` function, you can forward events to your analytics service:
:::android
```kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
println("analytics event: ${eventInfo.event.rawName}")
MyAnalytics.shared.track(eventInfo.event.rawName, eventInfo.params)
}
```
:::
You might also want to set user attribute to allow for [Cohorting in 3rd Party
Tools](/cohorting-in-3rd-party-tools)
Alternatively, if you want typed versions of all these events with associated values, you can access them via `eventInfo.event`:
:::android
```kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when(eventInfo.event) {
is SuperwallPlacement.AppClose -> TODO()
is SuperwallPlacement.AppInstall -> TODO()
is SuperwallPlacement.AppLaunch -> TODO()
is SuperwallPlacement.AppOpen -> TODO()
is SuperwallPlacement.DeepLink -> TODO()
is SuperwallPlacement.FirstSeen -> TODO()
is SuperwallPlacement.FreeTrialStart -> TODO()
is SuperwallPlacement.NonRecurringProductPurchase -> TODO()
is SuperwallPlacement.PaywallClose -> TODO()
is SuperwallPlacement.PaywallDecline -> TODO()
is SuperwallPlacement.PaywallOpen -> TODO()
is SuperwallPlacement.PaywallPresentationRequest -> TODO()
is SuperwallPlacement.PaywallProductsLoadComplete -> TODO()
is SuperwallPlacement.PaywallProductsLoadFail -> TODO()
is SuperwallPlacement.PaywallProductsLoadStart -> TODO()
is SuperwallPlacement.PaywallResponseLoadComplete -> TODO()
is SuperwallPlacement.PaywallResponseLoadFail -> TODO()
is SuperwallPlacement.PaywallResponseLoadNotFound -> TODO()
is SuperwallPlacement.PaywallResponseLoadStart -> TODO()
is SuperwallPlacement.PaywallWebviewLoadComplete -> TODO()
is SuperwallPlacement.PaywallWebviewLoadFail -> TODO()
is SuperwallPlacement.PaywallWebviewLoadStart -> TODO()
is SuperwallPlacement.PaywallWebviewLoadTimeout -> TODO()
is SuperwallPlacement.SessionStart -> TODO()
is SuperwallPlacement.SubscriptionStart -> TODO()
is SuperwallPlacement.SubscriptionStatusDidChange -> TODO()
is SuperwallPlacement.SurveyClose -> TODO()
is SuperwallPlacement.SurveyResponse -> TODO()
is SuperwallPlacement.TransactionAbandon -> TODO()
is SuperwallPlacement.TransactionComplete -> TODO()
is SuperwallPlacement.TransactionFail -> TODO()
is SuperwallPlacement.TransactionRestore -> TODO()
is SuperwallPlacement.TransactionStart -> TODO()
is SuperwallPlacement.TransactionTimeout -> TODO()
is SuperwallPlacement.TriggerFire -> TODO()
is SuperwallPlacement.UserAttributes -> TODO()
}
}
```
:::
Wanting to use events to see which product was purchased on a paywall? Check out this
[doc](/viewing-purchased-products).
---
# Advanced Configuration
Source: https://superwall.com/docs/android/guides/configuring
When configuring the SDK you can pass in options that configure Superwall, the paywall presentation, and its appearance.
### Logging
Logging is enabled by default in the SDK and is controlled by two properties: `level` and `scopes`.
`level` determines the minimum log level to print to the console. There are five types of log level:
1. **debug**: Prints all logs from the SDK to the console. Useful for debugging your app if something isn't working as expected.
2. **info**: Prints errors, warnings, and useful information from the SDK to the console.
3. **warn**: Prints errors and warnings from the SDK to the console.
4. **error**: Only prints errors from the SDK to the console.
5. **none**: Turns off all logs.
The SDK defaults to `info`.
`scopes` defines the scope of logs to print to the console. For example, you might only care about logs relating to `paywallPresentation` and `paywallTransactions`. This defaults to `.all`. Check out [LogScope](https://sdk.superwall.me/documentation/superwallkit/logscope) for all possible cases.
You set these properties like this:
:::android
```kotlin
val options = SuperwallOptions()
options.logging.level = LogLevel.warn
options.logging.scopes = EnumSet.of(LogScope.paywallPresentation, LogScope.paywallTransactions)
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or you can set:
Superwall.instance.logLevel = LogLevel.warn
// Or use the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
logging {
level = LogLevel.warn
scopes = EnumSet.of(LogScope.paywallPresentation, LogScope.paywallTransactions)
}
}
}
```
:::
### Preloading Paywalls
Paywalls are preloaded by default when the app is launched from a cold start. The paywalls that are preloaded are determined by the list of placements that result in a paywall for the user when [registered](/docs/feature-gating). Preloading is smart, only preloading paywalls that belong to audiences that could be matched.
Paywalls are cached by default, which means after they load once, they don't need to be reloaded from the network unless you make a change to them on the dashboard. However, if you have a lot of paywalls, preloading may increase network usage of your app on first load of the paywalls and result in slower loading times overall.
You can turn off preloading by setting `shouldPreload` to `false`:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.shouldPreload = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
shouldPreload = false
}
}
}
```
:::
Then, if you'd like to preload paywalls for specific placements you can use `preloadPaywalls(forPlacements:)`:
:::android
```kotlin
val eventNames = setOf("campaign_trigger")
Superwall.instance.preloadPaywalls(eventNames)
```
:::
If you'd like to preload all paywalls you can use `preloadAllPaywalls()`:
:::android
```kotlin
Superwall.instance.preloadAllPaywalls()
```
:::
Note: These methods will not reload any paywalls that have already been preloaded.
### External Data Collection
By default, Superwall sends all registered events and properties back to the Superwall servers. However, if you have privacy concerns, you can stop this by setting `isExternalDataCollectionEnabled` to `false`:
:::android
```kotlin
val options = SuperwallOptions()
options.isExternalDataCollectionEnabled = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
isExternalDataCollectionEnabled = false
}
}
```
:::
Disabling this will not affect your ability to create triggers based on properties.
### Automatically Dismissing the Paywall
By default, Superwall automatically dismisses the paywall when a product is purchased or restored. You can disable this by setting `automaticallyDismiss` to `false`:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.automaticallyDismiss = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
automaticallyDismiss = false
}
}
}
```
:::
To manually dismiss the paywall , call `Superwall.shared.dismiss()`.
### Custom Restore Failure Message
You can set the title, message and close button title for the alert that appears after a restoration failure:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.restoreFailed.title = "My Title"
options.paywalls.restoreFailed.message = "My message"
options.paywalls.restoreFailed.closeButtonTitle = "Close"
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
restoreFailed.title = "My Title"
restoreFailed.message = "My message"
restoreFailed.closeButtonTitle = "Close"
}
}
}
```
:::
### Haptic Feedback
On iOS, the paywall uses haptic feedback by default after a user purchases or restores a product, opens a URL from the paywall, or closes the paywall. To disable this, set the `isHapticFeedbackEnabled` `PaywallOption` to false:
Note: Android does not use haptic feedback.
### Transaction Background View
During a transaction, we add a `UIActivityIndicator` behind the view to indicate a loading status. However, you can remove this by setting the `transactionBackgroundView` to `nil`:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.transactionBackgroundView = null
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
transactionBackgroundView = null
}
}
}
```
:::
### Purchase Failure Alert
When a purchase fails, we automatically present an alert with the error message. If you'd like to show your own alert after failure, set the `shouldShowPurchaseFailureAlert` `PaywallOption` to `false`:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.shouldShowPurchaseFailureAlert = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
shouldShowPurchaseFailureAlert = false
}
}
}
```
:::
### Web Purchase Confirmation Alert
When a user completes a purchase via web checkout (app2web flow), you can control whether to show a confirmation alert. By default, this is set to `false` to prevent duplicate alerts. Set `shouldShowWebPurchaseConfirmationAlert` to `true` if you want to show the native confirmation alert:
:::android
```kotlin
val options = SuperwallOptions()
options.paywalls.shouldShowWebPurchaseConfirmationAlert = true
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
shouldShowWebPurchaseConfirmationAlert = true
}
}
}
```
:::
### Locale Identifier
When evaluating rules, the device locale identifier is set to `autoupdatingCurrent`. However, you can override this if you want to test a specific locale:
:::android
```kotlin
val options = SuperwallOptions()
options.localeIdentifier = "en_GB"
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
localeIdentifier = "en_GB"
}
}
```
:::
For a list of locales that are available on iOS, take a look at [this list](https://gist.github.com/jacobbubu/1836273). You can also preview your paywall in different locales using [In-App Previews](/docs/in-app-paywall-previews).
### Game Controller
If you're using a game controller, you can enable this in `SuperwallOptions` too. Check out our [Game Controller Support](/docs/game-controller-support) article.
Take a look at [SuperwallOptions](https://sdk.superwall.me/documentation/superwallkit/superwalloptions) in our SDK reference for more info.
---
# Using the Superwall Delegate
Source: https://superwall.com/docs/android/guides/using-superwall-delegate
undefined
Use Superwall's delegate to extend our SDK's functionality across several surface areas by assigning to the `delegate` property:
:::android
```kotlin
class SWDelegate : SuperwallDelegate {
// Implement delegate methods here
}
// When configuring the SDK...
Superwall.instance.delegate = SWDelegate()
```
:::
Some common use cases for using the Superwall delegate include:
* **Custom actions:** [Respond to custom tap actions from a paywall.](/custom-paywall-events#custom-paywall-actions)
* **Respond to purchases:** [See which product was purchased from the presented paywall.](/viewing-purchased-products)
* **Analytics:** [Forward events from Superwall to your own analytics.](/3rd-party-analytics)
Below are some commonly used implementations when using the delegate.
### Superwall Events
Most of what occurs in Superwall can be viewed using the delegate method to respond to events:
:::android
```kotlin
class SWDelegate : SuperwallDelegate {
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
// Handle any relevant events here...
when (eventInfo.event) {
is SuperwallPlacement.TransactionComplete -> {
val transaction = (eventInfo.event as SuperwallPlacement.TransactionComplete).transaction
val product = (eventInfo.event as SuperwallPlacement.TransactionComplete).product
val paywallInfo = (eventInfo.event as SuperwallPlacement.TransactionComplete).paywallInfo
println("Transaction Complete: $transaction, Product: $product, Paywall Info: $paywallInfo")
}
else -> {
// Handle other cases
}
}
}
}
```
:::
### Paywall Custom Actions
Using the [custom tap action](/custom-paywall-events), you can respond to any arbitrary event from a paywall:
:::android
```kotlin
class SWDelegate : SuperwallDelegate {
override fun handleCustomPaywallAction(withName: String) {
if (withName == "caffeineLogged") {
println("Custom paywall action: $withName")
}
}
}
```
:::
### Subscription status changes
You can be informed of subscription status changes using the delegate. If you need to set or handle the status on your own, use a [purchase controller](/advanced-configuration) — this function is only for informational, tracking or similar purposes:
:::android
```kotlin
class SWDelegate : SuperwallDelegate {
override fun subscriptionStatusDidChange(from: SubscriptionStatus, to: SubscriptionStatus) {
println("Subscription status changed from $from to $to")
}
}
```
:::
### Paywall events
The delegate also has callbacks for several paywall events, such dismissing, presenting, and more. Here's an example:
:::android
```kotlin
class SWDelegate : SuperwallDelegate {
override fun didPresentPaywall(withInfo: PaywallInfo) {
println("Paywall presented: $withInfo")
}
}
```
:::
---
# Vibe Coding
Source: https://superwall.com/docs/android/guides/vibe-coding
How to Vibe Code using the knowledge of the Superwall Docs
## Overview
We've built a few tools to help you Vibe Code using the knowledge of the Superwall Docs, right in your favorite AI tools:
* [Superwall Docs MCP](#superwall-docs-mcp) in Claude Code, Cursor, etc.
* [Superwall Docs GPT](#superwall-docs-gpt) in ChatGPT
And right here in the Superwall Docs:
* [Ask AI](#ask-ai)
* [Docs Links](#docs-links)
* [LLMs.txt](#llmstxt)
## Superwall Docs MCP
The Superwall Docs MCP ([Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server)) is a tool that allows your favorite AI tools to search the Superwall Docs and get context from the docs.
### Cursor
You can install the MCP server in Cursor by clicking this button:
[](https://cursor.com/en/install-mcp?name=superwall-docs-mcp\&config=eyJ1cmwiOiJodHRwczovL21jcC5zdXBlcndhbGwuY29tL21jcCJ9)
or by adding the following to your `~/.cursor/mcp.json` file:
```json
{
"mcpServers": {
"superwall-docs": {
"url": "https://mcp.superwall.com/mcp"
}
}
}
```
### Claude Code
You can install the MCP server in Claude Code by running the following command:
```bash
claude mcp add --transport sse superwall-docs https://mcp.superwall.com/sse
```
### Codex
You can install the MCP server in Codex by running the following command:
```bash
codex mcp add superwall --url https://mcp.superwall.com/mcp
```
## Superwall Docs GPT
You can use the [Superwall Docs GPT](https://chatgpt.com/g/g-6888175f1684819180302d66f4e61971-superwall-docs-gpt) right in the ChatGPT app, and use it to ask any Superwall question.
It has the full knowledge of the Superwall Docs, and can be used with all the ChatGPT features you love like using the context of your files straight from your IDE.
## Ask AI
The built-in [Ask AI tool](https://superwall.com/docs/ai) in the Superwall Docs is a great place to start if you have a question or issue.
## Docs Links
On each page of the Superwall Docs (including this one!), you can find in the top right corner:
* **Copy page**: to copy the page in Markdown format.
Also in the dropdown menu, you can access these options:
* **View as markdown**: to view the page in Markdown format
* **Open in ChatGPT**, **Open in Claude**: to open the page in the respective AI tool and add the page as context for your conversation
## LLMs.txt
The Superwall Docs website has `llms.txt` and `llms-full.txt` files, in total and for each SDK, that you can use to add context to your LLMs.
`llms.txt` is a summary of the docs with links to each page.
`llms-full.txt` is the full text of all of the docs.
| SDK | Summary | Full Text |
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| All | [`llms.txt`](https://superwall.com/docs/llms.txt) | [`llms-full.txt`](https://superwall.com/docs/llms-full.txt) |
| Dashboard | [`llms-dashboard.txt`](https://superwall.com/docs/llms-dashboard.txt) | [`llms-full-dashboard.txt`](https://superwall.com/docs/llms-full-dashboard.txt) |
| iOS | [`llms-ios.txt`](https://superwall.com/docs/llms-ios.txt) | [`llms-full-ios.txt`](https://superwall.com/docs/llms-full-ios.txt) |
| Android | [`llms-android.txt`](https://superwall.com/docs/llms-android.txt) | [`llms-full-android.txt`](https://superwall.com/docs/llms-full-android.txt) |
| Flutter | [`llms-flutter.txt`](https://superwall.com/docs/llms-flutter.txt) | [`llms-full-flutter.txt`](https://superwall.com/docs/llms-full-flutter.txt) |
| Expo | [`llms-expo.txt`](https://superwall.com/docs/llms-expo.txt) | [`llms-full-expo.txt`](https://superwall.com/docs/llms-full-expo.txt) |
| React Native (Deprecated) | [`llms-react-native.txt`](https://superwall.com/docs/llms-react-native.txt) | [`llms-full-react-native.txt`](https://superwall.com/docs/llms-full-react-native.txt) |
| Integrations | [`llms-integrations.txt`](https://superwall.com/docs/llms-integrations.txt) | [`llms-full-integrations.txt`](https://superwall.com/docs/llms-full-integrations.txt) |
| Web Checkout | [`llms-web-checkout.txt`](https://superwall.com/docs/llms-web-checkout.txt) | [`llms-full-web-checkout.txt`](https://superwall.com/docs/llms-full-web-checkout.txt) |
To minimize token use, we recommend using the files specific to your SDK.
---
# Using RevenueCat
Source: https://superwall.com/docs/android/guides/using-revenuecat
undefined
Not using RevenueCat? No problem! Superwall works out of the box without any additional SDKs.
You only need to use a
`PurchaseController`
if you want end-to-end control of the purchasing pipeline. The recommended way to use RevenueCat with Superwall is by putting it in observer mode.
You can integrate RevenueCat with Superwall using several approaches:
1. [**Using a purchase controller:**](#using-a-purchase-controller) Use this route if you want to maintain control over purchasing logic and code.
2. [**Using PurchasesAreCompletedBy:**](#using-purchasesarecompletedby) Here, you don't use a purchase controller and you tell RevenueCat that purchases are completed by your app using StoreKit. In this mode, RevenueCat will observe the purchases that the Superwall SDK makes. For more info [see here](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
## Using a purchase controller
### 1. Create a `PurchaseController`
Create a new file called `RCPurchaseController`, then copy and paste the following:
:::android
```kotlin
package com.superwall.superapp
import android.app.Activity
import android.content.Context
import com.android.billingclient.api.ProductDetails
import com.revenuecat.purchases.CustomerInfo
import com.revenuecat.purchases.LogLevel
import com.revenuecat.purchases.ProductType
import com.revenuecat.purchases.PurchaseParams
import com.revenuecat.purchases.Purchases
import com.revenuecat.purchases.PurchasesConfiguration
import com.revenuecat.purchases.PurchasesError
import com.revenuecat.purchases.PurchasesErrorCode
import com.revenuecat.purchases.getCustomerInfoWith
import com.revenuecat.purchases.interfaces.GetStoreProductsCallback
import com.revenuecat.purchases.interfaces.PurchaseCallback
import com.revenuecat.purchases.interfaces.ReceiveCustomerInfoCallback
import com.revenuecat.purchases.interfaces.UpdatedCustomerInfoListener
import com.revenuecat.purchases.models.StoreProduct
import com.revenuecat.purchases.models.StoreTransaction
import com.revenuecat.purchases.models.SubscriptionOption
import com.revenuecat.purchases.models.googleProduct
import com.revenuecat.purchases.purchaseWith
import com.superwall.sdk.Superwall
import com.superwall.sdk.delegate.PurchaseResult
import com.superwall.sdk.delegate.RestorationResult
import com.superwall.sdk.delegate.subscription_controller.PurchaseController
import com.superwall.sdk.models.entitlements.Entitlement
import com.superwall.sdk.models.entitlements.SubscriptionStatus
import kotlinx.coroutines.CompletableDeferred
suspend fun Purchases.awaitProducts(productIds: List): List {
val deferred = CompletableDeferred>()
getProducts(
productIds,
object : GetStoreProductsCallback {
override fun onReceived(storeProducts: List) {
deferred.complete(storeProducts)
}
override fun onError(error: PurchasesError) {
deferred.completeExceptionally(Exception(error.message))
}
},
)
return deferred.await()
}
interface PurchaseCompletion {
var storeTransaction: StoreTransaction
var customerInfo: CustomerInfo
}
// Create a custom exception class that wraps PurchasesError
private class PurchasesException(
val purchasesError: PurchasesError,
) : Exception(purchasesError.toString())
suspend fun Purchases.awaitPurchase(
activity: Activity,
storeProduct: StoreProduct,
): PurchaseCompletion {
val deferred = CompletableDeferred()
purchase(
PurchaseParams.Builder(activity, storeProduct).build(),
object : PurchaseCallback {
override fun onCompleted(
storeTransaction: StoreTransaction,
customerInfo: CustomerInfo,
) {
deferred.complete(
object : PurchaseCompletion {
override var storeTransaction: StoreTransaction = storeTransaction
override var customerInfo: CustomerInfo = customerInfo
},
)
}
override fun onError(
error: PurchasesError,
p1: Boolean,
) {
deferred.completeExceptionally(PurchasesException(error))
}
},
)
return deferred.await()
}
suspend fun Purchases.awaitRestoration(): CustomerInfo {
val deferred = CompletableDeferred()
restorePurchases(
object : ReceiveCustomerInfoCallback {
override fun onReceived(purchaserInfo: CustomerInfo) {
deferred.complete(purchaserInfo)
}
override fun onError(error: PurchasesError) {
deferred.completeExceptionally(error as Throwable)
}
},
)
return deferred.await()
}
class RevenueCatPurchaseController(
val context: Context,
) : PurchaseController,
UpdatedCustomerInfoListener {
init {
Purchases.logLevel = LogLevel.DEBUG
Purchases.configure(
PurchasesConfiguration
.Builder(
context,
"android_rc_key",
).build(),
)
// Make sure we get the updates
Purchases.sharedInstance.updatedCustomerInfoListener = this
}
fun syncSubscriptionStatus() {
// Refetch the customer info on load
Purchases.sharedInstance.getCustomerInfoWith {
if (hasAnyActiveEntitlements(it)) {
setSubscriptionStatus(
SubscriptionStatus.Active(
it.entitlements.active
.map {
Entitlement(it.key, Entitlement.Type.SERVICE_LEVEL)
}.toSet(),
),
)
} else {
setSubscriptionStatus(SubscriptionStatus.Inactive)
}
}
}
/**
* Callback for rc customer updated info
*/
override fun onReceived(customerInfo: CustomerInfo) {
if (hasAnyActiveEntitlements(customerInfo)) {
setSubscriptionStatus(
SubscriptionStatus.Active(
customerInfo.entitlements.active
.map {
Entitlement(it.key, Entitlement.Type.SERVICE_LEVEL)
}.toSet(),
),
)
} else {
setSubscriptionStatus(SubscriptionStatus.Inactive)
}
}
/**
* Initiate a purchase
*/
override suspend fun purchase(
activity: Activity,
productDetails: ProductDetails,
basePlanId: String?,
offerId: String?,
): PurchaseResult {
// Find products matching productId from RevenueCat
val products = Purchases.sharedInstance.awaitProducts(listOf(productDetails.productId))
// Choose the product which matches the given base plan.
// If no base plan set, select first product or fail.
val product =
products.firstOrNull { it.googleProduct?.basePlanId == basePlanId }
?: products.firstOrNull()
?: return PurchaseResult.Failed("Product not found")
return when (product.type) {
ProductType.SUBS, ProductType.UNKNOWN ->
handleSubscription(
activity,
product,
basePlanId,
offerId,
)
ProductType.INAPP -> handleInAppPurchase(activity, product)
}
}
private fun buildSubscriptionOptionId(
basePlanId: String?,
offerId: String?,
): String =
buildString {
basePlanId?.let { append("$it") }
offerId?.let { append(":$it") }
}
private suspend fun handleSubscription(
activity: Activity,
storeProduct: StoreProduct,
basePlanId: String?,
offerId: String?,
): PurchaseResult {
storeProduct.subscriptionOptions?.let { subscriptionOptions ->
// If subscription option exists, concatenate base + offer ID.
val subscriptionOptionId = buildSubscriptionOptionId(basePlanId, offerId)
// Find first subscription option that matches the subscription option ID or default
// to letting revenuecat choose.
val subscriptionOption =
subscriptionOptions.firstOrNull { it.id == subscriptionOptionId }
?: subscriptionOptions.defaultOffer
// Purchase subscription option, otherwise fail.
if (subscriptionOption != null) {
return purchaseSubscription(activity, subscriptionOption)
}
}
return PurchaseResult.Failed("Valid subscription option not found for product.")
}
private suspend fun purchaseSubscription(
activity: Activity,
subscriptionOption: SubscriptionOption,
): PurchaseResult {
val deferred = CompletableDeferred()
Purchases.sharedInstance.purchaseWith(
PurchaseParams.Builder(activity, subscriptionOption).build(),
onError = { error, userCancelled ->
deferred.complete(
if (userCancelled) {
PurchaseResult.Cancelled()
} else {
PurchaseResult.Failed(
error.message,
)
},
)
},
onSuccess = { _, _ ->
deferred.complete(PurchaseResult.Purchased())
},
)
return deferred.await()
}
private suspend fun handleInAppPurchase(
activity: Activity,
storeProduct: StoreProduct,
): PurchaseResult =
try {
Purchases.sharedInstance.awaitPurchase(activity, storeProduct)
PurchaseResult.Purchased()
} catch (e: PurchasesException) {
when (e.purchasesError.code) {
PurchasesErrorCode.PurchaseCancelledError -> PurchaseResult.Cancelled()
else ->
PurchaseResult.Failed(
e.message ?: "Purchase failed due to an unknown error",
)
}
}
/**
* Restore purchases
*/
override suspend fun restorePurchases(): RestorationResult {
try {
if (hasAnyActiveEntitlements(Purchases.sharedInstance.awaitRestoration())) {
return RestorationResult.Restored()
} else {
return RestorationResult.Failed(Exception("No active entitlements"))
}
} catch (e: Throwable) {
return RestorationResult.Failed(e)
}
}
/**
* Check if the customer has any active entitlements
*/
private fun hasAnyActiveEntitlements(customerInfo: CustomerInfo): Boolean {
val entitlements =
customerInfo.entitlements.active.values
.map { it.identifier }
return entitlements.isNotEmpty()
}
private fun setSubscriptionStatus(subscriptionStatus: SubscriptionStatus) {
if (Superwall.initialized) {
Superwall.instance.setSubscriptionStatus(subscriptionStatus)
}
}
}
```
:::
As discussed in [Purchases and Subscription Status](/docs/advanced-configuration), this `CustomPurchaseControllerProvider` is responsible for handling the subscription-related logic using the modern hooks-based approach.
### 2. Configure Superwall (Continued)
The example above shows the complete setup. The `CustomPurchaseControllerProvider` wraps your `SuperwallProvider` and handles all purchase and restore logic through RevenueCat.
For more advanced implementations, see the [example app](https://github.com/superwall/expo-superwall/tree/main/example).
**Legacy Approach**: If you're migrating from the old SDK or need the class-based purchase controller, you can use `expo-superwall/compat`. However, we recommend using the modern `CustomPurchaseControllerProvider` approach shown above.
### Removed Legacy Code Section
The following section contains the legacy class-based approach. Skip to the next section for the modern configuration.
As discussed in [Purchases and Subscription Status](/docs/advanced-configuration), this `PurchaseController` is responsible for handling the subscription-related logic. Take a few moments to look through the code to understand how it does this.
### 2. Configure Superwall
Initialize an instance of `RCPurchaseController` and pass it in to `Superwall.configure(apiKey:purchaseController)`:
:::android
```kotlin
val purchaseController = RCPurchaseController(this)
Superwall.configure(
this,
"MY_API_KEY",
purchaseController
)
// Make sure we sync the subscription status
// on first load and whenever it changes
purchaseController.syncSubscriptionStatus()
```
:::
### 3. Sync the subscription status
Then, call `purchaseController.syncSubscriptionStatus()` to keep Superwall's subscription status up to date with RevenueCat.
That's it! Check out our sample app for working examples:
:::android
* [Android](https://github.com/superwall/Superwall-Android/tree/develop/example/app/src/revenuecat)
:::
## Using PurchasesAreCompletedBy
If you're using RevenueCat's [PurchasesAreCompletedBy](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions), you don't need to create a purchase controller. Register your placements, present a paywall — and Superwall will take care of completing any purchase the user starts. However, there are a few things to note if you use this setup:
1. Here, you aren't using RevenueCat's [entitlements](https://www.revenuecat.com/docs/getting-started/entitlements#entitlements) as a source of truth. If your app is multiplatform, you'll need to consider how to link up pro features or purchased products for users.
2. If you require custom logic when purchases occur, then you'll want to add a purchase controller. In that case, Superwall handles purchasing flows and RevenueCat will still observe transactions to power their analytics and charts.
3. Be sure that user identifiers are set the same way across Superwall and RevenueCat.
For more information on observer mode, visit [RevenueCat's docs](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
---
# Changelog
Source: https://superwall.com/docs/android/changelog
Release notes for the Superwall Android SDK
## 2.6.6
## Enhancements
* Add dynamic notification support and scheduling enabling deeper personalization of notifications
* Provides a `CustomerInfo` class API, allowing you to observe the customer's purchases and subscription lifecycle via `Superwall.instance.customerInfo` flow
* Provides a new delegate method to observe customer info changes - `fun customerInfoDidChange(from: CustomerInfo, to: CustomerInfo)`
* Provides a `CustomerInfoDidChange` event to track customer info changes
* Overrides `Collection.plus`and `.toSet` methods to ensure our merging methods are used.
* Provides a `userAttributesDidChange(newAttributes: Map)` method in Superwall Delegate to track external (i.e. paywall) attribute changesg
* Allows triggering a `transaction_abandon` offer on a `paywall_decline` offer and vice-versa, whereas previously it would trigger a presentation error.
* Add a `Superwall.teardown` method and `Superwall.instance.refreshConfiguration()` for development with hot-reload based frameworks
## ⚠️ Warning ⚠️
If you are using a Purchase Controller and web2app or app2web purchases, you will have to update your purchase controller
to listen to `Superwall.instance.customerInfo` which will provide you with the relevant web entitlements and call
`setSubscriptionStatus` accordingly.
## 2.6.5
## Dependencies
* Reverts `androidx.lifecycle:lifecycle-runtime-ktx` to 2.8.4 to ensure old Compose BOM compatiblity
## Enhancements
* Improves error messaging in play store errors
## Fixes
* Fixes edge case bug with wrong entitlement being matched in cases where product ID's match and base plans differentiate by suffix only
* Fixes issue with composable paywall state updates not firing in onAttach
## 2.6.4
## Enhancements
* Improves error and timeout handling
* Hardens paywall recreation in case of render process crash
## 2.6.3
## Enhancements
* Adds `productIdentifier` to RedemptionResult's `PaywallInfo` object
## Fixes
* Fixes nested scrolling issue in Modal webviews
* Removes node removal for `com.google.android.gms.permission.AD_ID` from Manifest
* Ensures remote entitlements in the background refresh without feature flags
## 2.6.2
## Enhancements
* Adds `Superwall.instance.consume(purchaseToken)` method to help easily consume in-app purchases
## Fixes
* Fixes issue with deeplink params not being handled properly in some cases
* Fixes issue with Drawer and Modal displays on Android 14 Samsung devices
* Fixes selection issue with some OTP, ensures after consuming the Status is synced
## 2.6.1
## Enhancements
* Enables Stripe and Paddle checkout via in-app payment sheets
* Improves product handling and redemption for Stripe and Paddle
## Fixes
* Fixes issue with Google's Play Billing library auto-reconnection
## 2.6.0 ⚠️ \[Deprecated]
## Notes
* This version is deprecated due to discovery of an issue in Play Billing library which could cause runtime issues
* Please use version 2.6.1
## 2.5.8
## Fixes
* Fix lifetime purchase entitlements not being discovered in some cases on purchase
* Fix potential ANR issues where some animations would end up looping over on main thread
* Fix webview client not behaving properly when using a resetted paywall
## 2.6.0-alpha
* Add app2web support, allowing users to purchase Stripe or Paddle products without leaving your app
* Add `PaymentSheet` purchase type enabling quick bottom sheet purchases
* Add support for Android app links purchase redeeming
## 2.5.7
## Fixes
* Fix `demandScore` and `demandTier` getting removed from some events
* Fixes paywall navigation resetting after backgrounding
* Removes webview flags which can cause off-screen render issues
## 2.5.6
## Enhancements
* Add support for rerouting back button if enabled in paywall settings
* Handled by `SuperwallOptions.PaywallOptions.onBackPressed`, which enables you to consume the back press or let the SDK consume it
* Add support for redeeming web entitlements with Paddle
## Fixes
* Fix binary .so file regression to ensure 16kb page size compatibility
* Fix potential issue with paywall not dismissing due to paywall\_decline concurrency issue
## 2.5.5
## Enhancements
* Expose `signature` on `StoreTransaction`
## Fixes
* ⚠️ Important - in the recent versions we have added usage of Google AppSetId and AdID to enable automatic attribution with Google's ad networks.
* Due to issues with Google's detection of the usage, they have been removed temporarily and will be added back once the issue is resolved.
* As an alternative, you can set those attribution identifiers using `AttributionProvider.GOOGLE_APP_SET | AttributionProvider.GOOGLE_ADS`
## 2.5.4
## Enhancements
* `PaywallComposable` now reapplies theme on system change and `PaywallView` now exposes an `onThemeChanged()` method
* `DeepLink` event now exposes query params
## 2.5.3
## Enhancements
* Adds ability to specify a custom height and corner radius for the drawer presentation style.
* Adds ability to display a `Popup` presentation style
* Adds ability to request reviews from paywall actions, including:
* Value `device.reviewRequestCount` that returns total request counts
* Method `device.reviewRequestsInHour|Day|Week|Year|reviewRequestsSinceInstall` computed methods for granular targeting
* Adds `Superwall.instance.setIntegrationAttributes` method enabling you to set integration identifiers for the users from different platforms (Adjust, Mixpanel, Meta, etc.)
* Adds `Superwall.instance.showAlert` method enabling you to easily show an alert over the current paywall
* Adds `PaywallOptions.timeoutAfter` to easily control timeout of paywalls when not using fallback loading
* Adds `Superwall.instance.setIntegrationAttributes` and `Superwall.instance.integrationAttributes` to set integration identifiers (i.e. Mixpanel, Appsflyer, etc)
* Adds user attributes to `TransactionComplete` and `PaywallOpen` events
* Adds device ID to device attributes
## Fixes
* Fixes memory leak issues in `PaywallBuilder` would keep the paywall view alive in some cases
* Fixes issue where some events would be missing properties
## 2.5.1
## Enhancements
* Improves subscribed user experience in cases with slow configuration
## 2.5.0
## Enhancements
* Updates Google Play billing library to v8. Unfortunately, Google has broken backwards compatibility with previous versions, so if you're using the standalone library too ensure it is compatible with v8.
* Adds kotlin version to device variables
## Fixes
* Reduces noisy logging when product is missing an offer
* Ensures that getting experimental properties works for consumable products
## 2.4.1
## Fixes
* Google Play Billing integration with newer libraries (such as RC 9.\*)
* Reduces noisy logging when product is missing an offer
* Ensures that getting experimental properties works for consumable products
## 2.4.0
## Enhancements
* Increases superscript version to 1.0.2 with improved type and null safety
## 2.3.3
## Fixes
* Ensure properties are always properly serialized
## 2.3.2
## Enhancements
* Adds new properties to count placement occurrences in specific time: `placementsInHours`, `placementsInDay`, `placementsInWeek`, `placementsInMonth`, `placementsSinceInstall`
## Fixes
* Fixes an issue where a redemption could succeed but throw an error
* Fixes an issue with receipt manager when there is no purchases and experimental properties are enabled
## 2.3.1
## Fixes
* Fixes an issue where entitlements would not be reset on time
* Ensures `redeem` is only done on initial config not on config refresh
## Enhancements
* Adds `overrideProductsByName` property to allow globally overriding products on paywalls. This property accepts a map of product names to product identifiers (strings). Local overrides provided via `PaywallOverrides` take precedence over global overrides.
* Adds `ProductOverride` sealed class to provide flexible product override handling with support for both product IDs and `StoreProduct` objects.
## 2.3.0
## Enhancements
* Deprecated `Superwall.instance.handleDeepLink` in favor of static `Superwall.handleDeepLink` to ensure links received before `configure` completion are handled properly
* Adds `externalAcountId`, provided to Google Play billing upon purchase as a SHA256 of the userId or the userId itself if `passIdentifiersToPlayStore` option is provided.
* Adds a `SuperwallOption` named `enableExperimentalDeviceVariables`. When set to true, this enables additional device-level variables: `latestSubscriptionPeriodType`, `latestSubscriptionState`, and `latestSubscriptionWillAutoRenew`. These properties provide information about the most recent Google Play subscription on the device and can be used in audience filters. Note that due to their experimental nature, they are subject to change in future updates.
* Update `com.android.billingclient` to version 7.1.1 to align with Google's latest requirements
## Fixes
* Fixes issues with paywall destruction when activity performs a hot reload (i.e. during update)
* Fixes issue where the feature block would be triggered on non-gated paywalls when the app is minimised
## 2.2.3
## Fixes
* Fix potential issue with device enrichment and attributes synchronisation causing a lock
## 2.2.2
## Enhancements
* Adds `demandScore` and `demandTier` to device attributes using an off-device advanced machine learning model. A user is assigned these based on a variety of factors to determine whether they're more or less likely to convert and can be used within audience filters.
* Adds `deviceTier` to the device attributes using an on-device scoring system to place the device in a tier based on it's capabilities. This can be used in audience filters to display different paywalls based on the user's device capabilities. The value can be one of the following values `ultraLow`, `low`, `mid`, `high`, `ultra_high`, `unknown`. NOTE: This property is still experimental
## Fix
* Fixes potential issue in `web2app` with subscription being overriden by the polling due to extra API calls
## 2.2.0
## Enhancements
* Updates binaries to work on 16kb page sizes
## 2.1.2
## Fixes
* Fix issue with deep link referrer throwing a DeadObjectException
## 2.1.1
## Enhancements
* Add optimisticLoading paywall option that hides the shimmer when HTML is loaded
* Prevent stopping the paywall handler listening with onDismiss when reason is None
* Improve PaywallBuilder API for non-kotlin and non-coroutine users
* Expose `deviceAttributes()` function to retrieve session device attributes
## 2.1.0
## Enhancements
* Updates kotlin version to 2.0.21
* Updates `compileSDK` to 35
* Adds web checkout and redemption support
* Adds SuperwallDelegate methods `willRedeemLink` and `didRedeemLink`
## Fixes
* Removes lock while reading cache that could cause ANR on the main thread
* Fixes issue where experiment and variant ID would be missing due to concurrency issues
## 2.1.0-beta.1
## Enhancements
* Updates kotlin version to 2.0.21
* Updates `compileSDK` to 35
* Adds web checkout and redemption support
* Adds SuperwallDelegate methods `willRedeemLink` and `didRedeemLink`
## 2.0.8
## Fixes
* Fixes the serialization issue with Kotlin 2.0
## 2.0.7
## Enhancements
* Improves how errors are handled when loading, improving the UX and reloading in real failure cases
* Added `device.subscriptionStatus` to the device object
## Fixes
* Fixes an issue where users of kotlin 2.0 would experience a `NoAudienceMatch` when evaluating rules
## 2.0.6
## Fixes
* Fix potential crash while setting render priority
## 2.0.5
## Fixes
* Fix issue with `original_transaction_id` missing when using a `PurchaseController`
# 2.0.4
## Enhancements
* Provide overloads for Java interop
* Provide utility functions for Java interop with `PurchaseController`
# 2.0.3
## Enhancements
* Renames `SuperwallPlacement` back to `SuperwallEvent`
# 2.0.2
## Fixes
* Fixes issue with `NoAudienceMatch` appearing on some devices and issues with certain campaign rules
# 2.0.1
## Enhancements
* Changes back to `handleSuperwallEvent` naming with a deprecation notice and a typealias for previous methods
## Fixes
* Removes extra failure logging when displaying alerts
* Finds nearest activity instead of relying just on Context in `PaywallComposable`
* Improves cleanup in `PaywallComposable`
# 2.0.0
Our 2.0.0 release brings some major and minor changes to both our API's and core features. For more information, please look at our [migration docs](https://superwall.com/docs/migrating-to-v2-android)
## Enhancements
* Adds `PaywallBuilder` class as an alternative to existing `getPaywallView` method. This provides a cleaner API and an ability to change purchase loading bar and shimmer view.
* Ensure safety of static webview calls that are known to fail randomly due to Webview's internal issues
* Adds `purchase` method to `Superwall` you can use to purchase products without having to resort on paywalls. To purchase a product you can pass it in one of the following objects:
* Google Play's `ProductDetails`
* Superwall's `StoreProduct` object
* Or a string containing the product identifier, i.e. `Superwall.instance.purchase("product_id:base_plan:offer")`
* Adds `restorePurchases` method to `Superwall` you can use to handle restoring purchases
* Adds `getProducts` method to `Superwall` you can use to retrieve a list of `ProductDetails` given the product ID, i.e. i.e. `Superwall.instance.purchase("product_id:base_plan:offer")`
* Adds support for observing purchases done outside of Superwall paywalls. You can now observe purchases done outside of Superwall paywalls by setting the `shouldObservePurchases` option to true and either:
* Manually by calling `Superwall.instance.observe(PurchasingObserverState)` or utility methods `Superwall.instance.observePurchaseStart/observePurchaseError/observePurchaseResult`
* Automatically by replacing `launchBillingFlow` with `launchBillingFlowWithSuperwall`. This will automatically observe purchases done outside of Superwall paywalls.
* Adds consumer proguard rules to enable consumer minification
* `Superwall.instance` now provides blocking or callback based version of multiple calls, suffixed with `*Sync`
* Improves preloading performance and reduces impact on the main thread
* Reduces minSDK to 22
## Breaking Changes
* `SuperwallPaywallActivity` and `PaywallView` have been moved into `com.superwall.sdk.paywall.view` package from `com.superwall.sdk.paywall.vc` package.
* Removes `PaywallComposable` and Jetpack Compose support from the main SDK artifact in favor of `Superwall-Compose` module for Jetpack Compose support:
* You can find it at `com.superwall.sdk:superwall-compose:2.0.0-alpha`
* Usage remains the same as before, but now you need to include the `superwall-compose` module in your project.
* Removed methods previously marked as Deprecated
* `SubscriptionStatus.Active` now takes in a set of `Entitlements`, while `Inactive` and `Active` have been turned into objects.
* `Superwall.instance.register` now uses `placement` instead of `event` as the argument name
* `preloadPaywalls` now uses `placementNames` instead of `eventNames` as the argument name
* `PaywallPresentationHandler.onDismiss` now has two arguments, `PaywallInfo` and `PaywallResult`
* `PaywallComposable` now uses `placement` argument instead of `event`
* `TriggerResult.NoRuleMatch` and `TriggerResult.EventNotFound` have been renamed to `TriggerResult.NoAudienceMatch` and `TriggerResult.PlacementNotFound`
* `PresentationResult.NoRuleMatch` and `PresentationResult.EventNotFound` have been renamed to `PresentationResult.NoAudienceMatch` and `PresentationResult.PlacementNotFound`
* `SuperwallEvent` has been renamed to `SuperwallPlacement`, belonging properties with `eventName` have been renamed to `placementName`
* `SuperwallEventInfo` has been renamed to `SuperwallPlacementInfo`
* `ComputedPropertyRequest.eventName` has been renamed to `ComputedPropertyRequest.placementName`
* `Superwall.instance.events` has been renamed to `Superwall.instance.placements`
* `LogScope.events` has been renamed to `LogScope.placements`
* `PaywallPresentationRequestStatusReason.EventNotFound` has been renamed to `PaywallPresentationRequestStatusReason.PlacementNotFound`
* `PaywallSkippedReason.EventNotFound` has been renamed to `PaywallSkippedReason.PlacementNotFound`
* `SuperwallDelegate.handleSuperwallEvent` method has been renamed to `SuperwallDelegate.handleSuperwallPlacement`
* Removed `PurchaseResult.Restored`
# 2.0.0-beta.5
## Breaking changes
* `Superwall.instance.register` now uses `placement` instead of `event` as the argument name
* `preloadPaywalls` now uses `placementNames` instead of `eventNames` as the argument name
* Superwall's `PaywallPresentationHandler.onDismiss` now has two arguments, `PaywallInfo` and `PaywallResult`
* `PaywallComposable` now uses `placement` argument instead of `event`
* Remove `PurchaseResult.Restored`
# 2.0.0-beta.4
## Breaking changes
* `SuperwallEvents.entitlementStatusDidChange` has been renamed to `SuperwallEvents.subscriptionStatusDidChange`
* `SuperwallDelegate.entitlementStatusDidChange` has been renamed to `SuperwallEvents.entitlementStatusDidChange`
* `TriggerResult.NoRuleMatch` and `TriggerResult.EventNotFound` have been renamed to `TriggerResult.NoAudienceMatch` and `TriggerResult.PlacementNotFound`
* `PresentationResult.NoRuleMatch` and `PresentationResult.EventNotFound` have been renamed to `PresentationResult.NoAudienceMatch` and `PresentationResult.PlacementNotFound`
## 2.0.0-beta.3
### Breaking changes
* `SuperwallEvent` has been renamed to `SuperwallPlacement`, belonging properties with `eventName` have been renamed to `placementName`
* `SuperwallEventInfo` has been renamed to `SuperwallPlacementInfo`
* `ComputedPropertyRequest.eventName` has been renamed to `ComputedPropertyRequest.placementName`
* `Superwall.instance.events` has been renamed to `Superwall.instance.placements`
* `LogScope.events` has been renamed to `LogScope.placements`
* `PaywallPresentationRequestStatusReason.EventNotFound` has been renamed to `PaywallPresentationRequestStatusReason.PlacementNotFound`
* `PaywallSkippedReason.EventNotFound` has been renamed to `PaywallSkippedReason.PlacementNotFound`
* `SuperwallDelegate.handleSuperwallEvent` method has been renamed to `SuperwallDelegate.handleSuperwallPlacement`
## 2.0.0-beta.2
### Breaking Changes
* API Changes:
* Migration of `setEntitlementStatus` to `setSubscriptionStatus`
* Exposing `Superwall.instance.entitlementsStatus`
* Migration of `SuperwallDelegate.entitlementStatusDidChange` to `SuperwallDelegate.subscriptionStatusDidChange`
## 2.0.0-beta.1
## Enhancements
* Add `PaywallBuilder` class as an alternative to existing `getPaywallView` method. This provides a cleaner API and an ability to change purchase loading bar and shimmer view.
* Add callback versions of new 2.0 methods
* Ensure safety of static webview calls that are known to fail randomly due to Webview's internal issues
## 2.0.0-Alpha.1
### Breaking Changes
* `SuperwallPaywallActivity` and `PaywallView` have been moved into `com.superwall.sdk.paywall.view` package from `com.superwall.sdk.paywall.vc` package.
* Removes `PaywallComposable` and Jetpack Compose support from the main SDK artifact in favor of `Superwall-Compose` module for Jetpack Compose support:
* You can find it at `com.superwall.sdk:superwall-compose:2.0.0-alpha`
* Usage remains the same as before, but now you need to include the `superwall-compose` module in your project.
* Removed methods previously marked as Deprecated
* Removes `SubscriptionStatus`, together with belonging update methods and `subscriptionStatusDidChange` callback.
* These are replaced with `EntitlementStatus` and `entitlementStatusDidChange` callback. You can find more details on this migration in our docs.
### Enhancements
* Adds `purchase` method to `Superwall` you can use to purchase products without having to resort on paywalls. To purchase a product you can pass it in one of the following objects:
* Google Play's `ProductDetails`
* Superwall's `StoreProduct` object
* Or a string containing the product identifier, i.e. `Superwall.instance.purchase("product_id:base_plan:offer")`
* Adds `restorePurchases` method to `Superwall` you can use to handle restoring purchases
* Adds `getProducts` method to `Superwall` you can use to retrieve a list of `ProductDetails` given the product ID, i.e. i.e. `Superwall.instance.purchase("product_id:base_plan:offer")`
* Adds support for observing purchases done outside of Superwall paywalls. You can now observe purchases done outside of Superwall paywalls by setting the `shouldObservePurchases` option to true and either:
* Manually by calling `Superwall.instance.observe(PurchasingObserverState)` or utility methods `Superwall.instance.observePurchaseStart/observePurchaseError/observePurchaseResult`
* Automatically by replacing `launchBillingFlow` with `launchBillingFlowWithSuperwall`. This will automatically observe purchases done outside of Superwall paywalls.
* Adds consumer proguard rules to enable consumer minification
* Reduces minSDK to 22
* Adds `purchaseToken` to purchase events
* `Superwall.instance` now provides blocking or callback based version of multiple calls, suffixed with `*Sync`
* Improves preloading performance and reduces impact on the main thread
## 1.5.5
## Fixes
* Fixes potential distribution issues for variant selection in edge cases
* Fixes potential memory leaks of paywall calling activity
## 1.5.4
## Fixes
* Fixes issue when a paywall would dismiss with `ForNextPaywall` but next paywall could not be shown due to triggers or limits. Now it resolves into the proper dismiss status.
## 1.5.3
### Enhancements
* Add `purchaseToken` to TransactionComplete
## 1.5.2
### Fixes
* Fix chromium crashes caused by race conditions in webview's implementation
## 1.5.1
### Enhancements
* Updates superscript dependencies to reduce minSDK version
### Fixes
* Adds consumer proguard rules to avoid minifying JNA classes during minification
## 1.5.0
### Enhancements
* Adds `shimmerView_start` and `shimmerView_complete` events to track the loading of the shimmer animation.
* Makes `hasFreeTrial` match iOS SDK behavior by returning `true` for both free trials and non-free introductory offers
* Adds `Superwall.instance.events` - A SharedFlow instance emitting all Superwall events as `SuperwallEventInfo`. This can be used as an alternative to a delegate for listening to events.
* Adds a new shimmer animation
* Adds support for SuperScript expression evaluator
### Fixes
* Fixes concurrency issues with subscriptions triggered in Cordova apps
## 1.5.0-beta.2
## Enhancements
* Adds `shimmerView_start` and `shimmerView_complete` events to track the loading of the shimmer animation.
* Makes `hasFreeTrial` match iOS SDK behavior by returning `true` for both free trials and non-free introductory offers
## 1.5.0-beta.1
## Enhancements
* Adds `Superwall.instance.events` - A SharedFlow instance emitting all Superwall events as `SuperwallEventInfo`. This can be used as an alternative to a delegate for listening to events.
* Adds a new shimmer animation
* Adds support for SuperScript expression evaluator
## 1.4.1
### Enhancements
* Adds `appVersionPadded` attribute
### Fixes
* Fixes issue where `PaywallPresentationHandler.onError` would be skipped in case of `BillingError`s
## 1.4.0
## Enhancements
* Improves paywall loading and preloading performance
* Reduces impact of preloading on render performance
* Updates methods to return `kotlin.Result` instead of relying on throwing exceptions
* This introduces some minor breaking changes:
* `configure` completion block now provides a `Result` that can be used to check for success or failure
* `handleDeepLink` now returns a `Result`
* `getAssignments` now returns a `Result>`
* `confirmAllAssignments` now returns a `Result>`
* `getPresentationResult` now returns a `Result`
* `getPaywallComponents` now returns a `Result`
* Removes Gson dependency
* Adds `isScrollEnabled` flag to enable remote control of Paywall scrollability
* Adds `PaywallResourceLoadFail` event to enable tracking of failed resources in Paywall
* Improves bottom navigation bar color handling
## Fixes
* Fixes issue where paywalls without fallback would fail to load and missing resource would cause a failure event
* Fixes issue with `trialPeriodDays` rounding to the higher value instead of lower, i.e. where `P4W2D` would return 28 days instead of 30, it now returns 30.
* Fixes issue with system navigation bar not respecting paywall color
* Fixes issues with cursor allocation in Room transaction
* Improves handling of chromium render process crash
## 1.4.0-beta.3
* Fixes issue where paywalls without fallback would fail to load and missing resource would cause a failure event
## 1.4.0-beta.2
## Enhancements
* Removes Gson dependency
* Adds `isScrollEnabled` flag to enable remote controll of Paywall scrollability
## Fixes
* Fixes issue with `trialPeriodDays` rounding to the higher value instead of lower, i.e. where `P4W2D` would return 28 days instead of 30, it now returns 30.
* Fixes issue with system navigation bar not respecting paywall color
* Reduces impact of preloading on render performance
* Fixes issues with cursor allocation in Room transaction
## 1.4.0-beta.1
* Updates methods to return `kotlin.Result` instead of relying on throwing exceptions
* This introduces some minor breaking changes:
* `configure` completion block now provides a `Result` that can be used to check for success or failure
* `handleDeepLink` now returns a `Result`
* `getAssignments` now returns a `Result>`
* `confirmAllAssignments` now returns a `Result>`
* `getPresentationResult` now returns a `Result`
* `getPaywallComponents` now returns a `Result`
## 1.3.1
### Fixes
* Fixes issue when destroying activities during sleep would cause a background crash
* Fixes issue when using Superwall with some SDK's would cause a crash (i.e. Smartlook SDK)
## 1.3.0
### Enhancements
* The existing `getPaywall` method has been deprecated and renamed to `getPaywallOrThrow`. The new `getPaywall` method now returns a `kotlin.Result` instead of throwing an exception.
* Adds a new option to `SuperwallOptions` - `passIdentifiersToPlayStore` which allows you to pass the user's identifiers (from `Superwall.instance.identify(userId: String, ...)`) to the Play Store when making a purchase. Note: When passing in identifiers to use with the play store, please make sure to follow their \[guidelines]\([https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId(java.lang.String)](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId\(java.lang.String\)).
* Adds `Superwall.instance.confirmAllAssignments()`, which confirms assignments for all placements and returns an array of all confirmed experiment assignments. Note that the assignments may be different when a placement is registered due to changes in user, placement, or device parameters used in audience filters.
### Fixes
* Fixes issues with Paywall sometimes not displaying when returning from background
* Fixes issue with SDK crashing when WebView is not available
* Fixes issue with `SuperwallPaywallActivity` NPE
* Update visibility of internal `getPaywall` methods to `internal` to prevent misuse
## 1.2.9
### Fixes
* Fixes issues with `MODAL` presentation style and scrolling containers
* Fixes issues with `FULLSCREEN` presentation style rendering behind navigation
## 1.2.8
### Fixes
* Fixes issues with Paywall presentation styles not being properly passed
## 1.2.7
### Enhancements
* Exposes current configuration status via `Superwall.instance.configurationStatus`
### Fixes
* Fixes issues with Paywall previews not loading
## 1.2.6
### Fixes
* Fixes issue where the paywall would not show in some cases when using `minutes_since`
* Fixes issue with wrong URL being logged when a paywall fails to load
## 1.2.5
### Enhancements
* Adds a `Modifier` to `PaywallComposable` to allow for more control
* Adds a `PaywallView.setup(...)` method to allow for easy setup when using `PaywallView` directly
* Adds support for `MODAL` presentation style
### Fixes
* Fixes issue with displaying `PaywallComposable`
* Resolves issue where users would get `UninitializedPropertyAccessException` when calling `Superwall.instance`
## 1.2.4
### Enhancements
* For users who are not able to upgrade their AGP or Gradle versions, we have added a new artifact `superwall-android-agp-7` which keeps compatibility.
### Enhancements
* Fixes issue with decoding custom placements from paywalls.
## 1.2.3
### Enhancements
* Expose `placementName`, `paywallInfo` and `params` on a `custom_placement` event
## 1.2.2
### Enhancements
* Adds support for multiple paywall URLs, in case one CDN provider fails.
* `ActivityEncapsulatable` now uses a WeakReference instead of a reference
* SW-2900: Adds Superwall.instance.localeIdentifier as a convenience variable that you can use to dynamically update the locale used for evaluating rules and getting localized paywalls.
* SW-2919: Adds a `custom_placement` event that you can attach to any element in the paywall with a dictionary of parameters. When the element is tapped, the event will be tracked. The name of the placement can be used to trigger a paywall and its params used in audience filters.
* Adds support for bottom sheet presentation style (DRAWER), no animation style and default animation.
* Adds `build_id` and `cache_key` to `PaywallInfo`.
* SW-2917: Tracks a `config_attributes` event after calling `Superwall.configure`, which contains info about the configuration of the SDK. This gets tracked whenever you set the delegate.
* Adds in device attributes tracking after setting the interface style override.
* To comply with new Google Play Billing requirements we now avoid setting empty `offerToken` for one-time purchases
## 1.2.1
### Enhancements
* Adds the ability for the SDK to refresh the Superwall configuration every session start, subject to a feature flag.
* Tracks a `config_refresh` Superwall event when the configuration is refreshed.
* SW-2890: Adds `capabilities` to device attributes. This is a comma-separated list of capabilities the SDK has that you can target in audience filters. This release adds the `paywall_event_receiver` capability. This indicates that the paywall can receive transaction from the SDK.
* SW-2902: Adds `abandoned_product_id` to a `transaction_abandon` event to use in audience filters. You can use this to show a paywall if a user abandons the transaction for a specific product.
## 1.2.0
### Enhancements
* Adds DSL methods for configuring the SDK. You can now use a configuration block:
```kotlin
fun Application.configureSuperwall(
apiKey: String,
configure: SuperwallBuilder.() -> Unit,
)
```
This allows you to configure the SDK in a more idiomatic way:
```kotlin
configureSuperwall(CONSTANT_API_KEY){
options {
logging {
level = LogLevel.debug
}
paywalls {
shouldPreload = false
}
}
}
```
### Deprecations
This release includes multiple deprecations that will be removed in upcoming versions.
Most are internal and will not affect the public API, those that will are marked as such and a simple migration
path is provided. The notable ones in the public API are as follows:
* Deprecated `DebugViewControllerActivity` in favor of `DebugViewActivity`
* Deprecated `PaywallViewController` in favor of `PaywallView`
* Deprecated belonging methods:
* `viewWillAppear` in favor of `beforeViewCreated`
* `viewDidAppear` in favor of `onViewCreated`
* `viewWillDisappear` in favor of `beforeOnDestroy`
* `viewDidDisappear` in favor of `destroyed`
* `presentAlert` in favor of `showAlert`
* Deprecated `PaywallViewControllerDelegate` in favor of `PaywallViewCallback`
* Deprecated belonging methods:
* `didFinish` in favor of `onFinished`
* Deprecated `PaywallViewControllerEventDelegate` in favor of `PaywallViewEventCallback`
* Users might also note deprecation of `PaywallWebEvent.OpenedUrlInSafari` in favor of `PaywallWebEvent.OpenedUrlInChrome`
* `didFinish` in favor of `onFinished`
* In `Superwall`, the following methods were deprecated:
* `Superwall.paywallViewController` in favor of `Superwall.paywallView`
* `Superwall.eventDidOccur` argument `paywallViewController` in favor of `paywallView`
* `Superwall.dismiss` in favor of \`Superwall.presentPaywallView
* `Superwall.presentPaywallViewController` in favor of `Superwall.presentPaywallView`
* Deprecated `Paywallmanager.getPaywallViewController` in favor of `PaywallManager.getPaywallView`
* Deprecated `DebugManager.viewController` in favor of `DebugManager.view`
* Deprecated `DebugViewController` in favor of `DebugView`
* Deprecated `LogScope.debugViewController` in favor of `LogScope.debugView`
* Deprecated `PaywallPresentationRequestStatus.NoPaywallViewController` in favor of `NoPaywallView`
## 1.1.9
### Deprecations
* Deprecated configuration method `Superwall.configure(applicationContext: Context, ...)` in favor of `Superwall.configure(applicationContext: Application, ...)` to enforce type safety. The rest of the method signature remains the same.
### Fixes
* SW-2878: and it's related leaks. The `PaywallViewController` was not being properly detached when activity was stopped, causing memory leaks.
* SW-2872: Fixes issue where `deviceAttributes` event and fetching would not await for IP geo to complete.
* Fixes issues on tablet devices where the paywall would close after rotation/configuration change.
## 1.1.8
### Enhancements
* SW-2859: Adds error message to `paywallWebviewLoad_fail`.
* SW-2866: Logs error when trying to purchase a product that has failed to load.
* SW-2869: Add `Reset` event to track when `Superwall.instance.reset` is called.
* SW-2867: Prevents Geo api from being called when app is in the background
* SW-2431: Improves coroutine scope usages & threading limits
* Toolchain and dependency updates
### Fixes
* SW-2863: Fixed a `NullPointerException` some users on Android 12 & 13 would experience when calling `configure`.
## 1.1.7
### Enhancements
* SW-2805: Exposes a `presentation` property on the `PaywallInfo` object. This contains information about the presentation of the paywall.
* SW-2855: Adds `restore_start`, `restore_complete`, and `restore_fail` events.
### Fixes
* SW-2854: Fixed issue where abandoning the transaction by pressing back would prevent the user from restarting the transaction.
## 1.1.6
### Enhancements
* SW-2833: Adds support for dark mode paywall background color.
* Adds ability to target devices based on their IP address location. Use `device.ipRegion`,
`device.ipRegionCode`, `device.ipCountry`, `device.ipCity`, `device.ipContinent`, or `device.ipTimezone`.
* Adds `event_name` to the event params for use with audience filters.
### Fixes
* Fixes issue with products whose labels weren't primary/secondary/tertiary.
## 1.1.5
### Fixes
* Fixes thread safety crash when multiple threads attempted to initialize the `JavaScriptSandbox`
internally.
## 1.1.3
### Enhancements
* Tracks an `identity_alias` event whenever identify is called to alias Superwall's anonymous ID with a
developer provided id.
* Adds `setInterfaceStyle(interfaceStyle:)` which can be used to override the system interface style.
* Adds `device.interfaceStyleMode` to the device template, which can be `automatic` or `manual` if
overriding the interface style.
### Fixes
* Uses `JavascriptSandbox` when available for filter expression evaluation on a background thread
instead of running code on the main thread in a webview.
* Fixes crash where the loading spinner inside the `PaywallViewController` was being updated outside
the main thread.
## 1.1.2
### Enhancements
* Updates build.gradle configuration which means we can now upload the SDK to maven central. You no
longer need to specify our custom repo in your build.gradle to get our SDK and therefore installation
should be easier.
### Fixes
* Fixes `ConcurrentModificationException` crash that sometimes happened when identifying a user.
* Fixes crash on purchasing a free trial when using `getPaywall`.
## 1.1.1
### Fixes
* Fixes an issue loading products with offers.
## 1.1.0
### Enhancements
* SW-2768: Adds `device.regionCode` and `device.preferredRegionCode`, which returns the `regionCode`
of the locale. For example, if a locale is `en_GB`, the `regionCode` will be `GB`. You can use this
in the filters of your campaign.
* Adds support for unlimited products in a paywall.
* SW-2785: Adds internal feature flag to disable verbose events like `paywallResponseLoad_start`.
### Fixes
* SW-2732: User attributes weren't being sent on app open until identify was called. Now they are
sent every time there's a new session.
* SW-2733: Fixes issue where the spinner would still show on a paywall if a user had previously
purchased on it.
* SW-2744: Fixes issue where using the back button to dismiss a paywall presented via `getPaywall`
would call `didFinish` in the `PaywallViewControllerDelegate` with the incorrect values.
* Fixes issue where an invalid paywall background color would prevent the paywall from opening. If
this happens, it will now default to white.
* SW-2748: Exposes `viewWillAppear`, `viewDidAppear`, `viewWillDisappear` and `viewDidDisappear`
methods of `PaywallViewController` which you must call when using `getPaywall`.
* Stops `Superwall.configure` from being called multiple times.
* `getPresentationResult` now confirms assignments for holdouts.
* Gracefully handles unknown local notification types if new ones are added in the future.
* SW-2761: Fixes issue where "other" responses in paywall surveys weren't showing in the dashboard.
## 1.0.2
### Fixes
* Prevents a paywall from opening in a separate activity inside a task manager when using `taskAffinity`
within your app.
## 1.0.1
### Fixes
* Fixes serialization of `feature_gating` in `SuperwallEvents`.
* Changes the product loading so that if preloading is enabled, it makes one API request to get all
products available in paywalls. This results in fewer API requests. Also, it adds retry logic on failure.
If billing isn't available on device, the `onError` handler will be called.
## 1.0.0
### Breaking Changes
* Changes the import path for the `LogScope`, and `LogLevel`.
### Fixes
* Fixes rare thread-safety crash when sending events back to Superwall's servers.
* Calls the `onError` presentation handler block when there's no activity to present a paywall on.
* Fixes issue where the wrong product may be presented to purchase if a free trial had already been
used and you were letting Superwall handle purchases.
* Fixes `IllegalStateException` on Samsung devices when letting Superwall handle purchases.
* Keeps the text zoom of paywalls to 100% rather than respecting the accessibility settings text zoom,
which caused unexpected UI issues.
* Fixes rare `UninitializedPropertyAccessException` crash caused by a threading issue.
* Fixes crash when the user has disabled the Android System WebView.
## 1.0.0-alpha.45
### Fixes
* Fixes issue where the `paywallProductsLoad_fail` event wasn't correctly being logged. This is a
"soft fail", meaning that even though it gets logged, your paywall will still show. The error message
with the event has been updated to include all product subscription IDs that are failing to be retrieved.
## 1.0.0-alpha.44
### Fixes
* Fixes rare issue where paywall preloading was preventing paywalls from showing.
## 1.0.0-alpha.43
### Enhancements
* Adds `handleLog` to the `SuperwallDelegate`.
## 1.0.0-alpha.42
### Fixes
* Makes sure client apps use our proguard file.
## 1.0.0-alpha.41
### Fixes
* Removes need for `SCHEDULED_EXACT_ALARM` permission in manifest.
## 1.0.0-alpha.40
### Fixes
* Fixes issue presenting paywalls to users who had their device language set to Russian, Polish or
Czech.
## 1.0.0-alpha.39
### Fixes
* Adds missing `presentationSourceType` to `PaywallInfo`.
* Fixes issue where the status bar color was always dark regardless of paywall color.
* Adds `TypeToken` to proguard rules to prevent r8 from 'optimizing' our code and causing a crash.
## 1.0.0-alpha.38
### Enhancements
* SW-2682: Adds `Superwall.instance.latestPaywallInfo`, which you can use to get the `PaywallInfo` of
the most recently presented view controller.
* SW-2683: Adds `Superwall.instance.isLoggedIn`, which you can use to check if the user is logged in.
### Fixes
* Removes use of `USE_EXACT_ALARM` permission that was getting apps rejected.
* Fixes issue with scheduling notifications. The paywall wasn't waiting to schedule notifications
before dismissal so the permissions wasn't always showing.
## 1.0.0-alpha.37
### Enhancements
* SW-2684: Adds error logging if the `currentActivity` is `null` when trying to present a paywall.
### Fixes
* Fixes bug where paywalls might not present on first app install.
* Fixes bug where all `paywallResponseLoad_` events were being counted as `paywallResponseLoad_start`.
* Adds ProGuard rule to prevent `DefaultLifecycleObserver` from being removed.
## 1.0.0-alpha.36
### Enhancements
* Adds `X-Subscription-Status` header to all requests.
* Caches the last `subscriptionStatus`.
* Adds `subscriptionStatus_didChange` event that is fired whenever the subscription status changes.
* Calls the delegate method `subscriptionStatusDidChange` whenever the subscription status changes.
* SW-2676: Adds a completion block to the `configure` method.
### Fixes
* Fixes issue where the main thread was blocked when accessing some properties internally.
* SW-2679: Fixes issue where the `subscription_start` event was being fired even if a non-recurring product was
purchased.
## 1.0.0-alpha.35
### Fixes
* Fixes issue where `transaction_complete` events were being rejected by the server.
## 1.0.0-alpha.34
### Breaking Changes
* Changes `Superwall.instance.getUserAttributes()` to `Superwall.instance.userAttributes`.
* `SuperwallOptions.logging.logLevel` is now non-optional. Set it to `LogLevel.none` to prevent
logs from being printed to the console.
### Enhancements
* SW-2663: Adds `preloadAllPaywalls()` and `preloadPaywalls(eventNames:)` to be able to manually
preload paywalls.
* SW-2665: Adds `Superwall.instance.userId` so you can access the current user's id.
* SW-2668: Adds `preferredLocale` and `preferredLanguageLocale` to the device attributes for use in rules.
* Adds `Superwall.instance.logLevel` as a convenience variable to set and get the log level.
### Fixes
* SW-2664: Fixes race condition between resetting and presenting paywalls.
## 1.0.0-alpha.33
### Fixes
* Fixes issue where a user would be asked to enable notifications even if there weren't any attached
to the paywall.
## 1.0.0-alpha.32
### Enhancements
* SW-2214: Adds ability to use free trial notifications with a paywall.
* Adds `cancelAllScheduledNotifications()` to cancel any scheduled free trial notifications.
* SW-2640: Adds `computedPropertyRequests` to `PaywallInfo`.
* SW-2641: Makes `closeReason` in `PaywallInfo` non-optional.
### Fixes
* Fixes issue where thrown exceptions weren't always being caught.
## 1.0.0-alpha.31
### Enhancements
* SW-2638: Adds `Restored` to `PurchaseResult`.
* SW-2644: Adds `RestoreType` to `SuperwallEvent.TransactionRestore`.
* SW-2643: Makes `storePayment` non-optional for a `StoreTransaction`.
* SW-2642: Adds `productIdentifier` to `StorePayment`.
### Fixes
* SW-2635: Fixes crash that sometimes occurred if an app was trying to get Superwall's paywall
configuration in the background.
## 1.0.0-alpha.30
### Enhancements
* SW-2154: The SDK now includes a paywall debugger, meaning you can scan the QR code of any paywall in the
editor to preview it on device. You can change its localization, view product attributes, and view
the paywall with or without a trial.
### Fixes
* More bug fixes relating to the loading of products.
## 1.0.0-alpha.29
### Fixes
* SW-2631: Fixes issue where paywalls weren't showing if the products within them had a base plan or
offer ID set.
## 1.0.0-alpha.28
### Fixes
* SW-2615: Fixes crash on Android versions \< 8 when accessing the Android 8+ only class Period.
* SW-2616: Fixes crash where the `PaywallViewController` was sometimes being added to a new parent view before
being removed from it's existing parent view.
## 1.0.0-alpha.27
### Breaking Changes
* \#SW-2218: Changes the `PurchaseController` purchase function to `purchase(activity:productDetails:basePlanId:offerId:)`.
This adds support for purchasing offers and base plans.
### Enhancements
* \#SW-2600: Backport device attributes
* Adds support for localized paywalls.
* Paywalls are only preloaded if their associated rules can match.
* Adds status bar to full screen paywalls.
### Fixes
* Fixes issue where holdouts were still matching even if the limit set for their corresponding rules were exceeded.
* \#SW-2584: Fixes issue where prices with non-terminating decimals were causing products to fail to load.
## 1.0.0-alpha.26
### Fixes
* Additional fixes to make Google billing more robust.
* Fixes an issue that causes `transaction_complete` events to fail.
## 1.0.0-alpha.25
### Fixes
* Fixes [Google Billing Crash on Samsung devices](https://community.revenuecat.com/sdks-51/how-to-fix-crash-too-many-bind-requests-999-for-service-intent-inappbillingservice-3317).
## 1.0.0-alpha.24
### Fixes
* Fixes an issue that could cause "n/a" to be displayed on a paywall in place of the proper subscription period string.
## 1.0.0-alpha.23
### Fixes
* Fixes an issue where calling `identify` right after `configure` would hang b/c network requests need to access the user id to add to headers.
* Fixes a potential crash when loading data from disk
## 1.0.0-alpha.22
### Fixes
* Fixes threading issue
## 1.0.0-alpha.21
### Fixes
* Changes Activity to AppCompatActivity
## 1.0.0-alpha.20
### Enhancements
### Fixes
* Fixes `app_open` race condition
* Prevents calling purchase twice
* Disables interactivity during purchase
## 1.0.0-alpha.19
### Fixes
* Fixes `app_launch` event not triggering
## 1.0.0-alpha.18
### Enhancements
* Adds the ability to provide an `ActivityProvider` when configuring the SDK. This is an interface
containing the function `getCurrentActivity()`, which Superwall will use to present paywalls from.
You would typically conform an `ActivityLifecycleTracker` to this interface.
### Fixes
* Fixes a crash when storing a `List` to user attributes and if that List or a Map had a null value.
## 1.0.0-alpha.17
### Enhancements
* Adds automatic purchase controller
* Improves memory handling for webviews
* Hides the loading indicator on a paywall if transactionBackgroundView is set to NONE
## 1.0.0-alpha.14
### Enhancements
* Adds `trigger_session_id` to Superwall Events.
* Resets the scroll position of the paywall on close.
### Fixes
* Fixes issue where an invalid currency code on a device would crash the app when trying to retrieve products.
## 1.0.0-alpha.13
### Fixes
* Fixes concurrency issues when setting and retrieving values like the appUserId and seed.
## 1.0.0-alpha.11
### Fixes
* Can now use both non-recurring products and subscription products in paywalls.
* Fixes a crash issue that was caused by a lazy variable being accessed before it was initialized.
---
# Welcome
Source: https://superwall.com/docs/android
Welcome to the Superwall Android SDK documentation
## Quick Links
Get up and running with the Superwall Android SDK
Most common features and use cases
Reference the Superwall Android SDK
Guides for specific use cases
Example app for the Superwall Android SDK
Guides for troubleshooting common issues
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-android/issues).
---
# External Paywall Creation
Source: https://superwall.com/docs/advanced-paywall-creation
undefined
The legacy editor is deprecated. Please visit the docs covering our new
[editor](/paywall-editor-overview).
The following is only necessary if you're looking to build your own paywall website outside of Superwall. We strongly recommend using the paywall editor or templates instead.
### Data Tags
Data tags are specific attributes attached to elements, like text, links, or buttons, on the paywall webpage.\
These are recognised by a special script called [Paywall.js](/docs/advanced-paywall-creation#paywalljs) that interprets user feedback and transmits information to and from the SDK. These are built in to the templates we've created and you don't need to worry about them unless you're building your own paywall webpage. When you configure your paywall webpage on the Superwall dashboard, the dashboard instantly recognizes the data tags on your website. From there you can edit the text that appears in the tagged elements.
There are seven different types of data tag:
| Name | Value | Purpose |
| ----------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| data-pw-var | The reference name of the element, e.g. "Title". | This indicates to Superwall that the element should be remotely configurable. The Superwall dashboard will create an editable text field for this element. The reference name of that text field will be equal to the value you provide. |
| data-pw-close | Add anything as a value. It's ignored. | Closes the paywall. |
| data-pw-restore | Add anything as a value. It's ignored. | For restoring purchases, if you bought on a different device. |
| data-pw-purchase | Either primary, secondary, or tertiary. | This relates to your primary, secondary, or tertiary product set up in the Superwall dashboard respectively. When the tagged element is tapped, it tells the SDK to initialize a purchase of the specified product. |
| data-pw-open-url | A valid url. E.g.` .` | Normal href links do not work in a paywall. However, attaching this tag to an element opens the provided url. |
| data-pw-open-deep-link | A valid deep link url. E.g. fb://profile/33138223345. | Opens a deeplink from a button on a paywall. |
| data-pw-custom | A name for a custom action | When the tagged element is tapped, the SDK calls its delegate method handleCustomPaywallAction(withName:). The value you provide is passed to the function, from which you can perform custom logic. Check out [Custom Paywall Buttons](/docs/custom-paywall-events) for more. |
| data-pw-skip-inner-html | true | This prevents an element's text from being edited. It tells Paywall.js to keep looking into the element's children for more data-pw-var tags. This is useful when you want to hide a whole section or edit the style of a container, rather than edit its text. |
Here are a few examples of what data tags look like in the webpage HTML:
```html HTML
```
### Paywall.js
Paywall.js is a javascript utility that recognizes data tags and acts as the interface between the Superwall client SDK and the webpage presented to the user. It does a few fancy tricks to make the HTML feel native, but it's main purpose is to interpret user feedback and transmit information to and from the SDK. In addition, when you configure a paywall on the Superwall dashboard, the dashboard instantly recognizes the data tags you’ve provided. From there, you can edit the text of all tagged items.
To get your webpage to be operable with Superwall, you need to add the Paywall.js script to the header of your site.
We recommend using [Webflow](https://webflow.com). To add custom scripts to a Webflow webpage you need to have a paid Webflow account. However, our [clonable Webflow project](https://webflow.com/website/45-Paywall-Elements?ref=showcase-search\&searchValue=superwall) already includes this script. Therefore, we recommend using the cloned project as the basis of your paywalls. In this project, we've also removed the Webflow watermark that is attached to all free Webflow webpages.
If you'd like to add this script yourself, open the **Pages panel**, select the **cog wheel** next to the page name, then scroll down to the **Custom Code** section. In the **Inside head tag** section, add the following code:
```html HTML
```
Do not remove async
Paywall.js is available to Superwall customers subject to the terms of the subscription agreement
between Superwall and the customer, and is not available as an open-source project.
### Game Controller
Paywall.js now supports game controller input so users can make purchases while maintaining the native game controller experience.
#### Basic Setup
To attach an on-screen button to a game controller button, simply add the `data-pw-gc-button` tag to the element. The value of this tag must match the [unmappedLocalizedName](https://developer.apple.com/documentation/gamecontroller/gccontrollerelement/3681941-unmappedlocalizedname) of the game controller button in iOS.
For example, the following button would purchase the primary product if a user pressed the "A" button on their game controller.
```html HTML
Purchase
```
#### Styling
To allow users to style buttons, we will add and remove classes during the button press event. When the game controller input becomes depressed, we add `pw-gc-press`. When the button is let up, we will remove that class. Many users will use these classes to slightly shirk the button on press and restore it on press end.
```css CSS
.pw-gc-press {
opacity: 0.9;
transition: all .2s ease-in-out;
transform: scale(0.93);
}
```
#### Advanced
Some users may want to take other actions based on the game controller input so we will automatically forward all game controller events to a function on the window if it is defined.
```typescript TypeScript
type DirectionalInput = {
controller_element: string
directional: true
x: number
y: number
}
type NonDirectionalInput = {
controller_element: string
directional: false
value: number
}
export type Input =
| DirectionalInput
| NonDirectionalInput
window.onGameControllerInput = (data: Input) => {
// Do anything you want with the input!
}
```
---
# Using Implicit Events
Source: https://superwall.com/docs/using-implicit-events
The following [Superwall Events](/docs/tracking-analytics) are automatically registered by the SDK and can be added as events in campaigns to present paywalls.
This page is outdated. Please visit this [one](/campaigns-placements#implicit-placements) for more
relevant information.
* `app_install` \* `app_launch` \* `deepLink_open` \* `session_start` \* `paywall_decline` \* `transaction_fail`
* `transaction_abandon` \* `survey_response` \* `touches_began`
Visit [Superwall Events](/docs/tracking-analytics) to see a full list of parameters that you can use with these events.
### `paywall_decline`
This is registered when a user manually dismisses any paywall.
You can combine this with rules to show a paywall when a user closes a specific paywall:
Here, when a user closes the paywall named `Example Paywall | Non Gated`, a new paywall will show.
Note that you can't reference parameters that you've passed in to your original register call in your rules for `paywall_decline`.
### `survey_response`
This is registered when a response to a paywall survey as been recorded. First, you need to make sure your paywall [has a survey attached](/docs/surveys).
You can combine this with rules to show a paywall whenever a survey response is recorded or when the user gives a specific response:
Here if the user selects an option named `Too Expensive`, they will see another paywall. This is a great opportunity to show a discounted paywall to improve your conversion rate.
### `deepLink_open`
This is registered when a user opens the app via a deep link. First, you need to make sure to [tell Superwall when a deep link has been opened](/docs/in-app-paywall-previews).
You can use the URL parameters of the deep link within your rules:
This rule will match the deep link `myapp://paywall?offer=July20`.
---
# Setting User Attributes (Legacy)
Source: https://superwall.com/docs/legacy/legacy_setting-user-properties
By setting user attributes, you can display information about the user on the paywall. You can also define [audiences](/campaigns-audience) in a campaign to determine which paywall to show to a user, based on their user attributes.
You do this by passing a `[String: Any?]` dictionary of attributes to `Superwall.shared.setUserAttributes(_:)`:
```swift Swift
let attributes: [String: Any] = [
"name": user.name,
"apnsToken": user.apnsTokenString,
"email": user.email,
"username": user.username,
"profilePic": user.profilePicUrl
]
Superwall.shared.setUserAttributes(attributes) // (merges existing attributes)
```
```swift Objective-C
NSDictionary *attributes = @{
@"name": user.name,
@"apnsToken": user.apnsTokenString,
@"email": user.email,
@"username": user.username,
@"profilePic": user.profilePicUrl
};
[[Superwall sharedInstance] setUserAttributes:attributes]; // (merges existing attributes)
```
```kotlin Kotlin
val attributes = mapOf(
"name" to user.name,
"apnsToken" to user.apnsTokenString,
"email" to user.email,
"username" to user.username,
"profilePic" to user.profilePicUrl
)
Superwall.instance.setUserAttributes(attributes) // (merges existing attributes)
```
```dart Flutter
Map attributes = {
"name": user.name,
"apnsToken": user.apnsTokenString,
"email": user.email,
"username": user.username,
"profilePic": user.profilePicUrl
};
Superwall.shared.setUserAttributes(attributes); // (merges existing attributes)
```
```typescript React Native
const attributes = {
name: user.name,
apnsToken: user.apnsTokenString,
email: user.email,
username: user.username,
profilePic: user.profilePicUrl,
};
Superwall.shared.setUserAttributes(attributes);
```
This is a merge operation, such that if the existing user attributes dictionary
already has a value for a given property, the old value is overwritten. Other
existing properties will not be affected. To unset/delete a value, you can pass `nil`
for the value.
You can reference user attributes in [campaign filters](/campaigns-audience) to help decide when to display your paywall. When you configure your paywall, you can also reference the user attributes in its text variables. For more information on how to that, see [Configuring a Paywall](/paywall-editor-overview).
In the future, you'll be able to use user attributes to email/notify users about
discounts.
Begin showing paywalls!
---
# React Native - Package.json (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation-via-package
Install the Superwall React Native SDK via npm or yarn. To see the latest release, [check out the repository](https://github.com/superwall/react-native-superwall).
Note that Superwall does **not** refetch its configuration during hot reloads. So, if you add products, edit a paywall, or otherwise change anything with Superwall, re-run your app to see those changes.
## Option 1: React-Native package
To use Superwall in your React Native project, add `@superwall/react-native-superwall` as a dependency in your `package.json` file by using npm or yarn:
```bash npm
npm install @superwall/react-native-superwall
```
```bash yarn
yarn add @superwall/react-native-superwall
```
## Option 2: Using Expo
If you have an Expo project, you can add the dependency with npx:
```
npx expo install @superwall/react-native-superwall
```
Please note that Superwall does not support Expo Go. Expo Go only supports prebuilt Expo libraries; it cannot load third-party SDKs with custom native code. If you are using a **managed workflow**, create a [development build](https://docs.expo.dev/workflow/overview/#development-builds) to continue using Expo tools while including Superwall. Otherwise, you will encounter linking errors.
Here's a quick table to review your installation methods:
| **Workflow** | **Superwall Support** | **Notes** |
| --------------------- | --------------------------- | ------------------------------------ |
| **Expo Go** | ❌ Not supported | Expo Go cannot load native SDKs. |
| **Managed Workflow** | ℹ️ Requires additional step | Use a **Development Build**. |
| **Development Build** | ✅ Supported | Works with Expo tools + custom code. |
| **Unmanaged (Bare)** | ✅ Supported | Full control over native code. |
### iOS Deployment Target
Superwall requires iOS 14.0 or higher. Ensure your React Native project's iOS deployment target is 14.0 or higher by updating ios/Podfile.
```ruby
platform :ios, '14.0'
```
## Android Configuration
For Android projects, you'll also need to include Superwall's Maven repository.
First, install the `expo-build-properties` config plugin if your Expo project hasn’t yet:
```bash
npx expo install expo-build-properties
```
Then, add the following to your `app.json` or `app.config.js` file:
```json
{
"expo": {
"plugins": [
...
[
"expo-build-properties",
{
"android": {
"minSdkVersion": 26
}
}
]
]
}
}
```
Superwall requires a minimum SDK version of 26 or higher. Ensure your React Native project's Android SDK target is set to 26 or higher by updating `android/app/build.gradle`.
```groovy gradle
android {
...
defaultConfig {
...
minSdkVersion 26
...
}
}
```
**And you're done!** Now you're ready to configure the SDK 👇
Begin configuring the SDK to show paywalls inside your App!
---
# 3rd Party Analytics (Legacy)
Source: https://superwall.com/docs/legacy/legacy_3rd-party-analytics
Superwall can easily be integrated with 3rd party analytics tools.
### Hooking up Superwall events to 3rd party tools
SuperwallKit automatically tracks some internal events. You can [view the list of events here](/legacy/legacy_tracking-analytics). We encourage you to also track them in your own analytics by implementing the [Superwall delegate](/legacy/legacy_using-superwall-delegate). Using the `handleSuperwallEvent(withInfo:)` function, you can forward events to your analytics service:
```swift Swift
extension SuperwallService: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
print("analytics event called", eventInfo.event.description)
MyAnalyticsService.shared.track(
event: eventInfo.event.description,
params: eventInfo.params
)
}
}
```
```swift Objective-C
- (void)didTrackSuperwallEventInfo:(SWKSuperwallEventInfo *)info {
NSLog(@"Analytics event called %@", info.event.description));
[[MyAnalyticsService shared] trackEvent:info.event.description params:info.params];
}
```
```kotlin Kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
println("analytics event: ${eventInfo.event.rawName}")
MyAnalytics.shared.trac(eventInfo.event.rawName, eventInfo.params)
}
```
```dart Flutter
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
print("handleSuperwallEvent: $eventInfo");
// Example usage...
switch (eventInfo.event.type) {
case EventType.appOpen:
print("appOpen event");
case EventType.deviceAttributes:
print("deviceAttributes event: ${eventInfo.event.deviceAttributes} ");
case EventType.paywallOpen:
final paywallInfo = eventInfo.event.paywallInfo;
print("paywallOpen event: ${paywallInfo} ");
if (paywallInfo != null) {
final identifier = await paywallInfo.identifier;
print("paywallInfo.identifier: ${identifier} ");
final productIds = await paywallInfo.productIds;
print("paywallInfo.productIds: ${productIds} ");
}
default:
break;
}
}
```
```typescript React Native
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
console.log(`handleSuperwallEvent: ${eventInfo}`);
// Assuming eventInfo has a type property and other necessary properties
switch (eventInfo.event.type) {
case EventType.appOpen:
console.log("appOpen event");
break; // Don't forget to add break statements to prevent fall-through
case EventType.deviceAttributes:
console.log(`deviceAttributes event: ${eventInfo.event.deviceAttributes}`);
break;
case EventType.paywallOpen:
const paywallInfo = eventInfo.event.paywallInfo;
console.log(`paywallOpen event: ${paywallInfo}`);
if (paywallInfo !== null) {
paywallInfo.identifier().then((identifier: string) => {
console.log(`paywallInfo.identifier: ${identifier}`);
});
paywallInfo.productIds().then((productIds: string[]) => {
console.log(`paywallInfo.productIds: ${productIds}`);
});
}
break;
default:
break;
}
}
```
You might also want to set user attribute to allow for [Cohorting in 3rd Party Tools](/legacy/legacy_cohorting-in-3rd-party-tools)
Alternatively, if you want typed versions of all these events with associated values, you can access them via `eventInfo.event`:
```swift Swift
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case .firstSeen:
break
case .appOpen:
break
case .appLaunch:
break
case .appInstall:
break
case .sessionStart:
break
case .appClose:
break
case .deepLink(let url):
break
case .triggerFire(let eventName, let result):
break
case .paywallOpen(let paywallInfo):
break
case .paywallClose(let paywallInfo):
break
case .transactionStart(let product, let paywallInfo):
break
case .transactionFail(let error, let paywallInfo):
break
case .transactionAbandon(let product, let paywallInfo):
break
case .transactionComplete(let transaction, let product, let paywallInfo):
break
case .subscriptionStart(let product, let paywallInfo):
break
case .freeTrialStart(let product, let paywallInfo):
break
case .transactionRestore(let paywallInfo):
break
case .userAttributes(let attributes):
break
case .nonRecurringProductPurchase(let product, let paywallInfo):
break
case .paywallResponseLoadStart(let triggeredEventName):
break
case .paywallResponseLoadNotFound(let triggeredEventName):
break
case .paywallResponseLoadFail(let triggeredEventName):
break
case .paywallResponseLoadComplete(let triggeredEventName, let paywallInfo):
break
case .paywallWebviewLoadStart(let paywallInfo):
break
case .paywallWebviewLoadFail(let paywallInfo):
break
case .paywallWebviewLoadComplete(let paywallInfo):
break
case .paywallWebviewLoadTimeout(let paywallInfo):
break
case .paywallProductsLoadStart(let triggeredEventName, let paywallInfo):
break
case .paywallProductsLoadFail(let triggeredEventName, let paywallInfo):
break
case .paywallProductsLoadComplete(let triggeredEventName):
break
case .subscriptionStatusDidChange:
break
}
}
```
```kotlin Kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when(eventInfo.event) {
is SuperwallEvent.AppClose -> TODO()
is SuperwallEvent.AppInstall -> TODO()
is SuperwallEvent.AppLaunch -> TODO()
is SuperwallEvent.AppOpen -> TODO()
is SuperwallEvent.DeepLink -> TODO()
is SuperwallEvent.FirstSeen -> TODO()
is SuperwallEvent.FreeTrialStart -> TODO()
is SuperwallEvent.NonRecurringProductPurchase -> TODO()
is SuperwallEvent.PaywallClose -> TODO()
is SuperwallEvent.PaywallDecline -> TODO()
is SuperwallEvent.PaywallOpen -> TODO()
is SuperwallEvent.PaywallPresentationRequest -> TODO()
is SuperwallEvent.PaywallProductsLoadComplete -> TODO()
is SuperwallEvent.PaywallProductsLoadFail -> TODO()
is SuperwallEvent.PaywallProductsLoadStart -> TODO()
is SuperwallEvent.PaywallResponseLoadComplete -> TODO()
is SuperwallEvent.PaywallResponseLoadFail -> TODO()
is SuperwallEvent.PaywallResponseLoadNotFound -> TODO()
is SuperwallEvent.PaywallResponseLoadStart -> TODO()
is SuperwallEvent.PaywallWebviewLoadComplete -> TODO()
is SuperwallEvent.PaywallWebviewLoadFail -> TODO()
is SuperwallEvent.PaywallWebviewLoadStart -> TODO()
is SuperwallEvent.PaywallWebviewLoadTimeout -> TODO()
is SuperwallEvent.SessionStart -> TODO()
is SuperwallEvent.SubscriptionStart -> TODO()
is SuperwallEvent.SubscriptionStatusDidChange -> TODO()
is SuperwallEvent.SurveyClose -> TODO()
is SuperwallEvent.SurveyResponse -> TODO()
is SuperwallEvent.TransactionAbandon -> TODO()
is SuperwallEvent.TransactionComplete -> TODO()
is SuperwallEvent.TransactionFail -> TODO()
is SuperwallEvent.TransactionRestore -> TODO()
is SuperwallEvent.TransactionStart -> TODO()
is SuperwallEvent.TransactionTimeout -> TODO()
is SuperwallEvent.TriggerFire -> TODO()
is SuperwallEvent.UserAttributes -> TODO()
}
}
```
```dart Flutter
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
// Example usage...
switch (eventInfo.event.type) {
case EventType.appOpen:
print("appOpen event");
case EventType.deviceAttributes:
print("deviceAttributes event: ${eventInfo.event.deviceAttributes} ");
case EventType.paywallOpen:
final paywallInfo = eventInfo.event.paywallInfo;
print("paywallOpen event: ${paywallInfo} ");
if (paywallInfo != null) {
final identifier = await paywallInfo.identifier;
print("paywallInfo.identifier: ${identifier} ");
final productIds = await paywallInfo.productIds;
print("paywallInfo.productIds: ${productIds} ");
}
default:
break;
}
}
```
```typescript React Native
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
console.log(`handleSuperwallEvent: ${eventInfo}`);
// Assuming eventInfo has a type property and other necessary properties
switch (eventInfo.event.type) {
case EventType.appOpen:
console.log("appOpen event");
break; // Don't forget to add break statements to prevent fall-through
case EventType.deviceAttributes:
console.log(`deviceAttributes event: ${eventInfo.event.deviceAttributes}`);
break;
case EventType.paywallOpen:
const paywallInfo = eventInfo.event.paywallInfo;
console.log(`paywallOpen event: ${paywallInfo}`);
if (paywallInfo !== null) {
paywallInfo.identifier().then((identifier: string) => {
console.log(`paywallInfo.identifier: ${identifier}`);
});
paywallInfo.productIds().then((productIds: string[]) => {
console.log(`paywallInfo.productIds: ${productIds}`);
});
}
break;
default:
break;
}
}
```
### Using events to see purchased products
If your goal is simply to view which product was purchased from a paywall, you don't need a [purchase controller](/legacy/legacy_advanced-configuration) for that (though it can be done in one). Using a `SuperwallDelegate`, you can leverage the `transactionComplete` event, which provides direct access to the purchased product via `product`:
```swift
import SwiftUI
import SuperwallKit
class SWDelegate: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case .transactionComplete(let transaction, let product, let paywallInfo):
print("Converted from paywall: \(product.productIdentifier)")
default:
print("\(#function) - \(eventInfo.event)")
}
}
}
@main
struct AwesomeApp: App {
init() {
Superwall.configure(apiKey: "MY_API_KEY")
Superwall.shared.delegate = self.swDelegate
}
var body: some Scene {
WindowGroup {
ContentView()
.onAppear { Superwall.shared.register(event: "test_event") }
}
}
}
```
In that example, as soon as a user converts on a paywall, the product identifier will be printed to the console:
```bash
Converted from paywall: ex.someProduct.identifier
```
---
# Using RevenueCat (Legacy)
Source: https://superwall.com/docs/legacy/legacy_using-revenuecat
If you want to use RevenueCat to handle your subscription-related logic with Superwall, follow this guide.
Not using RevenueCat? No problem! Superwall works out of the box without any additional SDKs.
Integrate RevenueCat with Superwall in one of two ways:
1. **Using a purchase controller:** Use this route if you want to maintain control over purchasing logic and code.
2. **Using PurchasesAreCompletedBy:** Here, you don't use a purchase controller and you tell RevenueCat that purchases are completed by your app using StoreKit 1. In this mode, RevenueCat will observe the purchases that the Superwall SDK makes. For more info [see here](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
#### 1. Create a PurchaseController
Create a new file called `RCPurchaseController.swift` or `RCPurchaseController.kt`, then copy and paste the following:
```swift Swift
import SuperwallKit
import RevenueCat
import StoreKit
enum PurchasingError: Error {
case productNotFound
}
final class RCPurchaseController: PurchaseController {
// MARK: Sync Subscription Status
/// Makes sure that Superwall knows the customers subscription status by
/// changing `Superwall.shared.subscriptionStatus`
func syncSubscriptionStatus() {
assert(Purchases.isConfigured, "You must configure RevenueCat before calling this method.")
Task {
for await customerInfo in Purchases.shared.customerInfoStream {
// Gets called whenever new CustomerInfo is available
let hasActiveSubscription = !customerInfo.entitlements.activeInCurrentEnvironment.isEmpty // Why? -> https://www.revenuecat.com/docs/entitlements#entitlements
if hasActiveSubscription {
Superwall.shared.subscriptionStatus = .active
} else {
Superwall.shared.subscriptionStatus = .inactive
}
}
}
}
// MARK: Handle Purchases
/// Makes a purchase with RevenueCat and returns its result. This gets called when
/// someone tries to purchase a product on one of your paywalls.
func purchase(product: SKProduct) async -> PurchaseResult {
do {
guard let storeProduct = await Purchases.shared.products([product.productIdentifier]).first else {
throw PurchasingError.productNotFound
}
// This must be initialized before initiating the purchase.
let purchaseDate = Date()
let revenueCatResult = try await Purchases.shared.purchase(product: storeProduct)
if revenueCatResult.userCancelled {
return .cancelled
} else {
if let transaction = revenueCatResult.transaction,
purchaseDate > transaction.purchaseDate {
return .restored
} else {
return .purchased
}
}
} catch let error as ErrorCode {
if error == .paymentPendingError {
return .pending
} else {
return .failed(error)
}
} catch {
return .failed(error)
}
}
// MARK: Handle Restores
/// Makes a restore with RevenueCat and returns `.restored`, unless an error is thrown.
/// This gets called when someone tries to restore purchases on one of your paywalls.
func restorePurchases() async -> RestorationResult {
do {
_ = try await Purchases.shared.restorePurchases()
return .restored
} catch let error {
return .failed(error)
}
}
}
```
```kotlin Kotlin
// RCPurchaseController.kt
import android.app.Activity
import android.content.Context
import com.android.billingclient.api.ProductDetails
import com.revenuecat.purchases.*
import com.revenuecat.purchases.interfaces.GetStoreProductsCallback
import com.revenuecat.purchases.interfaces.PurchaseCallback
import com.revenuecat.purchases.interfaces.ReceiveCustomerInfoCallback
import com.revenuecat.purchases.interfaces.UpdatedCustomerInfoListener
import com.revenuecat.purchases.models.StoreProduct
import com.revenuecat.purchases.models.StoreTransaction
import com.revenuecat.purchases.models.SubscriptionOption
import com.revenuecat.purchases.models.googleProduct
import com.superwall.sdk.Superwall
import com.superwall.sdk.delegate.PurchaseResult
import com.superwall.sdk.delegate.RestorationResult
import com.superwall.sdk.delegate.SubscriptionStatus
import com.superwall.sdk.delegate.subscription_controller.PurchaseController
import kotlinx.coroutines.CompletableDeferred
// Extension function to convert callback to suspend function
suspend fun Purchases.awaitProducts(productIds: List): List {
val deferred = CompletableDeferred>()
getProducts(productIds, object : GetStoreProductsCallback {
override fun onReceived(storeProducts: List) {
deferred.complete(storeProducts)
}
override fun onError(error: PurchasesError) {
// Not sure about this cast...
deferred.completeExceptionally(Exception(error.message))
}
})
return deferred.await()
}
interface PurchaseCompletion {
var storeTransaction: StoreTransaction
var customerInfo: CustomerInfo
}
// Create a custom exception class that wraps PurchasesError
private class PurchasesException(val purchasesError: PurchasesError) : Exception(purchasesError.toString())
suspend fun Purchases.awaitPurchase(activity: Activity, storeProduct: StoreProduct): PurchaseCompletion {
val deferred = CompletableDeferred()
purchase(PurchaseParams.Builder(activity, storeProduct).build(), object : PurchaseCallback {
override fun onCompleted(storeTransaction: StoreTransaction, customerInfo: CustomerInfo) {
deferred.complete(object : PurchaseCompletion {
override var storeTransaction: StoreTransaction = storeTransaction
override var customerInfo: CustomerInfo = customerInfo
})
}
override fun onError(error: PurchasesError, p1: Boolean) {
deferred.completeExceptionally(PurchasesException(error))
}
})
return deferred.await()
}
suspend fun Purchases.awaitRestoration(): CustomerInfo {
val deferred = CompletableDeferred()
restorePurchases(object : ReceiveCustomerInfoCallback {
override fun onReceived(purchaserInfo: CustomerInfo) {
deferred.complete(purchaserInfo)
}
override fun onError(error: PurchasesError) {
deferred.completeExceptionally(error as Throwable)
}
})
return deferred.await()
}
class RCPurchaseController(val context: Context): PurchaseController, UpdatedCustomerInfoListener {
init {
Purchases.logLevel = LogLevel.DEBUG
Purchases.configure(PurchasesConfiguration.Builder(context, "MY_ANDROID_API_KEY").build())
// Make sure we get the updates
Purchases.sharedInstance.updatedCustomerInfoListener = this
}
fun syncSubscriptionStatus() {
// Refetch the customer info on load
Purchases.sharedInstance.getCustomerInfoWith {
if (hasAnyActiveEntitlements(it)) {
setSubscriptionStatus(SubscriptionStatus.ACTIVE)
} else {
setSubscriptionStatus(SubscriptionStatus.INACTIVE)
}
}
}
/**
* Callback for RC customer updated info
*/
override fun onReceived(customerInfo: CustomerInfo) {
if (hasAnyActiveEntitlements(customerInfo)) {
setSubscriptionStatus(SubscriptionStatus.ACTIVE)
} else {
setSubscriptionStatus(SubscriptionStatus.INACTIVE)
}
}
/**
* Initiate a purchase
*/
override suspend fun purchase(
activity: Activity,
productDetails: ProductDetails,
basePlanId: String?,
offerId: String?
): PurchaseResult {
// Find products matching productId from RevenueCat
val products = Purchases.sharedInstance.awaitProducts(listOf(productDetails.productId))
// Choose the product which matches the given base plan.
// If no base plan set, select first product or fail.
val product = products.firstOrNull { it.googleProduct?.basePlanId == basePlanId }
?: products.firstOrNull()
?: return PurchaseResult.Failed("Product not found")
return when (product.type) {
ProductType.SUBS, ProductType.UNKNOWN -> handleSubscription(activity, product, basePlanId, offerId)
ProductType.INAPP -> handleInAppPurchase(activity, product)
}
}
private fun buildSubscriptionOptionId(basePlanId: String?, offerId: String?): String =
buildString {
basePlanId?.let { append("$it") }
offerId?.let { append(":$it") }
}
private suspend fun handleSubscription(
activity: Activity,
storeProduct: StoreProduct,
basePlanId: String?,
offerId: String?
): PurchaseResult {
storeProduct.subscriptionOptions?.let { subscriptionOptions ->
// If subscription option exists, concatenate base + offer ID.
val subscriptionOptionId = buildSubscriptionOptionId(basePlanId, offerId)
// Find first subscription option that matches the subscription option ID or default
// to letting revenuecat choose.
val subscriptionOption = subscriptionOptions.firstOrNull { it.id == subscriptionOptionId }
?: subscriptionOptions.defaultOffer
// Purchase subscription option, otherwise fail.
if (subscriptionOption != null) {
return purchaseSubscription(activity, subscriptionOption)
}
}
return PurchaseResult.Failed("Valid subscription option not found for product.")
}
private suspend fun purchaseSubscription(activity: Activity, subscriptionOption: SubscriptionOption): PurchaseResult {
val deferred = CompletableDeferred()
Purchases.sharedInstance.purchaseWith(
PurchaseParams.Builder(activity, subscriptionOption).build(),
onError = { error, userCancelled ->
deferred.complete(if (userCancelled) PurchaseResult.Cancelled() else PurchaseResult.Failed(error.message))
},
onSuccess = { _, _ ->
deferred.complete(PurchaseResult.Purchased())
}
)
return deferred.await()
}
private suspend fun handleInAppPurchase(activity: Activity, storeProduct: StoreProduct): PurchaseResult =
try {
Purchases.sharedInstance.awaitPurchase(activity, storeProduct)
PurchaseResult.Purchased()
} catch (e: PurchasesException) {
when (e.purchasesError.code) {
PurchasesErrorCode.PurchaseCancelledError -> PurchaseResult.Cancelled()
else -> PurchaseResult.Failed(e.message ?: "Purchase failed due to an unknown error")
}
}
/**
* Restore purchases
*/
override suspend fun restorePurchases(): RestorationResult {
try {
if (hasAnyActiveEntitlements(Purchases.sharedInstance.awaitRestoration())) {
return RestorationResult.Restored()
} else {
return RestorationResult.Failed(Exception("No active entitlements"))
}
} catch (e: Throwable) {
return RestorationResult.Failed(e)
}
}
/**
* Check if the customer has any active entitlements
*/
private fun hasAnyActiveEntitlements(customerInfo: CustomerInfo): Boolean {
val entitlements = customerInfo.entitlements.active.values.map { it.identifier }
return entitlements.isNotEmpty()
}
private fun setSubscriptionStatus(subscriptionStatus: SubscriptionStatus) {
if (Superwall.initialized) {
Superwall.instance.setSubscriptionStatus(subscriptionStatus)
}
}
}
```
```dart Flutter
import 'package:flutter/services.dart';
import 'package:purchases_flutter/purchases_flutter.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart' hide LogLevel;
class RCPurchaseController extends PurchaseController {
// MARK: Configure and sync subscription Status
/// Makes sure that Superwall knows the customers subscription status by
/// changing `Superwall.shared.subscriptionStatus`
Future syncSubscriptionStatus() async {
// Configure RevenueCat
await Purchases.setLogLevel(LogLevel.debug);
PurchasesConfiguration configuration = Platform.isIOS ? PurchasesConfiguration("MY_IOS_API_KEY") : PurchasesConfiguration("MY_ANDROID_API_KEY");
await Purchases.configure(configuration);
// Listen for changes
Purchases.addCustomerInfoUpdateListener((customerInfo) {
// Gets called whenever new CustomerInfo is available
bool hasActiveEntitlementOrSubscription = customerInfo.hasActiveEntitlementOrSubscription(); // Why? -> https://www.revenuecat.com/docs/entitlements#entitlements
if (hasActiveEntitlementOrSubscription) {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.active);
} else {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.inactive);
}
});
}
// MARK: Handle Purchases
/// Makes a purchase from App Store with RevenueCat and returns its
/// result. This gets called when someone tries to purchase a product on
/// one of your paywalls from iOS.
@override
Future purchaseFromAppStore(String productId) async {
// Find products matching productId from RevenueCat
List products = await PurchasesAdditions.getAllProducts([productId]);
// Get first product for product ID (this will properly throw if empty)
StoreProduct? storeProduct = products.firstOrNull;
if (storeProduct == null) {
return PurchaseResult.failed("Failed to find store product for $productId");
}
PurchaseResult purchaseResult = await _purchaseStoreProduct(storeProduct);
return purchaseResult;
}
/// Makes a purchase from Google Play with RevenueCat and returns its
/// result. This gets called when someone tries to purchase a product on
/// one of your paywalls from Android.
@override
Future purchaseFromGooglePlay(String productId, String? basePlanId, String? offerId) async {
// Find products matching productId from RevenueCat
List products = await PurchasesAdditions.getAllProducts([productId]);
// Choose the product which matches the given base plan.
// If no base plan set, select first product or fail.
String storeProductId = "$productId:$basePlanId";
// Try to find the first product where the googleProduct's basePlanId matches the given basePlanId.
StoreProduct? matchingProduct;
// Loop through each product in the products list.
for (final product in products) {
// Check if the current product's basePlanId matches the given basePlanId.
if (product.identifier == storeProductId) {
// If a match is found, assign this product to matchingProduct.
matchingProduct = product;
// Break the loop as we found our matching product.
break;
}
}
// If a matching product is not found, then try to get the first product from the list.
StoreProduct? storeProduct = matchingProduct ?? (products.isNotEmpty ? products.first : null);
// If no product is found (either matching or the first one), return a failed purchase result.
if (storeProduct == null) {
return PurchaseResult.failed("Product not found");
}
switch (storeProduct.productCategory) {
case ProductCategory.subscription:
SubscriptionOption? subscriptionOption = await _fetchGooglePlaySubscriptionOption(storeProduct, basePlanId, offerId);
if (subscriptionOption == null) {
return PurchaseResult.failed("Valid subscription option not found for product.");
}
return await _purchaseSubscriptionOption(subscriptionOption);
case ProductCategory.nonSubscription:
return await _purchaseStoreProduct(storeProduct);
case null:
return PurchaseResult.failed("Unable to determine product category");
}
}
Future _fetchGooglePlaySubscriptionOption(
StoreProduct storeProduct,
String? basePlanId,
String? offerId,
) async {
final subscriptionOptions = storeProduct.subscriptionOptions;
if (subscriptionOptions != null && subscriptionOptions.isNotEmpty) {
// Concatenate base + offer ID
final subscriptionOptionId = _buildSubscriptionOptionId(basePlanId, offerId);
// Find first subscription option that matches the subscription option ID or use the default offer
SubscriptionOption? subscriptionOption;
// Search for the subscription option with the matching ID
for (final option in subscriptionOptions) {
if (option.id == subscriptionOptionId) {
subscriptionOption = option;
break;
}
}
// If no matching subscription option is found, use the default option
subscriptionOption ??= storeProduct.defaultOption;
// Return the subscription option
return subscriptionOption;
}
return null;
}
Future _purchaseSubscriptionOption(SubscriptionOption subscriptionOption) async {
// Define the async perform purchase function
Future performPurchase() async {
// Attempt to purchase product
CustomerInfo customerInfo = await Purchases.purchaseSubscriptionOption(subscriptionOption);
return customerInfo;
}
PurchaseResult purchaseResult = await _handleSharedPurchase(performPurchase);
return purchaseResult;
}
Future _purchaseStoreProduct(StoreProduct storeProduct) async {
// Define the async perform purchase function
Future performPurchase() async {
// Attempt to purchase product
CustomerInfo customerInfo = await Purchases.purchaseStoreProduct(storeProduct);
return customerInfo;
}
PurchaseResult purchaseResult = await _handleSharedPurchase(performPurchase);
return purchaseResult;
}
// MARK: Shared purchase
Future _handleSharedPurchase(Future Function() performPurchase) async {
try {
// Store the current purchase date to later determine if this is a new purchase or restore
DateTime purchaseDate = DateTime.now();
// Perform the purchase using the function provided
CustomerInfo customerInfo = await performPurchase();
// Handle the results
if (customerInfo.hasActiveEntitlementOrSubscription()) {
DateTime? latestTransactionPurchaseDate = customerInfo.getLatestTransactionPurchaseDate();
// If no latest transaction date is found, consider it as a new purchase.
bool isNewPurchase = (latestTransactionPurchaseDate == null);
// If the current date (`purchaseDate`) is after the latestTransactionPurchaseDate,
bool purchaseHappenedInThePast = latestTransactionPurchaseDate?.isBefore(purchaseDate) ?? false;
if (!isNewPurchase && purchaseHappenedInThePast) {
return PurchaseResult.restored;
} else {
return PurchaseResult.purchased;
}
} else {
return PurchaseResult.failed("No active subscriptions found.");
}
} on PlatformException catch (e) {
var errorCode = PurchasesErrorHelper.getErrorCode(e);
if (errorCode == PurchasesErrorCode.paymentPendingError) {
return PurchaseResult.pending;
} else if (errorCode == PurchasesErrorCode.purchaseCancelledError) {
return PurchaseResult.cancelled;
} else {
return PurchaseResult.failed(e.message ?? "Purchase failed in RCPurchaseController");
}
}
}
// MARK: Handle Restores
/// Makes a restore with RevenueCat and returns `.restored`, unless an error is thrown.
/// This gets called when someone tries to restore purchases on one of your paywalls.
@override
Future restorePurchases() async {
try {
await Purchases.restorePurchases();
return RestorationResult.restored;
} on PlatformException catch (e) {
// Error restoring purchases
return RestorationResult.failed(e.message ?? "Restore failed in RCPurchaseController");
}
}
}
// MARK: Helpers
String _buildSubscriptionOptionId(String? basePlanId, String? offerId) {
String result = '';
if (basePlanId != null) {
result += basePlanId;
}
if (offerId != null) {
if (basePlanId != null) {
result += ':';
}
result += offerId;
}
return result;
}
extension CustomerInfoAdditions on CustomerInfo {
bool hasActiveEntitlementOrSubscription() {
return (activeSubscriptions.isNotEmpty || entitlements.active.isNotEmpty);
}
DateTime? getLatestTransactionPurchaseDate() {
Map allPurchaseDates = this.allPurchaseDates;
if (allPurchaseDates.entries.isEmpty) {
return null;
}
DateTime latestDate = DateTime.fromMillisecondsSinceEpoch(0);
allPurchaseDates.forEach((key, value) {
DateTime date = DateTime.parse(value);
if (date.isAfter(latestDate)) {
latestDate = date;
}
});
return latestDate;
}
}
extension PurchasesAdditions on Purchases {
static Future> getAllProducts(List productIdentifiers) async {
final subscriptionProducts = await Purchases.getProducts(productIdentifiers, productCategory: ProductCategory.subscription);
final nonSubscriptionProducts = await Purchases.getProducts(productIdentifiers, productCategory: ProductCategory.nonSubscription);
final combinedProducts = [...subscriptionProducts, ...nonSubscriptionProducts];
return combinedProducts;
}
}
```
```typescript React Native
import { Platform } from "react-native"
import Superwall, {
PurchaseController,
PurchaseResult,
RestorationResult,
SubscriptionStatus,
PurchaseResultCancelled,
PurchaseResultFailed,
PurchaseResultPending,
PurchaseResultPurchased,
PurchaseResultRestored,
} from "@superwall/react-native-superwall"
import Purchases, {
type CustomerInfo,
PRODUCT_CATEGORY,
type PurchasesStoreProduct,
type SubscriptionOption,
PURCHASES_ERROR_CODE,
type MakePurchaseResult,
} from "react-native-purchases"
export class RCPurchaseController extends PurchaseController {
configureAndSyncSubscriptionStatus() {
// Configure RevenueCat
Purchases.setLogLevel(Purchases.LOG_LEVEL.DEBUG)
const apiKey =
Platform.OS === "ios" ? "MY_REVENUECAT_IOS_API_KEY" : "MY_REVENUECAT_ANDROID_API_KEY"
Purchases.configure({ apiKey })
// Listen for changes
Purchases.addCustomerInfoUpdateListener((customerInfo) => {
const hasActiveEntitlementOrSubscription =
this.hasActiveEntitlementOrSubscription(customerInfo)
Superwall.shared.setSubscriptionStatus(
hasActiveEntitlementOrSubscription ? SubscriptionStatus.ACTIVE : SubscriptionStatus.INACTIVE
)
})
}
async purchaseFromAppStore(productId: string): Promise {
const products = await Promise.all([
Purchases.getProducts([productId], PRODUCT_CATEGORY.SUBSCRIPTION),
Purchases.getProducts([productId], PRODUCT_CATEGORY.NON_SUBSCRIPTION),
]).then((results) => results.flat())
// Assuming an equivalent for Dart's firstOrNull is not directly available in TypeScript,
// so using a simple conditional check
const storeProduct = products.length > 0 ? products[0] : null
if (!storeProduct) {
return new PurchaseResultFailed("Failed to find store product for $productId")
}
return await this._purchaseStoreProduct(storeProduct)
}
async purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise {
// Find products matching productId from RevenueCat
const products = await Promise.all([
Purchases.getProducts([productId], PRODUCT_CATEGORY.SUBSCRIPTION),
Purchases.getProducts([productId], PRODUCT_CATEGORY.NON_SUBSCRIPTION),
]).then((results) => results.flat())
// Choose the product which matches the given base plan.
// If no base plan set, select first product or fail.
const storeProductId = `${productId}:${basePlanId}`
// Initialize matchingProduct as null explicitly
let matchingProduct: PurchasesStoreProduct | null = null
// Loop through each product in the products array
for (const product of products) {
// Check if the current product's identifier matches the given storeProductId
if (product.identifier === storeProductId) {
// If a match is found, assign this product to matchingProduct
matchingProduct = product
// Break the loop as we found our matching product
break
}
}
let storeProduct: PurchasesStoreProduct | null =
matchingProduct ??
(products.length > 0 && typeof products[0] !== "undefined" ? products[0] : null)
// If no product is found (either matching or the first one), return a failed purchase result.
if (storeProduct === null) {
return new PurchaseResultFailed("Product not found")
}
switch (storeProduct.productCategory) {
case PRODUCT_CATEGORY.SUBSCRIPTION:
const subscriptionOption = await this._fetchGooglePlaySubscriptionOption(
storeProduct,
basePlanId,
offerId
)
if (subscriptionOption === null) {
return new PurchaseResultFailed("Valid subscription option not found for product.")
}
return await this._purchaseSubscriptionOption(subscriptionOption)
case PRODUCT_CATEGORY.NON_SUBSCRIPTION:
return await this._purchaseStoreProduct(storeProduct)
default:
return new PurchaseResultFailed("Unable to determine product category")
}
}
private async _purchaseStoreProduct(
storeProduct: PurchasesStoreProduct
): Promise {
const performPurchase = async (): Promise => {
// Attempt to purchase product
const makePurchaseResult = await Purchases.purchaseStoreProduct(storeProduct)
return makePurchaseResult
}
return await this.handleSharedPurchase(performPurchase)
}
private async _fetchGooglePlaySubscriptionOption(
storeProduct: PurchasesStoreProduct,
basePlanId?: string,
offerId?: string
): Promise {
const subscriptionOptions = storeProduct.subscriptionOptions
if (subscriptionOptions && subscriptionOptions.length > 0) {
// Concatenate base + offer ID
const subscriptionOptionId = this.buildSubscriptionOptionId(basePlanId, offerId)
// Find first subscription option that matches the subscription option ID or use the default offer
let subscriptionOption: SubscriptionOption | null = null
// Search for the subscription option with the matching ID
for (const option of subscriptionOptions) {
if (option.id === subscriptionOptionId) {
subscriptionOption = option
break
}
}
// If no matching subscription option is found, use the default option
subscriptionOption = subscriptionOption ?? storeProduct.defaultOption
// Return the subscription option
return subscriptionOption
}
return null
}
private buildSubscriptionOptionId(basePlanId?: string, offerId?: string): string {
let result = ""
if (basePlanId !== null) {
result += basePlanId
}
if (offerId !== null) {
if (basePlanId !== null) {
result += ":"
}
result += offerId
}
return result
}
private async _purchaseSubscriptionOption(
subscriptionOption: SubscriptionOption
): Promise {
// Define the async perform purchase function
const performPurchase = async (): Promise => {
// Attempt to purchase product
const purchaseResult = await Purchases.purchaseSubscriptionOption(subscriptionOption)
return purchaseResult
}
const purchaseResult: PurchaseResult = await this.handleSharedPurchase(performPurchase)
return purchaseResult
}
private async handleSharedPurchase(
performPurchase: () => Promise
): Promise {
try {
// Store the current purchase date to later determine if this is a new purchase or restore
const purchaseDate = new Date()
// Perform the purchase using the function provided
const makePurchaseResult = await performPurchase()
// Handle the results
if (this.hasActiveEntitlementOrSubscription(makePurchaseResult.customerInfo)) {
const latestTransactionPurchaseDate = new Date(makePurchaseResult.transaction.purchaseDate)
// If no latest transaction date is found, consider it as a new purchase.
const isNewPurchase = latestTransactionPurchaseDate === null
// If the current date (`purchaseDate`) is after the latestTransactionPurchaseDate,
const purchaseHappenedInThePast = latestTransactionPurchaseDate
? purchaseDate > latestTransactionPurchaseDate
: false
if (!isNewPurchase && purchaseHappenedInThePast) {
return new PurchaseResultRestored()
} else {
return new PurchaseResultPurchased()
}
} else {
return new PurchaseResultFailed("No active subscriptions found.")
}
} catch (e: any) {
// Catch block to handle exceptions, adjusted for TypeScript
if (e.userCancelled) {
return new PurchaseResultCancelled()
}
if (e.code === PURCHASES_ERROR_CODE.PAYMENT_PENDING_ERROR) {
return new PurchaseResultPending()
} else {
return new PurchaseResultFailed(e.message)
}
}
}
async restorePurchases(): Promise {
try {
await Purchases.restorePurchases()
return RestorationResult.restored()
} catch (e: any) {
return RestorationResult.failed(e.message)
}
}
private hasActiveEntitlementOrSubscription(customerInfo: CustomerInfo): Boolean {
return (
customerInfo.activeSubscriptions.length > 0 ||
Object.keys(customerInfo.entitlements.active).length > 0
)
}
}
```
As discussed in [Purchases and Subscription Status](/legacy/legacy_advanced-configuration), this `PurchaseController` is responsible for handling the subscription-related logic. Take a few moments to look through the code to understand how it does this.
#### 2. Configure Superwall
Initialize an instance of `RCPurchaseController` and pass it in to `Superwall.configure(apiKey:purchaseController)`:
```swift Swift
let purchaseController = RCPurchaseController()
Superwall.configure(
apiKey: "MY_API_KEY",
purchaseController: purchaseController
)
```
```swift Objective-C
RCPurchaseController *purchaseController = [RCPurchaseController alloc] init];
[Superwall
configureWithApiKey:@"MY_API_KEY"
purchaseController:purchaseController
options:options
completion:nil
];
```
```kotlin Kotlin
val purchaseController = RCPurchaseController(this)
Superwall.configure(
this,
"MY_API_KEY",
purchaseController
)
// Make sure we sync the subscription status
// on first load and whenever it changes
purchaseController.syncSubscriptionStatus()
```
```dart Flutter
RCPurchaseController purchaseController = RCPurchaseController();
Superwall.configure(
apiKey,
purchaseController: purchaseController
);
await purchaseController.syncSubscriptionStatus();
```
```typescript React Native
React.useEffect(() => {
const apiKey = Platform.OS === "ios" ? "MY_SUPERWALL_IOS_API_KEY" : "MY_SUPERWALL_ANDROID_API_KEY"
const purchaseController = new RCPurchaseController()
Superwall.configure(apiKey, null, purchaseController)
purchaseController.configureAndSyncSubscriptionStatus()
}, [])
```
#### 3. Sync the subscription status
Then, call `purchaseController.syncSubscriptionStatus()` to keep Superwall's subscription status up to date with RevenueCat.
That's it! Check out our [RevenueCat iOS example app](https://github.com/superwall/Superwall-iOS/tree/master/Examples/UIKit%2BRevenueCat) for a working example of this integration.
### Using PurchasesAreCompletedBy
If you're using RevenueCat's [PurchasesAreCompletedBy](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions), you don't need to create a purchase controller. Register your placements, present a paywall — and Superwall will take care of completing any purchase the user starts. However, there are a few things to note if you use this setup:
1. Here, you aren't using RevenueCat's [entitlements](https://www.revenuecat.com/docs/getting-started/entitlements#entitlements) as a source of truth. If your app is multiplatform, you'll need to consider how to link up pro features or purchased products for users.
2. If you require custom logic when purchases occur, then you'll want to add a purchase controller. In that case, Superwall handles purchasing flows and RevenueCat will still observe transactions to power their analytics and charts.
3. Be sure that user identifiers are set the same way across Superwall and RevenueCat.
4. Finally, make sure that RevenueCat is using StoreKit 1.
Example:
```swift
Superwall.configure(apiKey: "superwall_public_key")
Superwall.shared.identify(userId: user.identifier)
Purchases.configure(with:
.builder(withAPIKey: "revcat_public_key")
.with(purchasesAreCompletedBy: .myApp, storeKitVersion: .storeKit1)
.with(appUserID: user.identifier)
.build()
)
```
For more information on observer mode, visit [RevenueCat's docs](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
---
# Purchases and Subscription Status (Legacy)
Source: https://superwall.com/docs/legacy/legacy_advanced-configuration
undefined
By default, Superwall handles basic subscription-related logic for you:
1. **Purchasing**: When the user initiates a checkout on a paywall.
2. **Restoring**: When the user restores previously purchased products.
3. **Subscription Status**: When the user's subscription status changes to active or expired (by checking the local receipt).
However, if you want more control, you can pass in a `PurchaseController` when configuring the SDK via `configure(apiKey:purchaseController:options:)` and manually set `Superwall.shared.subscriptionStatus` to take over this responsibility.
### Step 1: Creating a `PurchaseController`
A `PurchaseController` handles purchasing and restoring via protocol methods that you implement. You pass in your purchase controller when configuring the SDK:
```swift Swift
// MyPurchaseController.swift
import SuperwallKit
import StoreKit
final class MyPurchaseController: PurchaseController {
static let shared = MyPurchaseController()
// 1
func purchase(product: SKProduct) async -> PurchaseResult {
// TODO
// ----
// Purchase via StoreKit, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return .purchased // .cancelled, .pending, .failed(Error), .restored
}
// 2
func restorePurchases() async -> Bool {
// TODO
// ----
// Restore purchases and return true if successful.
return true // false
}
}
```
```swift Objective-C
@import SuperwallKit;
@import StoreKit;
// MyPurchaseController
@interface MyPurchaseController: NSObject
+ (instancetype)sharedInstance;
@end
@implementation MyPurchaseController
+ (instancetype)sharedInstance
{
static MyPurchaseController *sharedInstance = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
sharedInstance = [MyPurchaseController new];
});
return sharedInstance;
}
// 1
- (void)purchaseWithProduct:(SKProduct * _Nonnull)product completion:(void (^ _Nonnull)(enum SWKPurchaseResult, NSError * _Nullable))completion {
// TODO
// ----
// Purchase via StoreKit, RevenueCat, Qonversion or however
// you like and return a valid SWKPurchaseResult
completion(SWKPurchaseResultPurchased, nil);
}
// 2
- (void)restorePurchasesWithCompletion:(void (^ _Nonnull)(BOOL))completion {
// TODO
// ----
// Restore purchases and return YES if successful.
completion(YES);
}
@end
```
```kotlin Kotlin
// MyPurchaseController.kt
class MyPurchaseController(val context: Context): PurchaseController {
// 1
override suspend fun purchase(activity: Activity, product: SkuDetails): PurchaseResult {
// TODO
// ----
// Purchase via GoogleBilling, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.Purchased()
}
// 2
override suspend fun restorePurchases(): RestorationResult {
// TODO
// ----
// Restore purchases and return true if successful.
return RestorationResult.Success()
}
}
```
```dart Flutter
// MyPurchaseController.dart
class MyPurchaseController extends PurchaseController {
// 1
@override
Future purchaseFromAppStore(String productId) async {
// TODO
// ----
// Purchase via StoreKit, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.purchased;
}
@override
Future purchaseFromGooglePlay(
String productId,
String? basePlanId,
String? offerId
) async {
// TODO
// ----
// Purchase via Google Billing, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.purchased;
}
// 2
@override
Future restorePurchases() async {
// TODO
// ----
// Restore purchases and return true if successful.
return RestorationResult.restored;
}
}
```
```typescript React Native
export class MyPurchaseController extends PurchaseController {
// 1
async purchaseFromAppStore(productId: string): Promise {
// TODO
// ----
// Purchase via StoreKit, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
}
async purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise {
// TODO
// ----
// Purchase via Google Billing, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
}
// 2
async restorePurchases(): Promise {
// TODO
// ----
// Restore purchases and return true if successful.
}
}
```
Here’s what each method is responsible for:
1. Purchasing a given product. In here, enter your code that you use to purchase a product. Then, return the result of the purchase as a `PurchaseResult`. For Flutter, this is separated into purchasing from the App Store and Google Play. This is an enum that contains the following cases, all of which must be handled:
1. `.cancelled`: The purchase was cancelled.
2. `.purchased`: The product was purchased.
3. `.pending`: The purchase is pending/deferred and requires action from the developer.
4. `.failed(Error)`: The purchase failed for a reason other than the user cancelling or the payment pending.
5. `.restored`: The purchase was restored. This happens when the user tries to purchase a product that they've already purchased, resulting in a transaction whose `transactionDate` is before the the date you initiated the purchase.
2. Restoring purchases. Here, you restore purchases and return a boolean indicating whether the restoration was successful or not.
### Step 2: Configuring the SDK With Your `PurchaseController`
Pass your purchase controller to the `configure(apiKey:purchaseController:options:)` method:
```swift Swift
// AppDelegate.swift
import UIKit
import SuperwallKit
@main
class AppDelegate: UIResponder, UIApplicationDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Superwall.configure(
apiKey: "MY_API_KEY",
purchaseController: MyPurchaseController.shared // <- Handle purchases on your own
)
return true
}
}
```
```swift Objective-C
// AppDelegate.m
@import SuperwallKit;
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:[MyPurchaseController sharedInstance] options:nil completion:nil];
return YES;
}
```
```kotlin Kotlin
// MainApplication.kt
class MainApplication : android.app.Application(), SuperwallDelegate {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "MY_API_KEY", MyPurchaseController(this))
// OR using the DSL
configureSuperwall("MY_API_KEY") {
purchaseController = MyPurchaseController(this@MainApplication)
}
}
}
```
```dart Flutter
// main.dart
void initState() {
// Determine Superwall API Key for platform
String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";
// Create the purchase controller
MyPurchaseController purchaseController = MyPurchaseController();
Superwall.configure(apiKey, purchaseController);
}
```
```typescript React Native
export default function App() {
React.useEffect(() => {
const apiKey = Platform.OS === "ios" ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY"
const purchaseController = new MyPurchaseController()
Superwall.configure(apiKey, undefined, purchaseController)
}, [])
}
```
### Step 3: Keeping `subscriptionStatus` Up-To-Date
You **must** set `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise the SDK won't know who to show a paywall to. This is an enum that has three possible cases:
1. **`.unknown`**: This is the default value. In this state, paywalls will not show and their presentation will be ***automatically delayed*** until `subscriptionStatus` changes to a different value.
2. **`.active`**: Indicates that the user has an active subscription. Paywalls will not show in this state unless you remotely set the paywall to ignore subscription status.
3. **`.inactive`**: Indicates that the user doesn't have an active subscription. Paywalls can show in this state.
Here's how you might do this:
```swift Swift
import SuperwallKit
// On app launch, when you are waiting to determine a user's subscription status.
Superwall.shared.subscriptionStatus = .unknown
// When a subscription is purchased, restored, validated, expired, etc...
myService.subscriptionStatusDidChange {
if user.hasActiveSubscription {
Superwall.shared.subscriptionStatus = .active
} else {
Superwall.shared.subscriptionStatus = .inactive
}
}
```
```swift Objective-C
@import SuperwallKit;
// when you are waiting to determine a user's subscription status
[Superwall sharedInstance].subscriptionStatus = SWKSubscriptionStatusUnknown;
// when a subscription is purchased, restored, validated, expired, etc...
[myService setSubscriptionStatusDidChange:^{
if (user.hasActiveSubscription) {
[Superwall sharedInstance].subscriptionStatus = SWKSubscriptionStatusActive;
} else {
[Superwall sharedInstance].subscriptionStatus = SWKSubscriptionStatusInactive;
}
}];
```
```kotlin Kotlin
// On app launch, when you are waiting to determine a user's subscription status.
Superwall.instance.subscriptionStatus = SubscriptionStatus.UNKNOWN
// When a subscription is purchased, restored, validated, expired, etc...
myService.subscriptionStatusDidChange {
if (it.hasActiveSubscription) {
Superwall.instance.subscriptionStatus = SubscriptionStatus.ACTIVE
} else {
Superwall.instance.subscriptionStatus = SubscriptionStatus.INACTIVE
}
}
```
```dart Flutter
// On app launch, when you are waiting to determine a user's subscription status.
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.unknown);
// When a subscription is purchased, restored, validated, expired, etc...
myService.addSubscriptionStatusListener((hasActiveSubscription) {
if (hasActiveSubscription) {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.active);
} else {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.inactive);
}
});
```
```typescript React Native
// On app launch, when you are waiting to determine a user's subscription status.
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.UNKNOWN)
// When a subscription is purchased, restored, validated, expired, etc...
myService.addSubscriptionStatusListener((hasActiveSubscription: boolean) => {
if (hasActiveSubscription) {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.ACTIVE)
} else {
Superwall.shared.setSubscriptionStatus(SubscriptionStatus.INACTIVE)
}
})
```
`subscriptionStatus` is cached between app launches
### Listening for subscription status changes
If you need a simple way to observe when a user's subscription status changes, on iOS you can use the `Publisher` for it. Here's an example:
```swift
subscribedCancellable = Superwall.shared.$subscriptionStatus
.receive(on: DispatchQueue.main)
.sink { [weak self] status in
switch status {
case .unknown:
self?.subscriptionLabel.text = "Loading subscription status."
case .active:
self?.subscriptionLabel.text = "You currently have an active subscription. Therefore, the paywall will never show. For the purposes of this app, delete and reinstall the app to clear subscriptions."
case .inactive:
self?.subscriptionLabel.text = "You do not have an active subscription so the paywall will show when clicking the button."
}
}
```
You can do similar tasks with the `SuperwallDelegate`, such as [viewing which product was purchased from a paywall](/legacy/legacy_3rd-party-analytics#using-events-to-see-purchased-products).
---
# Retrieving and Presenting a Paywall Yourself (Legacy)
Source: https://superwall.com/docs/legacy/legacy_presenting
Use this technique to get an instance of a paywall manually, using either UIKit, SwiftUI, or Jetpack Compose.
If you want complete control over the paywall presentation process, you can use `getPaywall(forEvent:params:paywallOverrides:delegate:)`. This returns the `UIViewController` subclass `PaywallViewController`, which you can then present however you like. Or, you can use a SwiftUI `View` via `PaywallView`. The following is code is how you'd mimic [register](/legacy/legacy_feature-gating):
```swift Swift
final class MyViewController: UIViewController {
private func presentPaywall() async {
do {
// 1
let paywallVc = try await Superwall.shared.getPaywall(
forEvent: "campaign_trigger",
delegate: self
)
self.present(paywallVc, animated: true)
} catch let skippedReason as PaywallSkippedReason {
// 2
switch skippedReason {
case .holdout,
.noRuleMatch,
.eventNotFound,
.userIsSubscribed:
break
}
} catch {
// 3
print(error)
}
}
private func launchFeature() {
// Insert code to launch a feature that's behind your paywall.
}
}
// 4
extension MyViewController: PaywallViewControllerDelegate {
func paywall(
_ paywall: PaywallViewController,
didFinishWith result: PaywallResult,
shouldDismiss: Bool
) {
if shouldDismiss {
paywall.dismiss(animated: true)
}
switch result {
case .purchased,
.restored:
launchFeature()
case .declined:
let closeReason = paywall.info.closeReason
let featureGating = paywall.info.featureGatingBehavior
if closeReason != .forNextPaywall && featureGating == .nonGated {
launchFeature()
}
}
}
}
```
```swift Objective-C
@interface MyViewController : UIViewController
- (void)presentPaywall;
@end
@interface MyViewController ()
@end
@implementation MyViewController
- (void)presentPaywall {
// 1
[[Superwall sharedInstance] getPaywallForEvent:@"campaign_trigger" params:nil paywallOverrides:nil delegate:self completion:^(SWKGetPaywallResult * _Nonnull result) {
if (result.paywall != nil) {
[self presentViewController:result.paywall animated:YES completion:nil];
} else if (result.skippedReason != SWKPaywallSkippedReasonNone) {
switch (result.skippedReason) {
// 2
case SWKPaywallSkippedReasonHoldout:
case SWKPaywallSkippedReasonUserIsSubscribed:
case SWKPaywallSkippedReasonEventNotFound:
case SWKPaywallSkippedReasonNoRuleMatch:
case SWKPaywallSkippedReasonNone:
break;
};
} else if (result.error) {
// 3
NSLog(@"%@", result.error);
}
}];
}
-(void)launchFeature {
// Insert code to launch a feature that's behind your paywall.
}
// 4
- (void)paywall:(SWKPaywallViewController *)paywall didFinishWithResult:(enum SWKPaywallResult)result shouldDismiss:(BOOL)shouldDismiss {
if (shouldDismiss) {
[paywall dismissViewControllerAnimated:true completion:nil];
}
SWKPaywallCloseReason closeReason;
SWKFeatureGatingBehavior featureGating;
switch (result) {
case SWKPaywallResultPurchased:
case SWKPaywallResultRestored:
[self launchFeature];
break;
case SWKPaywallResultDeclined:
closeReason = paywall.info.closeReason;
featureGating = paywall.info.featureGatingBehavior;
if (closeReason != SWKPaywallCloseReasonForNextPaywall && featureGating == SWKFeatureGatingBehaviorNonGated) {
[self launchFeature];
}
break;
}
}
@end
```
```swift SwiftUI
import SuperwallKit
struct MyAwesomeApp: App {
@State var store: AppStore = .init()
init() {
Superwall.configure(apiKey: "MyAPIKey")
}
var body: some Scene {
WindowGroup {
ContentView()
.fullScreenCover(isPresented: $store.showPaywall) {
// You can just use 'event' at a minimum. The 'feature'
// Closure fires if they convert
PaywallView(event: "myEvent", onSkippedView: { skip in
switch skip {
case .userIsSubscribed,
.holdout(_),
.noRuleMatch,
.eventNotFound:
MySkipView()
}
}, onErrorView: { error in
MyErrorView()
}, feature: {
// User is subscribed as a result of the paywall purchase
// Or they already were (which would happen in `onSkippedView`)
})
}
}
}
}
```
```kotlin Kotlin
// This is an example of how to use `getPaywall` to use a composable`
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.viewinterop.AndroidView
import com.superwall.sdk.Superwall
import com.superwall.sdk.paywall.presentation.get_paywall.getPaywall
import com.superwall.sdk.paywall.presentation.internal.request.PaywallOverrides
import com.superwall.sdk.paywall.vc.PaywallView
import com.superwall.sdk.paywall.vc.delegate.PaywallViewCallback
@Composable
fun PaywallComposable(
event: String,
params: Map? = null,
paywallOverrides: PaywallOverrides? = null,
callback: PaywallViewCallback,
errorComposable: @Composable ((Throwable) -> Unit) = { error: Throwable ->
// Default error composable
Text(text = "No paywall to display")
},
loadingComposable: @Composable (() -> Unit) = {
// Default loading composable
Box(modifier = Modifier.fillMaxSize()) {
Column(
modifier = Modifier.align(Alignment.Center),
verticalArrangement = Arrangement.Center,
horizontalAlignment = Alignment.CenterHorizontally
) {
CircularProgressIndicator()
}
}
}
) {
val viewState = remember { mutableStateOf(null) }
val errorState = remember { mutableStateOf(null) }
val context = LocalContext.current
LaunchedEffect(Unit) {
try {
val newView = Superwall.instance.getPaywall(event, params, paywallOverrides, callback)
newView.encapsulatingActivity = context as? Activity
newView.beforeViewCreated()
viewState.value = newView
} catch (e: Throwable) {
errorState.value = e
}
}
when {
viewState.value != null -> {
viewState.value?.let { viewToRender ->
DisposableEffect(viewToRender) {
viewToRender.onViewCreated()
onDispose {
viewToRender.beforeOnDestroy()
viewToRender.encapsulatingActivity = null
CoroutineScope(Dispatchers.Main).launch {
viewToRender.destroyed()
}
}
}
AndroidView(
factory = { context ->
viewToRender
}
)
}
}
errorState.value != null -> {
errorComposable(errorState.value!!)
}
else -> {
loadingComposable()
}
}
}
```
This does the following:
1. Gets the paywall view controller.
2. Handles the cases where the paywall was skipped.
3. Catches any presentation errors.
4. Implements the delegate. This is called when the user is finished with the paywall. First, it checks `shouldDismiss`. If this is true then is dismissed the paywall from view before launching any features. This may depend on the `result` depending on how you first presented your view. Then, it switches over the `result`. If the result is `purchased` or `restored` the feature can be launched. However, if the result is `declined`, it checks that the the `featureGating` property of `paywall.info` is `nonGated` and that the `closeReason` isn't `.forNextPaywall`.
### Best practices
1. **Make sure to prevent a paywall from being accessed after a purchase has occurred**.
If a user purchases from a paywall, it is your responsibility to make sure that the user can't access that paywall again. For example, if after successful purchase you decide to push a new view on to the navigation stack, you should make sure that the user can't go back to access the paywall.
2. **Make sure the paywall view controller deallocates before presenting it elsewhere**.
If you have a paywall view controller presented somewhere and you try to present
the same view controller elsewhere, you will get a crash. For example, you may
have a paywall in a tab bar controller, and then you also try to present it
modally. We plan on improving this, but currently it's your responsibility to
ensure this doesn't happen.
3. **Listening for Loading State Changes**.
If you have logic that depends on the progress of the paywall's loading state, you can use the delegate function `paywall(_:loadingStateDidChange)`. Or, if you have an instance of a `PaywallViewController`, you can use the published property on iOS:
```swift
let stateSub = paywall.$loadingState.sink { state in
print(state)
}
```
---
# Deep Links and In-App Previews (Legacy)
Source: https://superwall.com/docs/legacy/legacy_in-app-paywall-previews
It's important to tell Superwall when a deep link has been opened. This enables two things:
1. Previewing paywalls on your device before going live.
2. Deep linking to specific [campaigns](/campaigns).
#### Adding a Custom URL Scheme
To handle deep links on iOS, you'll need to add a custom URL scheme for your app.
Open **Xcode**. In your **info.plist**, add a row called **URL Types**. Expand the automatically created **Item 0**, and inside the **URL identifier** value field, type your **Bundle ID**, e.g., **com.superwall.Superwall-SwiftUI**. Add another row to **Item 0** called **URL Schemes** and set its **Item 0** to a URL scheme you'd like to use for your app, e.g., **exampleapp**. Your structure should look like this:
With this example, the app will open in response to a deep link with the format **exampleapp\://**. You can [view Apple's documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) to learn more about custom URL schemes.
#### Handling Deep Links (Swift)
Depending on whether your app uses a SceneDelegate, AppDelegate, or is written in SwiftUI, there are different ways to tell Superwall that a deep link has been opened.
Be sure to click the tab that corresponds to your architecture:
```swift AppDelegate.swift
import SuperwallKit
class AppDelegate: UIResponder, UIApplicationDelegate {
// NOTE: if your app uses a SceneDelegate, this will NOT work!
func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
return Superwall.shared.handleDeepLink(url)
}
}
```
```swift SceneDelegate.swift
import SuperwallKit
class SceneDelegate: UIResponder, UIWindowSceneDelegate {
// for cold launches
func scene(_ scene: UIScene, willConnectTo session: UISceneSession, options connectionOptions: UIScene.ConnectionOptions) {
if let url = connectionOptions.urlContexts.first?.url {
Superwall.shared.handleDeepLink(url)
}
}
// for when your app is already running
func scene(_ scene: UIScene, openURLContexts URLContexts: Set) {
if let url = URLContexts.first?.url {
Superwall.shared.handleDeepLink(url)
}
}
}
```
```swift SwiftUI
import SuperwallKit
@main
struct MyApp: App {
var body: some Scene {
WindowGroup {
ContentView()
.onOpenURL { url in
Superwall.shared.handleDeepLink(url) // handle your deep link
}
}
}
}
```
```swift Objective-C
// In your SceneDelegate.m
#import "SceneDelegate.h"
@import SuperwallKit;
@interface SceneDelegate ()
@end
@implementation SceneDelegate
- (void)scene:(UIScene *)scene willConnectToSession:(UISceneSession *)session options:(UISceneConnectionOptions *)connectionOptions {
[self handleURLContexts:connectionOptions.URLContexts];
}
- (void)scene:(UIScene *)scene openURLContexts:(NSSet *)URLContexts {
[self handleURLContexts:URLContexts];
}
#pragma mark - Deep linking
- (void)handleURLContexts:(NSSet *)URLContexts {
[URLContexts enumerateObjectsUsingBlock:^(UIOpenURLContext * _Nonnull context, BOOL * _Nonnull stop) {
[[Superwall sharedInstance] handleDeepLink:context.URL];
}];
}
@end
```
#### Adding a Custom Intent Filter
For Android, add the following to your `AndroidManifest.xml` file:
```xml
```
This configuration allows your app to open in response to a deep link with the format `exampleapp://` from your `MainActivity` class.
#### Handling Deep Links (Kotlin)
In your `MainActivity` (or the activity specified in your intent-filter), add the following Kotlin code to handle deep links:
```kotlin Kotlin
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Respond to deep links
respondToDeepLinks()
}
private fun respondToDeepLinks() {
intent?.data?.let { uri ->
Superwall.instance.handleDeepLink(uri)
}
}
}
```
Setting up deep links nearly mirrors the process for iOS, save for a few different changes. First, you'll need to add a custom URL scheme for your app.
From terminal, navigate to your Flutter project's root directory and open its Xcode workspace:
```bash
$ cd documents/projects/myFlutterApp
$ open ios/Runner.xcworkspace
```
In its **info.plist**, add a row called **URL Types**. Expand the automatically created **Item 0**, and inside the **URL identifier** value field, type your **Bundle ID**, e.g., **com.superwall.Superwall-SwiftUI**. Add another row to **Item 0** called **URL Schemes** and set its **Item 0** to `runner` to match Flutter's Xcode project name.
Here's an example of what it should look like if you open the Flutter target's `Info` pane:
#### Handling the Deep Link in Flutter
In your Flutter app, use the Superwall SDK to handle the deep link via `Superwall.shared.handleDeepLink(theLink);`. Here's a complete example:
```dart
import 'package:flutter/material.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart';
import 'package:uni_links/uni_links.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
MyApp();
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State {
@override
void initState() {
super.initState();
Superwall.configure('pk_6c131449acdef827c4b0dd639f9a499972ac3c45ccd8b8d3');
_handleIncomingLinks();
}
void _handleIncomingLinks() {
uriLinkStream.listen((Uri? uri) {
if (uri != null) {
Superwall.shared.handleDeepLink(uri);
}
}, onError: (Object err) {
print('Error receiving incoming link: $err');
});
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Center(
child: Text(
'Deep Link Preview Example',
style: TextStyle(fontSize: 24),
),
),
),
);
}
}
```
To make in-app previews work, you'll first want to add a URL scheme to your Xcode project's workspace. From terminal, navigate to your React Native project's root directory and open its Xcode workspace:
```bash
$ cd documents/projects/myReactNativeApp
$ open ios/theProjectName.xcworkspace
```
Open **Xcode**. In your **info.plist**, add a row called **URL Types**. Expand the automatically created **Item 0**, and inside the **URL identifier** value field, type your **Bundle ID**, e.g., **com.superwall.Superwall-SwiftUI**. Add another row to **Item 0** called **URL Schemes** and set its **Item 0** to a URL scheme you'd like to use for your app, e.g., **exampleapp**.
Here's an example of what it should look like if you open the target's `Info` pane:
#### React Native Project setup
Next, you can use the Superwall SDK to handle the deeplink with `Superwall.shared.handleDeepLink(url);`. Here, we have code to ensure that the deep link opens a preview when the app is booted from the deep link, and when it's already in the foreground running:
```typescript
import React, { useEffect } from 'react';
import { Linking, AppState } from 'react-native';
import Superwall from '@superwall/react-native-superwall';
function handleDeepLink(url: string | null) {
if (url) {
Superwall.shared.handleDeepLink(url);
}
}
function App(): React.JSX.Element {
useEffect(() => {
Superwall.configure('YOUR_SUPERWALL_API_KEY');
const handleIncomingLink = async () => {
const url = await Linking.getInitialURL();
handleDeepLink(url);
};
// Handle any existing deep link on mount
handleIncomingLink();
const appStateSubscription = AppState.addEventListener('change', (nextAppState) => {
if (nextAppState === 'active') {
handleIncomingLink();
}
});
const linkingSubscription = Linking.addEventListener('url', (event) => {
handleDeepLink(event.url);
});
return () => {
appStateSubscription.remove();
linkingSubscription.remove();
};
}, []);
// Returning null since there's no UI for the example...
return null;
}
export default App;
```
### Previewing Paywalls
Next, build and run your app on your phone.
Then, head to the Superwall Dashboard. Click on **Settings** from the Dashboard panel on the left, then select **General**:
With the **General** tab selected, type your custom URL scheme, without slashes, into the **Apple Custom URL Scheme** field:
Next, open your paywall from the dashboard and click **Preview**. You'll see a QR code appear in a pop-up:
On your device, scan this QR code. You can do this via Apple's Camera app. This will take you to a paywall viewer within your app, where you can preview all your paywalls in different configurations.
### Using Deep Links to Present Paywalls
Deep links can also be used as a placement in a campaign to present paywalls. Simply add `deepLink_open` as an placement, and the URL parameters of the deep link can be used as parameters! You can also use custom placements for this purpose. [Read this doc](/legacy/legacy_presenting-paywalls-from-one-another) for examples of both.
---
# Installation (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation
Superwall can be installed with many different package managers. Please find your preferred package manager below.
### iOS
### Android
### Flutter
### React Native
---
# Flutter - pubspec.yaml (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation-via-pubspec
Install the Superwall Flutter SDK via pub package manager. To see the latest release, [check out the repository](https://github.com/superwall/Superwall-Flutter).
## Install via pubspec.yaml
To use Superwall in your Flutter project, add `superwallkit_flutter` as a dependency in your `pubspec.yaml` file:
```yaml
dependencies:
superwallkit_flutter: ^0.0.27
```
After adding the dependency, run `dart pub get` in your terminal to fetch the package.
## Install via Command Line (Alternative)
You can also add the dependency directly from your terminal using the following command:
```bash
$ flutter pub add superwallkit_flutter
```
### iOS Deployment Target
Superwall requires iOS 14.0 or higher. Ensure your Flutter project's iOS deployment target is 14.0 or higher by updating ios/Podfile.
```ruby
platform :ios, '14.0'
```
### Android Configuration
Superwall requires a minimum SDK version of 26 or higher and a minimum compile SDK target of 34. Ensure your Flutter project's Android minimal SDK target is set to 26 or higher and that your compilation SDK target is 34 by updating `android/app/build.gradle`.
```groovy gradle
android {
...
compileSdkVersion 34
...
defaultConfig {
...
minSdkVersion 26
...
}
}
```
To use the compile target SDK 34, you'll also need to ensure your Gradle version is 8.6 or higher and your Android Gradle plugin version is 8.4 or higher.
You can do that by checking your `gradle/wrapepr/gradle-wrapper.properties` file and ensuring it is updated to use the latest Gradle version:
```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
```
And your `android/build.gradle` file is updated to use the latest Android Gradle plugin version:
```groovy gradle
plugins {
id 'com.android.application' version '8.4.1' apply false
}
```
To find the latest compatible versions, you can always check the [Gradle Plugin Release Notes](https://developer.android.com/build/releases/gradle-plugin).
**And you're done!** Now you're ready to configure the SDK 👇
Begin configuring the SDK to show paywalls inside your App!
---
# Showing Paywalls (Legacy)
Source: https://superwall.com/docs/legacy/legacy_feature-gating
At the heart of Superwall's SDK lies `Superwall.shared.register(event:params:handler:feature:)`.
This allows you to register a [placement](/campaigns-placements) to access a feature that may or may not be paywalled later in time. It also allows you to choose whether the user can access the feature even if they don't make a purchase.
Here's an example.
We are in the process of updating our docs and SDK to rename `event` to `placement`. If you see `event` anywhere, you can mentally replace it with `placement`. They mean the same thing.
#### With Superwall
```swift Swift
func pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.register(event: "StartWorkout") {
navigation.startWorkout()
}
}
```
```swift Objective-C
- (void)pressedWorkoutButton {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
[[Superwall sharedInstance] registerWithEvent:@"StartWorkout" params:nil handler:nil feature:^{
[navigation startWorkout];
}];
}
```
```kotlin Kotlin
fun pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.instance.register("StartWorkout") {
navigation.startWorkout()
}
}
```
```dart Flutter
void pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.registerEvent('StartWorkout', feature: () {
navigation.startWorkout();
});
}
```
```typescript React Native
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.register('StartWorkout').then(() => {
navigation.startWorkout();
}
```
#### Without Superwall
```swift Swift
func pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout()
} else {
navigation.presentPaywall() { result in
if (result) {
navigation.startWorkout()
} else {
// user didn't pay, developer decides what to do
}
}
}
}
```
```swift Objective-C
- (void)pressedWorkoutButton {
if (user.hasActiveSubscription) {
[navigation startWorkout];
} else {
[navigation presentPaywallWithCompletion:^(BOOL result) {
if (result) {
[navigation startWorkout];
} else {
// user didn't pay, developer decides what to do
}
}];
}
}
```
```kotlin Kotlin
fun pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout()
} else {
navigation.presentPaywall { result ->
if (result) {
navigation.startWorkout()
} else {
// user didn't pay, developer decides what to do
}
}
}
}
```
```dart Flutter
void pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout();
} else {
navigation.presentPaywall().then((result) {
if (result) {
navigation.startWorkout();
} else {
// user didn't pay, developer decides what to do
}
});
}
}
```
```typescript React Native
function pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout()
} else {
navigation.presentPaywall().then((result: boolean) => {
if (result) {
navigation.startWorkout()
} else {
// user didn't pay, developer decides what to do
}
})
}
}
```
### How it works:
You can configure `"StartWorkout"` to present a paywall by [creating a campaign, adding the placement, and adding a rule](/campaigns) in the dashboard.
1. The SDK retrieves your campaign settings from the dashboard on app launch.
2. When a placement is called that belongs to a campaign, rules are evaluated ***on device*** and the user enters an experiment — this means there's no delay between registering a placement and presenting a paywall.
3. If it's the first time a user is entering an experiment, a paywall is decided for the user based on the percentages you set in the dashboard
4. Once a user is assigned a paywall for a rule, they will continue to see that paywall until you remove the paywall from the rule or reset assignments to the paywall.
5. After the paywall is closed, the Superwall SDK looks at the *Feature Gating* value associated with your paywall, configurable from the paywall editor under General > Feature Gating (more on this below)
1. If the paywall is set to ***Non Gated***, the `feature:` closure on `register(event: ...)` gets called when the paywall is dismissed (whether they paid or not)
2. If the paywall is set to ***Gated***, the `feature:` closure on `register(event: ...)` gets called only if the user is already paying or if they begin paying.
6. If no paywall is configured, the feature gets executed immediately without any additional network calls.
Given the low cost nature of how register works, we strongly recommend registering **all core functionality** in order to remotely configure which features you want to gate – **without an app update**.
```swift Swift
// on the welcome screen
func pressedSignUp() {
Superwall.shared.register(event: "SignUp") {
navigation.beginOnboarding()
}
}
// in another view controller
func pressedWorkoutButton() {
Superwall.shared.register(event: "StartWorkout") {
navigation.startWorkout()
}
}
```
```swift Objective-C
// on the welcome screen
- (void)pressedSignUp {
[[Superwall sharedInstance] registerWithEvent:@"SignUp" params:nil handler:nil feature:^{
[navigation beginOnboarding];
}];
}
// In another view controller
- (void)pressedWorkoutButton {
[[Superwall sharedInstance] registerWithEvent:@"StartWorkout" params:nil handler:nil feature:^{
[navigation startWorkout];
}];
}
```
```kotlin 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()
}
}
```
```dart Flutter
// on the welcome screen
void pressedSignUp() {
Superwall.shared.registerEvent("SignUp", feature: () {
navigation.beginOnboarding();
});
}
// In another view controller
void pressedWorkoutButton() {
Superwall.shared.registerEvent("StartWorkout", feature: () {
navigation.startWorkout();
});
}
```
```typescript React Native
// on the welcome screen
function pressedSignUp() {
Superwall.shared.registerEvent("SignUp").then(() => {
navigation.beginOnboarding()
})
}
function pressedWorkoutButton() {
Superwall.shared.register("StartWorkout").then(() => {
navigation.startWorkout()
})
}
```
### Placement Parameters
You can send parameters along with any placement you create. For example, if you had a caffeine logging app — perhaps you'd have a placement for logging caffeine:
```swift
// In iOS...
Superwall.shared.register(event: "caffeineLogged") {
store.log(amountToLog)
}
```
Now, imagine you could log caffeine from several different touch points in your app. You may wish to know *where* the user tried to log caffeine from, and you could tie a parameter to the `caffeineLogged` placement to do this:
```swift iOS
Superwall.shared.register(event: "caffeineLogged", params: ["via":"logging_page"]) {
store.log(amountToLog)
}
```
```kotlin Android
val params: Map = mapOf(
"via" to "logging_page"
)
Superwall.instance.register("caffeineLogged", params = params) {
store.log(amountToLog)
}
```
```dart Flutter
final params = {"via": "logging_page"};
Superwall.shared.registerEvent(
"event",
params: params,
feature: () {
logToStore(100);
}
);
```
```typescript React Native
Superwall.shared.register('caffeineLogged',
new Map([['via', 'logging_page']]),
undefined,
() => {
console.log('show coffee');
}
);
```
The `via` parameter could now be used all throughout Superwall. You could create a new [audience](/campaigns-audience) which has filters for each place users logged caffeine from, and unique paywalls for each of them.
Parameter placements can be used in three primary ways:
1. **Audience Filtering:** As mentioned above, you can filter against parameters when creating audiences. Following our example, you'd create a **placement parameter** named **via** and then choose how to filter off of the parameter's value:
2. **Templating in Text:** Parameters are available in our [paywall editor](/paywall-editor-overview), so you can easily use them in text components too:
```
Hey {{user.firstName}}! FitnessAI offers tons of {{user.fitnessGoal}} workouts to help you reach your goals :)
```
3. **Interfacing with Analytics:** Another common scenario is cohorting with your own analytics. See this [doc](/cohorting-in-3rd-party-tools) for more.
### Feature Gating from the Paywall Editor
##### Paywall Editor > General > Settings > Feature Gating
Feature gating allows your team to retroactively decide if this paywall is *Gated* or *Non Gated*
| Type | Behavior | Example |
| ----------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| **Non Gated** (default) | Show Paywall → Execute Feature | When "Sign Up" button is pressed, show a paywall, then continue onboarding once the paywall is dismissed. |
| **Gated** | Show Paywall → Is user paying?If Yes → Execute FeatureIf No → Do Nothing | When "Start Workout" button is pressed, show a paywall, then continue once the paywall is dismissed only if the user subscribes. |
Remember, the feature is always executed if:
1. No campaign is configured for the placement
2. The user is already paying
### Using the Handler
You can provide a `PaywallPresentationHandler` to `register`, whose functions provide status updates for a paywall:
* `onDismiss`: Called when the paywall is dismissed. Accepts a `PaywallInfo` object containing info about the dismissed paywall.
* `onPresent`: Called when the paywall did present. Accepts a `PaywallInfo` object containing info about the presented paywall.
* `onError`: Called when an error occurred when trying to present a paywall. Accepts an `Error` indicating why the paywall could not present.
* `onSkip`: Called when a paywall is skipped. Accepts a `PaywallSkippedReason` enum indicating why the paywall was skipped.
```swift Swift
let handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo in
print("The paywall dismissed. PaywallInfo:", paywallInfo)
}
handler.onPresent { paywallInfo in
print("The paywall presented. PaywallInfo:", paywallInfo)
}
handler.onError { error in
print("The paywall presentation failed with error \(error)")
}
handler.onSkip { reason in
switch reason {
case .userIsSubscribed:
print("Paywall not shown because user is subscribed.")
case .holdout(let experiment):
print("Paywall not shown because user is in a holdout group in Experiment: \(experiment.id)")
case .noRuleMatch:
print("Paywall not shown because user doesn't match any rules.")
case .eventNotFound:
print("Paywall not shown because this placement isn't part of a campaign.")
}
}
Superwall.shared.register(event: "campaign_trigger", handler: handler) {
// Feature launched
}
```
```swift Objective-C
SWKPaywallPresentationHandler *handler = [[SWKPaywallPresentationHandler alloc] init];
[handler onDismiss:^(SWKPaywallInfo * _Nonnull paywallInfo) {
NSLog(@"The paywall dismissed. PaywallInfo: %@", paywallInfo);
}];
[handler onPresent:^(SWKPaywallInfo * _Nonnull paywallInfo) {
NSLog(@"The paywall presented. PaywallInfo: %@", paywallInfo);
}];
[handler onError:^(NSError * _Nonnull error) {
NSLog(@"The paywall presentation failed with error %@", error);
}];
[handler onSkip:^(enum SWKPaywallSkippedReason reason) {
switch (reason) {
case SWKPaywallSkippedReasonUserIsSubscribed:
NSLog(@"Paywall not shown because user is subscribed.");
break;
case SWKPaywallSkippedReasonHoldout:
NSLog(@"Paywall not shown because user is in a holdout group.");
break;
case SWKPaywallSkippedReasonNoRuleMatch:
NSLog(@"Paywall not shown because user doesn't match any rules.");
break;
case SWKPaywallSkippedReasonEventNotFound:
NSLog(@"Paywall not shown because this placement isn't part of a campaign.");
break;
case SWKPaywallSkippedReasonNone:
// The paywall wasn't skipped.
break;
}
}];
[[Superwall sharedInstance] registerWithEvent:@"campaign_trigger" params:nil handler:handler feature:^{
// Feature launched.
}];
```
```kotlin Kotlin
val handler = PaywallPresentationHandler()
handler.onDismiss {
println("The paywall dismissed. PaywallInfo: ${it}")
}
handler.onPresent {
println("The paywall presented. PaywallInfo: ${it}")
}
handler.onError {
println("The paywall errored. Error: ${it}")
}
handler.onSkip {
when (it) {
is PaywallSkippedReason.EventNotFound -> {
println("The paywall was skipped because the placement was not found.")
}
is PaywallSkippedReason.Holdout -> {
println("The paywall was skipped because the user is in a holdout group.")
}
is PaywallSkippedReason.NoRuleMatch -> {
println("The paywall was skipped because no rule matched.")
}
is PaywallSkippedReason.UserIsSubscribed -> {
println("The paywall was skipped because the user is subscribed.")
}
}
}
Superwall.instance.register(event = "campaign_trigger", handler = handler) {
// Feature launched
}
```
```dart Flutter
PaywallPresentationHandler handler = PaywallPresentationHandler();
handler.onPresent((paywallInfo) async {
String name = await paywallInfo.name;
print("Handler (onPresent): $name");
});
handler.onDismiss((paywallInfo) async {
String name = await paywallInfo.name;
print("Handler (onDismiss): $name");
});
handler.onError((error) {
print("Handler (onError): ${error}");
});
handler.onSkip((skipReason) async {
String description = await skipReason.description;
if (skipReason is PaywallSkippedReasonHoldout) {
print("Handler (onSkip): $description");
final experiment = await skipReason.experiment;
final experimentId = await experiment.id;
print("Holdout with experiment: ${experimentId}");
} else if (skipReason is PaywallSkippedReasonNoRuleMatch) {
print("Handler (onSkip): $description");
} else if (skipReason is PaywallSkippedReasonEventNotFound) {
print("Handler (onSkip): $description");
} else if (skipReason is PaywallSkippedReasonUserIsSubscribed) {
print("Handler (onSkip): $description");
} else {
print("Handler (onSkip): Unknown skip reason");
}
});
Superwall.shared.registerEvent("campaign_trigger", handler: handler, feature: () {
// Feature launched
});
```
```typescript React Native
const handler = new PaywallPresentationHandler()
handler.onPresent((paywallInfo) => {
const name = paywallInfo.name
console.log(`Handler (onPresent): ${name}`)
})
handler.onDismiss((paywallInfo) => {
const name = paywallInfo.name
console.log(`Handler (onDismiss): ${name}`)
})
handler.onError((error) => {
console.log(`Handler (onError): ${error}`)
})
handler.onSkipHandler((skipReason) => {
const description = skipReason.description
if (skipReason instanceof PaywallSkippedReasonHoldout) {
console.log(`Handler (onSkipHandler): ${description}`)
const experiment = skipReason.experiment
const experimentId = experiment.id
console.log(`Holdout with experiment: ${experimentId}`)
} else if (skipReason instanceof PaywallSkippedReasonNoRuleMatch) {
console.log(`Handler (onSkip): ${description}`)
} else if (skipReason instanceof PaywallSkippedReasonEventNotFound) {
console.log(`Handler (onSkip): ${description}`)
} else if (skipReason instanceof PaywallSkippedReasonUserIsSubscribed) {
console.log(`Handler (onSkip): ${description}`)
} else {
console.log(`Handler (onSkip): Unknown skip reason`)
}
})
Superwall.shared.register("campaign_trigger", undefined, handler).then(() => {
// Feature launched
})
```
Wanting to see which product was just purchased from a paywall? Use the [SuperwallDelegate](/3rd-party-analytics#using-events-to-see-purchased-products).
### Automatically Registered Placements
The SDK [automatically registers](/docs/tracking-analytics) some internal placements which can be used to present paywalls:
* `app_install`
* `app_launch`
* `deepLink_open`
* `session_start`
* `transaction_abandon`
* `transaction_fail`
* `paywall_close`
### Register. Everything.
To provide your team with ultimate flexibility, we recommend registering *all* of your analytics events, even if you don't pass feature blocks through. This way you can retroactively add a paywall almost anywhere – **without an app update**!
If you're already set up with an analytics provider, you'll typically have an `Analytics.swift` singleton (or similar) to disperse all your events from. Here's how that file might look:
```swift Swift
import SuperwallKit
import Mixpanel
import Firebase
final class Analytics {
static var shared = Analytics()
func track(
event: String,
properties: [String: Any]
) {
// Superwall
Superwall.shared.register(event: event, params: properties)
// Firebase (just an example)
Firebase.Analytics.logEvent(event, parameters: properties)
// Mixpanel (just an example)
Mixpanel.mainInstance().track(event: event, properties: properties)
}
}
// And thus ...
Analytics.shared.track(
event: "workout_complete",
properties: ["total_workouts": 17]
)
// ... can now be turned into a paywall moment :)
```
**Need to know if a paywall will show beforehand?**
In some circumstances, you might like to know if a particular event will present a paywall. To do this, you can use `Superwall.shared.getPresentationResult(forEvent:params:)`.
### Handling Network Issues
Superwall's SDK handles network issues as gracefully as possible, but there are still some scenarios to consider. The behavior will be different based on if `subscriptionStatus` evaluates to `.active` or not.
**If it is `.active`** and Superwall has already fetched or cached its configuration, then paywall presentation proceeds as it normally would. If Superwall was unable to fetch its configuration, the SDK waits one second to give it a chance to be retrieved. After that time, if it's not available — then a timeout event is tracked and the `onSkip` handler will be invoked with a reason of `userIsSubscribed`. The "feature" block or closure will then be invoked:
```swift
Superwall.shared.register(event: "foo") {
// Your feature logic
}
```
**If it's not `.active`** then Superwall will retry network calls until we have retrieved the necessary data for up to one minute. If it's still unavailable, then the SDK fires the `onError` handler with the error type of `noConfig`.
---
# Cohorting in 3rd Party Tools (Legacy)
Source: https://superwall.com/docs/legacy/legacy_cohorting-in-3rd-party-tools
To easily view Superwall cohorts in 3rd party tools, we recommend you set user attributes based on the experiments that users are included in. You can also use custom placements for creating analytic events for actions such as interacting with an element on a paywall.
```swift Swift
extension SuperwallService: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
if eventInfo.event.description == "trigger_fire" {
MyAnalyticsService.shared.setUserAttributes([
"sw_experiment_\(eventInfo.event.params["experiment_id"])": true,
"sw_variant_\(eventInfo.event.params["variant_id"])": true
])
}
}
}
```
```kotlin Kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when(eventInfo.event) {
is SuperwallEvent.TriggerFire -> {
MyAnalyticsService.shared.setUserAttributes(
mapOf(
"sw_experiment_${eventInfo.params.get("experiment_id").toString()}" to true,
"sw_variant_${eventInfo.params.get("variant_id").toString()}" to true
)
)
}
else -> {}
}
}
```
```dart Flutter
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
final experimentId = eventInfo.params?['experiment_id'];
final variantId = eventInfo.params?['variant_id'];
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
"sw_experiment_$experimentId": true,
"sw_variant_$variantId": true
});
break;
default:
break;
}
}
```
```typescript React Native
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
const experimentId = eventInfo.params?['experiment_id']
const variantId = eventInfo.params?['variant_id']
if (!experimentId || !variantId) {
return
}
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
`sw_experiment_${experimentId}`: true,
`sw_variant_${variantId}`: true
});
break;
default:
break;
}
}
```
Once you've set this up, you can easily ask for all users who have an attribute `sw_experiment_1234` and breakdown by both variants to see how users in a Superwall experiment behave in other areas of your app.
### Creating custom analytics tracking using custom placements
By using custom placements, you can create analytic events for actions such as interacting with an element on a paywall. This can be useful for tracking how users interact with your paywall and how that affects their behavior in other areas of your app.
For example, in the paywall below, perhaps you're interested in tracking when people switch the plan from "Standard" and "Pro":
You could create a custom placement [tap behavior](/paywall-editor-styling-elements#tap-behaviors) which fires when a segment is tapped:
Then, you can listen for this event and forward it to your analytics service:
```swift Swift
extension SuperwallService: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case let .customPlacement(name, params, paywallInfo):
// Prints out didTapPro or didTapStandard
print("\(name) - \(params) - \(paywallInfo)")
MyAnalyticsService.shared.send(event: name, params: params)
default:
print("Default event: \(eventInfo.event.description)")
}
}
}
```
---
# Pre-Launch Checklist (Legacy)
Source: https://superwall.com/docs/legacy/legacy_pre-launch-checklist
Ready to ship your app with Superwall? Here is a last minute checklist to give you confidence that you're ready to ship without issue.
In your Superwall account, make sure you've got a card on file to avoid any service disruptions.
Go to `Settings->Billing` in your Superwall account to add one if you haven't yet.
Set up your products in their respective storefront first, whether that's App Store Connect or
Google Play. Once you've done that, add them into Superwall. All of their respective identifiers
should match what they are in each storefront. For more details, refer to this
[page](/products).
Each paywall should display one or more of those previously added products. You can associate
them easily on the left hand side of the paywall editor.
Be sure your paywall presents and our SDK is configured in your app. If you need to double check
things, check out the [docs for the relevant platform](/legacy/legacy_configuring-the-sdk).
Next, after your paywall shows in Testflight and beta builds, make sure you can successfully
purchase a product, start a trial or kick off a subscription. If you run into an issue, try
these steps in our [troubleshooting guide](/legacy/legacy_troubleshooting). They solve a majority of the
common problems.
Finally, make sure that your subscriptions have been approved in each storefront. On App Store
Connect, for example, you'll have to send off each one individually for review. If this is your
initial launch, you can have them approved alongside the first build of your app.
If everything looks good here, you should be ready to launch with Superwall.
### Bonus Steps
These aren't essential, but they are good to think about to make sure you're leveraging all Superwall has to offer.
No matter how much you optimize flows, designs or copy — the truth is that, statistically speaking, the majority of users will not convert. Finding out why is key, and you can do that with our surveys that you can attach to any paywall.
Once a user closes a paywall, we'll present the survey attached to it. See how to set them up [here](/surveys).
If you're new to Superwall, it might be tempting to use one, do-it-all placement — like `showPaywall` or something similar. We don't recommend this, please use an individual placement for each action or scenario that could possibly trigger a paywall. The more placements you have, the more flexible you can be. It opens up things like:
1. Showing a particular paywall based on a placement. For example, in a caffeine tracking app, two of them might be `caffeineLogged` and `viewedCharts`. Later, you could tailor the paywall based on which placement was fired.
2. You can dynamically make some placements "Pro" or temporarily free to test feature gating without submitting app updates.
3. In your campaign view, you can see which placements resulted in conversions. This helps you see what particular features users might value the most.
The easy advice is to simply create a placement for each action that might be paywalled. For a quick video on how to use placements, check out this [YouTube Short](https://youtube.com/shorts/lZx8fAL8Nvw?feature=shared).
Audiences are how Superwall can segment users by filtering by several different values such as the time of day, app version and more. This lets you target different paywalls to certain audiences. To see an example of how you might set up an advanced example, see this video:
---
# iOS - CocoaPods (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation-via-cocoapods
Install the Superwall iOS SDK via CocoaPods. To see the latest release, [check out the repository](https://github.com/superwall/Superwall-iOS).
## Install via CocoaPods
First, add the following to your Podfile:
`pod 'SuperwallKit', '< 4.0.0'
`
Next, run `pod repo update` to update your local spec repo. [Why?](https://stackoverflow.com/questions/43701352/what-exactly-does-pod-repo-update-do)
Finally, run `pod install` from your terminal.
### Updating to a New Release
To update to a new beta release, you'll need to update the version specified in the Podfile and then run `pod install` again.
### Import SuperwallKit
You should now be able to `import SuperwallKit`:
Swift:
`import SuperwallKit`
Objective-C:
`@import SuperwallKit;`
**And you're done!** Now you're ready to configure the SDK 👇
Begin configuring the SDK to show paywalls inside your App!
---
# Configuring the SDK (Legacy)
Source: https://superwall.com/docs/legacy/legacy_configuring-the-sdk
As soon as your app launches, you need to configure the SDK with your **Public API Key**. You'll retrieve this from the Superwall settings page.
If you haven't installed the SDK, [learn how to install the SDK](/legacy/legacy_installation)
### Sign Up & Grab Keys
If you haven't already, [sign up for a free account](https://superwall.com/sign-up) on Superwall. Then, when you're through to the Dashboard, click **Settings** from the panel on the left, click **Keys** and copy your **Public API Key**:
### Initialize Superwall in your app
Begin by editing your main Application entrypoint. Depending on the
platform this could be `AppDelegate.swift` or `SceneDelegate.swift` for iOS,
`MainApplication.kt` for Android, `main.dart` in Flutter, or `App.tsx` for React Native:
```swift Swift-UIKit
// AppDelegate.swift
import UIKit
import SuperwallKit
@main
final class AppDelegate: UIResponder, UIApplicationDelegate {
func application(
_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
Superwall.configure(apiKey: "MY_API_KEY") // Replace this with your API Key
return true
}
}
```
```swift SwiftUI
// App.swift
import SwiftUI
import SuperwallKit
@main
struct MyApp: App {
init() {
let apiKey = "MY_API_KEY" // Replace this with your API Key
Superwall.configure(apiKey: apiKey)
}
// etc...
}
```
```swift Objective-C
// AppDelegate.m
@import SuperwallKit;
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Initialize the Superwall service.
[Superwall configureWithApiKey:@"MY_API_KEY"];
return YES;
}
```
```kotlin Kotlin
// MainApplication.kt
class MainApplication : android.app.Application(), SuperwallDelegate {
override fun onCreate() {
super.onCreate()
// Setup
Superwall.configure(this, "MY_API_KEY")
// OR using the DSL
configureSuperwall("MY_API_KEY") {
purchaseController = MyPurchaseController(this@MainApplication)
}
}
}
```
```dart Flutter
// main.dart
void initState() {
// Determine Superwall API Key for platform
String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";
Superwall.configure(apiKey);
}
```
```typescript React Native
// App.tsx
import { Platform } from "react-native"
import Superwall from "@superwall/react-native-superwall"
export default function App() {
React.useEffect(() => {
const apiKey = Platform.OS === "ios" ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY"
Superwall.configure(apiKey)
}, [])
}
```
This configures a shared instance of `Superwall`, the primary class for interacting with the SDK's API. Make sure to replace `MY_API_KEY` with your public API key that you just retrieved.
By default, Superwall handles basic subscription-related logic for you. However, if you’d like
greater control over this process (e.g. if you’re using RevenueCat), you’ll want to pass in a
`PurchaseController` to your configuration call and manually set the `subscriptionStatus`. You can
also pass in `SuperwallOptions` to customize the appearance and behavior of the SDK. See
[Purchases and Subscription Status](/legacy/legacy_advanced-configuration) for more.
You've now configured Superwall!
For further help, check out our [iOS example apps](https://github.com/superwall/Superwall-iOS/tree/master/Examples) for working examples of implementing SuperwallKit.
---
# Presenting Paywalls from One Another (Legacy)
Source: https://superwall.com/docs/legacy/legacy_presenting-paywalls-from-one-another
Learn how to present a different paywall from one that's already presented.
It's possible to present another paywall from one already showing. This can be useful if you want to highlight a special discount, offer, or emphasize another feature more effectively using a different paywall. Check out the example here:
* A [placement](/campaigns-placements) is evaluated when the button is tapped. Superwall sees that the user isn't subscribed, so a paywall is shown.
* Next, the user taps the "Custom Icons Too 👀" button.
* The current paywall dismisses, and then presents the icons-centric paywall.
You can extend this technique to be used with several other interesting standard placements. For
example, presenting a paywall when the user abandons a transaction, responds to a survey and more.
Check out the examples [here](/campaigns-standard-placements#standard-placements).
There are two different ways you can do this, with [custom placements](/paywall-editor-styling-elements#tap-behaviors) or by using [deep links](/legacy/legacy_in-app-paywall-previews). We recommend using custom placements, as the setup is a little easier.
Custom placements minimum SDK requirements are 3.7.3 for iOS, 1.2.4 for Android, 1.2.2 for
flutter, and 1.2.6 for React Native.
They both have the same idea, though. You create a new campaign specifically for this purpose, attach a paywall and either add a filter (for deep linking) or a new placement (for custom placements) to match users to it.
While it's not *required* to make a new campaign, it is best practice. Then, if you later have
other paywalls you wish to open in the same manner, you can simply add a new
[audience](/campaigns-audience) for them in the campaign you make from the steps below.
### Use Custom Placements
Select a component on your paywall and add a **Custom Placement** Tap Behavior, and name it whatever you wish (i.e. showIconPaywall).
Finally, be sure to click **Publish** at the top of the editor to push your changes live
Create a new [campaign](/campaigns) specifically for this purpose, here — it's called "Custom Placement Example":
In your new campaign, [add a new placement](/campaigns-placements#adding-a-placement) that matches the name of your custom action you added in step one. For us, that's `showIconPaywall`:
Finally, choose a paywall that should present by **clicking** on the **Paywalls** button at the top:
### Use Deep Links
You'll need [deep links](/legacy/legacy_in-app-paywall-previews) set up for your app. This is how Superwall
will query parameters and later launch your desired paywall.
Choose the paywall you want to open another paywall from. Then, click the element (a button, text, etc.) that should open the new paywall:
1. In its component properties on the right-hand side, add a **Tap Behavior**.
2. Set its **Action** to **Open Url**.
3. For the URL, use your deep link scheme from step one, and then append a parameter which will represent which other paywall to present. This is specific to your app, but here — `offer` is the key and `icons` is the value. Your resulting URL should be constructed like this: `deepLinkScheme://?someKey=someValue`.
4. Set its **Type** to **Deep Link**.
5. Click **Done**.
Here's what it should look like (again, with your own values here):
Finally, be sure to click **Publish** at the top of the editor to push your changes live.
Create a new [campaign](/campaigns) specifically for this purpose, here — it's called "Deeplink Example":
In your new campaign, [add a placement](/campaigns-placements#adding-a-placement) for the `deepLink_open` standard placement:
Edit the default audience's filter to match `params.[whatever-you-named-the-parameter]`. Recall that in our example, the parameter was `offer` and the value was `icons`. So here, we'd type `params.offer` and **click** the **+** button:
Superwall will ask what type of new parameter this is — choose **Placement** and enter the parameter name once more (i.e. "offer"). Click **Save**:
Finally, choose the **is** operator and type in the value of your parameter (in our case, "icons"). Then, **click** the **+ Add Filter** button. Here's what it should look like:
Finally, choose a paywall that should present by **clicking** on the **Paywalls** button at the top:
### Test Opens
After following the steps above for either method, be sure to test out your presentation. Open the relevant paywall on a device and tap on whichever button should trigger the logic. The currently presented paywall should dismiss, and then immediately after — the other paywall will show.
---
# Passing in options (Legacy)
Source: https://superwall.com/docs/legacy/legacy_using-superwalloptions
When configuring the SDK you can pass in options that configure Superwall, the paywall presentation, and its appearance.
### Logging
Logging is enabled by default in the SDK and is controlled by two properties: `level` and `scopes`.
`level` determines the minimum log level to print to the console. There are five types of log level:
1. **debug**: Prints all logs from the SDK to the console. Useful for debugging your app if something isn't working as expected.
2. **info**: Prints errors, warnings, and useful information from the SDK to the console.
3. **warn**: Prints errors and warnings from the SDK to the console.
4. **error**: Only prints errors from the SDK to the console.
5. **none**: Turns off all logs.
The SDK defaults to `info`.
`scopes` defines the scope of logs to print to the console. For example, you might only care about logs relating to `paywallPresentation` and `paywallTransactions`. This defaults to `.all`. Check out [LogScope](https://sdk.superwall.me/documentation/superwallkit/logscope) for all possible cases.
You set these properties like this:
```swift Swift
let options = SuperwallOptions()
options.logging.level = .warn
options.logging.scopes = [.paywallPresentation, .paywallTransactions]
Superwall.configure(apiKey:"MY_API_KEY", options: options);
// Or you can set:
Superwall.shared.logLevel = .warn
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.logging.level = SWKLogLevelWarn;
[Superwall
configureWithApiKey:@"pk_e6bd9bd73182afb33e95ffdf997b9df74a45e1b5b46ed9c9"
purchaseController:nil
options:options
completion:nil
];
[Superwall sharedInstance].logLevel = SWKLogLevelWarn;
```
```kotlin Kotlin
val options = SuperwallOptions()
options.logging.level = LogLevel.warn
options.logging.scopes = EnumSet.of(LogScope.paywallPresentation, LogScope.paywallTransactions)
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or you can set:
Superwall.instance.logLevel = LogLevel.warn
// Or use the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
logging {
level = LogLevel.warn
scopes = EnumSet.of(LogScope.paywallPresentation, LogScope.paywallTransactions)
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.logging.level = LogLevel.arn;
options.logging.scopes = { LogScope.paywallPresentation, LogScope.paywallTransactions };
Superwall.configure(
"MY_API_KEY",
options: options
);
// Or you can set:
Superwall.instance.logLevel = LogLevel.warn;
```
```typescript React Native
const options = SuperwallOptions()
options.logging.level = LogLevel.Warn
options.logging.scopes = [LogScope.PaywallPresentation, LogScope.PaywallTransactions]
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
// Or you can set:
Superwall.instance.logLevel = LogLevel.Warn
```
### Preloading Paywalls
Paywalls are preloaded by default when the app is launched from a cold start. The paywalls that are preloaded are determined by the list of events that result in a paywall for the user when [registered](/docs/feature-gating). Preloading is smart, only preloading paywalls that belong to rules that could be matched.
Paywalls are cached by default, which means after they load once, they don't need to be reloaded from the network unless you make a change to them on the dashboard. However, if you have a lot of paywalls, preloading may increase network usage of your app on first load of the paywalls and result in slower loading times overall.
You can turn off preloading by setting `shouldPreload` to `false`:
```swift Swift
let options = SuperwallOptions()
options.paywalls.shouldPreload = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.shouldPreload = false;
[Superwall
configureWithApiKey:@"MY_API_KEY"
purchaseController:nil
options:options
completion:nil
];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.paywalls.shouldPreload = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
shouldPreload = false
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.shouldPreload = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.shouldPreload = false
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
// Or you can set:
Superwall.instance.logLevel = LogLevel.Warn
```
Then, if you'd like to preload paywalls for specific event names you can use `preloadPaywalls(forEvents:)`:
```swift Swift
Superwall.shared.preloadPaywalls(forEvents: ["campaign_trigger"]);
```
```swift Objective-C
NSMutableSet *eventNames = [NSMutableSet set];
[eventNames addObject:@"campaign_trigger"];
[[Superwall sharedInstance] preloadPaywallsForEvents:eventNames];
```
```kotlin Kotlin
val eventNames = setOf("campaign_trigger")
Superwall.instance.preloadPaywalls(eventNames)
```
```dart Flutter
var eventNames = {"campaign_trigger"};
Superwall.shared.preloadPaywallsForEvents(eventNames);
```
```typescript React Native
// Coming soon
```
If you'd like to preload all paywalls you can use `preloadAllPaywalls()`:
```swift Swift
Superwall.shared.preloadAllPaywalls()
```
```swift Objective-C
[[Superwall sharedInstance] preloadAllPaywalls];
```
```kotlin Kotlin
Superwall.instance.preloadAllPaywalls()
```
```dart Flutter
Superwall.shared.preloadAllPaywalls();
```
```typescript React Native
// Coming soon
```
Note: These methods will not reload any paywalls that have already been preloaded.
### External Data Collection
By default, Superwall sends all registered events and properties back to the Superwall servers. However, if you have privacy concerns, you can stop this by setting `isExternalDataCollectionEnabled` to `false`:
```swift Swift
let options = SuperwallOptions()
options.isExternalDataCollectionEnabled = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.isExternalDataCollectionEnabled = false;
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:nil options:options completion:nil];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.isExternalDataCollectionEnabled = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
isExternalDataCollectionEnabled = false
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.isExternalDataCollectionEnabled = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.isExternalDataCollectionEnabled = false
Superwall.configure(
"MY_API_KEY",
options: options
);
```
Disabling this will not affect your ability to create triggers based on properties.
### Automatically Dismissing the Paywall
By default, Superwall automatically dismisses the paywall when a product is purchased or restored. You can disable this by setting `automaticallyDismiss` to `false`:
```swift Swift
let options = SuperwallOptions()
options.paywalls.automaticallyDismiss = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.automaticallyDismiss = false;
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:nil options:options completion:^{}];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.paywalls.automaticallyDismiss = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
automaticallyDismiss = false
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.automaticallyDismiss = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.automaticallyDismiss = false
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
To manually dismiss the paywall , call `Superwall.shared.dismiss()`.
### Custom Restore Failure Message
You can set the title, message and close button title for the alert that appears after a restoration failure:
```swift Swift
let options = SuperwallOptions()
options.paywalls.restoreFailed.title = "My Title"
options.paywalls.restoreFailed.message = "My message"
options.paywalls.restoreFailed.closeButtonTitle = "Close"
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.restoreFailed.title = @"My Title";
options.paywalls.restoreFailed.message = @"My message";
options.paywalls.restoreFailed.closeButtonTitle = @"Close";
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:nil options:options completion:nil];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.paywalls.restoreFailed.title = "My Title"
options.paywalls.restoreFailed.message = "My message"
options.paywalls.restoreFailed.closeButtonTitle = "Close"
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
restoreFailed.title = "My Title"
restoreFailed.message = "My message"
restoreFailed.closeButtonTitle = "Close"
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.restoreFailed.title = "My Title";
options.paywalls.restoreFailed.message = "My message";
options.paywalls.restoreFailed.closeButtonTitle = "Close";
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.restoreFailed.title = "My Title"
options.paywalls.restoreFailed.message = "My message";
options.paywalls.restoreFailed.closeButtonTitle = "Close";
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
### Haptic Feedback
On iOS, the paywall uses haptic feedback by default after a user purchases or restores a product, opens a URL from the paywall, or closes the paywall. To disable this, set the `isHapticFeedbackEnabled` `PaywallOption` to false:
```swift Swift
let options = SuperwallOptions()
options.paywalls.isHapticFeedbackEnabled = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.isHapticFeedbackEnabled = false;
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:nil options:options completion:^{}];
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.isHapticFeedbackEnabled = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.isHapticFeedbackEnabled = false;
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
Note: Android does not use haptic feedback.
### Transaction Background View
During a transaction, we add a `UIActivityIndicator` behind the view to indicate a loading status. However, you can remove this by setting the `transactionBackgroundView` to `nil`:
```swift Swift
let options = SuperwallOptions()
options.paywalls.transactionBackgroundView = nil
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.transactionBackgroundView = SWKTransactionBackgroundViewNone;
[Superwall
configureWithApiKey:@"MY_API_KEY"
purchaseController:nil
options:options
completion:nil
];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.paywalls.transactionBackgroundView = null
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
transactionBackgroundView = null
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.transactionBackgroundView = TransactionBackgroundView.none;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.transactionBackgroundView = TransactionBackgroundView.none
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
### Purchase Failure Alert
When a purchase fails, we automatically present an alert with the error message. If you'd like to show your own alert after failure, set the `shouldShowPurchaseFailureAlert` `PaywallOption` to `false`:
```swift Swift
let options = SuperwallOptions()
options.paywalls.shouldShowPurchaseFailureAlert = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.paywalls.shouldShowPurchaseFailureAlert = false;
[Superwall
configureWithApiKey:@"MY_API_KEY"
purchaseController:nil
options:options
completion:nil
];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.paywalls.shouldShowPurchaseFailureAlert = false
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
paywalls {
shouldShowPurchaseFailureAlert = false
}
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.paywalls.shouldShowPurchaseFailureAlert = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.paywalls.shouldShowPurchaseFailureAlert = false;
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
### Locale Identifier
When evaluating rules, the device locale identifier is set to `autoupdatingCurrent`. However, you can override this if you want to test a specific locale:
```swift Swift
let options = SuperwallOptions()
options.localeIdentifier = "en_GB"
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
```swift Objective-C
SWKSuperwallOptions *options = [[SWKSuperwallOptions alloc] init];
options.localeIdentifier = @"en_GB";
[Superwall configureWithApiKey:@"MY_API_KEY" purchaseController:nil options:options completion:^{}];
```
```kotlin Kotlin
val options = SuperwallOptions()
options.localeIdentifier = "en_GB"
Superwall.configure(
this,
apiKey = "MY_API_KEY",
options = options
)
// Or using the configuration DSL
configureSuperwall("MY_API_KEY") {
options {
localeIdentifier = "en_GB"
}
}
```
```dart Flutter
SuperwallOptions options = SuperwallOptions();
options.localeIdentifier = "en_GB";
Superwall.configure(
"MY_API_KEY",
options: options
);
```
```typescript React Native
const options = SuperwallOptions()
options.localeIdentifier = "en_GB";
Superwall.configure(
"MY_API_KEY",
null,
options: options
);
```
For a list of locales that are available on iOS, take a look at [this list](https://gist.github.com/jacobbubu/1836273). You can also preview your paywall in different locales using [In-App Previews](/legacy/legacy_in-app-paywall-previews).
### Game Controller
If you're using a game controller, you can enable this in `SuperwallOptions` too. Check out our [Game Controller Support](../game-controller-support) article.
Take a look at [SuperwallOptions](https://sdk.superwall.me/documentation/superwallkit/superwalloptions) in our SDK reference for more info.
---
# Android - Gradle (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation-via-gradle
Install the Superwall Android SDK via Gradle. To see the latest release, [check out the repository](https://github.com/superwall/Superwall-Android).
## Install via Gradle
[Gradle](https://developer.android.com/build/releases/gradle-plugin) is the
preferred way to install Superwall for Android.
In your `build.gradle` or `build.gradle.kts` add the latest Superwall SDK. You
can find the [latest release here](https://github.com/superwall/Superwall-Android/releases).
```groovy build.gradle
implementation "com.superwall.sdk:superwall-android:1.3.2"
```
```kotlin build.gradle.kts
implementation("com.superwall.sdk:superwall-android:1.3.2")
```
```toml libs.version.toml
[libraries]
superwall-android = { group = "com.superwall.sdk", name = "superwall-android", version = "2.0.0-Alpha.1" }
// And in your build.gradle.kts
dependencies {
implementation(libs.superwall.android)
}
```
Make sure to run **Sync Now** to force Android Studio to update.
Go to your `AndroidManifest.xml` and add the following permissions:
```xml AndroidManifest.xml
```
Then add our Activity to your `AndroidManifest.xml`:
```xml AndroidManifest.xml
```
Set your app's theme in the `android:theme` section.
When choosing a device or emulator to run on make sure that it has the Play Store app and that you are signed in to your Google account on the Play Store.
**And you're done!** Now you're ready to configure the SDK 👇
Begin configuring the SDK to show paywalls inside your App!
---
# Using the Superwall Delegate (Legacy)
Source: https://superwall.com/docs/legacy/legacy_using-superwall-delegate
Use a Superwall delegate to help interface with 3rd party analytics, see which product was purchased on a paywall, handle custom events and more.
Use a Superwall's delegate to extend our SDK's functionality across several surface areas by assigning to the `delegate` property:
```swift Swift
class SWDelegate: SuperwallDelegate {
// Implement delegate methods here
}
// After configuring the SDK...
Superwall.shared.delegate = SWDelegate()
```
```swift Objective-C
// In its own file...
#import
@import SuperwallKit;
@interface SWDelegate : NSObject
@end
@implementation SWDelegate
// Implement delegate methods here
@end
// After configuring the SDK...
[[Superwall sharedInstance] setDelegate:[SWDelegate new]];
```
```kotlin Kotlin
class SWDelegate : SuperwallDelegate {
// Implement delegate methods here
}
// When configuring the SDK...
Superwall.shared.delegate = SWDelegate()
```
```dart Flutter
import 'package:superwall_flutter/superwall_flutter.dart';
class SWDelegate extends SuperwallDelegate {
// Implement delegate methods here
}
// When configuring the SDK...
void configureSDK() {
Superwall.shared.setDelegate(SWDelegate());
}
```
```typescript React Native
import {
PaywallInfo,
SubscriptionStatus,
SuperwallDelegate,
SuperwallEventInfo,
EventType,
} from '@superwall/react-native-superwall';
// Implement delegate methods
export class SWDelegate extends SuperwallDelegate {
}
// In your app.tsx...
import { SWDelegate } from './SWDelegate';
export default function App() {
const delegate = new SWDelegate();
React.useEffect(() => {
const setupSuperwall = async () => {
// After configuring the SDK...
Superwall.shared.setDelegate(delegate);
};
}, []);
}
```
Some common use cases for using the Superwall delegate include:
* **Custom actions:** [Respond to custom tap actions from a paywall.](/legacy/legacy_custom-paywall-events#custom-paywall-actions)
* **Respond to purchases:** [See which product was purchased from the presented paywall.](/legacy/legacy_3rd-party-analytics#using-events-to-see-purchased-products)
* **Analytics:** [Forward events from Superwall to your own analytics.](/legacy/legacy_3rd-party-analytics)
Below are some commonly used implementations when using the delegate.
### Superwall Events
Most of what occurs in Superwall can be viewed using the delegate method to respond to events:
```swift
class SWDelegate: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case .transactionComplete(let transaction, let product, let paywallInfo):
print("Converted from paywall originalTransactionIdentifier: \(transaction?.originalTransactionIdentifier ?? "")")
print("Converted from paywall storeTransactionId: \(transaction?.storeTransactionId ?? "")")
print("Converted from paywall productIdentifier: \(product.productIdentifier)")
print("Converted from paywall paywallInfo: \(paywallInfo.identifier)")
case .transactionRestore(let restoreType, let paywallInfo):
print("transactionRestore restoreType \(restoreType)")
case let .customPlacement(name, params, paywallInfo):
// Forward Mixpanel/Ampltiude/etc
print("\(name) - \(params) - \(paywallInfo)")
default:
// And several more events to use...
print("Default event: \(eventInfo.event.description)")
}
}
}
```
### Paywall Custom Actions
Using the [custom tap action](/legacy/legacy_custom-paywall-events), you can respond to any arbitrary event from a paywall:
```swift
class SWDelegate: SuperwallDelegate {
func handleCustomPaywallAction(withName name: String) {
if name == "showHelpCenter" {
DispatchQueue.main.asyncAfter(deadline: .now() + 0.33) {
self.showHelpCenter.toggle()
}
}
}
}
```
### Subscription status changes
You can be informed of subscription status changes using the delegate. If you need to set or handle the status on your own, use a [purchase controller](/legacy/legacy_advanced-configuration) — this function is only for informational, tracking or similar purposes:
```swift
class SWDelegate: SuperwallDelegate {
func subscriptionStatusDidChange(to newValue: SubscriptionStatus) {
// Log or handle subscription change in your Ui
}
}
```
### Paywall events
The delegate also has callbacks for several paywall events, such dismissing, presenting, and more. Here's an example:
```swift
class SWDelegate: SuperwallDelegate {
func didPresentPaywall(withInfo paywallInfo: PaywallInfo) {
// paywallInfo will contain all of the presented paywall's info
}
}
```
---
# User Management (Legacy)
Source: https://superwall.com/docs/legacy/legacy_identity-management
It is necessary to uniquely identify users to track their journey within Superwall.
### Anonymous Users
Superwall automatically generates a random user ID that persists internally until the user deletes/reinstalls your app.
You can call `Superwall.shared.reset()` to reset this ID and clear any paywall assignments.
### Identified Users
If you use your own user management system, call `identify(userId:options:)` when you have a user's identity. This will alias your `userId` with the anonymous Superwall ID enabling us to load the user’s assigned paywalls.
Calling `Superwall.shared.reset()` will reset the on-device userId to a random ID and clear the paywall assignments.
Note that for Android apps, if you want the `userId` passed to the Play Store when making purchases, you'll also need to set `passIdentifiersToPlayStore` via `SuperwallOptions`. Be aware of Google's rules that the `userId` must not contain any personally identifiable information, otherwise the purchase could [be rejected](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId).
```swift Swift
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.shared.identify(userId: user.id)
// When the user signs out
Superwall.shared.reset()
```
```swift Objective-C
// After retrieving a user's ID, e.g. from logging in or creating an account
[[Superwall sharedInstance] identifyWithUserId:user.id];
// When the user signs out
[[Superwall sharedInstance] resetWithCompletionHandler:completion];
```
```kotlin Kotlin
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.instance.identify(user.id)
// When the user signs out
Superwall.instance.reset()
```
```typescript React Native
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.shared.identify(user.id);
// When the user signs out
Superwall.shared.reset();
```
```dart Flutter
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.shared.identify(user.id);
// When the user signs out
Superwall.shared.reset();
```
**Advanced Use Case**
You can supply an `IdentityOptions` object, whose property `restorePaywallAssignments` you can set to `true`. This tells the SDK to wait to restore paywall assignments from the server before presenting any paywalls. This should only be used in advanced use cases. If you expect users of your app to switch accounts or delete/reinstall a lot, you'd set this when users log in to an existing account.
### Best Practices for a Unique User ID
* Do NOT make your User IDs guessable – they are public facing.
* Do NOT set emails as User IDs – this isn't GDPR compliant.
* Do NOT set IDFA or DeviceIds as User IDs – these are device specific / easily rotated by the operating system.
* Do NOT hardcode strings as User IDs – this will cause every user to be treated as the same user by Superwall.
**Identifying users from App Store server events**
On iOS, Superwall will set the value from `identify(userId:options:)` as the `applicationUsername` on `SKPayment`, which later comes back as the [appAccountToken](https://developer.apple.com/documentation/storekit/product/purchaseoption/3749440-appaccounttoken) in the notification to your server. Note that your application ID must be in a UUID format.
Begin showing paywalls!
---
# iOS - Swift Package Manager (Legacy)
Source: https://superwall.com/docs/legacy/legacy_installation-via-spm
Install the Superwall iOS SDK via Swift Package Manager. To see the latest release, [check out the repository](https://github.com/superwall/Superwall-iOS).
## Install via Swift Package Manager
[Swift Package Manager](https://swift.org/package-manager/) is a tool for automating the distribution of Swift code and is integrated into the Swift compiler.
In **Xcode**, select **File ▸ Add Packages...**:
{" "}
**Then, paste the GitHub repository URL:**
```
https://github.com/superwall/Superwall-iOS
```
in the search bar. With the **Superwall-iOS** source selected, set the **Dependency Rule** to **Up to Next Major Version** with the lower bound set to **3.0.0**. Make sure your project name is selected in **Add to Project**. Then click **Add Package**:
After the package has loaded, make sure **Add to Target** is set to your app's name and click **Add Package**:
**And you're done!** Now you're ready to configure the SDK 👇
Begin configuring the SDK to show paywalls inside your App!
---
# Superwall Events (Legacy)
Source: https://superwall.com/docs/legacy/legacy_tracking-analytics
The SDK automatically tracks some events, which power the charts in the dashboard.
We encourage you to track them in your own analytics as described in [3rd Party Analytics](/legacy/legacy_3rd-party-analytics).
The following Superwall events can be used as triggers to present paywalls:
* `app_install`
* `app_launch`
* `deepLink_open`
* `session_start`
* `paywall_decline`
* `transaction_fail`
* `transaction_abandon`
* `survey_response`
For more info about how to use these, check out [how to add them using a Placement](/campaigns-placements#adding-a-placement).
The full list of events is as follows:
| Event Name | Action | Parameters |
| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| app\_install | When the SDK is configured for the first time | \["is\_superwall": true, "app\_session\_id": String, "using\_purchase\_controller": Bool] |
| app\_launch | When the app is launched from a cold start | Same as app\_install |
| session\_start | When the app is opened either from a cold start, or after at least 60 minutes since last app\_close. | Same as app\_install |
| first\_seen | When the user is first seen in the app, regardless of whether the user is logged in or not. | Same as app\_install |
| app\_close | Anytime the app leaves the foreground | Same as app\_install |
| app\_open | Anytime the app enters the foreground | Same as app\_install |
| subscription\_start | When the user successfully completes a transaction for a subscription product with no introductory offers | \["product\_period\_days": String, "product\_price": String, "presentation\_source\_type": String?, "paywall\_response\_load\_complete\_time": String?, "product\_language\_code": String, "product\_trial\_period\_monthly\_price": String, "paywall\_products\_load\_duration": String?, "product\_currency\_symbol": String, "is\_superwall": true, "app\_session\_id": String, "product\_period\_months": String, "presented\_by\_event\_id": String?, "product\_id": String, "trigger\_session\_id": String, "paywall\_webview\_load\_complete\_time": String?, "paywall\_response\_load\_start\_time": String?, "product\_raw\_trial\_period\_price": String, "feature\_gating": Int, "paywall\_id": String, "product\_trial\_period\_daily\_price": String, "product\_period\_years": String, "presented\_by": String, "product\_period": String, "paywall\_url": String, "paywall\_name": String, "paywall\_identifier": String, "paywall\_products\_load\_start\_time": String?, "product\_trial\_period\_months": String, "product\_currency\_code": String, "product\_period\_weeks": String, "product\_periodly": String, "product\_trial\_period\_text": String, "paywall\_webview\_load\_start\_time": String?, "paywall\_products\_load\_complete\_time": String?, "primary\_product\_id": String, "product\_trial\_period\_yearly\_price": String, "paywalljs\_version": String?, "product\_trial\_period\_years": String, "tertiary\_product\_id": String, "paywall\_products\_load\_fail\_time": String?, "product\_trial\_period\_end\_date": String, "product\_weekly\_price": String, "variant\_id": String, "presented\_by\_event\_timestamp": String?, "paywall\_response\_load\_duration": String?, "secondary\_product\_id": String, "product\_trial\_period\_days": String, "product\_monthly\_price": String, "paywall\_product\_ids": String, "product\_locale": String, "product\_daily\_price": String, "product\_raw\_price": String, "product\_yearly\_price": String, "product\_trial\_period\_price": String, "product\_localized\_period": String, "product\_identifier": String, "experiment\_id": String, "is\_free\_trial\_available": Bool, "product\_trial\_period\_weeks": String, "paywall\_webview\_load\_duration": String?, "product\_period\_alt": String, "product\_trial\_period\_weekly\_price": String, "presented\_by\_event\_name": String?] |
| freeTrial\_start | When the user successfully completes a transaction for a subscription product with an introductory offer | Same as subscription\_start |
| nonRecurringProduct\_purchase | When the user purchased a non recurring product | Same as subscription\_start |
| transaction\_start | When the payment sheet is displayed to the user | Same as subscription\_start |
| transaction\_abandon | When the user cancels a transaction | Same as subscription\_start |
| transaction\_fail | When the payment sheet fails to complete a transaction (ignores user canceling the transaction) | Same as subscription\_start + \["message": String] |
| transaction\_restore | When the user successfully restores their purchases | Same as subscription\_start |
| transaction\_complete | When the user completes checkout in the payment sheet and any product was "purchased" | Same as subscription\_start + \["web\_order\_line\_item\_id": String, "app\_bundle\_id": String, "config\_request\_id": String, "state": String, "subscription\_group\_id": String, "is\_upgraded": String, "expiration\_date": String, "trigger\_session\_id": String, "original\_transaction\_identifier": String, "id": String, "transaction\_date": String, "is\_superwall": true, "store\_transaction\_id": String, "original\_transaction\_date": String, "app\_session\_id": String] |
| paywall\_close | When a paywall is closed (either by user interaction or do to a transaction succeeding) | \["paywall\_webview\_load\_complete\_time": String?, "paywall\_url": String, "paywall\_response\_load\_start\_time": String?, "paywall\_products\_load\_fail\_time": String?, "secondary\_product\_id": String, "feature\_gating": Int, "paywall\_response\_load\_complete\_time": String?, "is\_free\_trial\_available": Bool, "is\_superwall": true, "presented\_by": String, "paywall\_name": String, "paywall\_response\_load\_duration": String?, "paywall\_identifier": String, "paywall\_webview\_load\_start\_time": String?, "paywall\_products\_load\_complete\_time": String?, "paywall\_product\_ids": String, "tertiary\_product\_id": String, "paywall\_id": String, "app\_session\_id": String, "paywall\_products\_load\_start\_time": String?, "primary\_product\_id": String, "survey\_attached": Bool, "survey\_presentation": String?] |
| [paywall\_decline](/campaigns-placements#implicit-placements) | When a user manually dismisses a paywall. | Same as paywall\_close |
| paywall\_open | When a paywall is opened | Same as paywall\_close |
| paywallWebviewLoad\_start | When a paywall's URL begins to load | Same as paywall\_close |
| paywallWebviewLoad\_fail | When a paywall's URL fails to load | Same as paywall\_close |
| paywallWebviewLoad\_timeout | When the loading of a paywall's website times out. | Same as paywall\_close |
| paywallWebviewLoad\_complete | When a paywall's URL completes loading | Same as paywall\_close |
| trigger\_fire | When a tracked event triggers a paywall. | \["trigger\_name": String, "trigger\_session\_id": String, "variant\_id": String?, "experiment\_id": String?, "paywall\_identifier": String?, "result": String, "unmatched\_rule\_``": "``"]. unmatched\_rule\_`` indicates why a rule (with a specfiic experiment id) didn't match. It will only exist if the result is no\_rule\_match. Its outcome will either be OCCURRENCE, referring to the limit applied to a rule, or EXPRESSION. |
| paywallResponseLoad\_start | When a paywall's request to Superwall's servers has started | Same as app\_install +\["is\_triggered\_from\_event": Bool] |
| paywallResponseLoad\_fail | When a paywall's request to Superwall's servers has failed | Same as paywallResponseLoad\_start |
| paywallResponseLoad\_complete | When a paywall's request to Superwall's servers is complete | Same as paywallResponseLoad\_start |
| paywallResponseLoad\_notFound | When a paywall's request to Superwall's servers returned a 404 error. | Same as paywallResponseLoad\_start |
| paywallProductsLoad\_start | When the request to load the paywall's products started. | Same as paywallResponseLoad\_start |
| paywallProductsLoad\_fail | When the request to load the paywall's products failed. | Same as paywallResponseLoad\_start |
| paywallProductsLoad\_complete | When the request to load the paywall's products completed. | Same as paywallResponseLoad\_start |
| user\_attributes | When the user attributes are set. | \["aliasId": String, "seed": Int, "app\_session\_id": String, "applicationInstalledAt": String, "is\_superwall": true, "application\_installed\_at": String] + provided attributes |
| subscriptionStatus\_didChange | When the user's subscription status changes | \["is\_superwall": true, "app\_session\_id": String, "subscription\_status": String] |
| paywallPresentationRequest | When something happened during the paywall presentation, whether a success or failure. | \["source\_event\_name": String, "status": String, "is\_superwall": true, "app\_session\_id": String, "pipeline\_type": String, "status\_reason": String] |
| [deepLink\_open](/campaigns-placements#implicit-placements) | When a user opens the app via a deep link. | \["url": String, "path": String", "pathExtension": String, "lastPathComponent": String, "host": String, "query": String, "fragment": String] + any query parameters in the deep link URL |
| [survey\_response](/using-implicit-events#survey%5Fresponse) | When the response to a paywall survey as been recorded. | Same as subscription\_start + \["survey\_selected\_option\_title": String, "survey\_custom\_response": String, "survey\_id": String, "survey\_assignment\_key": String, "survey\_selected\_option\_id": String] |
| touches\_began | When the user touches the app's UIWindow for the first time. This is only tracked if there is an active touches\_began trigger in a campaign. | Same as app\_install |
| device\_attributes | When device attributes are sent to the backend every session. | \["app\_session\_id": String, "is\_superwall": Bool, "publicApiKey": String, "platform": String, "appUserId": String, "aliases":\[String], "vendorId": String, "appVersion": String, "osVersion": String, "deviceModel": String, "deviceLocale": String, "deviceLanguageCode": String, "deviceCurrencyCode": String, "deviceCurrencySymbol": String, "interfaceType": String, "timezoneOffset": Int, "radioType": String, "interfaceStyle": String, isLowPowerModeEnabled: Bool, "bundleId": String, "appInstallDate": String, "isMac": Bool, "daysSinceInstall": Int, "minutesSinceInstall": Int, "daysSinceLastPaywallView": Int?, "minutesSinceLastPaywallView": Int?, "totalPaywallViews": Int, "utcDate": String, "localDate": String, "utcTime": String, "localTime": String, "utcDateTime": String, "localDateTime": String, "isSandbox": String, "subscriptionStatus": String, "isFirstAppOpen": Bool, "sdkVersion": String, "sdkVersionPadded": String, "appBuildString": String, "appBuildStringNumber": Int?] |
---
# Troubleshooting (Legacy)
Source: https://superwall.com/docs/legacy/legacy_troubleshooting
undefined
### My paywall has unexpected presentation behaviour
If you are seeing a paywall when you think you shouldn't or vice versa, we recommend running through the following list to debug:
1. If you're [implementing subscription-related logic yourself](/legacy/legacy_advanced-configuration), check when you're setting `Superwall.shared.subscriptionStatus`. It's important that the variable here is kept in sync with the subscription status of the user. If it isn't, the paywall won't display when it is supposed to. If the status is `.unknown` or `.active`, the paywall won't show (unless you're specifically overriding that). [See here](/legacy/legacy_advanced-configuration) for more information about that.
2. Check your device. If you have already purchased a subscription on your device, your paywall wouldn't show again. If on iOS and you're using a local StoreKit file in your app for testing purposes, deleting and reinstalling your app will reset your device's subscription status.
3. Check your [campaign](/campaigns). Are you sending the necessary properties along with your trigger to match the rule? Is your trigger event name spelt correctly? If you have a holdout group in your campaign double check that this isn't the reason your paywall isn't displaying.
4. Check that the products on your paywall are available and their identifiers are correct. If not, you'll see an error printed to the console. On iOS, if you're using a StoreKit configuration file to test, make sure to add your products before trying to present the paywall.
### How can I debug paywall presentation in production?
If you know the userId of an account that's having trouble with paywalls, search for it in the Users tab on the dashboard. Clicking on it will reveal the user's events log. Whenever a paywall is or isn't shown, you'll see a `paywallPresentationRequest` event. Expanding that will give you a `status` and `status_reason` from which you can figure out what the issue is. If you're seeing `subscription_status_timeout` as a reason, it means that it took longer than 5 seconds to get the subscription status. This could be because you're not setting `Superwall.shared.subscriptionStatus` correctly or there's an issue with internet.
We recommend calling `identify(userId:)` in your app with the same userId that you use in your analytics to make life easier.
### In sandbox on iOS, my paywall shows free trial text but when I go to purchase, it doesn't show a free trial
If you've previously purchased a product within a subscription group and then deleted and reinstalled the app while testing in sandbox, this could happen. To fix this, restore products and try again. This is because we use the on-device receipt to determine whether a free trial is available. In sandbox, the app's receipt isn't retrieved until a purchase or restore is made. Therefore, the SDK won't be able to accurately determine whether the free trial is available. Fortunately, this won't happen in production.
### My products aren't loading or aren't working in production
If your products haven't loaded you'll get an error message printed to the console. Run through the following list to solve this:
1. On the Superwall dashboard:
1. Check that you have added products to all paywalls in the paywall editor. If any paywall doesn't contain a valid identifier you will see a error message in the console.
2. For iOS apps:
1. In Xcode:
1. If you're using a StoreKit configuration file locally, make sure your products have been added to it, either manually or by syncing with App Store Connect.
2. Make sure your app's bundle ID is the same as your app in App Store Connect.
3. Check you've added in-app purchase capability to your app's Xcode project.
2. On App Store Connect:
1. Make sure your free and paid apps agreements status are active.
2. Make sure that your tax and banking information has been added.
3. Make sure your product status is 'Ready to Submit'.
4. Check that the IDs of your products match those in the paywall.
5. Make sure you've waited at least 15 minutes after creating a product.
3. In Production:
1. Make sure you have waited for at least 72 hours after the release of a new app for your products to appear in your app. As soon as they appear on your App Store page, you'll know they're available in-app.
3. For Android apps:
1. Users in Russia and Belarus don't have access to Google Billing. In this instance, products won't load and paywalls won't show. The `onError` `PaywallPresentationHandler` handler will get called.
2. Make sure the device or emulator you're running on has the Play Store app and that you are signed in to your Google account on the Play Store.
3. Make sure your `applicationId` matches the applicationId on the Play Store.
4. If you're using RevenueCat:
1. Check that your product IDs are added to RevenueCat and associated with an entitlement.
2. If you're using offerings, make sure your product is associated with one.
---
# Custom Paywall Actions (Legacy)
Source: https://superwall.com/docs/legacy/legacy_custom-paywall-events
You can set the click behavior of any element on a paywall to be a custom paywall action. This allows you to tie any tap in your paywall to hard-coded application logic.
For example, adding a custom action called `help_center` to a button in your paywall gives you the opportunity to present a help center whenever that button is pressed. To set this up, implement `handleCustomPaywallAction(withName:)` in your `SuperwallDelegate`:
```swift Swift
func handleCustomPaywallAction(withName name: String) {
if name == "help_center" {
HelpCenterManager.present()
}
}
```
```swift Objective-C
- (void)handleCustomPaywallActionWithName:(NSString *)name {
if ([name isEqualToString:"help_center"]) {
[HelpCenterManager present];
}
}
```
```kotlin Kotlin
override fun handleCustomPaywallAction(name: String) {
if (name == "help_center") {
HelpCenterManager.present()
}
}
```
```dart Flutter
@override
void handleCustomPaywallAction(String name) {
if (name == "help_center") {
HelpCenterManager.present();
}
}
```
```typescript React Native
handleCustomPaywallAction(name: string) {
if (name == "help_center") {
HelpCenterManager.present();
}
}
```
Remember to set `Superwall.shared.delegate`! For implementation details, see the [Superwall Delegate](/legacy/legacy_using-superwall-delegate) guide.
---
# Using Superwall with Cursor
Source: https://superwall.com/docs/using-superwall-with-cursor
Use our SDK footprint file, along with a custom Cursor User Rule, to use Superwall with AI.
If you're developing an app using [Cursor](https://www.cursor.com/en), you can use our custom [Cursor User Rule](https://docs.cursor.com/context/rules-for-ai) to speed up your development. You can also prepend some of the examples found on [cursorrules.io](https://cursorrules.io), or use your current rule, in addition by adding in our following Superwall User Rule after it.
Right now, this is available for iOS and Swift with more SDKs and languages to come.
### Cursor user rules setup
To get started:
1. Download the User Rule file for iOS [here](https://github.com/superwall/cursor-rules/blob/main/ios-swiftui-cursor-rules-superwall-sdk.md).
2. In Cursor, go to **Cursor -> Settings... -> Cursor Settings**.
3. Under **User Rules**, paste in the text from the User Rule file.
This feature works much better if you remind Cursor that a code sample is related to Superwall. For example:
```md
// ✅ Try to do it this way!
Using the Superwall SDK, register a placement called "drinkCoffee" and include a print statement saying `Coffee time` in the block.
// ❌ Try not do it this way!
Register a placement called "drinkCoffee" and include a print statement saying `Coffee time` in the block.
```
Remember to check for updates to the User Cursor Rule, as we will edit it when our SDKs change.
Remember, LLMs can be hit or miss with advice — always review the code it suggests! Despite tuning the rules and prompts as best as we can, sometimes you may get inaccurate results.
---
# Interactive Paywall Preview
Source: https://superwall.com/docs/interactive-paywall-preview
The interactive paywall preview shows how your paywall looks on certain iOS devices, for different configurations:
The legacy editor is deprecated. Please visit the docs covering our new
[editor](/paywall-editor-overview).
The top bar allows you to change the localization of the paywall and the device that it's displayed on:
As you mouse-over the paywall, you'll see blue boxes appear highlighting the elements of the paywall that are editable. Clicking on one of these will bring up an editor to the right:
This is where you define what the end user sees for the selected element. It contains fields that are relevant to the type of element that's selected. For example, text can be edited in a textfield, and images and videos can be replaced.
Above this, you'll see two buttons: **Default** and **Free Trial**:
You can click these to toggle between the free trial and default (no free trial) behaviour of the selected element. This also toggles the device preview. When the SDK detects a free trial in any product and the user hasn't already used a free trial within that product's subscription group, it will use the content supplied in the free trial tab. Otherwise it will use the content in the default tab. The free trial tab automatically inherits from the default tab.
### Adding Variables
You can show product, user, or device data within text elements by adding a **Variable**. This uses a language called [Liquid](https://shopify.github.io/liquid/basics/introduction/) to substitute in data at runtime.
Click the **+ Add Variable** button to choose a variable:
This opens a navigation menu from which you can select the data you want to display, along with a preview of what that data looks like:
Clicking on a variable row will insert it inside your textfield with double curly brackets, which tells the device to replace it with real data:
The following objects can be referenced and templated within your paywalls:
| Object | Description | Example | User Sees |
| --------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| primary | Product information relating to the *primary product* defined in the *Product section* | `{{primary.trialPeriodDays}`} days free then only `{{primary.price}}` per `{{primary.period}} ` | 7 days free then only $89.99 per year |
| secondary | Product information relating to the *secondary product* defined in the *Product section* | Subscribe for only `{{secondary.price}}` per `{{secondary.period}}` | Subscribe for only $4.99 per month |
| tertiary | Product information relating to the *tertiary product* defined in the *Product section* | That's only `{{tertiary.weeklyPrice}}` per week! | That's only $2.49 per week! |
| user | User attributes your SDK implementation sets on the user. See [Setting User Attributes](/setting-user-properties) | Hey `{{user.firstName}}`! FitnessAI offers tons of `{{user.fitnessGoal}}` workouts to help you reach your goals :) | Hey Sam! FitnessAI offers tons of calorie burning workouts to help you reach your goals :) |
| params | Parameters defined when triggering a paywall. See [Showing Paywalls](/feature-gating). | Oh no, you lost! The secret word was `{{params.gameAnswer}}`. Start a free trial to play again! | Oh no, you lost! The secret word was MONEY. Start a free trial to play again! |
| device | Device attributes automatically created on device. | Compatible with your `{{ device.deviceModel }`} | Compatible with your iPhone 14 Pro |
You can do complex math on these variables using liquid. [Take a look at their documentation](https://shopify.github.io/liquid) for more on how to do that.
Additionally, you can use the following device properties: `device.minutesSince_X`, `device.hoursSince_X`, `device.daysSince_X`, `device.monthsSince_X`, and `device.yearsSince_X`, where X is the name of an event that you've [registered](/feature-gating) or a [Superwall event](/tracking-analytics). This gives you the days etc since the last occurrence of the event that you specify, excluding the event that triggered the paywall. For example, a paywall presented via an `app_open` event and the text It has been `{{ device.daysSince_app_open}}` since you last opened the app will show `{{ It has been 2 days since you last opened the app }}`.
### AI Powered Suggestions
When you edit a textfield, the AI Powered Suggestions section will offer alternative suggestions for your text using OpenAI's gpt3:
### Click Behavior
You can set the click behavior of an element by using the **Click Behavior** dropdown:
You choose from the following types of click behavior:
| Click Behavior | Functionality |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Do nothing | This won't do anything if the user taps on it. |
| Open deep link | This will open a deep link. After selecting this you can specify the link to use. We recommend sending deep links to the SDK: [Deep Links & In-App Previews](/in-app-paywall-previews). |
| Open URL | This will open a URL from within the paywall. |
| Open URL externally | This will open the provided URL in the user's browser. |
| Close the paywall | Closes the paywall. |
| Restore | Restores purchases via the restorePurchases(completion:) [delegate method](/configuring-the-sdk#conforming-to-the-delegate). |
| Custom action | Sends the custom action name you provide to the SDK's delegate method handleCustomPaywallAction(withName:). You can use this to perform custom logic from your app as discussed in [Custom Paywall Actions](/custom-paywall-events). |
| Purchase primary | Initiates the delegate method purchase(product:) with your primary product identifier. |
| Purchase secondary | Initiates the delegate method purchase(product:) with your secondary product identifier. |
| Purchase tertiary | Initiates the delegate method purchase(product:) with your tertiary product identifier. |
### Customizing design
You can customize the layout, typography, layer, size, margin, padding, corners, effects and background image using the fields below the click behavior:
---
# overrideProductsByName
Source: https://superwall.com/docs/flutter/sdk-reference/overrideProductsByName
Globally override products on any paywall by product name.
## Purpose
Allows you to globally override products on any paywall that have a given name. The key is the product name in the paywall, and the value is the product identifier to replace it with. This is useful for A/B testing different products or dynamically changing products based on user segments.
## Signature
```dart
// Setter
set overrideProductsByName(Map? overrideProducts)
// Getter
Future?> getOverrideProductsByName()
```
## Parameters
| Name | Type | Description |
| ---------------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| overrideProducts | Map\? | A map where keys are product names in paywalls (e.g., \`"primary"\`, \`"secondary"\`) and values are the product identifiers to replace them with (e.g., \`"com.example.premium\_monthly"\`). Pass \`null\` to clear all overrides. |
## Returns / State
* **Setter**: Sets the global product overrides. Changes take effect immediately for all future paywall presentations.
* **Getter**: Returns a `Future?>` containing the current override mapping, or `null` if no overrides are set.
## Usage
Setting product overrides:
```dart
// Override products globally
Superwall.shared.overrideProductsByName = {
'primary': 'com.example.premium_monthly',
'secondary': 'com.example.premium_annual',
'tertiary': 'com.example.premium_lifetime',
};
// All paywalls will now use these product identifiers
// instead of the ones configured in the dashboard
```
Clearing overrides:
```dart
// Clear all overrides
Superwall.shared.overrideProductsByName = null;
```
Getting current overrides:
```dart
final overrides = await Superwall.shared.getOverrideProductsByName();
if (overrides != null) {
print('Current overrides: $overrides');
} else {
print('No overrides set');
}
```
Dynamic overrides based on user segment:
```dart
void _setProductOverridesForUser(User user) {
if (user.isPremium) {
// Premium users get annual products
Superwall.shared.overrideProductsByName = {
'primary': 'com.example.premium_annual',
};
} else {
// Regular users get monthly products
Superwall.shared.overrideProductsByName = {
'primary': 'com.example.premium_monthly',
};
}
}
```
A/B testing different products:
```dart
void _setupProductABTest() {
final random = Random();
if (random.nextBool()) {
// Variant A: Monthly product
Superwall.shared.overrideProductsByName = {
'primary': 'com.example.premium_monthly',
};
} else {
// Variant B: Annual product
Superwall.shared.overrideProductsByName = {
'primary': 'com.example.premium_annual',
};
}
}
```
## Notes
* Overrides apply globally to all paywalls that use the specified product names
* Overrides take effect immediately for all future paywall presentations
* You can also set overrides per-paywall using [`PaywallOptions.overrideProductsByName`](/flutter/sdk-reference/PaywallOptions#overrideproductsbyname)
* Per-paywall overrides take precedence over global overrides
## Related
* [`PaywallOptions.overrideProductsByName`](/flutter/sdk-reference/PaywallOptions) - Override products for a specific paywall
* [`PaywallOptions`](/flutter/sdk-reference/PaywallOptions) - Paywall configuration options
---
# Superwall.shared
Source: https://superwall.com/docs/flutter/sdk-reference/Superwall
The shared Superwall instance that provides access to all SDK methods.
You must call [`configure()`](/flutter/sdk-reference/configure) before accessing `Superwall.shared`, or the app will crash.
## Purpose
Provides access to the configured Superwall instance after calling `configure()`.
## Signature
```dart
static Superwall get shared
```
## Returns / State
Returns the configured `Superwall` instance that can be used to access all SDK methods.
## Usage
Accessing the shared instance:
```dart
// After calling configure()
await Superwall.shared.registerPlacement('premium_feature');
await Superwall.shared.identify('user_123');
```
Reset the user:
```dart
await Superwall.shared.reset();
```
Avoid calling `Superwall.shared.reset()` repeatedly. Resetting rotates the anonymous user ID, clears local paywall assignments, and requires the SDK to re-download configuration state. Only trigger a reset when a user explicitly logs out or you intentionally need to forget their identity. See [User Management](/flutter/quickstart/user-management) for more guidance.
Common usage pattern:
```dart
void _upgradeUser() async {
await Superwall.shared.registerPlacement(
'upgrade_prompt',
feature: () {
// Feature unlocked after purchase
Navigator.pushNamed(context, '/premium-content');
},
);
}
```
With subscription status:
```dart
class _MyWidgetState extends State {
@override
void initState() {
super.initState();
// Listen to subscription status changes
Superwall.shared.subscriptionStatus.listen((status) {
setState(() {
// Update UI based on subscription status
});
});
}
}
```
---
# PurchaseController
Source: https://superwall.com/docs/flutter/sdk-reference/PurchaseController
An abstract class for handling custom purchase flows and subscription management.
Implementing a custom PurchaseController is advanced functionality. Most developers should use the default purchase controller with RevenueCat integration.
For RevenueCat integration, see the [Using RevenueCat guide](/flutter/guides/using-revenuecat) instead of implementing a custom PurchaseController.
## Purpose
Allows custom implementation of purchase flows, subscription validation, and cross-platform purchase handling.
## Signature
```dart
abstract class PurchaseController {
Future purchaseFromAppStore(String productId);
Future purchaseFromGooglePlay(
String productId,
String? basePlanId,
String? offerId,
);
Future restorePurchases();
}
```
## Parameters
| Name | Type | Description | Required |
| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------- | -------- |
| purchaseFromAppStore | productId: String | Handles iOS App Store purchases. | yes |
| purchaseFromGooglePlay | productId: String, basePlanId: String?, offerId: String? | Handles Google Play Store purchases with optional base plan and offer. | yes |
| restorePurchases | None | Restores previous purchases across platforms. | yes |
## Returns / State
* `purchaseFromAppStore` and `purchaseFromGooglePlay` return `Future`
* `restorePurchases` returns `Future`
## Usage
For most use cases, use RevenueCat integration instead:
See the [Using RevenueCat guide](/flutter/guides/using-revenuecat) for complete setup instructions.
Custom implementation is only needed for advanced use cases where you have your own purchase handling system.
---
# Entitlements
Source: https://superwall.com/docs/flutter/sdk-reference/Entitlements
Container for all entitlements available to the user, organized by status.
## Purpose
Provides organized access to user entitlements with methods to filter and query them. Returned by [`getEntitlements()`](/flutter/sdk-reference/getEntitlements).
## Signature
```dart
class Entitlements {
final Set active;
final Set inactive;
final Set all;
final Set web;
Future> byProductIds(Set productIds);
}
```
## Properties
| Name | Type | Description | Required |
| -------- | ----------------- | ---------------------------------------------- | -------- |
| active | Set\ | All active entitlements available to the user. | yes |
| inactive | Set\ | All inactive entitlements. | yes |
| all | Set\ | All entitlements (both active and inactive). | yes |
| web | Set\ | Entitlements from web checkout. | yes |
## Methods
### byProductIds()
Filters entitlements by product IDs. Returns all entitlements that contain any of the specified product IDs.
**Signature:**
```dart
Future> byProductIds(Set productIds)
```
**Parameters:**
* `productIds` - A set of product identifiers to search for
**Returns:** A future that resolves to a set of entitlements that contain any of the specified product IDs.
## Usage
Accessing different entitlement sets:
```dart
final entitlements = await Superwall.shared.getEntitlements();
// Check active entitlements
if (entitlements.active.isNotEmpty) {
print('User has ${entitlements.active.length} active entitlements');
}
// Check web checkout entitlements
if (entitlements.web.isNotEmpty) {
print('User has web checkout entitlements');
}
```
Filtering by product IDs:
```dart
final entitlements = await Superwall.shared.getEntitlements();
// Find entitlements for specific products
final premiumEntitlements = await entitlements.byProductIds({
'premium_monthly',
'premium_yearly',
'premium_lifetime',
});
if (premiumEntitlements.isNotEmpty) {
print('User has premium access');
for (final entitlement in premiumEntitlements) {
print('Premium entitlement: ${entitlement.id}');
}
}
```
Checking for specific entitlement:
```dart
final entitlements = await Superwall.shared.getEntitlements();
final hasPro = entitlements.all.any(
(entitlement) => entitlement.id == 'pro' && entitlement.isActive,
);
if (hasPro) {
// User has pro access
showProFeatures();
}
```
## Related
* [`getEntitlements()`](/flutter/sdk-reference/getEntitlements) - Method to retrieve entitlements
* [`Entitlement`](/flutter/sdk-reference/Entitlement) - Individual entitlement information
---
# SubscriptionTransaction
Source: https://superwall.com/docs/flutter/sdk-reference/SubscriptionTransaction
Represents a subscription transaction in the customer's purchase history.
The `offerType`, `subscriptionGroupId`, and `store` fields were added in 2.4.7.
## Purpose
Provides details about a single subscription transaction returned from [`CustomerInfo`](/flutter/sdk-reference/CustomerInfo). Use this to understand renewal status, applied offers, and the store that fulfilled the purchase.
## Properties
| Name | Type | Description | Required |
| ---------------------- | ---------------------------- | ----------------------------------------------------- | -------- |
| transactionId | String | Unique identifier for the transaction. | yes |
| productId | String | Product identifier for the subscription. | yes |
| purchaseDate | DateTime | When the store charged the account. | yes |
| willRenew | bool | Whether the subscription is set to auto-renew. | yes |
| isRevoked | bool | \`true\` if the transaction has been revoked. | yes |
| isInGracePeriod | bool | \`true\` if the subscription is in grace period. | yes |
| isInBillingRetryPeriod | bool | \`true\` if the subscription is in billing retry. | yes |
| isActive | bool | \`true\` when the subscription is currently active. | yes |
| expirationDate | DateTime? | Expiration date, if applicable. | no |
| offerType | LatestSubscriptionOfferType? | Offer applied to this transaction (2.4.7+). | no |
| subscriptionGroupId | String? | Subscription group identifier, if available (2.4.7+). | no |
| store | ProductStore? | Store that fulfilled the purchase (2.4.7+). | no |
## Offer types (2.4.7+)
* `trial` - introductory offer.
* `code` - offer redeemed with a promo code.
* `promotional` - promotional offer.
* `winback` - win-back offer (iOS 17.2+ only).
## Store values (2.4.7+)
`appStore`, `stripe`, `paddle`, `playStore`, `superwall`, `other`.
## Usage
Inspect subscription transactions:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
for (final subscription in customerInfo.subscriptions) {
print('Product: ${subscription.productId}');
print('Active: ${subscription.isActive}');
print('Store: ${subscription.store}');
print('Offer: ${subscription.offerType}');
print('Group: ${subscription.subscriptionGroupId ?? "unknown"}');
}
```
## Related
* [`CustomerInfo`](/flutter/sdk-reference/CustomerInfo) - Source of subscription data
* [`NonSubscriptionTransaction`](/flutter/sdk-reference/NonSubscriptionTransaction) - Non-subscription transactions
* [`getCustomerInfo()`](/flutter/sdk-reference/getCustomerInfo) - Fetch customer info
---
# PaywallOptions
Source: https://superwall.com/docs/flutter/sdk-reference/PaywallOptions
Configuration for paywall presentation and behavior in the Superwall Flutter SDK.
`PaywallOptions` is provided via the `paywalls` parameter on [`SuperwallOptions`](/flutter/sdk-reference/SuperwallOptions) and is passed when calling [`configure`](/flutter/sdk-reference/configure).
## Purpose
Customize how paywalls look and behave, including preload behavior, alerts, dismissal, and haptics.
## Signature
```dart
class PaywallOptions {
bool isHapticFeedbackEnabled = true;
RestoreFailed restoreFailed = RestoreFailed();
bool shouldShowPurchaseFailureAlert = true;
bool shouldPreload = true;
bool automaticallyDismiss = true;
TransactionBackgroundView transactionBackgroundView = TransactionBackgroundView.spinner;
bool shouldShowWebRestorationAlert = true;
Map? overrideProductsByName;
bool shouldShowWebPurchaseConfirmationAlert = true;
void Function(PaywallInfo?)? onBackPressed;
}
class RestoreFailed {
String title = 'No Subscription Found';
String message = "We couldn't find an active subscription for your account.";
String closeButtonTitle = 'Okay';
}
enum TransactionBackgroundView { spinner, none }
```
## Parameters
| Name | Type | Description | Default | Required |
| -------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | -------- |
| isHapticFeedbackEnabled | bool | Enables haptic feedback during key paywall interactions. | true | no |
| restoreFailed | RestoreFailed | Messaging for the restore-failed alert. | | yes |
| restoreFailed.title | String | Title for restore-failed alert. | No Subscription Found | no |
| restoreFailed.message | String | Message for restore-failed alert. | We couldn't find an active subscription for your account. | no |
| restoreFailed.closeButtonTitle | String | Close button title for restore-failed alert. | Okay | no |
| shouldShowPurchaseFailureAlert | bool | Shows an alert after a purchase fails. Set to \`false\` if you handle failures via a \`PurchaseController\`. | true | no |
| shouldPreload | bool | Preloads and caches trigger paywalls and products during SDK initialization. | true | no |
| automaticallyDismiss | bool | Automatically dismisses the paywall on successful purchase or restore. | true | no |
| transactionBackgroundView | TransactionBackgroundView | View shown behind the system payment sheet during a transaction. | .spinner | no |
| shouldShowWebRestorationAlert | bool | Shows an alert asking the user to try restoring on the web if web checkout is enabled. | true | no |
| overrideProductsByName | Map\? | Overrides products on all paywalls using name→identifier mapping (e.g., \`"primary"\` → \`"com.example.premium\_monthly"\`). | | no |
| shouldShowWebPurchaseConfirmationAlert | bool | Shows a localized alert confirming a successful web checkout purchase. | true | no |
| onBackPressed | void Function(PaywallInfo?)? | Android only. Invoked when the system back button is pressed while a paywall is visible. Call \`Superwall.shared.dismiss()\` inside if you want to close the paywall. | | no |
## Usage
```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,
);
```
## Related
* [`SuperwallOptions`](/flutter/sdk-reference/SuperwallOptions)
---
# registerPlacement()
Source: https://superwall.com/docs/flutter/sdk-reference/register
A function that registers a placement that can be remotely configured to show a paywall and gate feature access.
## Purpose
Registers a placement so that when it's added to a campaign on the Superwall Dashboard, it can trigger a paywall and optionally gate access to a feature.
## Signature
```dart
Future registerPlacement(
String placement, {
Map? params,
PaywallPresentationHandler? handler,
Function()? feature,
})
```
```dart
Future registerPlacement(
String placement, {
Map? params,
PaywallPresentationHandler? handler,
})
```
## Parameters
| Name | Type | Description | Default | Required |
| --------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| placement | String | The name of the placement you wish to register. | | yes |
| params | Map\? | Optional parameters to pass with your placement. These can be referenced within campaign rules. Keys beginning with \`$\` are reserved for Superwall and will be dropped. Nested maps and lists are currently unsupported and will be ignored. | null | no |
| handler | PaywallPresentationHandler? | A handler whose functions provide status updates for the paywall lifecycle. | null | no |
| feature | Function()? | A callback representing the gated feature. It is executed based on the paywall's gating mode: called immediately for \*\*Non-Gated\*\*, called after the user subscribes or if already subscribed for \*\*Gated\*\*. | | no |
## Returns / State
This function returns a `Future`. If you supply a `feature` callback, it will be executed according to the paywall's gating configuration, as described above.
## Usage
```dart
await Superwall.shared.registerPlacement(
"premium_feature",
params: {"source": "onboarding"},
feature: () {
// Code that unlocks the premium feature
openPremiumScreen();
},
);
```
```dart
await Superwall.shared.registerPlacement(
"onboarding_complete",
params: {"source": "onboarding"},
handler: myHandler,
);
```
---
# subscriptionStatus
Source: https://superwall.com/docs/flutter/sdk-reference/subscriptionStatus
A Stream that emits the user's current subscription status whenever it changes.
This Stream emits `SubscriptionStatus` values whenever the user's subscription status changes. Use it to reactively update your UI based on subscription state.
## Purpose
Provides a reactive stream of subscription status changes for updating UI and controlling feature access.
## Signature
```dart
Stream get subscriptionStatus
```
## Returns / State
Returns a `Stream` that emits values whenever the subscription status changes.
## Convenience
Use the `isActive` convenience property when you only need to know whether the user is subscribed:
```dart
Future ensureAccess() async {
final status = await Superwall.shared.subscriptionStatus.first;
if (status.isActive) {
enablePremiumFeatures();
} else {
showUpgradePrompt();
}
}
```
## Usage
Basic stream subscription:
```dart
class _MyAppState extends State {
StreamSubscription? _subscription;
SubscriptionStatus _currentStatus = SubscriptionStatus.unknown;
@override
void initState() {
super.initState();
_subscription = Superwall.shared.subscriptionStatus.listen((status) {
setState(() {
_currentStatus = status;
});
});
}
@override
void dispose() {
_subscription?.cancel();
super.dispose();
}
}
```
With SuperwallBuilder widget:
```dart
SuperWallBuilder(
builder: (context, subscriptionStatus) {
switch (subscriptionStatus) {
case SubscriptionStatus.active:
return PremiumContent();
case SubscriptionStatus.inactive:
return FreeContent();
default:
return LoadingIndicator();
}
},
)
```
Conditional UI rendering:
```dart
class PremiumFeatureButton extends StatefulWidget {
@override
_PremiumFeatureButtonState createState() => _PremiumFeatureButtonState();
}
class _PremiumFeatureButtonState extends State {
@override
Widget build(BuildContext context) {
return StreamBuilder(
stream: Superwall.shared.subscriptionStatus,
builder: (context, snapshot) {
final status = snapshot.data ?? SubscriptionStatus.unknown;
return ElevatedButton(
onPressed: status == SubscriptionStatus.active
? _accessPremiumFeature
: _showPaywall,
child: Text(
status == SubscriptionStatus.active
? 'Access Premium Feature'
: 'Upgrade to Premium',
),
);
},
);
}
}
```
---
# setSubscriptionStatus()
Source: https://superwall.com/docs/flutter/sdk-reference/advanced/setSubscriptionStatus
Manually sets the user's subscription status when using a custom PurchaseController.
This method should only be used with a custom [`PurchaseController`](/flutter/sdk-reference/PurchaseController). The default purchase controller manages subscription status automatically.
## Purpose
Manually updates the user's subscription status when implementing custom purchase logic.
## Signature
```dart
Future setSubscriptionStatus(SubscriptionStatus status)
```
## Parameters
| Name | Type | Description | Required |
| ------ | ------------------ | ----------------------------------------------------------- | -------- |
| status | SubscriptionStatus | The subscription status to set (active, inactive, unknown). | yes |
## Returns / State
Returns a `Future` that completes when the subscription status is updated.
## Usage
After custom purchase:
```dart
class MyPurchaseController extends PurchaseController {
@override
Future purchaseFromAppStore(String productId) async {
try {
// Custom purchase logic
final result = await MyPaymentService.purchase(productId);
if (result.success) {
// Update subscription status after successful purchase
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatus.active,
);
return PurchaseResult.purchased;
}
return PurchaseResult.failed;
} catch (e) {
return PurchaseResult.failed;
}
}
}
```
Subscription expiry handling:
```dart
Future _checkSubscriptionExpiry() async {
final expiryDate = await MyPaymentService.getSubscriptionExpiry();
if (expiryDate.isBefore(DateTime.now())) {
// Subscription has expired
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatus.inactive,
);
// Show renewal prompt
_showRenewalPrompt();
}
}
```
Manual status sync:
```dart
Future _syncSubscriptionStatus() async {
try {
final serverStatus = await MyAPI.getUserSubscriptionStatus();
final superwallStatus = serverStatus.isActive
? SubscriptionStatus.active
: SubscriptionStatus.inactive;
await Superwall.shared.setSubscriptionStatus(superwallStatus);
} catch (e) {
print('Failed to sync subscription status: $e');
}
}
```
---
# consume()
Source: https://superwall.com/docs/flutter/sdk-reference/consume
Consumes an in-app purchase by its purchase token.
## Purpose
Consumes a consumable in-app purchase using its purchase token. This is typically used for Google Play Store purchases that need to be consumed before they can be purchased again.
## Signature
```dart
Future consume(String purchaseToken)
```
## Parameters
| Name | Type | Description | Required |
| ------------- | ------ | ----------------------------------------------------- | -------- |
| purchaseToken | String | The purchase token of the in-app purchase to consume. | yes |
## Returns / State
Returns a `Future` that resolves to the purchase token of the consumed purchase.
## Usage
Consuming a purchase after successful purchase:
```dart
try {
final purchaseToken = await Superwall.shared.consume('purchase_token_123');
print('Purchase consumed: $purchaseToken');
} catch (e) {
print('Failed to consume purchase: $e');
}
```
Using with a PurchaseController:
```dart
class MyPurchaseController extends PurchaseController {
@override
Future purchase(Product product) async {
// Handle purchase
final transaction = await _processPurchase(product);
// If this is a consumable product, consume it
if (product.type == ProductType.consumable) {
try {
await Superwall.shared.consume(transaction.purchaseToken);
print('Consumable purchase consumed');
} catch (e) {
print('Failed to consume purchase: $e');
}
}
}
}
```
## Related
* [`PurchaseController`](/flutter/sdk-reference/PurchaseController) - Handles purchase logic
* [`Product`](/flutter/sdk-reference/Product) - Product information
---
# getEntitlements()
Source: https://superwall.com/docs/flutter/sdk-reference/getEntitlements
Gets all entitlements available to the user, organized by status.
## Purpose
Retrieves all entitlements available to the user, organized into active, inactive, all, and web entitlements. Also provides a method to filter entitlements by product IDs.
## Signature
```dart
Future getEntitlements()
```
## Returns / State
Returns a `Future` containing:
* `active` - Set of active entitlements
* `inactive` - Set of inactive entitlements
* `all` - Set of all entitlements (active and inactive)
* `web` - Set of entitlements from web checkout
* `byProductIds(productIds)` - Method to filter entitlements by product IDs
## Usage
Getting all entitlements:
```dart
final entitlements = await Superwall.shared.getEntitlements();
print('Active: ${entitlements.active.length}');
print('Inactive: ${entitlements.inactive.length}');
print('Total: ${entitlements.all.length}');
print('Web: ${entitlements.web.length}');
```
Checking for specific entitlements:
```dart
final entitlements = await Superwall.shared.getEntitlements();
final hasPremium = entitlements.active.any(
(entitlement) => entitlement.id == 'premium',
);
if (hasPremium) {
print('User has premium access');
}
```
Filtering entitlements by product IDs:
```dart
final entitlements = await Superwall.shared.getEntitlements();
// Get entitlements that contain any of these product IDs
final filtered = await entitlements.byProductIds({
'premium_monthly',
'premium_yearly',
});
print('Found ${filtered.length} entitlements for those products');
```
Checking web checkout entitlements:
```dart
final entitlements = await Superwall.shared.getEntitlements();
if (entitlements.web.isNotEmpty) {
print('User has ${entitlements.web.length} web checkout entitlements');
for (final entitlement in entitlements.web) {
print('Web entitlement: ${entitlement.id}');
}
}
```
## Related
* [`Entitlements`](/flutter/sdk-reference/Entitlements) - The entitlements container class
* [`Entitlement`](/flutter/sdk-reference/Entitlement) - Individual entitlement information
* [`getCustomerInfo()`](/flutter/sdk-reference/getCustomerInfo) - Get customer info including entitlements
---
# NonSubscriptionTransaction
Source: https://superwall.com/docs/flutter/sdk-reference/NonSubscriptionTransaction
Represents a non-subscription transaction (consumables and non-consumables).
The `store` field was added in 2.4.7.
## Purpose
Provides details about one-time purchases in [`CustomerInfo`](/flutter/sdk-reference/CustomerInfo), including which store fulfilled the purchase.
## Properties
| Name | Type | Description | Required |
| ------------- | ------------- | -------------------------------------------------------- | -------- |
| transactionId | String | Unique identifier for the transaction. | yes |
| productId | String | Product identifier for the purchase. | yes |
| purchaseDate | DateTime | When the charge occurred. | yes |
| isConsumable | bool | \`true\` for consumables, \`false\` for non-consumables. | yes |
| isRevoked | bool | \`true\` if the transaction has been revoked. | yes |
| store | ProductStore? | Store that fulfilled the purchase (2.4.7+). | no |
## Store values (2.4.7+)
`appStore`, `stripe`, `paddle`, `playStore`, `superwall`, `other`.
## Usage
Inspect non-subscription purchases:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
for (final purchase in customerInfo.nonSubscriptions) {
print('Product: ${purchase.productId}');
print('Store: ${purchase.store}');
print('Consumable: ${purchase.isConsumable}');
print('Revoked: ${purchase.isRevoked}');
}
```
## Related
* [`CustomerInfo`](/flutter/sdk-reference/CustomerInfo) - Source of transaction data
* [`SubscriptionTransaction`](/flutter/sdk-reference/SubscriptionTransaction) - Subscription transactions
* [`getCustomerInfo()`](/flutter/sdk-reference/getCustomerInfo) - Fetch customer info
---
# getUserId()
Source: https://superwall.com/docs/flutter/sdk-reference/getUserId
Gets the current user ID that was set via identify().
## Purpose
Retrieves the current user ID that was previously set using [`identify()`](/flutter/sdk-reference/identify).
## Signature
```dart
Future getUserId()
```
## Returns / State
Returns a `Future` containing the current user ID, or an empty string if no user has been identified.
## Usage
Basic usage:
```dart
final userId = await Superwall.shared.getUserId();
print('Current user ID: $userId');
```
Conditional logic:
```dart
Future _checkUserStatus() async {
final userId = await Superwall.shared.getUserId();
if (userId.isNotEmpty) {
print('User is logged in: $userId');
// Show personalized content
_loadUserSpecificData();
} else {
print('No user logged in');
// Show login prompt
_showLoginDialog();
}
}
```
With user attributes:
```dart
Future> _getCurrentUserInfo() async {
final userId = await Superwall.shared.getUserId();
final attributes = await Superwall.shared.getUserAttributes();
return {
'userId': userId,
'attributes': attributes,
};
}
```
---
# identify()
Source: https://superwall.com/docs/flutter/sdk-reference/identify
Associates a user ID with the current user for analytics and user tracking.
Call this method after a user logs in to track their subscription status and user attributes across devices.
## Purpose
Associates a user ID with the current user to enable cross-device tracking and user-specific analytics.
## Signature
```dart
Future identify(String userId, [IdentityOptions? options])
```
## Parameters
| Name | Type | Description | Required |
| ------- | ---------------- | --------------------------------------------- | -------- |
| userId | String | A unique identifier for the user. | yes |
| options | IdentityOptions? | Optional configuration for identity behavior. | no |
## Returns / State
Returns a `Future` that completes when the user identification is finished.
## Usage
Basic identification:
```dart
await Superwall.shared.identify('user_123');
```
After user login:
```dart
Future _onUserLogin(String email, String password) async {
// Authenticate user
final user = await AuthService.login(email, password);
// Identify user to Superwall
await Superwall.shared.identify(user.id);
// Set additional user attributes
await Superwall.setUserAttributes({
'email': user.email,
'plan': user.subscriptionPlan,
'signupDate': user.createdAt.toIso8601String(),
});
}
```
With error handling:
```dart
Future _identifyUser(String userId) async {
try {
await Superwall.shared.identify(userId);
print('User identified successfully');
} catch (e) {
print('Failed to identify user: $e');
}
}
```
---
# setIntegrationAttribute()
Source: https://superwall.com/docs/flutter/sdk-reference/setIntegrationAttribute
Sets a single attribute for third-party integrations.
## Purpose
Syncs a user identifier from an analytics or attribution provider with Superwall. This enables better user tracking and attribution across platforms.
## Signature
```dart
Future setIntegrationAttribute(
IntegrationAttribute attribute,
String? value,
)
```
## Parameters
| Name | Type | Description | Required |
| --------- | -------------------- | --------------------------------------------------------------------------------- | -------- |
| attribute | IntegrationAttribute | The integration attribute key specifying the integration provider. | yes |
| value | String? | The value to associate with the attribute. Pass \`null\` to remove the attribute. | no |
## Returns / State
Returns a `Future` that completes when the attribute is set.
## Usage
Setting an integration attribute:
```dart
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.mixpanelDistinctId,
'user_123',
);
```
Removing an integration attribute:
```dart
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.mixpanelDistinctId,
null,
);
```
Syncing with multiple providers:
```dart
// Mixpanel
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.mixpanelDistinctId,
mixpanelUserId,
);
// Amplitude
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.amplitudeUserId,
amplitudeUserId,
);
// Adjust
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.adjustId,
adjustId,
);
```
## Related
* [`setIntegrationAttributes()`](/flutter/sdk-reference/setIntegrationAttributes) - Set multiple attributes at once
* [`IntegrationAttribute`](/flutter/sdk-reference/IntegrationAttribute) - Available integration attribute types
---
# getCustomerInfo()
Source: https://superwall.com/docs/flutter/sdk-reference/getCustomerInfo
Gets the latest customer information including subscriptions, transactions, and entitlements.
## Purpose
Retrieves the most up-to-date customer information including subscription transactions, non-subscription transactions, entitlements, and user ID. This is useful for displaying subscription status, checking entitlements, or syncing with other services.
## Signature
```dart
Future getCustomerInfo()
```
## Returns / State
Returns a `Future` containing:
* `subscriptions` - List of subscription transactions
* `nonSubscriptions` - List of non-subscription transactions (consumables, non-consumables)
* `entitlements` - List of all entitlements available to the user
* `userId` - The ID of the user
## Usage
Getting customer info:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
print('User ID: ${customerInfo.userId}');
print('Active subscriptions: ${customerInfo.subscriptions.length}');
print('Entitlements: ${customerInfo.entitlements.length}');
```
Checking for specific entitlements:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
final hasPremium = customerInfo.entitlements.any(
(entitlement) => entitlement.id == 'premium' && entitlement.isActive,
);
if (hasPremium) {
print('User has premium access');
}
```
Accessing subscription transactions:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
for (final subscription in customerInfo.subscriptions) {
print('Product: ${subscription.productId}');
print('Active: ${subscription.isActive}');
print('Will renew: ${subscription.willRenew}');
if (subscription.expirationDate != null) {
print('Expires: ${subscription.expirationDate}');
}
}
```
## Related
* [`CustomerInfo`](/flutter/sdk-reference/CustomerInfo) - The customer information class
* [`getEntitlements()`](/flutter/sdk-reference/getEntitlements) - Gets entitlements directly
* [`subscriptionStatus`](/flutter/sdk-reference/subscriptionStatus) - Stream of subscription status changes
---
# getPresentationResult()
Source: https://superwall.com/docs/flutter/sdk-reference/getPresentationResult
Check the outcome of a placement without presenting a paywall.
## Purpose
Retrieves the presentation result for a placement without presenting the paywall. Call this when you need to know whether a placement would show a paywall, send the user to a holdout, or fail due to missing configuration before you decide how to render UI.
## Signature
```dart
Future getPresentationResult(
String placement, {
Map? params,
})
```
## Parameters
| Name | Type | Description | Default | Required |
| --------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| placement | String | The name of the placement to check. | | yes |
| params | Map\? | Optional parameters to pass with the placement. These can be referenced within campaign rules. Keys beginning with \`$\` are reserved for Superwall and will be dropped. Nested maps and lists are currently unsupported and will be ignored. | null | no |
## Returns / State
Returns a `Future` that resolves to one of the following:
* `PlacementNotFoundPresentationResult` - The placement was not found
* `NoAudienceMatchPresentationResult` - No audience match for the placement
* `PaywallPresentationResult` - A paywall would be presented (contains experiment information)
* `HoldoutPresentationResult` - User is in a holdout group (contains experiment information)
* `PaywallNotAvailablePresentationResult` - Paywall is not available
## Usage
Checking if a paywall would be shown:
```dart
final result = await Superwall.shared.getPresentationResult(
'premium_feature',
params: {'source': 'onboarding'},
);
if (result is PaywallPresentationResult) {
print('Paywall would be shown');
print('Experiment ID: ${result.experiment.id}');
print('Group ID: ${result.experiment.groupId}');
} else if (result is HoldoutPresentationResult) {
print('User is in holdout group');
print('Experiment ID: ${result.experiment.id}');
} else if (result is NoAudienceMatchPresentationResult) {
print('No audience match');
} else if (result is PlacementNotFoundPresentationResult) {
print('Placement not found');
} else if (result is PaywallNotAvailablePresentationResult) {
print('Paywall not available');
}
```
Using with switch expressions:
```dart
final result = await Superwall.shared.getPresentationResult('premium_feature');
switch (result) {
case PaywallPresentationResult(experiment: final exp):
print('Paywall would show for experiment ${exp.id}');
case HoldoutPresentationResult(experiment: final exp):
print('User in holdout for experiment ${exp.id}');
case NoAudienceMatchPresentationResult():
print('No audience match');
case PlacementNotFoundPresentationResult():
print('Placement not found');
case PaywallNotAvailablePresentationResult():
print('Paywall not available');
}
```
## Related
* [`registerPlacement()`](/flutter/sdk-reference/register) - Registers and presents a paywall
* [`PresentationResult`](/flutter/sdk-reference/PresentationResult) - The result type returned by this method
---
# setIntegrationAttributes()
Source: https://superwall.com/docs/flutter/sdk-reference/setIntegrationAttributes
Sets multiple attributes for third-party integrations at once.
## Purpose
Syncs multiple user identifiers from analytics and attribution providers with Superwall in a single call. This is more efficient than calling `setIntegrationAttribute()` multiple times.
## Signature
```dart
Future setIntegrationAttributes(
Map attributes,
)
```
## Parameters
| Name | Type | Description | Required |
| ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | -------- |
| attributes | Map\ | A map of integration attribute keys to their values. Pass \`null\` as a value to remove that attribute. | yes |
## Returns / State
Returns a `Future` that completes when all attributes are set.
## Usage
Setting multiple integration attributes:
```dart
await Superwall.shared.setIntegrationAttributes({
IntegrationAttribute.mixpanelDistinctId: 'user_123',
IntegrationAttribute.amplitudeUserId: 'amp_456',
IntegrationAttribute.adjustId: 'adjust_789',
});
```
Setting and removing attributes in one call:
```dart
await Superwall.shared.setIntegrationAttributes({
IntegrationAttribute.mixpanelDistinctId: 'user_123',
IntegrationAttribute.amplitudeUserId: 'amp_456',
IntegrationAttribute.adjustId: null, // Remove this attribute
});
```
Syncing with all analytics providers:
```dart
void _syncAllAnalyticsIds() async {
// Collect IDs from all analytics SDKs
final analyticsIds = {
IntegrationAttribute.mixpanelDistinctId: await _getMixpanelId(),
IntegrationAttribute.amplitudeUserId: await _getAmplitudeId(),
IntegrationAttribute.adjustId: await _getAdjustId(),
IntegrationAttribute.appsflyerId: await _getAppsflyerId(),
};
// Sync all at once
await Superwall.shared.setIntegrationAttributes(analyticsIds);
}
```
## Related
* [`setIntegrationAttribute()`](/flutter/sdk-reference/setIntegrationAttribute) - Set a single integration attribute
* [`IntegrationAttribute`](/flutter/sdk-reference/IntegrationAttribute) - Available integration attribute types
---
# configure()
Source: https://superwall.com/docs/flutter/sdk-reference/configure
A static method that configures the Superwall SDK with your API key.
This method is typically called once in your app's initialization, such as in your `main()` function or during app startup.
## Purpose
Configures the Superwall SDK with your API key and optional configuration settings.
## Signature
```dart Flutter
static Superwall configure(
String apiKey, {
PurchaseController? purchaseController,
SuperwallOptions? options,
Function? completion,
})
```
```swift iOS
static func configure(
apiKey: String,
purchaseController: PurchaseController? = nil,
options: SuperwallOptions? = nil,
completion: ((Result) -> Void)? = nil
)
```
```kotlin Android
fun configure(
application: Application,
apiKey: String,
purchaseController: PurchaseController? = null,
options: SuperwallOptions? = null,
completion: ((Result) -> Unit)? = null
)
```
## Parameters
| Name | Type | Description | Default | Required |
| ------------------ | ------------------- | ------------------------------------------------------ | -------------------------------------- | -------- |
| apiKey | String | Your Superwall API key from the dashboard. | | yes |
| purchaseController | PurchaseController? | Optional custom purchase controller. | \`null\` to use the default controller | no |
| options | SuperwallOptions? | Optional configuration options. | \`null\` for default settings | no |
| completion | Function? | Optional callback called when configuration completes. | | no |
## Returns / State
Returns a `Superwall` instance that is immediately configured and ready to use.
## Usage
Basic configuration:
```dart
import 'package:superwallkit_flutter/superwallkit_flutter.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
Superwall.configure('pk_your_api_key_here');
runApp(MyApp());
}
```
With options:
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
final options = SuperwallOptions(
paywalls: PaywallOptions(
shouldPreload: true,
automaticallyDismiss: false,
),
logging: Logging(
level: LogLevel.debug,
),
);
Superwall.configure(
'pk_your_api_key_here',
options: options,
);
runApp(MyApp());
}
```
With completion callback:
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
Superwall.configure(
'pk_your_api_key_here',
completion: () {
print('Superwall configuration completed');
},
);
runApp(MyApp());
}
```
---
# PresentationResult
Source: https://superwall.com/docs/flutter/sdk-reference/PresentationResult
The result of a paywall presentation attempt.
## Purpose
Represents the possible outcomes when checking or presenting a paywall. Used by [`getPresentationResult()`](/flutter/sdk-reference/getPresentationResult) and paywall presentation handlers.
## Signature
```dart
sealed class PresentationResult {
factory PresentationResult.placementNotFound() = PlacementNotFoundPresentationResult;
factory PresentationResult.noAudienceMatch() = NoAudienceMatchPresentationResult;
factory PresentationResult.paywall(Experiment experiment) = PaywallPresentationResult;
factory PresentationResult.holdout(Experiment experiment) = HoldoutPresentationResult;
factory PresentationResult.paywallNotAvailable() = PaywallNotAvailablePresentationResult;
}
class PlacementNotFoundPresentationResult extends PresentationResult;
class NoAudienceMatchPresentationResult extends PresentationResult;
class PaywallPresentationResult extends PresentationResult {
final Experiment experiment;
}
class HoldoutPresentationResult extends PresentationResult {
final Experiment experiment;
}
class PaywallNotAvailablePresentationResult extends PresentationResult;
```
## Cases
| Name | Type | Description |
| ---- | ---- | ----------- |
## Experiment Information
When a paywall is presented or the user is in a holdout group, the result includes an `Experiment` object:
```dart
class Experiment {
final String id;
final String groupId;
}
```
* `id` - The unique identifier for the experiment
* `groupId` - The identifier for the experiment group the user is in
## Usage
Handling different presentation results:
```dart
final result = await Superwall.shared.getPresentationResult('premium_feature');
if (result is PaywallPresentationResult) {
// Paywall would be shown
final experimentId = result.experiment.id;
final groupId = result.experiment.groupId;
print('Experiment: $experimentId, Group: $groupId');
} else if (result is HoldoutPresentationResult) {
// User is in holdout
print('User in holdout for experiment ${result.experiment.id}');
} else if (result is NoAudienceMatchPresentationResult) {
// No audience match
print('No audience match for placement');
} else if (result is PlacementNotFoundPresentationResult) {
// Placement not found
print('Placement not found');
} else if (result is PaywallNotAvailablePresentationResult) {
// Paywall not available
print('Paywall not available');
}
```
Using pattern matching:
```dart
final result = await Superwall.shared.getPresentationResult('premium_feature');
switch (result) {
case PaywallPresentationResult(experiment: final exp):
// Handle paywall presentation
print('Paywall for experiment ${exp.id}');
case HoldoutPresentationResult(experiment: final exp):
// Handle holdout
print('Holdout for experiment ${exp.id}');
case NoAudienceMatchPresentationResult():
// Handle no match
print('No audience match');
case PlacementNotFoundPresentationResult():
// Handle not found
print('Placement not found');
case PaywallNotAvailablePresentationResult():
// Handle not available
print('Paywall not available');
}
```
## Related
* [`getPresentationResult()`](/flutter/sdk-reference/getPresentationResult) - Gets presentation result without showing paywall
* [`registerPlacement()`](/flutter/sdk-reference/register) - Registers and presents a paywall
* [`PaywallPresentationHandler`](/flutter/sdk-reference/PaywallPresentationHandler) - Handles paywall presentation lifecycle
---
# PaywallPresentationHandler
Source: https://superwall.com/docs/flutter/sdk-reference/PaywallPresentationHandler
A handler class that provides status updates for paywall presentation in registerPlacement() calls.
Use this handler when you need fine-grained control over paywall events for a specific [`registerPlacement()`](/flutter/sdk-reference/registerPlacement) call, rather than global events via [`SuperwallDelegate`](/flutter/sdk-reference/SuperwallDelegate).
This handler is specific to the individual `registerPlacement()` call. For global paywall events across your app, use [`SuperwallDelegate`](/flutter/sdk-reference/SuperwallDelegate) instead.
## Purpose
Provides callbacks for paywall lifecycle events when using [`registerPlacement()`](/flutter/sdk-reference/registerPlacement) with a specific handler instance.
## Signature
```dart
class PaywallPresentationHandler {
void onPresent(Function(PaywallInfo) handler);
void onDismiss(Function(PaywallInfo, PaywallResult) handler);
void onSkip(Function(PaywallSkippedReason) handler);
void onError(Function(String) handler);
}
```
## Parameters
| Name | Type | Description | Required |
| --------- | --------------------------------------------- | --------------------------------------------------------------- | -------- |
| onPresent | handler: (PaywallInfo) -> void | Sets a handler called when the paywall is presented. | yes |
| onDismiss | handler: (PaywallInfo, PaywallResult) -> void | Sets a handler called when the paywall is dismissed. | yes |
| onSkip | handler: (PaywallSkippedReason) -> void | Sets a handler called when paywall presentation is skipped. | yes |
| onError | handler: (String) -> void | Sets a handler called when an error occurs during presentation. | yes |
## Returns / State
Each method returns `void` and configures the handler for the specific paywall lifecycle event.
## Usage
Basic handler setup:
```dart
Future _registerFeatureWithHandler() async {
final handler = PaywallPresentationHandler();
handler.onPresent((paywallInfo) {
print('Paywall presented: ${paywallInfo.identifier}');
// Pause background tasks, analytics, etc.
});
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();
},
);
}
```
Handle skip and error cases:
```dart
Future _setupComprehensiveHandler() async {
final handler = PaywallPresentationHandler();
handler.onSkip((reason) {
print('Paywall skipped: $reason');
switch (reason) {
case PaywallSkippedReason.userIsSubscribed:
_proceedToFeature();
break;
case PaywallSkippedReason.holdout:
_proceedToFeature();
break;
default:
break;
}
});
handler.onError((error) {
print('Paywall error: $error');
_showErrorDialog(error);
});
await Superwall.shared.registerPlacement(
'remove_ads',
handler: handler,
feature: () {
_hideAdsFromUI();
},
);
}
```
Reusable handler class:
```dart
class ReusablePaywallHandler {
static PaywallPresentationHandler create({
VoidCallback? onSuccess,
VoidCallback? onCancel,
}) {
final handler = PaywallPresentationHandler();
handler.onPresent((_) {
// Analytics tracking
Analytics.track('paywall_presented');
});
handler.onDismiss((_, result) {
switch (result) {
case PaywallResult.purchased:
onSuccess?.call();
break;
case PaywallResult.cancelled:
onCancel?.call();
break;
default:
break;
}
});
return handler;
}
}
// Usage
final handler = ReusablePaywallHandler.create(
onSuccess: () => Navigator.pushNamed(context, '/premium'),
onCancel: () => _showRetentionOffer(),
);
```
---
# handleDeepLink()
Source: https://superwall.com/docs/flutter/sdk-reference/handleDeepLink
Processes deep links to trigger paywall previews and handle Superwall URLs.
This method is used to handle deep links that can trigger paywall previews or other Superwall functionality. It's commonly used for testing paywalls during development.
## Purpose
Processes deep links to handle Superwall-specific URLs for paywall previews and testing.
## Signature
```dart
Future handleDeepLink(Uri url)
```
## Parameters
| Name | Type | Description | Required |
| ---- | ---- | ----------------------------- | -------- |
| url | Uri | The deep link URL to process. | yes |
## Returns / State
Returns a `Future` indicating whether the URL was handled by Superwall (`true`) or should be processed by your app (`false`).
## Usage
Basic deep link handling:
```dart
Future _handleIncomingLink(String link) async {
final uri = Uri.parse(link);
// Let Superwall handle the link first
final handled = await Superwall.shared.handleDeepLink(uri);
if (!handled) {
// Handle non-Superwall deep links
_handleAppDeepLink(uri);
}
}
```
With error handling:
```dart
Future _safeHandleDeepLink(String linkString) async {
try {
final uri = Uri.parse(linkString);
final handled = await Superwall.shared.handleDeepLink(uri);
if (!handled) {
_routeToAppScreen(uri);
}
} catch (e) {
print('Error handling deep link: $e');
}
}
```
---
# CustomerInfo
Source: https://superwall.com/docs/flutter/sdk-reference/CustomerInfo
Contains the latest subscription and entitlement information about the customer.
## Purpose
Represents the complete customer information including all subscription transactions, non-subscription transactions, entitlements, and user identification.
## Signature
```dart
class CustomerInfo {
final List subscriptions;
final List nonSubscriptions;
final List entitlements;
final String userId;
}
```
## Properties
| Name | Type | Description | Required |
| ---------------- | --------------------------------- | -------------------------------------------------------------------------------------- | -------- |
| subscriptions | List\ | All subscription transactions the user has made. | yes |
| nonSubscriptions | List\ | All non-subscription transactions (consumables and non-consumables) the user has made. | yes |
| entitlements | List\ | All entitlements available to the user. | yes |
| userId | String | The ID of the user. | yes |
## Usage
Getting customer info:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
// Access user ID
print('User ID: ${customerInfo.userId}');
// Check entitlements
final activeEntitlements = customerInfo.entitlements
.where((e) => e.isActive)
.toList();
// Access subscriptions
for (final subscription in customerInfo.subscriptions) {
if (subscription.isActive) {
print('Active subscription: ${subscription.productId}');
}
}
```
Checking for specific entitlements:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
final hasPremium = customerInfo.entitlements.any(
(entitlement) =>
entitlement.id == 'premium' &&
entitlement.isActive,
);
if (hasPremium) {
// User has premium access
showPremiumContent();
}
```
Filtering active subscriptions:
```dart
final customerInfo = await Superwall.shared.getCustomerInfo();
final activeSubscriptions = customerInfo.subscriptions
.where((sub) => sub.isActive && !sub.isRevoked)
.toList();
print('User has ${activeSubscriptions.length} active subscriptions');
```
## Related
* [`getCustomerInfo()`](/flutter/sdk-reference/getCustomerInfo) - Method to retrieve customer info
* [`SubscriptionTransaction`](/flutter/sdk-reference/SubscriptionTransaction) - Subscription transaction details
* [`NonSubscriptionTransaction`](/flutter/sdk-reference/NonSubscriptionTransaction) - Non-subscription transaction details
* [`Entitlement`](/flutter/sdk-reference/Entitlement) - Entitlement information
---
# SuperwallDelegate
Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallDelegate
An abstract class that receives global SDK events for analytics and lifecycle management.
Use this delegate for global events across your entire app. For events specific to individual [`registerPlacement()`](/flutter/sdk-reference/registerPlacement) calls, use [`PaywallPresentationHandler`](/flutter/sdk-reference/PaywallPresentationHandler) instead.
## Purpose
Receives global SDK events including paywall lifecycle, subscription changes, and custom actions.
## Signature
```dart
abstract class SuperwallDelegate {
void subscriptionStatusDidChange(SubscriptionStatus newValue);
void handleSuperwallEvent(SuperwallEventInfo eventInfo);
void handleCustomPaywallAction(String name);
void willDismissPaywall(PaywallInfo paywallInfo);
void willPresentPaywall(PaywallInfo paywallInfo);
void didDismissPaywall(PaywallInfo paywallInfo);
void didPresentPaywall(PaywallInfo paywallInfo);
void paywallWillOpenURL(Uri url);
void paywallWillOpenDeepLink(Uri url);
void handleSuperwallDeepLink(Uri fullURL, List pathComponents, Map queryParameters);
void customerInfoDidChange(CustomerInfo from, CustomerInfo to);
void userAttributesDidChange(Map newAttributes);
}
```
## Implementation
Extend the abstract class and implement the methods you need:
```dart
class MySuperwallDelegate extends SuperwallDelegate {
@override
void subscriptionStatusDidChange(SubscriptionStatus newValue) {
print('Subscription status changed to: $newValue');
// Update user interface, send analytics, etc.
}
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) {
print('Superwall event: ${eventInfo.event}');
// Send to your analytics platform
Analytics.track(eventInfo.event.rawName, eventInfo.params);
}
@override
void willPresentPaywall(PaywallInfo paywallInfo) {
print('About to present paywall: ${paywallInfo.identifier}');
// Pause video, hide overlays, etc.
}
@override
void didDismissPaywall(PaywallInfo paywallInfo) {
print('Paywall dismissed: ${paywallInfo.identifier}');
// Resume video, show overlays, etc.
}
@override
void handleCustomPaywallAction(String name) {
print('Custom action triggered: $name');
switch (name) {
case 'contact_support':
_openSupportChat();
break;
case 'share_app':
_shareApp();
break;
}
}
@override
void handleSuperwallDeepLink(Uri fullURL, List pathComponents, Map queryParameters) {
print('Superwall deep link: $fullURL');
print('Path: $pathComponents');
print('Query: $queryParameters');
// Handle deep link navigation
}
@override
void customerInfoDidChange(CustomerInfo from, CustomerInfo to) {
print('Customer info changed');
// Sync with your backend, update UI, etc.
}
@override
void userAttributesDidChange(Map newAttributes) {
print('User attributes updated: $newAttributes');
// Sync with analytics or update in-memory state.
}
}
```
## Usage
Set up the delegate:
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Superwall.configure('pk_your_api_key');
// Set the delegate
Superwall.shared.setDelegate(MySuperwallDelegate());
runApp(MyApp());
}
```
Minimal delegate implementation:
```dart
class MinimalDelegate extends SuperwallDelegate {
@override
void subscriptionStatusDidChange(SubscriptionStatus newValue) {
// Required: Handle subscription status changes
}
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) {
// Required: Handle SDK events
}
// All other methods have default implementations
}
```
---
# setUserAttributes()
Source: https://superwall.com/docs/flutter/sdk-reference/setUserAttributes
Sets custom attributes for the current user that can be used in campaign targeting.
User attributes are key-value pairs that help you target campaigns to specific user segments. They're also sent with events for analytics.
## Purpose
Sets custom attributes for the current user that can be used for campaign targeting and analytics.
## Signature
```dart
Future setUserAttributes(Map userAttributes)
```
## Parameters
| Name | Type | Description | Required |
| -------------- | -------------------- | ------------------------------------------------------------------------------------ | -------- |
| userAttributes | Map\ | A map of user attributes to set. Values can be strings, numbers, booleans, or dates. | yes |
## Returns / State
Returns a `Future` that completes when the user attributes are set.
If you have a [`SuperwallDelegate`](/flutter/sdk-reference/SuperwallDelegate) set, `userAttributesDidChange` is invoked after the SDK applies the updated attributes.
## Usage
Basic usage:
```dart
await Superwall.shared.setUserAttributes({
'plan': 'premium',
'age': 25,
'hasCompletedOnboarding': true,
});
```
After user signup:
```dart
Future _setUserProfile(User user) async {
await Superwall.shared.setUserAttributes({
'email': user.email,
'name': user.name,
'signupDate': user.createdAt.toIso8601String(),
'referralSource': user.referralSource ?? 'direct',
'trialEndDate': user.trialEndDate?.toIso8601String(),
'isFirstTimeUser': user.isFirstTimeUser,
});
}
```
Updating subscription info:
```dart
Future _updateSubscriptionAttributes(Subscription subscription) async {
await Superwall.shared.setUserAttributes({
'subscriptionTier': subscription.tier,
'subscriptionStartDate': subscription.startDate.toIso8601String(),
'subscriptionStatus': subscription.status,
'monthlySpend': subscription.monthlyAmount,
});
}
```
With error handling:
```dart
Future _safeSetUserAttributes(Map attributes) async {
try {
await Superwall.shared.setUserAttributes(attributes);
print('User attributes updated successfully');
} catch (e) {
print('Failed to set user attributes: $e');
}
}
```
---
# SuperwallOptions
Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallOptions
Configuration options for customizing Superwall SDK behavior.
## Purpose
Configures various aspects of the Superwall SDK including paywall behavior, logging, and network settings.
## Signature
```dart
class SuperwallOptions {
PaywallOptions paywalls = PaywallOptions();
NetworkEnvironment networkEnvironment = NetworkEnvironment.release;
bool isExternalDataCollectionEnabled = true;
String? localeIdentifier;
bool isGameControllerEnabled = false;
Logging logging = Logging();
bool passIdentifiersToPlayStore = false;
}
```
## Parameters
| Name | Type | Description | Default | Required |
| ------------------------------- | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- | -------- |
| paywalls | PaywallOptions (see /flutter/sdk-reference/PaywallOptions) | Configuration for paywall presentation behavior. | | yes |
| networkEnvironment | NetworkEnvironment | Network environment for API calls (release/releaseCandidate/developer). Only change when instructed by Superwall. | | yes |
| isExternalDataCollectionEnabled | bool | Enables external analytics collection. | true | no |
| localeIdentifier | String? | Override locale for paywall localization. | device locale | no |
| isGameControllerEnabled | bool | Enables game controller support. | false | no |
| logging | Logging | Configuration for SDK logging levels and behavior. | | yes |
| passIdentifiersToPlayStore | bool | When \`true\`, Android builds send the plain \`appUserId\` to Google Play as \`obfuscatedExternalAccountId\`. | false | no |
## Android-only: `passIdentifiersToPlayStore`
Flutter apps can target both iOS and Android. Google Play always consumes the identifier you send through `BillingFlowParams.Builder.setObfuscatedAccountId`, which the SDK sources from `Superwall.instance.externalAccountId`.
* When `passIdentifiersToPlayStore` is **`false`** (default) we SHA-256 hash your `userId` before sending it. Play Console and the Superwall backend will show the hashed value.
* When it is **`true`**, we pass the exact `appUserId` you supplied to `Superwall.shared.identify`. This only changes behavior on Android—the flag is ignored on iOS builds.
Set the option at configuration time when you specifically need the un-hashed identifier:
```dart
final options = SuperwallOptions()
..passIdentifiersToPlayStore = true;
await Superwall.configure(
apiKey,
options: options,
);
```
Make sure the identifier complies with [Google's policy](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId) and never contains personally identifiable information.
## Usage
Basic options:
```dart
final options = SuperwallOptions()
..paywalls = PaywallOptions()
..logging = (Logging()..level = LogLevel.debug);
await Superwall.configure(
'pk_your_api_key',
options: options,
);
```
Production configuration:
```dart
final productionOptions = SuperwallOptions()
..paywalls = (PaywallOptions()
..shouldPreload = true
..automaticallyDismiss = true)
..networkEnvironment = NetworkEnvironment.release
..isExternalDataCollectionEnabled = true
..logging = (Logging()..level = LogLevel.warn);
```
Development configuration (with Play Store IDs on Android):
```dart
final developmentOptions = SuperwallOptions()
..paywalls = (PaywallOptions()
..shouldPreload = false
..automaticallyDismiss = false)
..networkEnvironment = NetworkEnvironment.developer
..logging = (Logging()
..level = LogLevel.debug
..scopes = {LogScope.all})
..passIdentifiersToPlayStore = true; // Android only
```
Custom locale:
```dart
final localizedOptions = SuperwallOptions()
..localeIdentifier = 'es_ES' // Spanish (Spain)
..paywalls = (PaywallOptions()..shouldPreload = true);
```
## Related
* [`PaywallOptions`](/flutter/sdk-reference/PaywallOptions)
---
# IntegrationAttribute
Source: https://superwall.com/docs/flutter/sdk-reference/IntegrationAttribute
Attributes for third-party integrations with Superwall.
## Purpose
Enumeration of integration attributes that allow you to sync user identifiers from your analytics and attribution providers with Superwall. This enables better user tracking and attribution across platforms.
## Signature
```dart
enum IntegrationAttribute {
adjustId,
amplitudeDeviceId,
amplitudeUserId,
appsflyerId,
brazeAliasName,
brazeAliasLabel,
onesignalId,
fbAnonId,
firebaseAppInstanceId,
iterableUserId,
iterableCampaignId,
iterableTemplateId,
mixpanelDistinctId,
mparticleId,
clevertapId,
airshipChannelId,
kochavaDeviceId,
tenjinId,
posthogUserId,
customerioId;
}
```
## Values
| Name | Type | Description |
| ---- | ---- | ----------- |
## Usage
Setting a single integration attribute:
```dart
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.mixpanelDistinctId,
'user_123',
);
```
Setting multiple integration attributes:
```dart
await Superwall.shared.setIntegrationAttributes({
IntegrationAttribute.mixpanelDistinctId: 'user_123',
IntegrationAttribute.amplitudeUserId: 'amp_456',
IntegrationAttribute.adjustId: 'adjust_789',
});
```
Removing an integration attribute:
```dart
// Set to null to remove
await Superwall.shared.setIntegrationAttribute(
IntegrationAttribute.mixpanelDistinctId,
null,
);
```
Syncing with analytics providers:
```dart
void _syncAnalyticsIds() async {
// Get IDs from your analytics SDKs
final mixpanelId = await MixpanelSDK.getDistinctId();
final amplitudeId = await AmplitudeSDK.getUserId();
// Sync with Superwall
await Superwall.shared.setIntegrationAttributes({
IntegrationAttribute.mixpanelDistinctId: mixpanelId,
IntegrationAttribute.amplitudeUserId: amplitudeId,
});
}
```
## Related
* [`setIntegrationAttribute()`](/flutter/sdk-reference/setIntegrationAttribute) - Set a single integration attribute
* [`setIntegrationAttributes()`](/flutter/sdk-reference/setIntegrationAttributes) - Set multiple integration attributes at once
---
# Overview
Source: https://superwall.com/docs/flutter/sdk-reference
Reference documentation for the Superwall Flutter SDK.
## Welcome to the Superwall Flutter SDK Reference
You can find the source code for the SDK [on GitHub](https://github.com/superwall/Superwall-Flutter) along with our [example app](https://github.com/superwall/Superwall-Flutter/tree/main/example).
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-flutter/issues).
---
# Tracking Subscription State
Source: https://superwall.com/docs/flutter/quickstart/tracking-subscription-state
Here's how to view whether or not a user is on a paid plan in Flutter.
Superwall tracks the subscription state of a user for you. However, there are times in your app where you need to know if a user is on a paid plan or not. For example, you might want to conditionally show certain UI elements or enable premium features based on their subscription status.
## Using subscriptionStatus stream
The easiest way to track subscription status in Flutter is by listening to the `subscriptionStatus` stream:
```dart
class _MyAppState extends State {
StreamSubscription? _subscription;
SubscriptionStatus _currentStatus = SubscriptionStatus.unknown;
@override
void initState() {
super.initState();
_subscription = Superwall.shared.subscriptionStatus.listen((status) {
setState(() {
_currentStatus = status;
});
switch (status) {
case SubscriptionStatus.active:
print('User has active subscription');
_showPremiumContent();
break;
case SubscriptionStatus.inactive:
print('User is on free plan');
_showFreeContent();
break;
case SubscriptionStatus.unknown:
print('Subscription status unknown');
_showLoadingState();
break;
}
});
}
@override
void dispose() {
_subscription?.cancel();
super.dispose();
}
}
```
The `SubscriptionStatus` enum has three possible values:
* `SubscriptionStatus.unknown` - Status is not yet determined
* `SubscriptionStatus.active` - User has an active subscription
* `SubscriptionStatus.inactive` - User has no active subscription
Use the `isActive` convenience property when you only need to know if the user is subscribed:
```dart
Superwall.shared.subscriptionStatus.listen((status) {
if (status.isActive) {
_showPremiumContent();
} else {
_showFreeContent();
}
});
```
## Using SuperwallBuilder widget
For reactive UI updates based on subscription status, use the `SuperwallBuilder` widget:
```dart
SuperwallBuilder(
builder: (context, subscriptionStatus) {
switch (subscriptionStatus) {
case SubscriptionStatus.active:
return PremiumContent();
case SubscriptionStatus.inactive:
return FreeContent();
default:
return LoadingIndicator();
}
},
)
```
This widget automatically rebuilds whenever the subscription status changes, making it perfect for conditionally rendering UI:
```dart
class SubscriptionStatusDisplay extends StatelessWidget {
@override
Widget build(BuildContext context) {
return SuperwallBuilder(
builder: (context, status) => Center(
child: Text('Subscription Status: $status'),
),
);
}
}
```
## Using StreamBuilder
You can also use Flutter's `StreamBuilder` for more control over the stream subscription:
```dart
class PremiumFeatureButton extends StatelessWidget {
@override
Widget build(BuildContext context) {
return StreamBuilder(
stream: Superwall.shared.subscriptionStatus,
builder: (context, snapshot) {
final status = snapshot.data ?? SubscriptionStatus.unknown;
final isActive = status.isActive;
return ElevatedButton(
onPressed: isActive
? _accessPremiumFeature
: _showPaywall,
child: Text(
isActive
? 'Access Premium Feature'
: 'Upgrade to Premium',
),
);
},
);
}
void _accessPremiumFeature() {
// Access premium feature
}
void _showPaywall() {
Superwall.shared.registerPlacement('premium_feature');
}
}
```
## Checking subscription status programmatically
If you need to check the subscription status at a specific moment without listening to the stream:
```dart
Future checkSubscription() async {
// Note: You'll need to get the current value from the stream
final subscription = Superwall.shared.subscriptionStatus.listen((status) {
if (status.isActive) {
// User is subscribed
enablePremiumFeatures();
} else {
// User is not subscribed
showUpgradePrompt();
}
});
// Remember to cancel when done
subscription.cancel();
}
```
## Setting subscription status
When using Superwall with a custom purchase controller or third-party billing service, you need to manually update the subscription status. Here's how to sync with RevenueCat:
```dart
class RCPurchaseController extends PurchaseController {
Future syncSubscriptionStatus() async {
try {
final customerInfo = await Purchases.getCustomerInfo();
final hasActiveSubscription = customerInfo.entitlements.active.isNotEmpty;
if (hasActiveSubscription) {
final entitlements = customerInfo.entitlements.active.keys
.map((id) => Entitlement(id: id))
.toSet();
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusActive(entitlements: entitlements)
);
} else {
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusInactive()
);
}
} catch (e) {
print('Failed to sync subscription status: $e');
}
}
@override
Future purchaseFromAppStore(String productId) async {
try {
final result = await Purchases.purchaseProduct(productId);
if (result.isSuccess) {
// Sync status after successful purchase
await syncSubscriptionStatus();
return PurchaseResult.purchased;
}
return PurchaseResult.failed;
} catch (e) {
return PurchaseResult.failed;
}
}
}
```
You can also listen for subscription changes from your payment service:
```dart
void setupSubscriptionListener() {
myPaymentService.addSubscriptionStatusListener((subscriptionInfo) {
final entitlements = subscriptionInfo.entitlements.active.keys
.map((id) => Entitlement(id: id))
.toSet();
final hasActiveSubscription = subscriptionInfo.isActive;
if (hasActiveSubscription) {
Superwall.shared.setSubscriptionStatus(
SubscriptionStatusActive(entitlements: entitlements)
);
} else {
Superwall.shared.setSubscriptionStatus(
SubscriptionStatusInactive()
);
}
});
}
```
## Using SuperwallDelegate
You can also listen for subscription status changes using the `SuperwallDelegate`:
```dart
class _MyAppState extends State implements SuperwallDelegate {
@override
void initState() {
super.initState();
// Set delegate
Superwall.shared.setDelegate(this);
}
@override
void subscriptionStatusDidChange(SubscriptionStatus newValue) {
print('Subscription status changed to: $newValue');
switch (newValue) {
case SubscriptionStatus.active:
print('User is now premium');
_handlePremiumUser();
break;
case SubscriptionStatus.inactive:
print('User is now free');
_handleFreeUser();
break;
case SubscriptionStatus.unknown:
print('Status unknown');
break;
}
}
void _handlePremiumUser() {
// Update UI or app state for premium user
}
void _handleFreeUser() {
// Update UI or app state for free user
}
}
```
## Handling subscription expiry
If you need to check for subscription expiry manually:
```dart
Future checkSubscriptionExpiry() async {
final expiryDate = await MyPaymentService.getSubscriptionExpiry();
if (expiryDate.isBefore(DateTime.now())) {
// Subscription has expired
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusInactive()
);
// Show renewal prompt
_showRenewalPrompt();
}
}
```
## Superwall checks subscription status for you
Remember that the Superwall SDK uses its [audience filters](/campaigns-audience#matching-to-entitlements) for determining when to show paywalls. You generally don't need to wrap your calls to register placements with subscription status checks:
```dart
// ❌ Unnecessary
final subscription = Superwall.shared.subscriptionStatus.listen((status) {
if (status != SubscriptionStatus.active) {
Superwall.shared.registerPlacement('campaign_trigger');
}
});
// ✅ Just register the placement
Superwall.shared.registerPlacement('campaign_trigger');
```
In your [audience filters](/campaigns-audience#matching-to-entitlements), you can specify whether the subscription state should be considered, which keeps your codebase cleaner and puts the "Should this paywall show?" logic where it belongs—in the Superwall dashboard.
---
# Setting User Attributes
Source: https://superwall.com/docs/flutter/quickstart/setting-user-properties
undefined
By setting user attributes, you can display information about the user on the paywall. You can also define [audiences](/campaigns-audience) in a campaign to determine which paywall to show to a user, based on their user attributes.
If a paywall uses the **Set user attributes** action, the merged attributes are sent back to your app via `SuperwallDelegate.userAttributesDidChange(newAttributes:)`.
You do this by passing a `[String: Any?]` dictionary of attributes to `Superwall.shared.setUserAttributes(_:)`:
:::flutter
```dart Flutter
Map attributes = {
"name": user.name,
"apnsToken": user.apnsTokenString,
"email": user.email,
"username": user.username,
"profilePic": user.profilePicUrl,
"stripe_customer_id": user.stripeCustomerId, // Optional: For Stripe checkout prefilling
};
Superwall.shared.setUserAttributes(attributes); // (merges existing attributes)
```
:::
## Usage
This is a merge operation, such that if the existing user attributes dictionary
already has a value for a given property, the old value is overwritten. Other
existing properties will not be affected. To unset/delete a value, you can pass `nil`
for the value.
You can reference user attributes in [audience filters](/campaigns-audience) to help decide when to display your paywall. When you configure your paywall, you can also reference the user attributes in its text variables. For more information on how to that, see [Configuring a Paywall](/paywall-editor-overview).
---
# Presenting Paywalls
Source: https://superwall.com/docs/flutter/quickstart/feature-gating
Control access to premium features with Superwall placements.
This allows you to register a [placement](/campaigns-placements) to access a feature that may or may not be paywalled later in time. It also allows you to choose whether the user can access the feature even if they don't make a purchase.
Here's an example.
#### With Superwall
:::flutter
```dart Flutter
void pressedWorkoutButton() {
// remotely decide if a paywall is shown and if
// navigation.startWorkout() is a paid-only feature
Superwall.shared.registerPlacement('StartWorkout', feature: () {
navigation.startWorkout();
});
}
```
:::
#### Without Superwall
:::flutter
```dart Flutter
void pressedWorkoutButton() {
if (user.hasActiveSubscription) {
navigation.startWorkout();
} else {
navigation.presentPaywall().then((result) {
if (result) {
navigation.startWorkout();
} else {
// user didn't pay, developer decides what to do
}
});
}
}
```
:::
### How registering placements presents paywalls
You can configure `"StartWorkout"` to present a paywall by [creating a campaign, adding the placement, and adding a paywall to an audience](/campaigns) in the dashboard.
1. The SDK retrieves your campaign settings from the dashboard on app launch.
2. When a placement is called that belongs to a campaign, audiences are evaluated ***on device*** and the user enters an experiment — this means there's no delay between registering a placement and presenting a paywall.
3. If it's the first time a user is entering an experiment, a paywall is decided for the user based on the percentages you set in the dashboard
4. Once a user is assigned a paywall for an audience, they will continue to see that paywall until you remove the paywall from the audience or reset assignments to the paywall.
5. After the paywall is closed, the Superwall SDK looks at the *Feature Gating* value associated with your paywall, configurable from the paywall editor under General > Feature Gating (more on this below)
1. If the paywall is set to ***Non Gated***, the `feature:` closure on `register(placement: ...)` gets called when the paywall is dismissed (whether they paid or not)
2. If the paywall is set to ***Gated***, the `feature:` closure on `register(placement: ...)` gets called only if the user is already paying or if they begin paying.
6. If no paywall is configured, the feature gets executed immediately without any additional network calls.
Given the low cost nature of how register works, we strongly recommend registering **all core functionality** in order to remotely configure which features you want to gate – **without an app update**.
:::flutter
```dart Flutter
// on the welcome screen
void pressedSignUp() {
Superwall.shared.registerPlacement("SignUp", feature: () {
navigation.beginOnboarding();
});
}
// In another view controller
void pressedWorkoutButton() {
Superwall.shared.registerPlacement("StartWorkout", feature: () {
navigation.startWorkout();
});
}
```
:::
### Automatically Registered Placements
The SDK [automatically registers](/tracking-analytics) some internal placements which can be used to present paywalls:
### Register. Everything.
To provide your team with ultimate flexibility, we recommend registering *all* of your analytics events, even if you don't pass feature blocks through. This way you can retroactively add a paywall almost anywhere – **without an app update**!
If you're already set up with an analytics provider, you'll typically have an `Analytics.swift` singleton (or similar) to disperse all your events from. Here's how that file might look:
### Getting a presentation result
Use `getPresentationResult(forPlacement:params:)` when you need to ask the SDK what would happen when registering a placement — without actually showing a paywall. Superwall evaluates the placement and its audience filters then returns a `PresentationResult`. You can use this to adapt your app's behavior based on the outcome (such as showing a lock icon next to a pro feature if they aren't subscribed).
In short, this lets you peek at the outcome first and decide how your app should respond:
---
# Configure the SDK
Source: https://superwall.com/docs/flutter/quickstart/configure
undefined
As soon as your app launches, you need to configure the SDK with your **Public API Key**. You'll retrieve this from the Superwall settings page.
### Sign Up & Grab Keys
If you haven't already, [sign up for a free account](https://superwall.com/sign-up) on Superwall. Then, when you're through to the Dashboard, click **Settings** from the panel on the left, click **Keys** and copy your **Public API Key**:
### Initialize Superwall in your app
Begin by editing your main Application entrypoint. Depending on the
platform this could be `AppDelegate.swift` or `SceneDelegate.swift` for iOS,
`MainApplication.kt` for Android, `main.dart` in Flutter, or `App.tsx` for React Native:
:::flutter
```dart Flutter
// main.dart
void initState() {
// Determine Superwall API Key for platform
String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";
Superwall.configure(apiKey);
}
```
:::
This configures a shared instance of `Superwall`, the primary class for interacting with the SDK's API. Make sure to replace `MY_API_KEY` with your public API key that you just retrieved.
By default, Superwall handles basic subscription-related logic for you. However, if you’d like
greater control over this process (e.g. if you’re using RevenueCat), you’ll want to pass in a
`PurchaseController` to your configuration call and manually set the `subscriptionStatus`. You can
also pass in `SuperwallOptions` to customize the appearance and behavior of the SDK. See
[Purchases and Subscription Status](/advanced-configuration) for more.
You've now configured Superwall!
:::flutter
For further help, check out our [Flutter example apps](https://github.com/superwall/Superwall-Flutter/tree/master/example) for working examples of implementing the Superwall SDK.
:::
---
# User Management
Source: https://superwall.com/docs/flutter/quickstart/user-management
undefined
### Anonymous Users
Superwall automatically generates a random user ID that persists internally until the user deletes/reinstalls your app.
You can call `Superwall.shared.reset()` to reset this ID and clear any paywall assignments.
### Identified Users
If you use your own user management system, call `identify(userId:options:)` when you have a user's identity. This will alias your `userId` with the anonymous Superwall ID enabling us to load the user’s assigned paywalls.
Calling `Superwall.shared.reset()` will reset the on-device userId to a random ID and clear the paywall assignments.
:::flutter
When you ship the Flutter SDK on Android, you must explicitly set `options.passIdentifiersToPlayStore = true` (for example, `final options = SuperwallOptions()..passIdentifiersToPlayStore = true;`) if you need the un-hashed `appUserId` to flow through Google Play's **`obfuscatedExternalAccountId`** field. This flag has no effect on iOS builds. Follow [Google's rules](https://developer.android.com/reference/com/android/billingclient/api/BillingFlowParams.Builder#setObfuscatedAccountId) so the value is not rejected.
:::
:::flutter
```dart Flutter
// After retrieving a user's ID, e.g. from logging in or creating an account
Superwall.shared.identify(user.id);
// When the user signs out
Superwall.shared.reset();
```
:::
**Advanced Use Case**
You can supply an `IdentityOptions` object, whose property `restorePaywallAssignments` you can set to `true`. This tells the SDK to wait to restore paywall assignments from the server before presenting any paywalls. This should only be used in advanced use cases. If you expect users of your app to switch accounts or delete/reinstall a lot, you'd set this when users log in to an existing account.
### Best Practices for a Unique User ID
* Do NOT make your User IDs guessable – they are public facing.
* Do NOT set emails as User IDs – this isn't GDPR compliant.
* Do NOT set IDFA or DeviceIds as User IDs – these are device specific / easily rotated by the operating system.
* Do NOT hardcode strings as User IDs – this will cause every user to be treated as the same user by Superwall.
### Identifying users from App Store server events
On iOS, Superwall always supplies an [`appAccountToken`](https://developer.apple.com/documentation/storekit/product/purchaseoption/3749440-appaccounttoken) with every StoreKit 2 transaction:
| Scenario | Value used for `appAccountToken` |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| You’ve called `Superwall.shared.identify(userId:)` | The exact `userId` you passed |
| You *haven’t* called `identify` yet | The UUID automatically generated for the anonymous user (the **alias ID**), **without** the `$SuperwallAlias:` prefix |
| You passed a non‑UUID `userId` to `identify` | StoreKit rejects it; Superwall falls back to the alias UUID |
Because the SDK falls back to the alias UUID, purchase notifications sent to your server always include a stable, unique identifier—even before the user signs in.
:::flutter
On iOS, `appAccountToken` must be a UUID to be accepted by StoreKit.
If the `userId` you pass to `identify` is not a valid UUID string, StoreKit will not accept it for `appAccountToken` and the SDK will fall back to the anonymous alias UUID. This can cause the identifier in App Store Server Notifications to differ from the `userId` you passed. See Apple's docs: [appAccountToken](https://developer.apple.com/documentation/appstoreserverapi/appaccounttoken).
:::
```swift
// Generate and use a UUID user ID in Swift
let userId = UUID().uuidString
Superwall.shared.identify(userId: userId)
```
---
# Install the SDK
Source: https://superwall.com/docs/flutter/quickstart/install
Install the Superwall Flutter SDK via pub package manager.
## Overview
To see the latest release, [check out the repository](https://github.com/superwall/Superwall-Flutter).
## Install via pubspec.yaml
To use Superwall in your Flutter project, add `superwallkit_flutter` as a dependency in your `pubspec.yaml` file:
```yaml
dependencies:
superwallkit_flutter: ^2.0.5
```
After adding the dependency, run `dart pub get` in your terminal to fetch the package.
## Install via Command Line (Alternative)
You can also add the dependency directly from your terminal using the following command:
```bash
$ flutter pub add superwallkit_flutter
```
### iOS Deployment Target
Superwall requires iOS 14.0 or higher. Ensure your Flutter project's iOS deployment target is 14.0 or higher by updating ios/Podfile.
```ruby
platform :ios, '14.0'
```
### Android Configuration
First, add our SuperwallActivity to your `AndroidManifest.xml`:
```xml
```
Superwall requires a minimum SDK version of 26 or higher and a minimum compile SDK target of 34. Ensure your Flutter project's Android minimal SDK target is set to 26 or higher and that your compilation SDK target is 34 by updating `android/app/build.gradle`.
```groovy gradle
android {
...
compileSdkVersion 34
...
defaultConfig {
...
minSdkVersion 26
...
}
}
```
To use the compile target SDK 34, you'll also need to ensure your Gradle version is 8.6 or higher and your Android Gradle plugin version is 8.4 or higher.
You can do that by checking your `gradle/wrapepr/gradle-wrapper.properties` file and ensuring it is updated to use the latest Gradle version:
```properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
```
And your `android/build.gradle` file is updated to use the latest Android Gradle plugin version:
```groovy gradle
plugins {
id 'com.android.application' version '8.4.1' apply false
}
```
To find the latest compatible versions, you can always check the [Gradle Plugin Release Notes](https://developer.android.com/build/releases/gradle-plugin).
**And you're done!** Now you're ready to configure the SDK 👇
---
# Handling Deep Links
Source: https://superwall.com/docs/flutter/quickstart/in-app-paywall-previews
undefined
1. Previewing paywalls on your device before going live.
2. Deep linking to specific [campaigns](/campaigns).
3. Web Checkout [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting)
## Setup
:::flutter
There are two ways to deep link into your app: URL Schemes and Universal Links (iOS only).
:::
### Adding a Custom URL Scheme
:::flutter
#### iOS
Open **Xcode**. In your **info.plist**, add a row called **URL Types**. Expand the automatically created **Item 0**, and inside the **URL identifier** value field, type your **Bundle ID**, e.g., **com.superwall.Superwall-SwiftUI**. Add another row to **Item 0** called **URL Schemes** and set its **Item 0** to a URL scheme you'd like to use for your app, e.g., **exampleapp**. Your structure should look like this:
With this example, the app will open in response to a deep link with the format **exampleapp\://**. You can [view Apple's documentation](https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app) to learn more about custom URL schemes.
:::
:::flutter
#### Android
Add the following to your `AndroidManifest.xml` file:
```xml
```
This configuration allows your app to open in response to a deep link with the format `exampleapp://` from your `MainActivity` class.
:::
:::flutter
### Adding a Universal Link (iOS only)
Only required for [Web Checkout](/web-checkout), otherwise you can skip this step.
Before configuring in your app, first [create](/web-checkout-creating-an-app) and [configure](/web-checkout-configuring-stripe-keys-and-settings) your Stripe app on the Superwall Dashboard.
#### Add a new capability in Xcode
Select your target in Xcode, then select the **Signing & Capabilities** tab. Click on the **+ Capability** button and select **Associated Domains**. This will add a new capability to your app.
#### Set the domain
Next, enter in the domain using the format `applinks:[your-web-checkout-url]`. This is the domain that Superwall will use to handle universal links. Your `your-web-checkout-url` value should match what's under the "Web Paywall Domain" section.
#### Testing
If your Stripe app's iOS Configuration is incomplete or incorrect, universal links **will not work**
You can verify that your universal links are working a few different ways. Keep in mind that it usually takes a few minutes for the associated domain file to propagate:
1. **Use Branch's online validator:** If you visit [branch.io's online validator](https://branch.io/resources/aasa-validator//) and enter in your web checkout URL, it'll run a similar check and provide the same output.
2. **Test opening a universal link:** If the validation passes from either of the two steps above, make sure visiting a universal link opens your app. Your link should be formatted as `https://[your web checkout link]/app-link/` — which is simply your web checkout link with `/app-link/` at the end. This is easiest to test on device, since you have to tap an actual link instead of visiting one directly in Safari or another browser. In the iOS simulator, adding the link in the Reminders app works too:
:::
### Handling Deep Links
:::flutter
In your `pubspec.yaml` file, add the `uni_links` package to your dependencies:
```yaml
dependencies:
uni_links: ^0.5.1
```
Then, run `flutter pub get` to install the package. Next, in your Flutter app, use the Superwall SDK to handle the deep link via `Superwall.shared.handleDeepLink(theLink);`. Here's a complete example:
```dart
import 'package:flutter/material.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart';
import 'package:uni_links/uni_links.dart';
void main() {
runApp(const MyApp());
}
class MyApp extends StatefulWidget {
MyApp();
@override
_MyAppState createState() => _MyAppState();
}
class _MyAppState extends State {
@override
void initState() {
super.initState();
Superwall.configure('YOUR_SUPERWALL_API_KEY');
_handleIncomingLinks();
}
void _handleIncomingLinks() {
uriLinkStream.listen((Uri? uri) {
if (uri != null) {
Superwall.shared.handleDeepLink(uri);
}
}, onError: (Object err) {
print('Error receiving incoming link: $err');
});
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: Scaffold(
body: Center(
child: Text(
'Deep Link Preview Example',
style: TextStyle(fontSize: 24),
),
),
),
);
}
}
```
:::
## Previewing Paywalls
Next, build and run your app on your phone.
Then, head to the Superwall Dashboard. Click on **Settings** from the Dashboard panel on the left, then select **General**:
With the **General** tab selected, type your custom URL scheme, without slashes, into the **Apple Custom URL Scheme** field:
Next, open your paywall from the dashboard and click **Preview**. You'll see a QR code appear in a pop-up:
On your device, scan this QR code. You can do this via Apple's Camera app. This will take you to a paywall viewer within your app, where you can preview all your paywalls in different configurations.
## Using Deep Links to Present Paywalls
Deep links can also be used as a placement in a campaign to present paywalls. Simply add `deepLink_open` as an placement, and the URL parameters of the deep link can be used as parameters! You can also use custom placements for this purpose. [Read this doc](/presenting-paywalls-from-one-another) for examples of both.
---
# Post-Checkout Redirecting
Source: https://superwall.com/docs/flutter/guides/web-checkout/post-checkout-redirecting
Learn how to handle users redirecting back to your app after a web purchase.
After a user completes a web purchase, Superwall needs to redirect them back to your app. You can configure this behavior in two ways:
## Post-Purchase Behavior Modes
You can configure how users are redirected after checkout in your [Application Settings](/web-checkout-configuring-stripe-keys-and-settings#post-purchase-behavior):
### Redeem Mode (Default)
Superwall manages the entire redemption experience:
* Users are automatically deep linked to your app with a redemption code
* Fallback to App Store/Play Store if the app isn't installed
* Redemption emails are sent automatically
* The SDK handles redemption via delegate methods (detailed below)
This is the recommended mode for most apps.
### Redirect Mode
Redirect users to your own custom URL with purchase information:
* **When to use**: You want to show a custom success page, perform additional actions before redemption, or have your own deep linking infrastructure
* **What you receive**: Purchase data is passed as query parameters to your URL
**Query Parameters Included**:
* `app_user_id` - The user's identifier from your app
* `email` - User's email address
* `stripe_subscription_id` - The Stripe subscription ID
* Any custom placement parameters you set
**Example**:
```
https://yourapp.com/success?
app_user_id=user_123&
email=user@example.com&
stripe_subscription_id=sub_1234567890&
campaign_id=summer_sale
```
You'll need to implement your own logic to handle the redirect and deep link users into your app.
***
## Setting Up Deep Links
Whether you're showing a checkout page in a browser or using the In-App Browser, the Superwall SDK relies on deep links to redirect back to your app.
#### Prerequisites
1. [Configuring Stripe Keys and Settings](/web-checkout-configuring-stripe-keys-and-settings)
2. [Deep Links](/in-app-paywall-previews)
If you're not using Superwall to handle purchases, then you'll need to follow extra steps to redeem the web purchase in your app.
* [Using RevenueCat](/web-checkout-using-revenuecat)
* [Using a PurchaseController](/web-checkout-linking-membership-to-iOS-app#using-a-purchasecontroller)
***
## Handling Redemption (Redeem Mode)
When using Redeem mode (the default), handle the user experience when they're redirected back to your app using `SuperwallDelegate` methods:
### willRedeemLink
When your app opens via the deep link, we will call the delegate method `willRedeemLink()` before making a network call to redeem the code.
At this point, you might wish to display a loading indicator in your app so the user knows that the purchase is being redeemed.
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
import 'package:flutter/material.dart';
class MySuperwallDelegate extends SuperwallDelegate {
@override
void willRedeemLink() {
// Show a loading indicator to the user
print('Activating your purchase...');
// You might show a SnackBar or loading dialog here
}
}
```
You can manually dismiss the paywall at this point if needed, but note that the paywall will be dismissed automatically when the `didRedeemLink` method is called.
### didRedeemLink
After receiving a response from the network, we will call `didRedeemLink(result)` with the result of redeeming the code. The result is a `RedemptionResult` which can be one of:
* `RedemptionResult` with `type: RedemptionResultType.success`: The redemption succeeded and contains information about the redeemed code.
* `RedemptionResult` with `type: RedemptionResultType.error`: An error occurred while redeeming. You can check the error message via the error parameter.
* `RedemptionResult` with `type: RedemptionResultType.expiredCode`: The code expired and contains information about whether a redemption email has been resent and an optional obfuscated email address.
* `RedemptionResult` with `type: RedemptionResultType.invalidCode`: The code that was redeemed was invalid.
* `RedemptionResult` with `type: RedemptionResultType.expiredSubscription`: The subscription that the code redeemed has expired.
On network failure, the SDK will retry up to 6 times before returning an `error` `RedemptionResult` in `didRedeemLink(result)`.
Here, you should remove any loading UI you added in `willRedeemLink` and show a message to the user based on the result. If a paywall is presented, it will be dismissed automatically.
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
import 'package:flutter/material.dart';
class MySuperwallDelegate extends SuperwallDelegate {
final BuildContext context; // Pass context if you need to show dialogs/snackbars
MySuperwallDelegate(this.context);
@override
void didRedeemLink(RedemptionResult result) {
switch (result.type) {
case RedemptionResultType.expiredCode:
_showMessage('Expired Link');
print('[!] code expired: ${result.code}, ${result.expiredInfo}');
break;
case RedemptionResultType.error:
_showMessage(result.error?.message ?? 'An error occurred');
print('[!] error: ${result.code}, ${result.error}');
break;
case RedemptionResultType.expiredSubscription:
_showMessage('Expired Subscription');
print('[!] expired subscription: ${result.code}, ${result.redemptionInfo}');
break;
case RedemptionResultType.invalidCode:
_showMessage('Invalid Link');
print('[!] invalid code: ${result.code}');
break;
case RedemptionResultType.success:
final email = result.redemptionInfo?.purchaserInfo?.email;
if (email != null) {
Superwall.shared.setUserAttributes({'email': email});
_showMessage('Welcome, $email!');
} else {
_showMessage('Welcome!');
}
break;
}
}
void _showMessage(String message) {
// Show a snackbar or toast message
ScaffoldMessenger.of(context).showSnackBar(
SnackBar(content: Text(message)),
);
}
}
```
### Setting up the delegate
Make sure to set your delegate when configuring Superwall:
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Superwall.configure('pk_your_api_key');
// Set the delegate (you'll need access to BuildContext for UI operations)
runApp(MyApp());
}
class MyApp extends StatefulWidget {
@override
State createState() => _MyAppState();
}
class _MyAppState extends State {
@override
void initState() {
super.initState();
// Set the delegate after the widget is initialized
WidgetsBinding.instance.addPostFrameCallback((_) {
Superwall.shared.setDelegate(MySuperwallDelegate(context));
});
}
@override
Widget build(BuildContext context) {
return MaterialApp(
home: YourHomeScreen(),
);
}
}
```
---
# Redeeming In-App
Source: https://superwall.com/docs/flutter/guides/web-checkout/linking-membership-to-iOS-app
Handle a deep link in your app and use the delegate methods.
After purchasing from a web paywall, the user will be redirected to your app by a deep link to redeem their purchase on device.
Please follow our [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting) guide to handle this user experience.
If you're using Superwall to handle purchases, then you don't need to do anything here.
If you're using your own `PurchaseController`, you will need to update the subscription status with the redeemed web entitlements. If you're using RevenueCat, you should follow our [Using RevenueCat](/web-checkout-using-revenuecat) guide.
### Using a PurchaseController
If you're using a custom PurchaseController (with either iOS StoreKit or Android Play Billing), you'll need to merge the web entitlements with the device entitlements before setting the subscription status.
Here's an example of how you might do this:
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
Future syncSubscriptionStatus() async {
// Get the device entitlements from your purchase controller
// This will vary based on whether you're using RevenueCat, StoreKit, or Play Billing
final deviceEntitlements = await getDeviceEntitlements();
// Get the web entitlements from Superwall
final webEntitlements = Superwall.shared.entitlements?.web ?? [];
// Merge the two sets of entitlements
final allEntitlementIds = {
...deviceEntitlements,
...webEntitlements.map((e) => e.id),
};
// Update subscription status
if (allEntitlementIds.isNotEmpty) {
final entitlements = allEntitlementIds
.map((id) => Entitlement(id: id))
.toSet();
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusActive(entitlements: entitlements),
);
} else {
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusInactive(),
);
}
}
// Helper function to get device entitlements
// This is a simplified example - your implementation will depend on your purchase system
Future> getDeviceEntitlements() async {
// For RevenueCat:
// final customerInfo = await Purchases.getCustomerInfo();
// return customerInfo.entitlements.active.keys.toList();
// For custom StoreKit/Play Billing:
// Query your store's API for current purchases
// Extract entitlement IDs from those purchases
// Return list of entitlement IDs
return []; // Replace with your actual implementation
}
```
In addition to syncing the subscription status when purchasing and restoring, you'll need to sync it whenever `didRedeemLink(result)` is called:
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
class MySuperwallDelegate extends SuperwallDelegate {
@override
void didRedeemLink(RedemptionResult result) {
// Don't use async here directly, spawn a separate task
_handleRedemption(result);
}
Future _handleRedemption(RedemptionResult result) async {
await syncSubscriptionStatus();
}
}
```
### Refreshing of web entitlements
If you aren't using a Purchase Controller, the SDK will refresh the web entitlements every 24 hours.
### Redeeming while a paywall is open
If a redeem event occurs when a paywall is open, the SDK will track that as a restore event and the paywall will close.
---
# Using RevenueCat
Source: https://superwall.com/docs/flutter/guides/web-checkout/using-revenuecat
Handle a deep link in your app and use the delegate methods to link web checkouts with RevenueCat in Flutter.
After purchasing from a web paywall, the user will be redirected to your app by a deep link to redeem their purchase on device. Please follow our [Post-Checkout Redirecting](/web-checkout-post-checkout-redirecting) guide to handle this user experience.
If you're using Superwall to handle purchases, then you don't need to do anything here.
You only need to use a `PurchaseController` if you want end-to-end control of the purchasing pipeline. The recommended way to use RevenueCat with Superwall is by putting it in observer mode.
If you're using your own `PurchaseController`, you should follow our [Redeeming In-App](/web-checkout-linking-membership-to-iOS-app) guide.
### Using a PurchaseController with RevenueCat
If you're using RevenueCat, you'll need to follow [steps 1 to 4 in their guide](https://www.revenuecat.com/docs/web/integrations/stripe) to set up Stripe with RevenueCat. Then, you'll need to
associate the RevenueCat customer with the Stripe subscription IDs returned from redeeming the code. You can do this by extracting the ids from the `RedemptionResult` and sending them to RevenueCat's API
by using the `didRedeemLink()` delegate method:
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
import 'package:purchases_flutter/purchases_flutter.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';
class MySuperwallDelegate extends SuperwallDelegate {
// The user tapped on a deep link to redeem a code
@override
void willRedeemLink() {
print('[!] willRedeemLink');
// Optionally show a loading indicator here
}
// Superwall received a redemption result and validated the purchase with Stripe.
@override
void didRedeemLink(RedemptionResult result) async {
print('[!] didRedeemLink: $result');
// Send Stripe IDs to RevenueCat to link purchases to the customer
// Get a list of subscription ids tied to the customer
final stripeSubscriptionIds = result.stripeSubscriptionIds;
if (stripeSubscriptionIds == null || stripeSubscriptionIds.isEmpty) {
return;
}
const revenueCatStripePublicAPIKey = 'strp.....'; // replace with your RevenueCat Stripe Public API Key
final appUserId = await Purchases.appUserID;
// In the background, send requests to RevenueCat
for (final stripeSubscriptionId in stripeSubscriptionIds) {
try {
final url = Uri.parse('https://api.revenuecat.com/v1/receipts');
final response = await http.post(
url,
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-Platform': 'stripe',
'Authorization': 'Bearer $revenueCatStripePublicAPIKey',
},
body: jsonEncode({
'app_user_id': appUserId,
'fetch_token': stripeSubscriptionId,
}),
);
if (response.statusCode != 200) {
throw Exception(
'RevenueCat responded with ${response.statusCode}: ${response.body}',
);
}
final json = jsonDecode(response.body);
print('[!] Success: linked $stripeSubscriptionId to user $appUserId: $json');
} catch (error) {
print('[!] Error: unable to link $stripeSubscriptionId to user $appUserId: $error');
}
}
// After all network calls complete, invalidate the cache
try {
final customerInfo = await Purchases.getCustomerInfo();
/// If you're using Purchases.customerInfoStream, or keeping Superwall Entitlements in sync
/// via RevenueCat's PurchasesDelegate methods, you don't need to do anything here. Those methods will be
/// called automatically when this call fetches the most up to date customer info, ignoring any local caches.
/// Otherwise, if you're manually calling Purchases.getCustomerInfo to keep Superwall's entitlements
/// in sync, you should use the newly updated customer info here to do so.
/// You could always access web entitlements here as well
/// final webEntitlements = Superwall.shared.entitlements?.web;
// Perform UI updates, like letting the user know their subscription was redeemed
print('[!] Customer info updated after redemption');
} catch (error) {
print('[!] Error fetching customer info: $error');
}
}
}
```
The example throws when RevenueCat responds with an error so you can add retries, alerts, or custom
UI. Adapt the error-handling strategy to your networking and logging requirements.
Set up the delegate when configuring Superwall:
```dart
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Superwall.configure('pk_your_api_key');
// Set the delegate
Superwall.shared.setDelegate(MySuperwallDelegate());
runApp(MyApp());
}
```
If you call `logIn` from RevenueCat's SDK, then you need to call the logic you've implemented
inside `didRedeemLink()` again. For example, that means if `logIn` was invoked from
RevenueCat, you'd either abstract out this logic above into a function to call again, or simply
call this function directly.
The web entitlements will be returned along with other existing entitlements in the `CustomerInfo` object accessible via RevenueCat's SDK.
If you're logging in and out of RevenueCat, make sure to resend the Stripe subscription IDs to RevenueCat's endpoint after logging in.
### Alternative implementation using async/await properly
Here's a cleaner implementation that properly handles async operations:
```dart
class MySuperwallDelegate extends SuperwallDelegate {
@override
void willRedeemLink() {
print('[!] willRedeemLink');
// Show loading indicator
}
@override
void didRedeemLink(RedemptionResult result) {
// Don't use async here directly, spawn a separate task
_handleRedemption(result);
}
Future _handleRedemption(RedemptionResult result) async {
final stripeSubscriptionIds = result.stripeSubscriptionIds;
if (stripeSubscriptionIds == null || stripeSubscriptionIds.isEmpty) {
print('[!] No Stripe subscription IDs found');
return;
}
const revenueCatStripePublicAPIKey = 'strp.....';
final appUserId = await Purchases.appUserID;
// Link each subscription to RevenueCat
await Future.wait(
stripeSubscriptionIds.map((stripeSubscriptionId) async {
try {
await _linkSubscriptionToRevenueCat(
stripeSubscriptionId,
appUserId,
revenueCatStripePublicAPIKey,
);
} catch (e) {
print('[!] Failed to link $stripeSubscriptionId: $e');
}
}),
);
// Refresh customer info
try {
await Purchases.getCustomerInfo();
print('[!] Successfully refreshed customer info');
} catch (e) {
print('[!] Failed to refresh customer info: $e');
}
}
Future _linkSubscriptionToRevenueCat(
String stripeSubscriptionId,
String appUserId,
String apiKey,
) async {
final url = Uri.parse('https://api.revenuecat.com/v1/receipts');
final response = await http.post(
url,
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
'X-Platform': 'stripe',
'Authorization': 'Bearer $apiKey',
},
body: jsonEncode({
'app_user_id': appUserId,
'fetch_token': stripeSubscriptionId,
}),
);
if (response.statusCode != 200) {
throw Exception(
'RevenueCat responded with ${response.statusCode}: ${response.body}',
);
}
print('[!] Successfully linked $stripeSubscriptionId to $appUserId');
}
}
```
Remember to add the `http` package to your `pubspec.yaml`:
```yaml
dependencies:
http: ^1.1.0
purchases_flutter: ^6.0.0
superwall_flutter: ^1.0.0
```
---
# Web Checkout
Source: https://superwall.com/docs/flutter/guides/web-checkout
Integrate Superwall web checkout with your iOS app for seamless cross-platform subscriptions
## Dashboard Setup
1. [Set up Web Checkout in the dashboard](/web-checkout/web-checkout-overview)
2. [Add web products to your paywall](/web-checkout/web-checkout-direct-stripe-checkout)
## SDK Setup
1. [Set up deep links](/sdk/quickstart/in-app-paywall-previews)
2. [Handle Post-Checkout redirecting](/sdk/guides/web-checkout/post-checkout-redirecting)
3. **Only if you're using RevenueCat:** [Using RevenueCat](/sdk/guides/web-checkout/using-revenuecat)
4. **Only if you're using your own PurchaseController:** [Redeeming In-App](/sdk/guides/web-checkout/linking-membership-to-iOS-app)
## Testing
1. [Testing Purchases](/web-checkout/web-checkout-testing-purchases)
2. [Managing Memberships](/web-checkout/web-checkout-managing-memberships)
## Troubleshooting
If a user has issues accessing their subscription in your app after paying via web checkout, direct them to your plan management page to retrieve their subscription link or manage billing:
For example: `http://yourapp.superwall.app/manage`
## FAQ
[Web Checkout FAQ](/web-checkout/web-checkout-faq)
---
# Migrating from v1 to v2 - Flutter
Source: https://superwall.com/docs/flutter/guides/migrations/migrating-to-v2
SuperwallKit 2.0 is a major release of Superwall's Flutter SDK. This introduces breaking changes.
## Migration steps
## 1. Update code references
### 1.1 Rename references from `event` to `placement`
In some cases, you should be able to update references using the automatic renaming suggestions that Xcode provides. For other cases where this hasn't been possible, you'll need to run through this list to manually update your code.
| Before | After |
| ------------------------------------ | ---------------------------------------- |
| fun registerEvent(event:) | fun registerPlacement(placement:) |
| fun preloadPaywalls(forEvents:) | fun preloadPaywalls(forPlacements:) |
| fun getPaywall(forEvent:) | fun getPaywall(forPlacement:) |
| fun getPresentationResult(forEvent:) | fun getPresentationResult(forPlacement:) |
| TriggerResult.eventNotFound | TriggerResult.placementNotFound |
## 2. SuperwallBuilder
To make tracking and reacting to subscription status changes easier, we've introduced a new `SuperwallBuilder` widget.
Using it is quite simple - just add it to your widget tree and every time the subscription status is changed, the builder function
will be invoked, triggering a re-render of it's child widgets.
For example, here's a simple implementation that will change the text based on the subscription status:
```dart Flutter
SuperwallBuilder(
builder: (context, status) => Center(
child: Text('Subscription Status: ${status}'),
)
)
```
### 3. Getting the purchased product
The `onDismiss` block of the `PaywallPresentationHandler` now accepts both a `PaywallInfo` object and a `PaywallResult` object. This allows you to easily access
the purchased product from the result when the paywall dismisses.
### 4. Entitlements
The `subscriptionStatus` has been changed to accept a set of `Entitlement` objects. This allows you to give access to entitlements based on products purchased.
For example, in your app you might have Bronze, Silver, and Gold subscription tiers, i.e. entitlements, which entitle a user to access a certain set of features within your app.
Every subscription product must be associated with one or more entitlements, which is controlled via the dashboard. Superwall will already have associated all your
products with a default entitlement. If you don't use more than one entitlement tier within your app and you only use subscription products, you don't need to do anything extra.
However, if you use one-time purchases or multiple entitlements, you should review your products and their entitlements. In general, consumables should not be associated with an
entitlement, whereas non-consumables should be. Check your products [here](https://superwall.com/applications/\:app/products/v2).
If you're using a `PurchaseController`, you'll need to set the `entitlements` with the `subscriptionStatus`:
| Before | After |
| ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Superwall.shared.setSubscriptionStatus(SubscriptionStatus.active) | Superwall.shared.setSubscriptionStatus(SubscriptionStatusActive(entitlements: entitlements)) |
Here is an example of how you'd sync your subscription status with Superwall using these methods:
```dart RevenueCat
// Only necessary if you're using a PurchaseController.
// Otherwise, Superwall does this automatically.
fun syncSubscriptionStatus() {
Purchases.addCustomerInfoUpdateListener((customerInfo) async {
// Gets called whenever new CustomerInfo is available
final entitlements = customerInfo.entitlements.active.keys
.map((id) => Entitlement(id: id))
.toSet();
final hasActiveEntitlementOrSubscription = customerInfo
.hasActiveEntitlementOrSubscription(); // Why? -> https://www.revenuecat.com/docs/entitlements#entitlements
if (hasActiveEntitlementOrSubscription) {
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusActive(entitlements: entitlements));
} else {
await Superwall.shared
.setSubscriptionStatus(SubscriptionStatusInactive());
}
});
}
```
You can listen to the published property `Superwall.shared.subscriptionStatus` to be notified when the subscriptionStatus changes. Or you can use the `SuperwallDelegate`
method `subscriptionStatusDidChange(from:to:)`, which replaces `subscriptionStatusDidChange(to:)`.
### 5. Paywall Presentation Condition
In the Paywall Editor you can choose whether to always present a paywall or ask the SDK to check the user subscription before presenting a paywall.
For users on v1 of the SDK, this is replaced with a check on the entitlements within the audience filter. As you migrate your users from v1 to v2 of the
SDK, you'll need to make sure you set both the entitlements check and the paywall presentation condition in the paywall editor.
## 6. Check out the full change log
You can view this on [our GitHub page](https://github.com/superwall/Superwall-Flutter/blob/main/CHANGELOG.md).
## 7. Check out our updated example apps
All of our [example apps](https://github.com/superwall/Superwall-Flutter/tree/main/example) have been updated to use the latest SDK. We now only have two apps: Basic and Advanced. Basic shows you the basic integration of Superwall
without needing a purchase controller or multiple entitlements. Advanced shows you how to use entitlements within your app as well as optionally using a purchase controller with StoreKit or RevenueCat.
---
# Using the Presentation Handler
Source: https://superwall.com/docs/flutter/guides/advanced/using-the-presentation-handler
undefined
You can provide a `PaywallPresentationHandler` to `register`, whose functions provide status updates for a paywall:
* `onDismiss`: Called when the paywall is dismissed. Accepts a `PaywallInfo` object containing info about the dismissed paywall, and there is a `PaywallResult` informing you of any transaction.
* `onPresent`: Called when the paywall did present. Accepts a `PaywallInfo` object containing info about the presented paywall.
* `onError`: Called when an error occurred when trying to present a paywall. Accepts an `Error` indicating why the paywall could not present.
* `onSkip`: Called when a paywall is skipped. Accepts a `PaywallSkippedReason` enum indicating why the paywall was skipped.
```swift Swift
let handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result in
print("The paywall dismissed. PaywallInfo: \(paywallInfo). Result: \(result)")
}
handler.onPresent { paywallInfo in
print("The paywall presented. PaywallInfo:", paywallInfo)
}
handler.onError { error in
print("The paywall presentation failed with error \(error)")
}
handler.onSkip { reason in
switch reason {
case .holdout(let experiment):
print("Paywall not shown because user is in a holdout group in Experiment: \(experiment.id)")
case .noAudienceMatch:
print("Paywall not shown because user doesn't match any audiences.")
case .placementNotFound:
print("Paywall not shown because this placement isn't part of a campaign.")
}
}
Superwall.shared.register(placement: "campaign_trigger", handler: handler) {
// Feature launched
}
```
```swift Objective-C
SWKPaywallPresentationHandler *handler = [[SWKPaywallPresentationHandler alloc] init];
[handler onDismiss:^(SWKPaywallInfo * _Nonnull paywallInfo,
enum SWKPaywallResult result,
SWKStoreProduct * _Nullable product) {
NSLog(@"The paywall presented. PaywallInfo: %@ - result: %ld", paywallInfo, (long)result);
}];
[handler onPresent:^(SWKPaywallInfo * _Nonnull paywallInfo) {
NSLog(@"The paywall presented. PaywallInfo: %@", paywallInfo);
}];
[handler onError:^(NSError * _Nonnull error) {
NSLog(@"The paywall presentation failed with error %@", error);
}];
[handler onSkip:^(enum SWKPaywallSkippedReason reason) {
switch (reason) {
case SWKPaywallSkippedReasonUserIsSubscribed:
NSLog(@"Paywall not shown because user is subscribed.");
break;
case SWKPaywallSkippedReasonHoldout:
NSLog(@"Paywall not shown because user is in a holdout group.");
break;
case SWKPaywallSkippedReasonNoAudienceMatch:
NSLog(@"Paywall not shown because user doesn't match any audiences.");
break;
case SWKPaywallSkippedReasonPlacementNotFound:
NSLog(@"Paywall not shown because this placement isn't part of a campaign.");
break;
case SWKPaywallSkippedReasonNone:
// The paywall wasn't skipped.
break;
}
}];
[[Superwall sharedInstance] registerWithPlacement:@"campaign_trigger" params:nil handler:handler feature:^{
// Feature launched.
}];
```
```kotlin Kotlin
val handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result ->
println("The paywall dismissed. PaywallInfo: ${it}")
}
handler.onPresent {
println("The paywall presented. PaywallInfo: ${it}")
}
handler.onError {
println("The paywall errored. Error: ${it}")
}
handler.onSkip {
when (it) {
is PaywallSkippedReason.PlacementNotFound -> {
println("The paywall was skipped because the placement was not found.")
}
is PaywallSkippedReason.Holdout -> {
println("The paywall was skipped because the user is in a holdout group.")
}
is PaywallSkippedReason.NoAudienceMatch -> {
println("The paywall was skipped because no audience matched.")
}
}
}
Superwall.instance.register(placement = "campaign_trigger", handler = handler) {
// Feature launched
}
```
```dart Flutter
PaywallPresentationHandler handler = PaywallPresentationHandler();
handler.onPresent((paywallInfo) async {
String name = await paywallInfo.name;
print("Handler (onPresent): $name");
});
handler.onDismiss((paywallInfo, paywallResult) async {
String name = await paywallInfo.name;
print("Handler (onDismiss): $name");
});
handler.onError((error) {
print("Handler (onError): ${error}");
});
handler.onSkip((skipReason) async {
String description = await skipReason.description;
if (skipReason is PaywallSkippedReasonHoldout) {
print("Handler (onSkip): $description");
final experiment = await skipReason.experiment;
final experimentId = await experiment.id;
print("Holdout with experiment: ${experimentId}");
} else if (skipReason is PaywallSkippedReasonNoAudienceMatch) {
print("Handler (onSkip): $description");
} else if (skipReason is PaywallSkippedReasonPlacementNotFound) {
print("Handler (onSkip): $description");
} else {
print("Handler (onSkip): Unknown skip reason");
}
});
Superwall.shared.registerPlacement("campaign_trigger", handler: handler, feature: () {
// Feature launched
});
```
```typescript React Native
const handler = new PaywallPresentationHandler()
handler.onPresent((paywallInfo) => {
const name = paywallInfo.name
console.log(`Handler (onPresent): ${name}`)
})
handler.onDismiss((paywallInfo, paywallResult) => {
const name = paywallInfo.name
console.log(`Handler (onDismiss): ${name}`)
})
handler.onError((error) => {
console.log(`Handler (onError): ${error}`)
})
handler.onSkip((skipReason) => {
const description = skipReason.description
if (skipReason instanceof PaywallSkippedReasonHoldout) {
console.log(`Handler (onSkip): ${description}`)
const experiment = skipReason.experiment
const experimentId = experiment.id
console.log(`Holdout with experiment: ${experimentId}`)
} else if (skipReason instanceof PaywallSkippedReasonNoAudienceMatch) {
console.log(`Handler (onSkip): ${description}`)
} else if (skipReason instanceof PaywallSkippedReasonPlacementNotFound) {
console.log(`Handler (onSkip): ${description}`)
} else {
console.log(`Handler (onSkip): Unknown skip reason`)
}
})
Superwall.shared.register({
placement: 'campaign_trigger',
handler: handler,
feature: () => {
// Feature launched
}
});
```
Wanting to see which product was just purchased from a paywall? Use `onDismiss` and the `result`
parameter. Or, you can use the
[SuperwallDelegate](/3rd-party-analytics#using-events-to-see-purchased-products).
---
# Observer Mode
Source: https://superwall.com/docs/flutter/guides/advanced/observer-mode
undefined
If you wish to make purchases outside of Superwall's SDK and paywalls, you can use **observer mode** to report purchases that will appear in the Superwall dashboard, such as transactions:
This is useful if you are using Superwall solely for revenue tracking, and you're making purchases using frameworks like StoreKit or Google Play Billing Library directly. Observer mode will also properly link user identifiers to transactions. To enable observer mode, set it using `SuperwallOptions` when configuring the SDK:
There are a few things to keep in mind when using observer mode:
1. On iOS, if you're using StoreKit 2, then Superwall solely reports transaction completions. If you're using StoreKit 1, then Superwall will report transaction starts, abandons, and completions.
2. When using observer mode, you can't make purchases using our SDK — such as `Superwall.shared.purchase(aProduct)`.
For more on setting up revenue tracking, check out this [doc](/overview-settings-revenue-tracking).
---
# Viewing Purchased Products
Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products
undefined
When a paywall is presenting and a user converts, you can view the purchased products in several different ways.
### Use the `PaywallPresentationHandler`
Arguably the easiest of the options — simply pass in a presentation handler and check out the product within the `onDismiss` block.
```swift Swift
let handler = PaywallPresentationHandler()
handler.onDismiss { _, result in
switch result {
case .declined:
print("No purchased occurred.")
case .purchased(let product):
print("Purchased \(product.productIdentifier)")
case .restored:
print("Restored purchases.")
}
}
Superwall.shared.register(placement: "caffeineLogged", handler: handler) {
logCaffeine()
}
```
```swift Objective-C
SWKPaywallPresentationHandler *handler = [SWKPaywallPresentationHandler new];
[handler onDismiss:^(SWKPaywallInfo * _Nonnull info,
enum SWKPaywallResult result,
SWKStoreProduct * _Nullable product) {
switch (result) {
case SWKPaywallResultPurchased:
NSLog(@"Purchased %@", product.productIdentifier);
default:
NSLog(@"Unhandled event.");
}
}];
[[Superwall sharedInstance] registerWithPlacement:@"caffeineLogged"
params:@{}
handler:handler
feature:^{
[self logCaffeine];
}];
```
```kotlin Android
val handler = PaywallPresentationHandler()
handler.onDismiss { _, paywallResult ->
when (paywallResult) {
is PaywallResult.Purchased -> {
// The user made a purchase!
val purchasedProductId = paywallResult.productId
println("User purchased product: $purchasedProductId")
// ... do something with the purchased product ID ...
}
is PaywallResult.Declined -> {
// The user declined to make a purchase.
println("User declined to make a purchase.")
// ... handle the declined case ...
}
is PaywallResult.Restored -> {
// The user restored a purchase.
println("User restored a purchase.")
// ... handle the restored case ...
}
}
}
Superwall.instance.register(placement = "caffeineLogged", handler = handler) {
logCaffeine()
}
```
```dart Flutter
PaywallPresentationHandler handler = PaywallPresentationHandler();
handler.onDismiss((paywallInfo, paywallResult) async {
String name = await paywallInfo.name;
print("Handler (onDismiss): $name");
switch (paywallResult) {
case PurchasedPaywallResult(productId: var id):
// The user made a purchase!
print('User purchased product: $id');
// ... do something with the purchased product ID ...
break;
case DeclinedPaywallResult():
// The user declined to make a purchase.
print('User declined the paywall.');
// ... handle the declined case ...
break;
case RestoredPaywallResult():
// The user restored a purchase.
print('User restored a previous purchase.');
// ... handle the restored case ...
break;
}
});
Superwall.shared.registerPlacement(
"caffeineLogged", handler: handler, feature: () {
logCaffeine();
});
```
```typescript React Native
import * as React from "react"
import Superwall from "../../src"
import { PaywallPresentationHandler, PaywallInfo } from "../../src"
import type { PaywallResult } from "../../src/public/PaywallResult"
const Home = () => {
const navigation = useNavigation()
const presentationHandler: PaywallPresentationHandler = {
onDismiss: (handler: (info: PaywallInfo, result: PaywallResult) => void) => {
handler = (info, result) => {
console.log("Paywall dismissed with info:", info, "and result:", result)
if (result.type === "purchased") {
console.log("Product purchased with ID:", result.productId)
}
}
},
onPresent: (handler: (info: PaywallInfo) => void) => {
handler = (info) => {
console.log("Paywall presented with info:", info)
// Add logic for when the paywall is presented
}
},
onError: (handler: (error: string) => void) => {
handler = (error) => {
console.error("Error presenting paywall:", error)
// Handle any errors that occur during presentation
}
},
onSkip: () => {
console.log("Paywall presentation skipped")
// Handle the case where the paywall presentation is skipped
},
}
const nonGated = () => {
Superwall.shared.register({ placement: "non_gated", handler: presentationHandler, feature: () => {
navigation.navigate("caffeineLogged", {
value: "Go for caffeine logging",
})
});
}
return // Your view code here
}
```
### Use `SuperwallDelegate`
Next, the [SuperwallDelegate](/using-superwall-delegate) offers up much more information, and can inform you of virtually any Superwall event that occurred:
```swift Swift
class SWDelegate: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case .transactionComplete(_, let product, _, _):
print("Transaction complete: product: \(product.productIdentifier)")
case .subscriptionStart(let product, _):
print("Subscription start: product: \(product.productIdentifier)")
case .freeTrialStart(let product, _):
print("Free trial start: product: \(product.productIdentifier)")
case .transactionRestore(_, _):
print("Transaction restored")
case .nonRecurringProductPurchase(let product, _):
print("Consumable product purchased: \(product.id)")
default:
print("Unhandled event.")
}
}
}
@main
struct Caffeine_PalApp: App {
@State private var swDelegate: SWDelegate = .init()
init() {
Superwall.configure(apiKey: "my_api_key")
Superwall.shared.delegate = swDelegate
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
```swift Objective-C
// SWDelegate.h...
#import
@import SuperwallKit;
NS_ASSUME_NONNULL_BEGIN
@interface SWDelegate : NSObject
@end
NS_ASSUME_NONNULL_END
// SWDelegate.m...
@implementation SWDelegate
- (void)handleSuperwallEventWithInfo:(SWKSuperwallEventInfo *)eventInfo {
switch(eventInfo.event) {
case SWKSuperwallEventTransactionComplete:
NSLog(@"Transaction complete: %@", eventInfo.params[@"primary_product_id"]);
}
}
// In AppDelegate.m...
#import "AppDelegate.h"
#import "SWDelegate.h"
@import SuperwallKit;
@interface AppDelegate ()
@property (strong, nonatomic) SWDelegate *delegate;
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
self.delegate = [SWDelegate new];
[Superwall configureWithApiKey:@"my_api_key"];
[Superwall sharedInstance].delegate = self.delegate;
return YES;
}
```
```kotlin Android
class SWDelegate : SuperwallDelegate {
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when (eventInfo.event) {
is SuperwallPlacement.TransactionComplete -> {
val transaction = (eventInfo.event as SuperwallPlacement.TransactionComplete).transaction
val product = (eventInfo.event as SuperwallPlacement.TransactionComplete).product
val paywallInfo = (eventInfo.event as SuperwallPlacement.TransactionComplete).paywallInfo
println("Transaction Complete: $transaction, Product: $product, Paywall Info: $paywallInfo")
}
else -> {
// Handle other cases
}
}
}
}
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "my_api_key")
Superwall.instance.delegate = SWDelegate()
}
}
```
```dart Flutter
import 'dart:io';
import 'package:flutter/material.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart';
class _MyAppState extends State implements SuperwallDelegate {
final logging = Logging();
@override
void initState() {
super.initState();
configureSuperwall(useRevenueCat);
}
Future configureSuperwall(bool useRevenueCat) async {
try {
final apiKey = Platform.isIOS
? 'ios_api_project_key'
: 'android_api_project_key';
final logging = Logging();
logging.level = LogLevel.warn;
logging.scopes = {LogScope.all};
final options = SuperwallOptions();
options.paywalls.shouldPreload = false;
options.logging = logging;
Superwall.configure(apiKey,
purchaseController: null,
options: options, completion: () {
logging.info('Executing Superwall configure completion block');
});
Superwall.shared.setDelegate(this);
} catch (e) {
// Handle any errors that occur during configuration
logging.error('Failed to configure Superwall:', e);
}
}
@override
Future handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
switch (eventInfo.event.type) {
case PlacementType.transactionComplete:
final product = eventInfo.params?['product'];
logging.info('Transaction complete event received with product: $product');
// Add any additional logic you need to handle the transaction complete event
break;
// Handle other events if necessary
default:
logging.info('Unhandled event type: ${eventInfo.event.type}');
break;
}
}
}
```
```typescript React Native
import {
PaywallInfo,
SubscriptionStatus,
SuperwallDelegate,
SuperwallPlacementInfo,
PlacementType,
} from '../../src';
export class MySuperwallDelegate extends SuperwallDelegate {
handleSuperwallPlacement(placementInfo: SuperwallPlacementInfo) {
console.log('Handling Superwall placement:', placementInfo);
switch (placementInfo.placement.type) {
case PlacementType.transactionComplete:
const product = placementInfo.params?.["product"];
if (product) {
console.log(`Product: ${product}`);
} else {
console.log("Product not found in params.");
}
break;
default:
break;
}
}
}
export default function App() {
const delegate = new MySuperwallDelegate();
React.useEffect(() => {
const setupSuperwall = async () => {
const apiKey =
Platform.OS === 'ios'
? 'ios_api_project_key'
: 'android_api_project_key';
Superwall.configure({
apiKey: apiKey,
});
Superwall.shared.setDelegate(delegate);
};
}
}
```
### Use a purchase controller
If you are controlling the purchasing pipeline yourself via a [purchase controller](/advanced-configuration), then naturally the purchased product is available:
```swift Swift
final class MyPurchaseController: PurchaseController {
func purchase(product: StoreProduct) async -> PurchaseResult {
print("Kicking off purchase of \(product.productIdentifier)")
do {
let result = try await MyPurchaseLogic.purchase(product: product)
return .purchased // .cancelled, .pending, .failed(Error)
} catch {
return .failed(error)
}
}
// 2
func restorePurchases() async -> RestorationResult {
print("Restoring purchases")
return .restored // false
}
}
@main
struct Caffeine_PalApp: App {
private let pc: MyPurchaseController = .init()
init() {
Superwall.configure(apiKey: "my_api_key", purchaseController: pc)
}
var body: some Scene {
WindowGroup {
ContentView()
}
}
}
```
```swift Objective-C
// In MyPurchaseController.h...
#import
@import SuperwallKit;
@import StoreKit;
NS_ASSUME_NONNULL_BEGIN
@interface MyPurchaseController : NSObject
+ (instancetype)sharedInstance;
@end
NS_ASSUME_NONNULL_END
// In MyPurchaseController.m...
#import "MyPurchaseController.h"
@implementation MyPurchaseController
+ (instancetype)sharedInstance
{
static MyPurchaseController *sharedInstance = nil;
static dispatch_once_t onceToken;
dispatch_once(&onceToken, ^{
sharedInstance = [MyPurchaseController new];
});
return sharedInstance;
}
- (void)purchaseWithProduct:(SWKStoreProduct * _Nonnull)product
completion:(void (^ _Nonnull)(enum SWKPurchaseResult, NSError * _Nullable))completion {
NSLog(@"Kicking off purchase of %@", product.productIdentifier);
// Do purchase logic here
completion(SWKPurchaseResultPurchased, nil);
}
- (void)restorePurchasesWithCompletion:(void (^ _Nonnull)(enum SWKRestorationResult, NSError * _Nullable))completion {
// Do restore logic here
completion(SWKRestorationResultRestored, nil);
}
@end
// In AppDelegate.m...
#import "AppDelegate.h"
#import "MyPurchaseController.h"
@import SuperwallKit;
@interface AppDelegate ()
@end
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
[Superwall configureWithApiKey:@"my_api_key"
purchaseController:[MyPurchaseController sharedInstance]
options:nil
completion:^{
}];
return YES;
}
```
```kotlin Android
class MyPurchaseController(val context: Context): PurchaseController {
override suspend fun purchase(
activity: Activity,
productDetails: ProductDetails,
basePlanId: String?,
offerId: String?
): PurchaseResult {
println("Kicking off purchase of $basePlanId")
return PurchaseResult.Purchased()
}
override suspend fun restorePurchases(): RestorationResult {
TODO("Not yet implemented")
}
}
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Superwall.configure(this, "my_api_key", purchaseController = MyPurchaseController(this))
}
}
```
```dart Flutter
class MyPurchaseController extends PurchaseController {
// 1
@override
Future purchaseFromAppStore(String productId) async {
print('Attempting to purchase product with ID: $productId');
// Do purchase logic
return PurchaseResult.purchased;
}
@override
Future purchaseFromGooglePlay(
String productId,
String? basePlanId,
String? offerId
) async {
print('Attempting to purchase product with ID: $productId and basePlanId: $basePlanId');
// Do purchase logic
return PurchaseResult.purchased;
}
@override
Future restorePurchases() async {
// Do resture logic
}
}
```
```typescript React Native
export class MyPurchaseController extends PurchaseController {
// 1
async purchaseFromAppStore(productId: string): Promise {
console.log("Kicking off purchase of ", productId)
// Purchase logic
return await this._purchaseStoreProduct(storeProduct)
}
async purchaseFromGooglePlay(
productId: string,
basePlanId?: string,
offerId?: string
): Promise {
console.log("Kicking off purchase of ", productId, " base plan ID", basePlanId)
// Purchase logic
return await this._purchaseStoreProduct(storeProduct)
}
// 2
async restorePurchases(): Promise {
// TODO
// ----
// Restore purchases and return true if successful.
}
}
```
### SwiftUI - Use `PaywallView`
The `PaywallView` allows you to show a paywall by sending it a placement. It also has a dismiss handler where the purchased product will be vended:
```swift
@main
struct Caffeine_PalApp: App {
@State private var presentPaywall: Bool = false
init() {
Superwall.configure(apiKey: "my_api_key")
}
var body: some Scene {
WindowGroup {
Button("Log") {
presentPaywall.toggle()
}
.sheet(isPresented: $presentPaywall) {
PaywallView(placement: "caffeineLogged", params: nil, paywallOverrides: nil) { info, result in
switch result {
case .declined:
print("No purchased occurred.")
case .purchased(let product):
print("Purchased \(product.productIdentifier)")
case .restored:
print("Restored purchases.")
}
} feature: {
print("Converted")
presentPaywall.toggle()
}
}
}
}
}
```
---
# Custom Paywall Actions
Source: https://superwall.com/docs/flutter/guides/advanced/custom-paywall-actions
undefined
For example, adding a custom action called `help_center` to a button in your paywall gives you the opportunity to present a help center whenever that button is pressed. To set this up, implement `handleCustomPaywallAction(withName:)` in your `SuperwallDelegate`:
:::flutter
```dart
@override
void handleCustomPaywallAction(String name) {
if (name == "help_center") {
HelpCenterManager.present();
}
}
```
:::
Remember to set `Superwall.shared.delegate`! For implementation details, see the [Superwall Delegate](/using-superwall-delegate) guide.
---
# Retrieving and Presenting a Paywall Yourself
Source: https://superwall.com/docs/flutter/guides/advanced/presenting-paywalls
undefined
If you want complete control over the paywall presentation process, you can use `getPaywall(forPlacement:params:paywallOverrides:delegate:)`. This returns the `UIViewController` subclass `PaywallViewController`, which you can then present however you like. Or, you can use a SwiftUI `View` via `PaywallView`. The following is code is how you'd mimic [register](/docs/feature-gating):
```swift Swift
final class MyViewController: UIViewController {
private func presentPaywall() async {
do {
// 1
let paywallVc = try await Superwall.shared.getPaywall(
forPlacement: "campaign_trigger",
delegate: self
)
self.present(paywallVc, animated: true)
} catch let skippedReason as PaywallSkippedReason {
// 2
switch skippedReason {
case .holdout,
.noAudienceMatch,
.placementNotFound:
break
}
} catch {
// 3
print(error)
}
}
private func launchFeature() {
// Insert code to launch a feature that's behind your paywall.
}
}
// 4
extension MyViewController: PaywallViewControllerDelegate {
func paywall(
_ paywall: PaywallViewController,
didFinishWith result: PaywallResult,
shouldDismiss: Bool
) {
if shouldDismiss {
paywall.dismiss(animated: true)
}
switch result {
case .purchased,
.restored:
launchFeature()
case .declined:
let closeReason = paywall.info.closeReason
let featureGating = paywall.info.featureGatingBehavior
if closeReason != .forNextPaywall && featureGating == .nonGated {
launchFeature()
}
}
}
}
```
```swift Objective-C
@interface MyViewController : UIViewController
- (void)presentPaywall;
@end
@interface MyViewController ()
@end
@implementation MyViewController
- (void)presentPaywall {
// 1
[[Superwall sharedInstance] getPaywallForEvent:@"campaign_trigger" params:nil paywallOverrides:nil delegate:self completion:^(SWKGetPaywallResult * _Nonnull result) {
if (result.paywall != nil) {
[self presentViewController:result.paywall animated:YES completion:nil];
} else if (result.skippedReason != SWKPaywallSkippedReasonNone) {
switch (result.skippedReason) {
// 2
case SWKPaywallSkippedReasonHoldout:
case SWKPaywallSkippedReasonUserIsSubscribed:
case SWKPaywallSkippedReasonEventNotFound:
case SWKPaywallSkippedReasonNoRuleMatch:
case SWKPaywallSkippedReasonNone:
break;
};
} else if (result.error) {
// 3
NSLog(@"%@", result.error);
}
}];
}
-(void)launchFeature {
// Insert code to launch a feature that's behind your paywall.
}
// 4
- (void)paywall:(SWKPaywallViewController *)paywall didFinishWithResult:(enum SWKPaywallResult)result shouldDismiss:(BOOL)shouldDismiss {
if (shouldDismiss) {
[paywall dismissViewControllerAnimated:true completion:nil];
}
SWKPaywallCloseReason closeReason;
SWKFeatureGatingBehavior featureGating;
switch (result) {
case SWKPaywallResultPurchased:
case SWKPaywallResultRestored:
[self launchFeature];
break;
case SWKPaywallResultDeclined:
closeReason = paywall.info.closeReason;
featureGating = paywall.info.featureGatingBehavior;
if (closeReason != SWKPaywallCloseReasonForNextPaywall && featureGating == SWKFeatureGatingBehaviorNonGated) {
[self launchFeature];
}
break;
}
}
@end
```
```swift SwiftUI
import SuperwallKit
struct MyAwesomeApp: App {
@State var store: AppStore = .init()
init() {
Superwall.configure(apiKey: "MyAPIKey")
}
var body: some Scene {
WindowGroup {
ContentView()
.fullScreenCover(isPresented: $store.showPaywall) {
// You can just use 'placement' at a minimum. The 'feature'
// Closure fires if they convert
PaywallView(placement: "a_placement", onSkippedView: { skip in
switch skip {
case .userIsSubscribed,
.holdout(_),
.noRuleMatch,
.eventNotFound:
MySkipView()
}
}, onErrorView: { error in
MyErrorView()
}, feature: {
// User is subscribed as a result of the paywall purchase
// Or they already were (which would happen in `onSkippedView`)
})
}
}
}
}
```
```kotlin Kotlin
// This is an example of how to use `getPaywall` to use a composable`
import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.material3.CircularProgressIndicator
import androidx.compose.material3.Text
import androidx.compose.runtime.Composable
import androidx.compose.runtime.LaunchedEffect
import androidx.compose.runtime.mutableStateOf
import androidx.compose.runtime.remember
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.viewinterop.AndroidView
import com.superwall.sdk.Superwall
import com.superwall.sdk.paywall.presentation.get_paywall.getPaywall
import com.superwall.sdk.paywall.presentation.internal.request.PaywallOverrides
import com.superwall.sdk.paywall.vc.PaywallView
import com.superwall.sdk.paywall.vc.delegate.PaywallViewCallback
@Composable
fun PaywallComposable(
event: String,
params: Map? = null,
paywallOverrides: PaywallOverrides? = null,
callback: PaywallViewCallback,
errorComposable: @Composable ((Throwable) -> Unit) = { error: Throwable ->
// Default error composable
Text(text = "No paywall to display")
},
loadingComposable: @Composable (() -> Unit) = {
// Default loading composable
Box(modifier = Modifier.fillMaxSize()) {
Column(
modifier = Modifier.align(Alignment.Center),
verticalArrangement = Arrangement.Center,
horizontalAlignment = Alignment.CenterHorizontally
) {
CircularProgressIndicator()
}
}
}
) {
val viewState = remember { mutableStateOf(null) }
val errorState = remember { mutableStateOf(null) }
val context = LocalContext.current
LaunchedEffect(Unit) {
PaywallBuilder(event)
.params(params)
.overrides(paywallOverrides)
.delegate(delegate)
.activity(context as Activity)
.build()
.fold(onSuccess = {
viewState.value = it
}, onFailure = {
errorState.value = it
})
}
when {
viewState.value != null -> {
viewState.value?.let { viewToRender ->
DisposableEffect(viewToRender) {
viewToRender.onViewCreated()
onDispose {
viewToRender.beforeOnDestroy()
viewToRender.encapsulatingActivity = null
CoroutineScope(Dispatchers.Main).launch {
viewToRender.destroyed()
}
}
}
AndroidView(
factory = { context ->
viewToRender
}
)
}
}
errorState.value != null -> {
errorComposable(errorState.value!!)
}
else -> {
loadingComposable()
}
}
}
```
This does the following:
1. Gets the paywall view controller.
2. Handles the cases where the paywall was skipped.
3. Catches any presentation errors.
4. Implements the delegate. This is called when the user is finished with the paywall. First, it checks `shouldDismiss`. If this is true then is dismissed the paywall from view before launching any features. This may depend on the `result` depending on how you first presented your view. Then, it switches over the `result`. If the result is `purchased` or `restored` the feature can be launched. However, if the result is `declined`, it checks that the the `featureGating` property of `paywall.info` is `nonGated` and that the `closeReason` isn't `.forNextPaywall`.
### Best practices
1. **Make sure to prevent a paywall from being accessed after a purchase has occurred**.
If a user purchases from a paywall, it is your responsibility to make sure that the user can't access that paywall again. For example, if after successful purchase you decide to push a new view on to the navigation stack, you should make sure that the user can't go back to access the paywall.
2. **Make sure the paywall view controller deallocates before presenting it elsewhere**.
If you have a paywall view controller presented somewhere and you try to present
the same view controller elsewhere, you will get a crash. For example, you may
have a paywall in a tab bar controller, and then you also try to present it
modally. We plan on improving this, but currently it's your responsibility to
ensure this doesn't happen.
---
# Game Controller Support
Source: https://superwall.com/docs/flutter/guides/advanced/game-controller-support
undefined
:::android
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```kotlin
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
:::flutter
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```dart
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
:::expo
First set the `SuperwallOption` `isGameControllerEnabled` to `true`:
```typescript
Superwall.instance.options.isGameControllerEnabled = true
```
Then Superwall will automatically listen for gamepad events and forward them to your paywall!
:::
---
# Experimental Flags
Source: https://superwall.com/docs/flutter/guides/experimental-flags
undefined
Experimental flags in Superwall's SDK allow you to opt into features that are safe for production but are still being refined. These features may undergo naming changes or internal restructuring in future SDK versions. We expose them behind flags to give you early access while preserving flexibility for ongoing development.
These flags are configured via the `SuperwallOptions` struct:
```swift
let options = SuperwallOptions()
options.enableExperimentalDeviceVariables = true
Superwall.configure(apiKey: "my_api_key",
options: options)
```
## Available experimental flags
When these flags are enabled and the user runs your app, these values become available in campaign filters. Currently, these include:
**Latest Subscription Period Type (String)**:
Represents whether the user is in a trial, promotional, or a similar phase. Possible values include:
* `trial`
* `code`
* `subscription`
* `promotional`
* `winback`
* `revoked`
Represented as `latestSubscriptionPeriodType` in campaign filters.
**Latest Subscription State (String)**:
Represents what *state* the actual subscription is in. Possible values include:
* `inGracePeriod`
* `subscribed`
* `expired`
* `inBillingRetryPeriod`
* `revoked`
Represented as `latestSubscriptionState` in campaign filters.
**Latest Subscription Will Auto Renew (Bool)**:
If the user is set to renew or not. Either `true` or `false`
Represented as `latestSubscriptionWillAutoRenew` in campaign filters.
### Detecting users who've cancelled an active trial
One common use case for these flags is detecting users who've cancelled an active trial. In that case, the filter in the campaign would check for `latestSubscriptionWillAutoRenew` to be `false` and `latestSubscriptionPeriodType` to be `trial`.
:::flutter
### Platform Availability
These variables are currently only available on **iOS**, support for Android is not yet available.
:::
---
# Advanced Purchasing
Source: https://superwall.com/docs/flutter/guides/advanced-configuration
If you need fine-grain control over the purchasing pipeline, use a purchase controller to manually handle purchases and subscription status.
Using a `PurchaseController` is only recommended for **advanced** use cases. By default, Superwall handles all
subscription-related logic and purchasing operations for you out of the box.
By default, Superwall handles basic subscription-related logic for you:
1. **Purchasing**: When the user initiates a checkout on a paywall.
2. **Restoring**: When the user restores previously purchased products.
3. **Subscription Status**: When the user's subscription status changes to active or expired (by checking the local receipt).
However, if you want more control, you can pass in a `PurchaseController` when configuring the SDK via `configure(apiKey:purchaseController:options:)` and manually set `Superwall.shared.subscriptionStatus` to take over this responsibility.
### Step 1: Creating a `PurchaseController`
A `PurchaseController` handles purchasing and restoring via protocol methods that you implement.
:::flutter
```dart Flutter
// MyPurchaseController.dart
class MyPurchaseController extends PurchaseController {
// 1
@override
Future purchaseFromAppStore(String productId) async {
// TODO
// ----
// Purchase via StoreKit, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.purchased;
}
@override
Future purchaseFromGooglePlay(
String productId,
String? basePlanId,
String? offerId
) async {
// TODO
// ----
// Purchase via Google Billing, RevenueCat, Qonversion or however
// you like and return a valid PurchaseResult
return PurchaseResult.purchased;
}
// 2
@override
Future restorePurchases() async {
// TODO
// ----
// Restore purchases and return true if successful.
return RestorationResult.restored;
}
}
```
:::
Here’s what each method is responsible for:
1. Purchasing a given product. In here, enter your code that you use to purchase a product. Then, return the result of the purchase as a `PurchaseResult`. For Flutter, this is separated into purchasing from the App Store and Google Play. This is an enum that contains the following cases, all of which must be handled:
1. `.cancelled`: The purchase was cancelled.
2. `.purchased`: The product was purchased.
3. `.pending`: The purchase is pending/deferred and requires action from the developer.
4. `.failed(Error)`: The purchase failed for a reason other than the user cancelling or the payment pending.
2. Restoring purchases. Here, you restore purchases and return a `RestorationResult` indicating whether the restoration was successful or not. If it was, return `.restore`, or `failed` along with the error reason.
### Step 2: Configuring the SDK With Your `PurchaseController`
Pass your purchase controller to the `configure(apiKey:purchaseController:options:)` method:
:::flutter
```dart Flutter
// main.dart
void initState() {
// Determine Superwall API Key for platform
String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";
// Create the purchase controller
MyPurchaseController purchaseController = MyPurchaseController();
Superwall.configure(apiKey, purchaseController);
}
```
:::
### Step 3: Keeping `subscriptionStatus` Up-To-Date
You **must** set `Superwall.shared.subscriptionStatus` every time the user's subscription status changes, otherwise the SDK won't know who to show a paywall to. This is an enum that has three possible cases:
1. **`.unknown`**: This is the default value. In this state, paywalls will not show and their presentation will be ***automatically delayed*** until `subscriptionStatus` changes to a different value.
2. **`.active(let entitlements)`**: Indicates that the user has an active entitlement. Paywalls will not show in this state unless you remotely set the paywall to ignore subscription status. A user can have one or more active entitlement.
3. **`.inactive`**: Indicates that the user doesn't have an active entitlement. Paywalls can show in this state.
Here's how you might do this:
:::flutter
```dart Flutter
// When a subscription is purchased, restored, validated, expired, etc...
myService.addSubscriptionStatusListener((subscriptionInfo) {
var entitlements = subscriptionInfo.entitlements.active.keys
.map((id) => Entitlement(id: id))
.toSet();
var hasActiveSubscription = subscriptionInfo.isActive;
if (hasActiveSubscription) {
Superwall.shared.setSubscriptionStatus(SubscriptionStatusActive(entitlements: entitlements));
} else {
Superwall.shared.setSubscriptionStatus(SubscriptionStatusInactive());
}
});
```
:::
`subscriptionStatus`
is cached between app launches
### Listening for subscription status changes
If you need a simple way to observe when a user's subscription status changes, on iOS you can use the `Publisher` for it. Here's an example:
:::flutter
```dart Flutter
Superwall.shared.subscriptionStatus.listen((status) {
// React to changes
}
//Or use SuperwallBuilder widget which triggers the builder closure when subscription status changes
SuperwallBuilder(
builder: (context, status) => Center(
child: Text('Subscription Status: ${status}'),
)
)
```
:::
You can do similar tasks with the `SuperwallDelegate`, such as [viewing which product was purchased from a paywall](/3rd-party-analytics#using-events-to-see-purchased-products).
### Product Overrides
Product overrides allow you to dynamically substitute products on paywalls without modifying the paywall design in the Superwall dashboard.
When using a `PurchaseController`, you may want to override specific products shown on your paywalls. This is useful for:
* A/B testing different subscription tiers
* Showing region-specific products
* Dynamically changing products based on user segments
* Testing promotional pricing without modifying paywalls
**How Product Overrides Work:**
1. Product names (e.g., "primary", "secondary") must match exactly as defined in the Superwall dashboard's Paywall Editor
2. The SDK substitutes the original product IDs with your override IDs before fetching from the App Store
3. The paywall maintains its visual design while showing the substituted products
4. Your `PurchaseController` will receive the overridden products when `purchase(product:)` is called
Product overrides only affect the products shown on paywalls. They don't change your subscription logic or entitlement validation.
---
# Cohorting in 3rd Party Tools
Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/cohorting-in-3rd-party-tools
To easily view Superwall cohorts in 3rd party tools, we recommend you set user attributes based on the experiments that users are included in. You can also use custom placements for creating analytics events for actions such as interacting with an element on a paywall.
:::android
```kotlin Kotlin
override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
when(eventInfo.event) {
is SuperwallEvent.TriggerFire -> {
MyAnalyticsService.shared.setUserAttributes(
mapOf(
"sw_experiment_${eventInfo.params.get("experiment_id").toString()}" to true,
"sw_variant_${eventInfo.params.get("variant_id").toString()}" to true
)
)
}
else -> {}
}
}
```
:::
:::flutter
```dart Flutter
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
final experimentId = eventInfo.params?['experiment_id'];
final variantId = eventInfo.params?['variant_id'];
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
"sw_experiment_$experimentId": true,
"sw_variant_$variantId": true
});
break;
default:
break;
}
}
```
:::
:::expo
```typescript React Native
handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
const experimentId = eventInfo.params?['experiment_id']
const variantId = eventInfo.params?['variant_id']
if (!experimentId || !variantId) {
return
}
switch (eventInfo.event.type) {
case EventType.triggerFire:
MyAnalyticsService.shared.setUserAttributes({
`sw_experiment_${experimentId}`: true,
`sw_variant_${variantId}`: true
});
break;
default:
break;
}
}
```
:::
Once you've set this up, you can easily ask for all users who have an attribute `sw_experiment_1234` and breakdown by both variants to see how users in a Superwall experiment behave in other areas of your app.
---
# Custom Paywall Analytics
Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/custom-paywall-analytics
Learn how to log events from paywalls, such as a button tap or product change, to forward to your analytics service.
You can create customized analytics tracking for any paywall event by using custom placements. With them, you can get callbacks for actions such as interacting with an element on a paywall sent to your [Superwall delegate](/using-superwall-delegate). This can be useful for tracking how users interact with your paywall and how that affects their behavior in other areas of your app.
For example, in the paywall below, perhaps you're interested in tracking when people switch the plan from "Standard" and "Pro":
You could create a custom placement [tap behavior](/paywall-editor-styling-elements#tap-behaviors) which fires when a segment is tapped:
Then, you can listen for this placement and forward it to your analytics service:
```swift Swift
extension SuperwallService: SuperwallDelegate {
func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
switch eventInfo.event {
case let .customPlacement(name, params, paywallInfo):
// Prints out didTapPro or didTapStandard
print("\(name) - \(params) - \(paywallInfo)")
MyAnalyticsService.shared.send(event: name, params: params)
default:
print("Default event: \(eventInfo.event.description)")
}
}
}
```
For a walkthrough example, check out this [video on YouTube](https://youtu.be/4rM1rGRqDL0).
---
# Superwall Events
Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/tracking-analytics
The SDK automatically tracks some events, which power the charts in the dashboard.
We encourage you to track them in your own analytics as described in [3rd Party Analytics](/3rd-party-analytics).
The following Superwall events can be used as placements to present paywalls:
* `app_install`
* `app_launch`
* `deepLink_open`
* `session_start`
* `paywall_decline`
* `transaction_fail`
* `transaction_abandon`
* `survey_response`
For more info about how to use these, check out [how to add them using a Placement](/campaigns-placements#adding-a-placement).
The full list of events is as follows:
| **Event Name** | **Action** | **Parameters** |
| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `adServicesTokenRequestComplete` | When the AdServices token request finishes. | `["token": String]` |
| `adServicesTokenRequestFail` | When the AdServices token request fails. | `["error": Error]` |
| `adServicesTokenRequestStart` | When the AdServices token request starts. | None |
| `app_close` | Anytime the app leaves the foreground. | Same as `app_install` |
| `app_install` | When the SDK is configured for the first time. | `["is_superwall": true, "app_session_id": String, "using_purchase_controller": Bool]` |
| `app_launch` | When the app is launched from a cold start. | Same as `app_install` |
| `app_open` | Anytime the app enters the foreground. | Same as `app_install` |
| `configAttributes` | When the attributes affecting Superwall's configuration are set or changed. | None |
| `configFail` | When the Superwall configuration fails to be retrieved. | None |
| `configRefresh` | When the Superwall configuration is refreshed. | None |
| `confirmAllAssignments` | When all experiment assignments are confirmed. | None |
| `customPlacement` | When the user taps on an element in the paywall that has a `custom_placement` action. | `["name": String, "params": [String: Any], "paywallInfo": PaywallInfo]` |
| [`deepLink_open`](/campaigns-standard-placements#using-the-deeplink-open-event) | When a user opens the app via a deep link. | `["url": String, "path": String", "pathExtension": String, "lastPathComponent": String, "host": String, "query": String, "fragment": String]` + any query parameters in the deep link URL |
| `device_attributes` | When device attributes are sent to the backend every session. | Includes `app_session_id`, `app_version`, `os_version`, `device_model`, `device_locale`, and various hardware/software details. |
| `first_seen` | When the user is first seen in the app, regardless of login status. | Same as `app_install` |
| `freeTrial_start` | When a user completes a transaction for a subscription product with an introductory offer. | Same as `subscription_start` |
| `identityAlias` | When the user's identity aliases after calling `identify`. | None |
| `nonRecurringProduct_purchase` | When the user purchases a non-recurring product. | Same as `subscription_start` |
| `paywall_close` | When a paywall is closed (either manually or after a transaction succeeds). | \[“paywall\_webview\_load\_complete\_time”: String?, “paywall\_url”: String, “paywall\_response\_load\_start\_time”: String?, “paywall\_products\_load\_fail\_time”: String?, “secondary\_product\_id”: String, “feature\_gating”: Int, “paywall\_response\_load\_complete\_time”: String?, “is\_free\_trial\_available”: Bool, “is\_superwall”: true, “presented\_by”: String, “paywall\_name”: String, “paywall\_response\_load\_duration”: String?, “paywall\_identifier”: String, “paywall\_webview\_load\_start\_time”: String?, “paywall\_products\_load\_complete\_time”: String?, “paywall\_product\_ids”: String, “tertiary\_product\_id”: String, “paywall\_id”: String, “app\_session\_id”: String, “paywall\_products\_load\_start\_time”: String?, “primary\_product\_id”: String, “survey\_attached”: Bool, “survey\_presentation”: String?] |
| [`paywall_decline`](/campaigns-standard-placements#using-the-paywall-decline-event) | When a user manually dismisses a paywall. | Same as `paywall_close` |
| `paywall_open` | When a paywall is opened. | Same as `paywall_close` |
| `paywallPresentationRequest` | When something happened during the paywall presentation, whether a success or failure. | `[“source_event_name”: String, “status”: String, “is_superwall”: true, “app_session_id”: String, “pipeline_type”: String, “status_reason”: String]` |
| `paywallProductsLoad_complete` | When the request to load a paywall's products completes. | Same as `paywallResponseLoad_start` |
| `paywallProductsLoad_fail` | When the request to load a paywall's products fails. | Same as `paywallResponseLoad_start` |
| `paywallProductsLoad_retry` | When the request to load a paywall's products fails and is being retried. | `["triggeredPlacementName": String?, "paywallInfo": PaywallInfo, "attempt": Int]` |
| `paywallProductsLoad_start` | When the request to load a paywall's products starts. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_complete` | When a paywall request to Superwall's servers completes. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_fail` | When a paywall request to Superwall's servers fails. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_notFound` | When a paywall request returns a 404 error. | Same as `paywallResponseLoad_start` |
| `paywallResponseLoad_start` | When a paywall request to Superwall's servers has started. | Same as `app_install` + `["is_triggered_from_event": Bool]` |
| `paywallWebviewLoad_complete` | When a paywall's webpage completes loading. | Same as `paywall_close` |
| `paywallWebviewLoad_fail` | When a paywall's webpage fails to load. | Same as `paywall_close` |
| `paywallWebviewLoad_fallback` | When a paywall's webpage fails and loads a fallback version. | Same as `paywall_close` |
| `paywallWebviewLoad_start` | When a paywall's webpage begins to load. | Same as `paywall_close` |
| `paywallWebviewLoad_processTerminated` | When the paywall's web view content process terminates. | Same as `paywall_close` |
| `reset` | When `Superwall.reset()` is called. | None |
| `restoreComplete` | When a restore completes successfully. | None |
| `restoreFail` | When a restore fails. | `["message": String]` |
| `restoreStart` | When a restore is initiated. | None |
| `session_start` | When the app is opened after at least 60 minutes since last `app_close`. | Same as `app_install` |
| `shimmerViewComplete` | When the shimmer view stops showing. | None |
| `shimmerViewStart` | When the shimmer view starts showing. | None |
| `subscription_start` | When a user completes a transaction for a subscription product without an introductory offer. | \[“product\_period\_days”: String, “product\_price”: String, “presentation\_source\_type”: String?, “paywall\_response\_load\_complete\_time”: String?, “product\_language\_code”: String, “product\_trial\_period\_monthly\_price”: String, “paywall\_products\_load\_duration”: String?, “product\_currency\_symbol”: String, “is\_superwall”: true, “app\_session\_id”: String, “product\_period\_months”: String, “presented\_by\_event\_id”: String?, “product\_id”: String, “trigger\_session\_id”: String, “paywall\_webview\_load\_complete\_time”: String?, “paywall\_response\_load\_start\_time”: String?, “product\_raw\_trial\_period\_price”: String, “feature\_gating”: Int, “paywall\_id”: String, “product\_trial\_period\_daily\_price”: String, “product\_period\_years”: String, “presented\_by”: String, “product\_period”: String, “paywall\_url”: String, “paywall\_name”: String, “paywall\_identifier”: String, “paywall\_products\_load\_start\_time”: String?, “product\_trial\_period\_months”: String, “product\_currency\_code”: String, “product\_period\_weeks”: String, “product\_periodly”: String, “product\_trial\_period\_text”: String, “paywall\_webview\_load\_start\_time”: String?, “paywall\_products\_load\_complete\_time”: String?, “primary\_product\_id”: String, “product\_trial\_period\_yearly\_price”: String, “paywalljs\_version”: String?, “product\_trial\_period\_years”: String, “tertiary\_product\_id”: String, “paywall\_products\_load\_fail\_time”: String?, “product\_trial\_period\_end\_date”: String, “product\_weekly\_price”: String, “variant\_id”: String, “presented\_by\_event\_timestamp”: String?, “paywall\_response\_load\_duration”: String?, “secondary\_product\_id”: String, “product\_trial\_period\_days”: String, “product\_monthly\_price”: String, “paywall\_product\_ids”: String, “product\_locale”: String, “product\_daily\_price”: String, “product\_raw\_price”: String, “product\_yearly\_price”: String, “product\_trial\_period\_price”: String, “product\_localized\_period”: String, “product\_identifier”: String, “experiment\_id”: String, “is\_free\_trial\_available”: Bool, “product\_trial\_period\_weeks”: String, “paywall\_webview\_load\_duration”: String?, “product\_period\_alt”: String, “product\_trial\_period\_weekly\_price”: String, “presented\_by\_event\_name”: String?] |
| `subscriptionStatus_didChange` | When a user's subscription status changes. | `["is_superwall": true, "app_session_id": String, "subscription_status": String]` |
| `surveyClose` | When the user chooses to close a survey instead of responding. | None |
| [`survey_response`](/campaigns-standard-placements#using-the-survey-response-event) | When a user responds to a paywall survey. | `["survey_selected_option_title": String, "survey_custom_response": String, "survey_id": String, "survey_assignment_key": String, "survey_selected_option_id": String]` |
| `touches_began` | When the user touches the app's UIWindow for the first time (if tracked by a campaign). | Same as `app_install` |
| `transaction_abandon` | When the user cancels a transaction. | Same as `subscription_start` |
| `transaction_complete` | When the user completes checkout and any product is purchased. | Same as subscription\_start + \[“web\_order\_line\_item\_id”: String, “app\_bundle\_id”: String, “config\_request\_id”: String, “state”: String, “subscription\_group\_id”: String, “is\_upgraded”: String, “expiration\_date”: String, “trigger\_session\_id”: String, “original\_transaction\_identifier”: String, “id”: String, “transaction\_date”: String, “is\_superwall”: true, “store\_transaction\_id”: String, “original\_transaction\_date”: String, “app\_session\_id”: String] |
| `transaction_fail` | When the payment sheet fails to complete a transaction (ignores user cancellation). | Same as `subscription_start` + `["message": String]` |
| `transaction_restore` | When the user successfully restores their purchases. | Same as `subscription_start` |
| `transaction_start` | When the payment sheet is displayed to the user. | Same as `subscription_start` |
| `transaction_timeout` | When the transaction takes longer than 5 seconds to display the payment sheet. | `["paywallInfo": PaywallInfo]` |
| `trigger_fire` | When a registered placement triggers a paywall. | `[“trigger_name”: String, “trigger_session_id”: String, “variant_id”: String?, “experiment_id”: String?, “paywall_identifier”: String?, “result”: String, “unmatched_rule_”: “”]. unmatched_rule_ indicates why a rule (with a specfiic experiment id) didn’t match. It will only exist if the result is no_rule_match. Its outcome will either be OCCURRENCE, referring to the limit applied to a rule, or EXPRESSION.` |
| `user_attributes` | When the user attributes are set. | `[“aliasId”: String, “seed”: Int, “app_session_id”: String, “applicationInstalledAt”: String, “is_superwall”: true, “application_installed_at”: String] + provided attributes` |
---
# 3rd Party Analytics
Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics
undefined
### Hooking up Superwall events to 3rd party tools
SuperwallKit automatically tracks some internal events. You can [view the list of events here](/tracking-analytics). We encourage you to also track them in your own analytics by implementing the [Superwall delegate](/using-superwall-delegate). Using the `handleSuperwallEvent(withInfo:)` function, you can forward events to your analytics service:
:::flutter
```dart
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
print("handleSuperwallEvent: $eventInfo");
// Example usage...
switch (eventInfo.event.type) {
case EventType.appOpen:
print("appOpen event");
case EventType.deviceAttributes:
print("deviceAttributes event: ${eventInfo.event.deviceAttributes} ");
case EventType.paywallOpen:
final paywallInfo = eventInfo.event.paywallInfo;
print("paywallOpen event: ${paywallInfo} ");
if (paywallInfo != null) {
final identifier = await paywallInfo.identifier;
print("paywallInfo.identifier: ${identifier} ");
final productIds = await paywallInfo.productIds;
print("paywallInfo.productIds: ${productIds} ");
}
default:
break;
}
}
```
:::
You might also want to set user attribute to allow for [Cohorting in 3rd Party
Tools](/cohorting-in-3rd-party-tools)
Alternatively, if you want typed versions of all these events with associated values, you can access them via `eventInfo.event`:
:::flutter
```dart
@override
void handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
// Example usage...
switch (eventInfo.event.type) {
case PlacementType.appOpen:
print("appOpen event");
case PlacementType.deviceAttributes:
print("deviceAttributes event: ${eventInfo.event.deviceAttributes} ");
case PlacementType.paywallOpen:
final paywallInfo = eventInfo.event.paywallInfo;
print("paywallOpen event: ${paywallInfo} ");
if (paywallInfo != null) {
final identifier = await paywallInfo.identifier;
print("paywallInfo.identifier: ${identifier} ");
final productIds = await paywallInfo.productIds;
print("paywallInfo.productIds: ${productIds} ");
}
default:
break;
}
}
```
:::
Wanting to use events to see which product was purchased on a paywall? Check out this
[doc](/viewing-purchased-products).
---
# Using Superwall Deep Links
Source: https://superwall.com/docs/flutter/guides/superwall-deep-links
(iOS only) How to use Superwall Deep Links to trigger paywalls or custom in-app behavior.
A Superwall Deep Link is a URL hosted at `https://.superwall.app/app-link/...` that opens your app to trigger a paywall as configured on the Superwall dashboard, or custom in-app behavior via the Superwall delegate.
## Prerequisites
:::flutter
1. Set up [deep link handling](/flutter/quickstart/in-app-paywall-previews)
:::
2. Create a [Web Checkout app](/web-checkout/web-checkout-creating-an-app), even if you do not plan to charge through Web Checkout, this provisions the `*.superwall.app` domain that powers Superwall Deep Links.
## Handling incoming links
* Always call `handleDeepLink` first. It returns `true` when the SDK recognizes the URL and plans to take over presentation, or `false` when you should continue routing inside your own app.
* When a recognized link arrives before `Superwall.configure(...)` finishes, the SDK caches it and replays it immediately after configuration completes, so it is safe to forward links during cold launch.
* If the return value is `false`, continue with your normal router—those links are not associated with any Superwall experience.
:::flutter
```dart
Future _handleIncomingLink(Uri uri) async {
final handled = await Superwall.shared.handleDeepLink(uri);
if (!handled) {
_routeInternally(uri);
}
}
void _listenForLinks() {
uriLinkStream.listen((uri) {
if (uri != null) {
_handleIncomingLink(uri);
}
});
}
```
:::
## Link formats and campaigns
Deep link URLs are hosted at `https://.superwall.app/app-link/...`, you can have anything after the `/app-link/` path, including query parameters. These values will be availble to you in audience filters on the Superwall dashboard, or in the `handleSuperwallDeepLink` delegate method.
:::flutter
```dart
class PaywallDelegate extends SuperwallDelegate {
@override
void handleSuperwallDeepLink(
Uri fullURL,
List pathComponents,
Map queryParameters,
) {
if (pathComponents.isEmpty) {
return;
}
switch (pathComponents.first) {
case 'campaign':
final placementId =
pathComponents.length > 1 ? pathComponents[1] : null;
if (placementId != null) {
_routeToPlacement(placementId, queryParameters);
}
break;
default:
break;
}
}
}
```
:::
Keep your own routing logic in place for non-Superwall URLs and for any additional behaviors you want to stack on top of Superwall’s default presentation flow.
---
# Advanced Configuration
Source: https://superwall.com/docs/flutter/guides/configuring
When configuring the SDK you can pass in options that configure Superwall, the paywall presentation, and its appearance.
### Logging
Logging is enabled by default in the SDK and is controlled by two properties: `level` and `scopes`.
`level` determines the minimum log level to print to the console. There are five types of log level:
1. **debug**: Prints all logs from the SDK to the console. Useful for debugging your app if something isn't working as expected.
2. **info**: Prints errors, warnings, and useful information from the SDK to the console.
3. **warn**: Prints errors and warnings from the SDK to the console.
4. **error**: Only prints errors from the SDK to the console.
5. **none**: Turns off all logs.
The SDK defaults to `info`.
`scopes` defines the scope of logs to print to the console. For example, you might only care about logs relating to `paywallPresentation` and `paywallTransactions`. This defaults to `.all`. Check out [LogScope](https://sdk.superwall.me/documentation/superwallkit/logscope) for all possible cases.
You set these properties like this:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.logging.level = LogLevel.warn;
options.logging.scopes = { LogScope.paywallPresentation, LogScope.paywallEvents };
Superwall.configure(
"MY_API_KEY",
options: options
);
// Or you can set:
Superwall.logging.logLevel = LogLevel.warn;
```
:::
### Preloading Paywalls
Paywalls are preloaded by default when the app is launched from a cold start. The paywalls that are preloaded are determined by the list of placements that result in a paywall for the user when [registered](/docs/feature-gating). Preloading is smart, only preloading paywalls that belong to audiences that could be matched.
Paywalls are cached by default, which means after they load once, they don't need to be reloaded from the network unless you make a change to them on the dashboard. However, if you have a lot of paywalls, preloading may increase network usage of your app on first load of the paywalls and result in slower loading times overall.
You can turn off preloading by setting `shouldPreload` to `false`:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.shouldPreload = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
Then, if you'd like to preload paywalls for specific placements you can use `preloadPaywalls(forPlacements:)`:
:::flutter
```dart
var placements = {"campaign_trigger"};
Superwall.shared.preloadPaywallsForPlacements(placements);
```
:::
If you'd like to preload all paywalls you can use `preloadAllPaywalls()`:
:::flutter
```dart
Superwall.shared.preloadAllPaywalls();
```
:::
Note: These methods will not reload any paywalls that have already been preloaded.
### External Data Collection
By default, Superwall sends all registered events and properties back to the Superwall servers. However, if you have privacy concerns, you can stop this by setting `isExternalDataCollectionEnabled` to `false`:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.isExternalDataCollectionEnabled = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
Disabling this will not affect your ability to create triggers based on properties.
### Automatically Dismissing the Paywall
By default, Superwall automatically dismisses the paywall when a product is purchased or restored. You can disable this by setting `automaticallyDismiss` to `false`:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.automaticallyDismiss = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
To manually dismiss the paywall , call `Superwall.shared.dismiss()`.
### Custom Restore Failure Message
You can set the title, message and close button title for the alert that appears after a restoration failure:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.restoreFailed.title = "My Title";
options.paywalls.restoreFailed.message = "My message";
options.paywalls.restoreFailed.closeButtonTitle = "Close";
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
### Haptic Feedback
On iOS, the paywall uses haptic feedback by default after a user purchases or restores a product, opens a URL from the paywall, or closes the paywall. To disable this, set the `isHapticFeedbackEnabled` `PaywallOption` to false:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.isHapticFeedbackEnabled = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
Note: Android does not use haptic feedback.
### Transaction Background View
During a transaction, we add a `UIActivityIndicator` behind the view to indicate a loading status. However, you can remove this by setting the `transactionBackgroundView` to `nil`:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.transactionBackgroundView = TransactionBackgroundView.none;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
### Purchase Failure Alert
When a purchase fails, we automatically present an alert with the error message. If you'd like to show your own alert after failure, set the `shouldShowPurchaseFailureAlert` `PaywallOption` to `false`:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.shouldShowPurchaseFailureAlert = false;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
### Web Purchase Confirmation Alert
When a user completes a purchase via web checkout (app2web flow), you can control whether to show a confirmation alert. By default, this is set to `false` to prevent duplicate alerts. Set `shouldShowWebPurchaseConfirmationAlert` to `true` if you want to show the native confirmation alert:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.paywalls.shouldShowWebPurchaseConfirmationAlert = true;
Superwall.configure(
"MY_API_KEY",
options: options
);
```
:::
### Locale Identifier
When evaluating rules, the device locale identifier is set to `autoupdatingCurrent`. However, you can override this if you want to test a specific locale:
:::flutter
```dart
SuperwallOptions options = SuperwallOptions();
options.localeIdentifier = "en_GB";
Superwall.configure(
"MY_API_KEY",
options: options
);
// Or you can set:
Superwall.shared.setLocaleIdentifier("en_GB");
// To revert to default:
Superwall.shared.setLocaleIdentifier(null);
```
:::
For a list of locales that are available on iOS, take a look at [this list](https://gist.github.com/jacobbubu/1836273). You can also preview your paywall in different locales using [In-App Previews](/docs/in-app-paywall-previews).
### Game Controller
If you're using a game controller, you can enable this in `SuperwallOptions` too. Check out our [Game Controller Support](/docs/game-controller-support) article.
Take a look at [SuperwallOptions](https://sdk.superwall.me/documentation/superwallkit/superwalloptions) in our SDK reference for more info.
---
# StoreKit testing (iOS only)
Source: https://superwall.com/docs/flutter/guides/testing-purchases
How to set up StoreKit testing for iOS when using the Flutter SDK.
StoreKit testing in Xcode is a local test environment for testing in-app purchases without requiring a connection to App Store servers. Set up in-app purchases in a local StoreKit configuration file in your Xcode project, or create a synced StoreKit configuration file in Xcode from your in-app purchase settings in App Store Connect. After you enable the configuration file, the test environment uses this local data on your paywalls when your app calls StoreKit APIs.
### Add a StoreKit Configuration File
Go to **File ▸ New ▸ File...** in the menu bar , select **StoreKit Configuration File** and hit **Next**:
Give it the name **Products**. For a configuration file synced with an app on App Store Connect, select the checkbox, specify your team and app in the drop-down menus that appear, then click **Next**. For a local configuration, leave the checkbox unselected, then click **Next**. Save the file in the top-level folder of your project. You don't need to add it to your target.
### Create a New Scheme for StoreKit Testing
It's best practice to create a new scheme in Xcode to be used for StoreKit testing. This allows you to separate out staging and production environments.
Click the scheme in the scheme menu and click **Manage Schemes...**:
If you haven't already got a Staging scheme, select your current scheme and click **Duplicate**:
In the scheme editor, add the StoreKit Configuration file to your scheme by clicking on **Run** in the side bar, selecting the **Options** tab and choosing your configuration file in **StoreKit Configuration**. Then, click **Close**:
You can rename your scheme to **MyAppName (Staging)**.
### Setting up the StoreKit Configuration File
If you've chosen to sync your configuration file with the App Store, your apps will automatically be loaded into your StoreKit Configuration file. When you add new products, just sync again.
If you're using a local configuration, open **Products.storekit**, click the **+** button at the bottom and create a new product. In this tutorial, we'll create an auto-renewable subscription:
Enter a name for a new subscription group and click **Done**. The subscription group name should match one that is set up for your app in App Store Connect, but it's not a requirement. That means you can test your subscription groups and products in the simulator and then create the products in App Store Connect later:
Configure the subscription as needed by filling in the **Reference Name**, **Product ID**, **Price**, **Subscription Duration**, and optionally an **Introductory Offer**. Again, this product doesn't have to exist in App Store Connect for you to test purchasing in the simulator. Here is a sample configuration:
Repeat this for all of your products. When configuring a paywall, the product ID you enter here must match the product ID on the paywall.
You're now all set!
## Testing purchases with Transaction Manager
Once you've set up your StoreKit configuration file, you can leverage Xcode's Transaction Manager. Find it under **Debug -> StoreKit -> Manage Transactions...**:
Use this to quickly test purchasing your products. Once you make a purchase, you can open Transaction Manager to delete it, refund it, request parental approval and much more. Most commonly, you'll probably delete the transaction to reset your subscription state:
This makes everything a little faster, saving you the trouble of having to delete and reinstall your app to test these states. If you'd like to see a video over how to use it, check this one out:
---
# Using the Superwall Delegate
Source: https://superwall.com/docs/flutter/guides/using-superwall-delegate
undefined
Use Superwall's delegate to extend our SDK's functionality across several surface areas by assigning to the `delegate` property:
:::flutter
```dart
import 'package:superwall_flutter/superwall_flutter.dart';
class SWDelegate extends SuperwallDelegate {
// Implement delegate methods here
}
// When configuring the SDK...
void configureSDK() {
Superwall.shared.setDelegate(SWDelegate());
}
```
:::
Some common use cases for using the Superwall delegate include:
* **Custom actions:** [Respond to custom tap actions from a paywall.](/custom-paywall-events#custom-paywall-actions)
* **Respond to purchases:** [See which product was purchased from the presented paywall.](/viewing-purchased-products)
* **Analytics:** [Forward events from Superwall to your own analytics.](/3rd-party-analytics)
Below are some commonly used implementations when using the delegate.
### Superwall Events
Most of what occurs in Superwall can be viewed using the delegate method to respond to events:
:::flutter
```dart
class _MyAppState extends State implements SuperwallDelegate {
@override
Future handleSuperwallEvent(SuperwallEventInfo eventInfo) async {
switch (eventInfo.event.type) {
// Handle any other event types as needed
case PlacementType.transactionComplete:
final product = eventInfo.params?['product'];
logging.info('Transaction complete event received with product: $product');
break;
default:
logging.info('Unhandled event type: ${eventInfo.event.type}');
break;
}
}
}
```
:::
### Paywall Custom Actions
Using the [custom tap action](/custom-paywall-events), you can respond to any arbitrary event from a paywall:
:::flutter
```dart
class _MyAppState extends State implements SuperwallDelegate {
final logging = Logging();
@override
void handleCustomPaywallAction(String name) {
logging.info('handleCustomPaywallAction: $name');
}
}
```
:::
### Subscription status changes
You can be informed of subscription status changes using the delegate. If you need to set or handle the status on your own, use a [purchase controller](/advanced-configuration) — this function is only for informational, tracking or similar purposes:
:::flutter
```dart
class _MyAppState extends State implements SuperwallDelegate {
final logging = Logging();
@override
void subscriptionStatusDidChange(SubscriptionStatus newValue) {
logging.info('subscriptionStatusDidChange: $newValue');
}
}
```
:::
### Paywall events
The delegate also has callbacks for several paywall events, such dismissing, presenting, and more. Here's an example:
:::flutter
```dart
class _MyAppState extends State implements SuperwallDelegate {
final logging = Logging();
@override
void didPresentPaywall(PaywallInfo paywallInfo) {
logging.info('didPresentPaywall: $paywallInfo');
}
}
```
:::
---
# Vibe Coding
Source: https://superwall.com/docs/flutter/guides/vibe-coding
How to Vibe Code using the knowledge of the Superwall Docs
## Overview
We've built a few tools to help you Vibe Code using the knowledge of the Superwall Docs, right in your favorite AI tools:
* [Superwall Docs MCP](#superwall-docs-mcp) in Claude Code, Cursor, etc.
* [Superwall Docs GPT](#superwall-docs-gpt) in ChatGPT
And right here in the Superwall Docs:
* [Ask AI](#ask-ai)
* [Docs Links](#docs-links)
* [LLMs.txt](#llmstxt)
## Superwall Docs MCP
The Superwall Docs MCP ([Model Context Protocol](https://modelcontextprotocol.io/docs/tutorials/use-remote-mcp-server)) is a tool that allows your favorite AI tools to search the Superwall Docs and get context from the docs.
### Cursor
You can install the MCP server in Cursor by clicking this button:
[](https://cursor.com/en/install-mcp?name=superwall-docs-mcp\&config=eyJ1cmwiOiJodHRwczovL21jcC5zdXBlcndhbGwuY29tL21jcCJ9)
or by adding the following to your `~/.cursor/mcp.json` file:
```json
{
"mcpServers": {
"superwall-docs": {
"url": "https://mcp.superwall.com/mcp"
}
}
}
```
### Claude Code
You can install the MCP server in Claude Code by running the following command:
```bash
claude mcp add --transport sse superwall-docs https://mcp.superwall.com/sse
```
### Codex
You can install the MCP server in Codex by running the following command:
```bash
codex mcp add superwall --url https://mcp.superwall.com/mcp
```
## Superwall Docs GPT
You can use the [Superwall Docs GPT](https://chatgpt.com/g/g-6888175f1684819180302d66f4e61971-superwall-docs-gpt) right in the ChatGPT app, and use it to ask any Superwall question.
It has the full knowledge of the Superwall Docs, and can be used with all the ChatGPT features you love like using the context of your files straight from your IDE.
## Ask AI
The built-in [Ask AI tool](https://superwall.com/docs/ai) in the Superwall Docs is a great place to start if you have a question or issue.
## Docs Links
On each page of the Superwall Docs (including this one!), you can find in the top right corner:
* **Copy page**: to copy the page in Markdown format.
Also in the dropdown menu, you can access these options:
* **View as markdown**: to view the page in Markdown format
* **Open in ChatGPT**, **Open in Claude**: to open the page in the respective AI tool and add the page as context for your conversation
## LLMs.txt
The Superwall Docs website has `llms.txt` and `llms-full.txt` files, in total and for each SDK, that you can use to add context to your LLMs.
`llms.txt` is a summary of the docs with links to each page.
`llms-full.txt` is the full text of all of the docs.
| SDK | Summary | Full Text |
| ------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| All | [`llms.txt`](https://superwall.com/docs/llms.txt) | [`llms-full.txt`](https://superwall.com/docs/llms-full.txt) |
| Dashboard | [`llms-dashboard.txt`](https://superwall.com/docs/llms-dashboard.txt) | [`llms-full-dashboard.txt`](https://superwall.com/docs/llms-full-dashboard.txt) |
| iOS | [`llms-ios.txt`](https://superwall.com/docs/llms-ios.txt) | [`llms-full-ios.txt`](https://superwall.com/docs/llms-full-ios.txt) |
| Android | [`llms-android.txt`](https://superwall.com/docs/llms-android.txt) | [`llms-full-android.txt`](https://superwall.com/docs/llms-full-android.txt) |
| Flutter | [`llms-flutter.txt`](https://superwall.com/docs/llms-flutter.txt) | [`llms-full-flutter.txt`](https://superwall.com/docs/llms-full-flutter.txt) |
| Expo | [`llms-expo.txt`](https://superwall.com/docs/llms-expo.txt) | [`llms-full-expo.txt`](https://superwall.com/docs/llms-full-expo.txt) |
| React Native (Deprecated) | [`llms-react-native.txt`](https://superwall.com/docs/llms-react-native.txt) | [`llms-full-react-native.txt`](https://superwall.com/docs/llms-full-react-native.txt) |
| Integrations | [`llms-integrations.txt`](https://superwall.com/docs/llms-integrations.txt) | [`llms-full-integrations.txt`](https://superwall.com/docs/llms-full-integrations.txt) |
| Web Checkout | [`llms-web-checkout.txt`](https://superwall.com/docs/llms-web-checkout.txt) | [`llms-full-web-checkout.txt`](https://superwall.com/docs/llms-full-web-checkout.txt) |
To minimize token use, we recommend using the files specific to your SDK.
---
# Using RevenueCat
Source: https://superwall.com/docs/flutter/guides/using-revenuecat
undefined
Not using RevenueCat? No problem! Superwall works out of the box without any additional SDKs.
You only need to use a
`PurchaseController`
if you want end-to-end control of the purchasing pipeline. The recommended way to use RevenueCat with Superwall is by putting it in observer mode.
You can integrate RevenueCat with Superwall using several approaches:
1. [**Using a purchase controller:**](#using-a-purchase-controller) Use this route if you want to maintain control over purchasing logic and code.
2. [**Using PurchasesAreCompletedBy:**](#using-purchasesarecompletedby) Here, you don't use a purchase controller and you tell RevenueCat that purchases are completed by your app using StoreKit. In this mode, RevenueCat will observe the purchases that the Superwall SDK makes. For more info [see here](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
## Using a purchase controller
### 1. Create a `PurchaseController`
Create a new file called `RCPurchaseController`, then copy and paste the following:
:::flutter
```dart
import 'dart:io';
import 'package:flutter/services.dart';
import 'package:purchases_flutter/purchases_flutter.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart' hide LogLevel;
class RCPurchaseController extends PurchaseController {
// MARK: Configure and sync subscription Status
/// Makes sure that Superwall knows the customers subscription status by
/// changing `Superwall.shared.subscriptionStatus`
Future configureAndSyncSubscriptionStatus() async {
// Configure RevenueCat
await Purchases.setLogLevel(LogLevel.debug);
final configuration = Platform.isIOS
? PurchasesConfiguration('ios_rc_key')
: PurchasesConfiguration('android_rc_key');
await Purchases.configure(configuration);
// Listen for changes
Purchases.addCustomerInfoUpdateListener((customerInfo) async {
// Gets called whenever new CustomerInfo is available
final entitlements = customerInfo.entitlements.active.keys
.map((id) => Entitlement(id: id))
.toSet();
final hasActiveEntitlementOrSubscription = customerInfo
.hasActiveEntitlementOrSubscription(); // Why? -> https://www.revenuecat.com/docs/entitlements#entitlements
if (hasActiveEntitlementOrSubscription) {
await Superwall.shared.setSubscriptionStatus(
SubscriptionStatusActive(entitlements: entitlements));
} else {
await Superwall.shared
.setSubscriptionStatus(SubscriptionStatusInactive());
}
});
}
// MARK: Handle Purchases
/// Makes a purchase from App Store with RevenueCat and returns its
/// result. This gets called when someone tries to purchase a product on
/// one of your paywalls from iOS.
@override
Future purchaseFromAppStore(String productId) async {
// Find products matching productId from RevenueCat
final products = await PurchasesAdditions.getAllProducts([productId]);
// Get first product for product ID (this will properly throw if empty)
final storeProduct = products.firstOrNull;
if (storeProduct == null) {
return PurchaseResult.failed(
'Failed to find store product for $productId');
}
final purchaseResult = await _purchaseStoreProduct(storeProduct);
return purchaseResult;
}
/// Makes a purchase from Google Play with RevenueCat and returns its
/// result. This gets called when someone tries to purchase a product on
/// one of your paywalls from Android.
@override
Future purchaseFromGooglePlay(
String productId, String? basePlanId, String? offerId) async {
// Find products matching productId from RevenueCat
List products =
await PurchasesAdditions.getAllProducts([productId]);
// Choose the product which matches the given base plan.
// If no base plan set, select first product or fail.
String storeProductId = "$productId:$basePlanId";
// Try to find the first product where the googleProduct's basePlanId matches the given basePlanId.
StoreProduct? matchingProduct;
// Loop through each product in the products list.
for (final product in products) {
// Check if the current product's basePlanId matches the given basePlanId.
if (product.identifier == storeProductId) {
// If a match is found, assign this product to matchingProduct.
matchingProduct = product;
// Break the loop as we found our matching product.
break;
}
}
// If a matching product is not found, then try to get the first product from the list.
StoreProduct? storeProduct =
matchingProduct ?? (products.isNotEmpty ? products.first : null);
// If no product is found (either matching or the first one), return a failed purchase result.
if (storeProduct == null) {
return PurchaseResult.failed("Product not found");
}
switch (storeProduct.productCategory) {
case ProductCategory.subscription:
SubscriptionOption? subscriptionOption =
await _fetchGooglePlaySubscriptionOption(
storeProduct, basePlanId, offerId);
if (subscriptionOption == null) {
return PurchaseResult.failed(
"Valid subscription option not found for product.");
}
return await _purchaseSubscriptionOption(subscriptionOption);
case ProductCategory.nonSubscription:
return await _purchaseStoreProduct(storeProduct);
case null:
return PurchaseResult.failed("Unable to determine product category");
}
}
Future _fetchGooglePlaySubscriptionOption(
StoreProduct storeProduct,
String? basePlanId,
String? offerId,
) async {
final subscriptionOptions = storeProduct.subscriptionOptions;
if (subscriptionOptions != null && subscriptionOptions.isNotEmpty) {
// Concatenate base + offer ID
final subscriptionOptionId =
_buildSubscriptionOptionId(basePlanId, offerId);
// Find first subscription option that matches the subscription option ID or use the default offer
SubscriptionOption? subscriptionOption;
// Search for the subscription option with the matching ID
for (final option in subscriptionOptions) {
if (option.id == subscriptionOptionId) {
subscriptionOption = option;
break;
}
}
// If no matching subscription option is found, use the default option
subscriptionOption ??= storeProduct.defaultOption;
// Return the subscription option
return subscriptionOption;
}
return null;
}
Future _purchaseSubscriptionOption(
SubscriptionOption subscriptionOption) async {
// Define the async perform purchase function
// For versions of Flutter Purchases <9
/*Future performPurchase() async {
// Attempt to purchase product
CustomerInfo customerInfo =
await Purchases.purchaseSubscriptionOption(subscriptionOption);
return customerInfo;
}*/
// Flutter Purchases version 9+
Future performPurchase() async {
// Attempt to purchase product
final result = await Purchases.purchase(
PurchaseParams.storeProduct(storeProduct),
);
return result.customerInfo;
}
PurchaseResult purchaseResult =
await _handleSharedPurchase(performPurchase);
return purchaseResult;
}
Future _purchaseStoreProduct(
StoreProduct storeProduct) async {
// Define the async perform purchase function
/* For Flutter Purchases <9
Future performPurchase() async {
// Attempt to purchase product
CustomerInfo customerInfo =
await Purchases.purchaseStoreProduct(storeProduct);
return customerInfo;
}
*/
// For flutter purchases 9+
Future performPurchase() async {
// flutter_purchases 9+ API: use purchase(PurchaseParams) instead
final result = await Purchases.purchase(
PurchaseParams.storeProduct(storeProduct),
);
return result.customerInfo;
}
PurchaseResult purchaseResult =
await _handleSharedPurchase(performPurchase);
return purchaseResult;
}
// MARK: Shared purchase
Future _handleSharedPurchase(
Future Function() performPurchase) async {
try {
// Perform the purchase using the function provided
CustomerInfo customerInfo = await performPurchase();
// Handle the results
if (customerInfo.hasActiveEntitlementOrSubscription()) {
return PurchaseResult.purchased;
} else {
return PurchaseResult.failed("No active subscriptions found.");
}
} on PlatformException catch (e) {
var errorCode = PurchasesErrorHelper.getErrorCode(e);
if (errorCode == PurchasesErrorCode.paymentPendingError) {
return PurchaseResult.pending;
} else if (errorCode == PurchasesErrorCode.purchaseCancelledError) {
return PurchaseResult.cancelled;
} else {
return PurchaseResult.failed(
e.message ?? "Purchase failed in RCPurchaseController");
}
}
}
// MARK: Handle Restores
/// Makes a restore with RevenueCat and returns `.restored`, unless an error is thrown.
/// This gets called when someone tries to restore purchases on one of your paywalls.
@override
Future restorePurchases() async {
try {
await Purchases.restorePurchases();
return RestorationResult.restored;
} on PlatformException catch (e) {
// Error restoring purchases
return RestorationResult.failed(
e.message ?? "Restore failed in RCPurchaseController");
}
}
}
// MARK: Helpers
String _buildSubscriptionOptionId(String? basePlanId, String? offerId) {
String result = '';
if (basePlanId != null) {
result += basePlanId;
}
if (offerId != null) {
if (basePlanId != null) {
result += ':';
}
result += offerId;
}
return result;
}
extension CustomerInfoAdditions on CustomerInfo {
bool hasActiveEntitlementOrSubscription() {
return (activeSubscriptions.isNotEmpty || entitlements.active.isNotEmpty);
}
}
extension PurchasesAdditions on Purchases {
static Future> getAllProducts(
List productIdentifiers) async {
final subscriptionProducts = await Purchases.getProducts(productIdentifiers,
productCategory: ProductCategory.subscription);
final nonSubscriptionProducts = await Purchases.getProducts(
productIdentifiers,
productCategory: ProductCategory.nonSubscription);
final combinedProducts = [
...subscriptionProducts,
...nonSubscriptionProducts
];
return combinedProducts;
}
}
```
:::
As discussed in [Purchases and Subscription Status](/docs/advanced-configuration), this `CustomPurchaseControllerProvider` is responsible for handling the subscription-related logic using the modern hooks-based approach.
### 2. Configure Superwall (Continued)
The example above shows the complete setup. The `CustomPurchaseControllerProvider` wraps your `SuperwallProvider` and handles all purchase and restore logic through RevenueCat.
For more advanced implementations, see the [example app](https://github.com/superwall/expo-superwall/tree/main/example).
**Legacy Approach**: If you're migrating from the old SDK or need the class-based purchase controller, you can use `expo-superwall/compat`. However, we recommend using the modern `CustomPurchaseControllerProvider` approach shown above.
### Removed Legacy Code Section
The following section contains the legacy class-based approach. Skip to the next section for the modern configuration.
As discussed in [Purchases and Subscription Status](/docs/advanced-configuration), this `PurchaseController` is responsible for handling the subscription-related logic. Take a few moments to look through the code to understand how it does this.
### 2. Configure Superwall
Initialize an instance of `RCPurchaseController` and pass it in to `Superwall.configure(apiKey:purchaseController)`:
:::flutter
```dart
RCPurchaseController purchaseController = RCPurchaseController();
Superwall.configure(
apiKey,
purchaseController: purchaseController
);
await purchaseController.configureAndSyncSubscriptionStatus();
```
:::
### 3. Sync the subscription status
Then, call `purchaseController.syncSubscriptionStatus()` to keep Superwall's subscription status up to date with RevenueCat.
That's it! Check out our sample app for working examples:
:::flutter
* [Flutter](https://github.com/superwall/Superwall-Flutter/blob/main/example/lib/RCPurchaseController.dart)
:::
## Using PurchasesAreCompletedBy
If you're using RevenueCat's [PurchasesAreCompletedBy](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions), you don't need to create a purchase controller. Register your placements, present a paywall — and Superwall will take care of completing any purchase the user starts. However, there are a few things to note if you use this setup:
1. Here, you aren't using RevenueCat's [entitlements](https://www.revenuecat.com/docs/getting-started/entitlements#entitlements) as a source of truth. If your app is multiplatform, you'll need to consider how to link up pro features or purchased products for users.
2. If you require custom logic when purchases occur, then you'll want to add a purchase controller. In that case, Superwall handles purchasing flows and RevenueCat will still observe transactions to power their analytics and charts.
3. Be sure that user identifiers are set the same way across Superwall and RevenueCat.
For more information on observer mode, visit [RevenueCat's docs](https://www.revenuecat.com/docs/migrating-to-revenuecat/sdk-or-not/finishing-transactions).
---
# Changelog
Source: https://superwall.com/docs/flutter/changelog
Release notes for the Superwall Flutter SDK
## 2.4.7
### Enhancements
* Updates iOS SDK to 4.12.7 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.12.7).
* Updates Android SDK to 2.6.8 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.6.8).
## 2.4.6
## Enhancements
* Adds `isActive` convenience property on the `SubscriptionStatus` class
* Adds support for `SuperwallOptions.paywalls.onBackPressed` callback to react to back button presses on Android
## 2.4.5
### Enhancements
* Updates iOS SDK to 4.10.6 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.10.6).
* Updates Android SDK to 2.6.5 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.6.5).
## 2.4.4
## Enhancements
* Adds `Superwall.shared.consume(purchaseToken)` method to allow consuming inapp purchases
* Updates Android SDK to 2.6.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.6.2).
## 2.4.3
### Enhancements
* Updates Android SDK to 2.6.1 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.6.1).
## 2.4.2
### Enhancements
* Exposes `Superwall.shared.overrideProductsByName` variable.
## 2.4.1
### Enhancements
* Updates iOS SDK to 4.7.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.7.0).
* Updates Android SDK to 2.5.1 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.5.1). Note: This contains an update to Play Billing 8.
* Adds `overrideProductsByName` to `PaywallOptions` - allows globally overriding products on any paywall by product name.
* Adds `shouldShowWebPurchaseConfirmationAlert` to `PaywallOptions` - shows localized alert confirming successful web checkout purchases (iOS only).
### Fixes
* Fixes missing paywall info
## 2.4.0
## Enhancements
* Updates Android SDK to 2.3.1 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.3.1).
## 2.3.5
### Fixes
* Adds `params` mapping back to `EventInfo` for easier forwarding to analytics
## 2.3.4
### Enhancements
* Updates iOS SDK to 4.5.2 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.5.2).
* Updates Android SDK to 2.2.3 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.2.3).
### Fixes
* Fixes issue where `shouldShowWebRestorationAlert` wasn't getting through to the iOS `PaywallOptions`.
## 2.3.3
### Enhancements
* Exposes `shouldShowWebRestorationAlert` in `PaywallOptions`.
## 2.3.2
### Enhancements
* Expose `getPresentationResult` method
* Updates Android SDK to 2.2.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.2.2).
## 2.3.1
### Enhancements
* Updates Android SDK to 2.1.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.2).
### Fixes
* Fixes issue with `registerPlacement` blocking
## 2.3.0
### Enhancements
* Exposes `ConfirmedAssignments` and `StoreProduct` to `superwallkit_flutter`.
* Adds `Superwall.shared.getDeviceAttributes()`, which returns the device attributes that are used when evaluating audience filters.
* Updates iOS SDK to 4.4.1 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.4.1).
* Updates Android SDK to 2.1.1 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.1).
### Fixes
* Fixes issue where `SuperwallEventInfo` didn't contain all expected variables.
* Fixes issue when building for app that deploys with a minimum version of iOS 13.
## 2.2.2
### Fixes
* Fixes issue with paywall presentation handlers not working.
## 2.2.1
### Fixes
* Fixes issue with iOS side of project not building.
## 2.2.0
### Fixes
* Fixes missing Event info
### Enhancements
* Updates iOS SDK to 4.3.11 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.11)
* Updates Android SDK to 2.1.0 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.0)
## 2.2.0-beta.2
### Enhancements
* Updates iOS SDK to 4.3.8 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.8)
## 2.2.0-beta.1
### Enhancements
* Adds support for web checkout.
* Updates kotlin version of the underlying Android SDK to 2.0.21
* Updates iOS SDK to 4.3.5 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.5)
* Updates iOS SDK to 2.1.0-beta.2 [View iOS SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.1.0-beta.2)
## 2.1.0
### Enhancements
* Updates Android SDK to 2.0.8 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.8)
* Updates iOS SDK to 4.3.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.3.0)
## 2.1.0-beta.2
### Enhancements
* Adds `restorePurchases` function
* Updates Android SDK to 2.0.6 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.6)
* Updates iOS SDK to 4.2.0 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.2.0)
## 2.1.0-beta.1
### Enhancements
* Reworks the SDK's beneath the surface to rely on Pigeon codegen
* Improves stability
* Improved correctness of the SDK
### Note:
* This could include some potentially breaking changes. If you find some, please open an issue or reach out to the team.
## 2.0.8
### Enhancements
* Updates iOS SDK to 4.0.6 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.6)
* Updates Android SDK to 2.0.5 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.5)
## 2.0.7
### Fixes
* Fixes issue when accessing `presentedByPlacement*` properties from a custom placement
## 2.0.6
## Enhancements
* Adds a subscription stream example in the example app
## Fixes
* Fixes issue with second subscriber not receiving the `SubscriptionStatus` broadcast stream
* Fixes issue with `PurchasedPaywallResult` not properly deserialising in `onDismiss`
## 2.0.5
### Enhancements
* Update `SuperwallPlacement` to `SuperwallEvent`
* Update `PlacementType` to `EventType`
* Updates Android SDK to 2.0.3 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.3)
* Updates iOS SDK to 4.0.3 [View iOS SDK release notes](https://github.com/superwall/Superwall-iOS/releases/tag/4.0.3)
## 2.0.4
### Enhancements
* Updates onDismissHandler to now receive a PaywallResult also
* Updates Android SDK to 2.0.2 [View Android SDK release notes](https://github.com/superwall/Superwall-Android/releases/tag/2.0.2)
* `handleSuperwallPlacement(SuperwallPlacementInfo eventInfo)` has been replaced with `handleSuperwallEvent(SuperwallEventtInfo eventInfo)`
## 2.0.3
### Fixes
* Fixes BridgeInstance crashes
* Adds awaiting on shared instance of BridgeCreator to avoid crashes when plugin is yet to attach
## 2.0.2
* Updates iOS SDK to 1.5.4 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/4.0.1)
* Updates Android SDK to 2.0.1 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/2.0.1)
## 2.0.1
* Upgrades iOS SDK to 4.0.0 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/4.0.0)
## 2.0.0
###
* Adds entitlements to subscriptions, allowing you to set them using:
* `await Superwall.shared.setSubscriptionStatus(status)` by passing in one of:
* `SubscriptionStatusActive(entitlements: entitlements))`
* Note: Passing in empty entitlements will set the subscription status to inactive
* `SubscriptionStatusInactive`
* `SubscriptionStatusUnknown`
* Subscribing to subscription status updates via stream `Superwall.shared.subscriptionStatus`
* `SuperwallBuilder` which will automatically update the state whenever subscription status changes
* `Superwall.shared.registerEvent` has now been replaced with `Superwall.shared.registerPlacement`
* `handleSuperwallEvent(SuperwallEventInfo eventInfo)` has been replaced with `handleSuperwallPlacement(SuperwallPlacementInfo placementInfo)`
* `PaywallPresentationHandler.onDismiss` now has 2 arguments, `PaywallInfo` and `PaywallResult`
## 2.0.0-alpha.1
* Adds entitlements to subscriptions, allowing you to set them using:
* `await Superwall.shared.setSubscriptionStatus(status)` by passing in one of:
* `SubscriptionStatusActive(entitlements: entitlements))`
* Note: Passing in empty entitlements will set the subscription status to inactive
* `SubscriptionStatusInactive`
* `SubscriptionStatusUnknown`
* Subscribing to subscription status updates via stream `Superwall.shared.subscriptionStatus`
* `SuperwallBuilder` which will automatically update the state whenever subscription status changes
* `Superwall.shared.registerEvent` has now been replaced with `Superwall.shared.registerPlacement`
* `handleSuperwallEvent(SuperwallEventInfo eventInfo)` has been replaced with `handleSuperwallPlacement(SuperwallPlacementInfo placementInfo)`
## 1.3.11
### Fixes
* Fixes BridgeInstance crashes
* Adds awaiting on shared instance of BridgeCreator to avoid crashes when plugin is yet to attach
## 1.3.10
### Fixes
* Fixes an issue on iOS where the plugin could get registered multiple times resulting in a `MissingPluginException`.
## 1.3.9
### Fixes
* Fixes a compatibility issue with `WorkManager` and other isolate-running libraries where the plugin would detach and cause a `Missing Activity` or `BridgeCreator` exception
### Enhancements
* Updates Android SDK to 1.5.4 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.5.4)
## 1.3.8
### Fixes
* Removes unnecessary date comparison from PurchaseController example code.
## 1.3.7
### Enhancements
* Upgrades iOS SDK to 3.12.1 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.1)
## 1.3.6
### Enhancements
* Updates Android SDK to 1.5.1 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.5.1)
## 1.3.5
### Enhancements
* Upgrades iOS SDK to 3.12.0 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.12.0)
* Updates Android SDK to 1.5.0 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.5.0)
### Fixes
* Fixes issue with `PaywallInfoBridge` and other bridges throwing NPE when reattaching to activities from deep sleep.
## 1.3.4
### Enhancements
* Adds `setLocaleIdentifier(_:)` and `getLocaleIdentifier()`.
## 1.3.3
* Upgrades Android SDK to 1.3.1 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.3.1)
* This fixes the issue when using Superwall with some SDK's would cause a crash (i.e. Smartlook SDK)
## 1.3.2
* Updates project linting and formatting to be consistent with the Flutter style
* Removes rogue logging statements by matching them with the provided Log level
* Adds `passIdentifiersToPlayStore` to `SuperwallOptions` which allows you to pass user identifiers to the Play Store purchases as account identifiers. This is useful for tracking user purchases in the Play Store console.
## 1.3.1
### Enhancements
* Upgrades Android SDK to 1.3.0 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.3.0)
* Upgrades iOS SDK to 3.10.1 [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.10.1)
* Adds `confirmAllAssignments` method to `Superwall` which confirms assignments for all placements and returns an array of all confirmed experiment assignments. Note that the assignments may be different when a placement is registered due to changes in user, placement, or device parameters used in audience filters.
## 1.3.0
### Enhancements
* Upgrades iOS SDK to 3.9.1. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.9.1)
* Upgrades Android SDK to 1.2.7 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.7)
* Exposes the `SuperwallOption` `collectAdServicesAttribution` for iOS. When `true`, this collects the AdServices attribute token, which will be process by our backend. Adds `adServicesTokenRequest_start`, `adServicesTokenRequest_complete`, and `adServicesTokenRequest_fail`.
* Exposes `getConfigurationStatus()`, which replaces `getIsConfigured()`. This returns either `ConfigurationStatusPending`, `ConfigurationStatusConfigured`, or `ConfigurationStatusFailed`.
## 1.2.2
### Enhancements
* Upgrades Android SDK to 1.2.4 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.4)
### Fixes
* Reapply the single bridge instance limit to fix issues with `setDelegate` where plugins with multiple isolates are used
* Fixes stateful bridges by applying new state when invoking create, resolving issues seen in #23
## 1.2.1
### Enhancements
* Upgrades Android SDK to 1.2.3 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.3)
* Upgrades iOS SDK to 3.7.2. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.7.2)
## 1.2.0
### Enhancements
* Upgrades Android SDK to 1.2.0 [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.2.0)
### Fixes
* Updates `compileSDKVersion` to 34 fixing build issues on Android.
## 1.1.9
### Enhancements
* Upgrades Android SDK to 1.1.8. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.8)
### Fixes
* Bumps minimum Kotlin version to 1.8.0 and Android Gradle Plugin to 8.1.0 to be able to be
compatible with the latest Android SDK. This was necessary for important bug fixes.
* SW-2868: Fixes transaction issues caused by hot restart.
## 1.1.8
### Enhancements
* Upgrades iOS SDK to 3.6.6. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.6)
* Upgrades Android SDK to 1.1.7. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.7)
## 1.1.7
### Enhancements
* Upgrades iOS SDK to 3.6.5. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.5)
## 1.1.6
### Enhancements
* Upgrades Android SDK to 1.1.6. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.6)
## 1.1.5
### Enhancements
* Upgrades Android SDK to 1.1.5. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.5)
## 1.1.4
### Enhancements
* Upgrades Android SDK to 1.1.4. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.4)
* Upgrades iOS SDK to 3.6.2. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.2)
* Adds `identityAlias` `SuperwallEvent`.
### Fixes
* Updates the UUID framework dependency to the latest version to prevent conflicts.
## 1.1.3
### Fixes
* Fixes crash that occurred if an Android foreground service was started and the app was relaunched from a cold start.
## 1.1.2
### Enhancements
* Upgrades Android SDK to 1.1.2. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.2)
* Upgrades iOS SDK to 3.6.1. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.1)
## 1.1.1
### Fixes
* Fixes `LocalNotification` issue that was trying to initialise an `int` with a `double`.
## 1.1.0
### Enhancements
* Upgrades Android SDK to 1.1.1. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.1.1)
* Upgrades iOS SDK to 3.6.0. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.6.0)
## 1.0.1
### Fixes
* Fixes issue with invalid imports due to a breaking change on Android.
## 1.0.0
### Enhancements
* Upgrades Android SDK to 1.0.0. [View Android SDK release notes](https://github.com/superwall-me/Superwall-Android/releases/tag/1.0.0)
* Upgrades iOS SDK to 3.5.0. [View iOS SDK release notes](https://github.com/superwall-me/Superwall-iOS/releases/tag/3.5.0)
---
# Welcome
Source: https://superwall.com/docs/flutter
Welcome to the Superwall Flutter SDK documentation
## Quick Links
Get up and running with the Superwall Flutter SDK
Most common features and use cases
Reference the Superwall Flutter SDK
Guides for specific use cases
Example app for the Superwall Flutter SDK
Guides for troubleshooting common issues
## Feedback
We are always improving our SDKs and documentation!
If you have feedback on any of our docs, please leave a rating and message at the bottom of the page.
If you have any issues with the SDK, please [open an issue on GitHub](https://github.com/superwall/superwall-flutter/issues).
---
# Video: Revenue Charts Tour
Source: https://superwall.com/docs/support/dashboard/2563776677-revenue-charts-tour
undefined
Learn all about our brand new, completely free revenue charts. Track how your app is doing from a proceeds standpoint. Or, check into paywall conversions, refund rates, and much more. Plus, you can aggregate data using filters, and export anything to a .csv format.
Revenue charts are available to everyone, and you can use them with our SDK or by simply setting up revenue tracking with Superwall.
---
# How is the Estimated ARPU metric calculated in Superwall?
Source: https://superwall.com/docs/support/dashboard/4129730749-how-is-the-estimated-arpu-metric-calculated-in-superwall
undefined
## Answer
The Estimated ARPU (Average Revenue Per User) in Superwall is calculated using the following formula:
(Projected Trial Proceeds + Actual Proceeds) / Number of Users
The "estimated" component of this metric comes from the projected trial proceeds, which are calculated based on:
* Historical trial conversion rates for specific products/paywalls
The accuracy of the Estimated ARPU improves over time as more trial conversion data becomes available for your campaigns.
---
# How do I change my login email address?
Source: https://superwall.com/docs/support/dashboard/2125187334-how-do-i-change-my-login-email-address
undefined
Currently, it is not possible to directly change the email address associated with your Superwall account. However, you can follow these steps to set up access with a new email address:
1. Invite your new email address as a team member to your Superwall project
2. Create a separate account using the new email address
3. Use the new account credentials to access your Superwall dashboard
---
# How do I find my Superwall Server Secret?
Source: https://superwall.com/docs/support/dashboard/5346543318-how-do-i-find-my-superwall-server-secret
undefined
## Answer
To find your Superwall Server Secret for RevenueCat integration, follow these steps:
1. Log in to your Superwall dashboard
2. Navigate to Settings
3. Click on Revenue Tracking
4. Select the RevenueCat tab
The Server Secret is different from your Public Key, which can be found in the general Keys section. Make sure you're specifically in the Revenue Tracking section under Settings to find the Server Secret for RevenueCat integration.
---
# Video: Configuring Products to use in Superwall
Source: https://superwall.com/docs/support/dashboard/8137029255-configuring-products-to-use-in-superwall
undefined
Whether using App Store Connect or Revenue Cat, it's easy to get products into Superwall. Here's a step-by-step video showing how it's done.
---
# How do I add my VAT number to invoices?
Source: https://superwall.com/docs/support/dashboard/9023151337-how-do-i-add-my-vat-number-to-invoices
undefined
When you need to include your VAT number on invoices from Superwall, you can add it through the Billing Settings.
To add your VAT number:
1. Go to Settings / Billing
2. Locate your name field
3. Add your VAT number next to your name
Once added, your VAT number will automatically appear on all future invoices.
---
# Why is initial conversion lower than new trials on some days?
Source: https://superwall.com/docs/support/dashboard/9621028514-why-is-initial-conversion-lower-than-new-trials-on-some-days
undefined
When looking at analytics data in Superwall, you may notice that the initial conversion numbers can sometimes be lower than new trials for the same day. This is due to how these metrics are calculated differently.
Initial conversion and new trials metrics differ in the following ways:
* Initial conversion counts users who both download the app AND convert on a paywall within the specified time period
* New trials are not cohorted based on install date - they simply show the total number of new trials started on that day regardless of when the user installed the app
For example, if on July 25th you see:
* Initial conversions: 332
* New trials: 346
This means that 332 users who installed the app on that day converted on a paywall, while 346 total users started trials (including users who may have installed the app on previous days).
---
# Video: Get Started with Apple Search Ads
Source: https://superwall.com/docs/support/dashboard/8851145816-get-started-with-apple-search-ads
undefined
Integrate Apple Search Ads with Superwall to unlock powerful chart analytics, create audience filters, and view user attributes acquired via search ads.
---
# A Superwall product tour
Source: https://superwall.com/docs/support/dashboard/9588935743-a-superwall-product-tour
undefined
New to Superwall? Curious how it can help your app increase revenue? This is the perfect place to start. We'll show you around in just a few minutes. We'll cover how to use our revenue charts, set up a campaign, what placements are, how to edit paywalls and much more.
---
# How do I update my Apple Small Business Program status in Superwall?
Source: https://superwall.com/docs/support/dashboard/2132346026-how-do-i-update-my-apple-small-business-program-status-in-superwall
undefined
## Context
When participating in Apple's Small Business Program, your proceeds cut is 15% instead of the standard 30%. To ensure your Superwall dashboard reflects the correct revenue calculations, you'll need to configure your program status in the settings.
## Answer
To update your Apple Small Business Program status in Superwall:
1. Navigate to [Settings/General](https://superwall.com/applications/\:app/settings) in your Superwall dashboard
2. Locate the Apple Small Business Program section
3. Enter your program start date, and if applicable, exit date
4. Save your changes
Note: The updated proceeds cut calculation will only apply to transactions processed after you've saved these settings. Historical transactions will not be recalculated.
---
# What is the difference between "Trial Cancel" and "Trial Expire" tags?
Source: https://superwall.com/docs/support/dashboard/9274386153-what-is-the-difference-between-trial-cancel-and-trial-expire-tags
undefined
The "Trial Cancel" and "Trial Expire" tags represent different stages in a user's trial journey:
* **"Trial Cancel"** occurs when a user actively cancels their trial during the trial period, before it converts to a paid subscription.
* **"Trial Expire"** occurs when the trial period ends without the user converting to a paid subscription. This can happen for two reasons:
* The user previously canceled their trial
* A billing issue prevented the conversion to a paid subscription ([read more here](/support/troubleshooting/4741512872-why-am-i-seeing-a-billing-issue-after-my-free-trial-ends))
### Example Timeline
Here's how these events would appear if a user signed up for a 1 week trial and cancels after a day:
* Day 0: Trial Start
* Day 1: Trial Cancel (user actively cancels)
* Day 7: Trial Expire (trial period officially ends)
---
# Video: How to Show Different Paywalls to Certain Users with Audiences
Source: https://superwall.com/docs/support/dashboard/8360602963-how-to-show-different-paywalls-to-certain-users-with-audiences
undefined
With Superwall, you can easily test and experiment with paywalls in production in your iOS, Flutter, Android or React Native app. Here, Superwall's audience feature is demonstrated, which shows how you can easily present different paywalls based off of audiences you setup. This video will walk you through three different audiences being used, each with its own paywall:
* Showing a paywall based upon users who tap a certain button.
* Showing a paywall based upon the time of day locally.
* And, using a general audience to show a paywall to those who don't fit the above audiences.
---
# Video: Breaking Down Revenue Charts by User Attributes
Source: https://superwall.com/docs/support/dashboard/3633020467-breaking-down-revenue-charts-by-user-attributes
undefined
Superwall lets users break down revenue data by user attributes. In this video, developer advocate Jordan shows how it works.
---
# How to Optimize Refund Protection Settings
Source: https://superwall.com/docs/support/dashboard/5483562984-how-to-optimize-refund-protection-settings
undefined
Refund Protection is a feature that helps prevent unauthorized refunds in your app. [Recent changes to Apple's refund system](https://www.linkedin.com/posts/anglinb_apple-refund-consumptionabrrequest-activity-7333996574819196928-eb_R?utm_source=share\&utm_medium=member_desktop\&rcm=ACoAAAvEWioBgC5C7eVYxz8Rn8pOs1tHZXLGVf0) have affected the overall effectiveness of refund protection across all apps. Understanding and optimizing your refund protection settings is crucial for better performance.
To verify if your Refund Protection is working:
1. Monitor your app's conversion rates
2. Check if refund events are being processed in your dashboard.
3. Review your current Refund Protection preference setting
To optimize your Refund Protection:
1. Navigate to your Refund Protection settings
2. **Change the setting from "No preference" to "Prefer decline"**
3. Monitor the performance after making this change.
Note: The "Prefer decline" setting is recommended for optimal protection against unauthorized refunds.
---
# Why don't trial conversion and cancellation rates add up to 100%?
Source: https://superwall.com/docs/support/dashboard/2172810792-why-don-t-trial-conversion-and-cancellation-rates-add-up-to-100
undefined
When looking at analytics for trial conversions and cancellations, it may seem counterintuitive that the trial conversion rate and trial cancellation rate don't always sum to 100%. This is because these metrics are calculated using different user groups as their base.
Here's how these metrics are calculated:
* **Trial Conversion Rate:** This metric only considers users who have completed their trial period. It shows the percentage of these users who converted to paying customers.
* **Trial Cancellation Rate:** This metric includes all users who started a trial, regardless of whether they completed it or not. It represents the percentage of total trial starts that resulted in cancellations.
Additionally, there is a third category of users who neither convert nor cancel - those who encounter billing issues during their trial period. These users are counted separately from both conversions and cancellations.
This means that a 40% trial conversion rate and an 83% trial cancellation rate can coexist because they're measuring different things against different total populations of users.
---
# Dashboard
Source: https://superwall.com/docs/support/dashboard
Learn how to use the Superwall Dashboard to manage your paywalls, campaigns, and users.
import { SupportFolderList } from '@/components/SupportFolderList'
---
# How can I recover an archived product in Superwall?
Source: https://superwall.com/docs/support/dashboard/9149611399-can-i-recover-an-archived-product-in-superwall
undefined
When a product (subscription) has been archived in Superwall, there is currently no way to unarchive it directly through the user interface. To continue using a product that was previously archived, you will need to create a new product with the same configuration information.
---
# Are video and images automatically compressed when uploaded to a paywall via the editor?
Source: https://superwall.com/docs/support/paywall-editor/1523245773-are-videos-automatically-compressed-when-uploaded-to-a-paywall-via-the-editor
undefined
## Answer
Yes, when you upload a video through the editor for use in a paywall, it will automatically be compressed for you. This automatic compression helps optimize the video for web delivery while maintaining quality.
Although we will compress video, there is still a minimum amount of bandwidth and therefore latency which you will incur by using long videos or many images. We recommend sticking to 3-10 second videos and less than 20 images.
Video compression happens automatically in the background - there's no additional action needed on your part.
---
# Video: Using Custom Actions to Setup Referral Systems
Source: https://superwall.com/docs/support/paywall-editor/2079174387-using-custom-actions-to-setup-referral-systems
undefined
In this video from Superwall office hours, Nick and Jordan show how you can use custom actions to perform app-specific logic using the Superwall SDK. In particular, Jordan covers an entire referral system flow that you could setup for your app today using either mobile or web checkout.
---
# Video: How to use custom actions in your paywall
Source: https://superwall.com/docs/support/paywall-editor/2427577661-how-to-use-custom-actions-in-your-paywall
undefined
Using custom actions is a great way to fire off app-specific logic from your paywall. In this tip, we'll show you how to set them up.
---
# Video: AI Image Generation in Paywalls
Source: https://superwall.com/docs/support/paywall-editor/8950966564-ai-image-generation-in-paywalls
undefined
Create hero images, banners, icons and more using Superwall's AI image generation feature - now live for all users.
---
# Video: Adding Products to Paywalls
Source: https://superwall.com/docs/support/paywall-editor/1502195570-adding-products-to-paywalls
undefined
Here's how to add products into paywalls. Most Superwall templates have room for two products, but all of them can be customized to support as many products as required.
---
# Video: How to use Dynamic Values
Source: https://superwall.com/docs/support/paywall-editor/6485999553-how-to-use-dynamic-values
undefined
Dynamic values are a core part of the Superwall editor. Using them, you can update all sorts of things in your paywalls depending on a certain condition:
* If there's a free trial, show this button.
* If they select this plan, update that text.
* If it's on an iPad, show these components.
* etc.
Here, developer advocate Jordan will walk you through how they work, and how to use existing dynamic values already present on a paywall.
---
# Can I delete or update existing snippets?
Source: https://superwall.com/docs/support/paywall-editor/7448860745-can-i-delete-or-update-existing-snippets
undefined
While snippets cannot be deleted, you can update existing snippets rather than creating new ones. This helps keep your snippet library clean and up-to-date.
To update an existing snippet:
1. Make your desired changes to the snippet element or stack
2. Click "Create Snippet"
3. When prompted, select the option to update the existing snippet instead of creating a new one
---
# Video: Feature Gating
Source: https://superwall.com/docs/support/paywall-editor/4876966592-feature-gating
undefined
You can change what's "paywalled" in production any time by using "Feature Gating", an available setting on every paywall you've created with Superwall. When you have it enabled, it means users will see a paywall if they aren't "pro" and Superwall will restrict access to features. On the other hand, disabling it means that users will still see a paywall, but the "pro" content will be available to them once it dismisses.
This is an effective technique to run promotions or during onboarding. Users still see a paywall, giving you a shot at conversion, but also get to experience pro features that will hopefully convince them to convert later on.
---
# When adding a product, is it possible to fetch the price for non subscription products?
Source: https://superwall.com/docs/support/paywall-editor/2306253672-can-i-use-a-feature-shown-in-the-attached-screenshot
undefined
## Answer
Unfortunately, this feature is currently not supported for non subscription products.
Keep an eye on our product updates and release notes for information about new features as they become available.
---
# How do I animate elements in the Superwall editor?
Source: https://superwall.com/docs/support/paywall-editor/6426797732-how-do-i-animate-text-elements-in-the-superwall-editor
undefined
## Context
When designing paywalls in Superwall, you might want to add animations to elements to make them more engaging. While CSS keyframe animations are not currently supported, there are alternative methods available for adding animations to your paywall elements.
## Answer
There are currently two ways to add animations to elements in the Superwall editor:
1. Using Lottie animations
* For example the "Delayed X" element uses Lottie animation
2. Using the Effects section
* Can be used to animate value changes
* Requires triggering through user actions (such as button presses)
* Works in conjunction with [Dynamic Values](https://superwall.com/docs/paywall-editor-dynamic-values#dynamic-values)
---
# Video: Tracking User Behavior on Paywalls
Source: https://superwall.com/docs/support/paywall-editor/6666110181-tracking-user-behavior-on-paywalls
undefined
In this video from Superwall office hours, Nick and Jordan demonstrate how custom placements can be used to track user behavior. This is critical for understanding how users act on your paywalls — things like:
* Did they click this button? How many times?
* Do they advance to page X on a multi-page paywall?
* Which plans are toggled off and on?
By the end, you'll have a full understanding of to start tracking interactions on paywalls.
---
# Video: Showing paywalls with a discount for abandoned transactions
Source: https://superwall.com/docs/support/paywall-editor/2455479259-showing-paywalls-with-a-discount-for-abandoned-transactions
undefined
Unlocking some lost revenue with transaction abandoned discounts. In this short tutorial, we'll show you how to get things setup in Superwall to show discounted products when someone starts a transaction, but cancels it. Best of all, if you have the Superwall SDK installed - there's no app updates you need to make.
This technique has boosted revenue by 25-40% in several apps using Superwall. Around only 50% of users complete an in-app purchase after starting one. If your trial rate is 10%, that means 20% of installs are considering a purchase. Users who tap the buy button show interest but may hesitate at the full price. So, offer them a discount!
---
# Video: Building a Multi-Tier Paywall using the Superwall Editor
Source: https://superwall.com/docs/support/paywall-editor/6032457649-building-a-multi-tier-paywall-using-the-superwall-editor
undefined
Learn how to build a multi-tier paywall using Superwall's paywall editor. These types of paywalls can be particularly useful for showing off several "tiers" of service. For example, if you had a "Standard" and "Pro" tier, each with its own annual or monthly plan, then this type of paywall can help express that value to users.
---
# Video: Using Custom Placements for Tracking Paywall Interactions
Source: https://superwall.com/docs/support/paywall-editor/3696237744-using-custom-placements-for-tracking-paywall-interactions
undefined
Need to track certain interactions on your paywall? Custom placements are the right tool for the job. Add them as a tap behavior on any element you'd like to forward to your analytics service.
In this video, Superwall's developer advocate will walk you through each of the simple steps required to get this working in your own app.
---
# How do I copy a paywall from one account to another?
Source: https://superwall.com/docs/support/paywall-editor/7124788686-how-do-i-copy-a-paywall-from-one-account-to-another
undefined
## Answer
You can easily share a paywall between different Superwall accounts using the built-in sharing feature. Here's how:
1. Open the paywall you want to share in the Paywall Editor
2. Click the **Share** icon in the editor
3. Click **Generate a link** to create a shareable URL
4. Send that link to the person with the other account
5. When they open the link, the paywall will be duplicated into their Superwall project
**Important:** The duplicated paywall will come without your existing products. The recipient will need to attach their own products to the paywall after importing it.
To make the paywall private again after sharing, click the **Share** button and select **Take Private**.
---
# Display dynamic images in your paywalls
Source: https://superwall.com/docs/support/paywall-editor/4109039578-display-dynamic-images-in-your-paywalls
undefined
You can use variables inside of image URLs in Superwall's editor to show dynamic content. This is perfect for:
* Sports apps who want to promote a certain game
* Dating apps might show a tapped profile
* Community gathering apps could show a particular event
You'll have access to the vast array of variables available in the editor, feel free to get creative!
---
# Video: How to create a countdown timer on a paywall
Source: https://superwall.com/docs/support/paywall-editor/1377495156-how-to-create-a-countdown-timer-on-a-paywall
undefined
Learn how to create live countdown timers for your paywalls using Superwall's editor.
---
# Video: How to make paywalls adapt to device, light or dark mode, and more.
Source: https://superwall.com/docs/support/paywall-editor/5453267914-how-to-make-paywalls-adapt-to-device-light-or-dark-mode-and-more
undefined
Superwall's best-in-class editor lets you adapt your paywalls to any situation. You can hide and show elements based on the device, available width, light or dark mode, and more.
Here, developer advocate Jordan walks you through a practical example and shows you where to look in the editor to achieve similar results.
---
# Paywall Editor: Menus or Modals Closing
Source: https://superwall.com/docs/support/paywall-editor/6770999766-paywall-editor-menus-or-modals-closing
undefined
If you experience issues with Menus or Modals automatically closing while editing your paywall, this may be caused by browser extensions interfering with the editors functionality.
### Debugging
* Open the Paywall Editor in an Incognito/Private window
* Temporarily disable your browser extensions
If the issue stops, then it could be one of your browser extensions causing the issue.
### Still Having Issues?
If you continue experiencing problems after trying these steps, please contact our support team for further assistance.
---
# Video: Building your first paywall
Source: https://superwall.com/docs/support/paywall-editor/1932646675-building-your-first-paywall
undefined
If you've never built a paywall using Superwall's editor, this is the video for you. Developer advocate Jordan will take you through from the very beginning, to building one from scratch, all the way to testing it on your device.
---
# Paywall Editor
Source: https://superwall.com/docs/support/paywall-editor
Learn how to use the Superwall Paywall Editor to create and manage your paywalls.
import { SupportFolderList } from '@/components/SupportFolderList'
---
# How do I disable the activation link email for web checkout?
Source: https://superwall.com/docs/support/web-checkout/3969573187-how-do-i-disable-the-activation-link-email-for-web-checkout
undefined
## Context
When using web checkout, customers receive an automated activation email from Superwall by default after checkout. It goes to the email entered at checkout, from `Your app name `, with the subject `Your activation link from your app name`. This contains the redemption link that powers the web-to-app flow.
## Answer
To disable the activation link emails, follow these steps:
1. Navigate to your Stripe app in the Superwall dashboard
2. Go to Settings / General
3. Locate the "Disable Superwall Emails" setting
4. Change the value from "false" to "true"
This setting will affect all automated emails sent by Superwall. Make sure this aligns with your desired user experience before making the change.
---
# Why am I seeing "An error occurred while loading the Stripe Portal" in the manage subscription page?
Source: https://superwall.com/docs/support/web-checkout/3771535881-why-am-i-seeing-an-error-occurred-while-loading-the-stripe-portal-in-the-manage-subscription-page
undefined
If you encounter an error when trying to access the "Manage Subscription" page Stripe Portal through a web2app redemption link, this typically means that the customer portal configuration for sandbox environment has not been set up in your Stripe account yet.
To resolve this issue:
1. Go to your Stripe Dashboard's Customer Portal settings page: [https://dashboard.stripe.com/test/settings/billing/portal](https://dashboard.stripe.com/test/settings/billing/portal)
2. Configure your customer portal settings for the sandbox/test environment
3. Save your configuration
Once configured, the Stripe Portal should load correctly when accessing it through the redemption link.
Note: Our team is working on automating this setup process to prevent this error from occurring in the future.
---
# Why is there no revenue tracking setup for web checkout?
Source: https://superwall.com/docs/support/web-checkout/web-checkout-revenue-tracking-is-automatic
Web checkout revenue tracking is automatic when using Stripe, unlike iOS and Android which require manual configuration.
When using Superwall's web checkout with Stripe, revenue tracking is **automatic**. There is no separate "Revenue Tracking" setup required like there is for iOS (App Store Connect) or Android (Google Play).
## Why the difference?
For native mobile apps, Superwall needs you to configure server notifications from Apple or Google because those payment systems are external to Superwall. The revenue events must be forwarded to Superwall so they can be associated with paywalls and campaigns.
With web checkout, payments flow directly through Superwall's integration with Stripe. Superwall processes these transactions and automatically captures all revenue data, including:
* Subscription purchases
* One-time purchases
* Renewals
* Cancellations
* Refunds
## What you need to do
1. **Configure your Stripe keys** in your Superwall app's [Settings](/web-checkout-configuring-stripe-keys-and-settings)
2. **Create products** in Stripe and [add them to Superwall](/web-checkout-adding-a-stripe-product)
3. **Add products to your paywalls** and start showing them
Once a purchase completes through your web checkout paywall, conversions and revenue will appear automatically in your Superwall dashboard.
It can take a few minutes for new transactions to appear in your dashboard metrics after a purchase completes.
## Troubleshooting missing conversions
If you have completed purchases in Stripe but no conversions showing in Superwall:
1. **Verify your Stripe keys are configured correctly** - Check that both your Publishable Key and Secret Key are entered in Settings and show "Configured"
2. **Check you're using the correct mode** - If testing, ensure you're using Sandbox keys with test purchases. Production keys are required for live transactions.
3. **Confirm the purchase was made through Superwall** - Only purchases initiated through Superwall paywalls will be tracked. Direct Stripe purchases outside of Superwall will not appear.
4. **Allow time for data to sync** - New transactions may take a few minutes to appear in your analytics
## Related
* [Stripe Setup](/web-checkout-configuring-stripe-keys-and-settings)
* [Revenue Tracking for iOS and Android](/dashboard/dashboard-settings/overview-settings-revenue-tracking)
* [Web Checkout Overview](/web-checkout-overview)
---
# How do I retrieve Stripe customer data after web checkout?
Source: https://superwall.com/docs/support/web-checkout/how-to-retrieve-stripe-customer-data-after-web-checkout
Learn how to access the Stripe customer ID and email after a user completes a web checkout purchase.
## Context
After a user completes a web checkout purchase via Stripe, you may need to access their Stripe customer ID and email for integration with your backend systems or third-party services.
## Answer
Use the `didRedeemLink(result:)` delegate method to access Stripe customer data when a redemption link is successfully processed.
### Accessing Stripe customer ID and email
When the redemption result is successful, the `RedemptionInfo` object contains a `PurchaserInfo` with the customer's email and store identifiers:
```swift
func didRedeemLink(result: RedemptionResult) {
guard case let .success(_, redemptionInfo) = result else { return }
// Get the customer's email
let email = redemptionInfo.purchaserInfo.email
// Get the Stripe customer ID and subscription IDs
if case let .stripe(customerId, subscriptionIds) = redemptionInfo.purchaserInfo.storeIdentifiers {
print("Stripe Customer ID: \(customerId)")
print("Subscription IDs: \(subscriptionIds)")
// Send to your backend or analytics
sendToBackend(
stripeCustomerId: customerId,
email: email,
subscriptionIds: subscriptionIds
)
}
}
```
### What happens if the user kills the app during checkout?
If a user completes the Stripe checkout but terminates the app before returning, the `didRedeemLink(result:)` callback will not fire. However, their purchase is not lost.
**Recovery mechanisms:**
1. **Redemption email**: After a successful Stripe checkout, Superwall automatically sends the customer an email with an activation link. When they tap it, your app opens and `didRedeemLink` fires with the Stripe customer ID and email.
2. **Plan management page**: Users can visit `https://{yoursubdomain}.superwall.app/manage`, enter their email, and receive a new redemption link.
3. **Automatic entitlement sync**: The SDK polls for web entitlements when the app enters foreground, so subscription status updates automatically. However, this sync only updates entitlements and does not trigger `didRedeemLink`, meaning you will not receive the Stripe customer ID or email through this path.
To programmatically receive the Stripe customer ID and email, the user must tap a redemption link (either from the automatic email or the manage page).
### Stripe metadata
Superwall automatically includes your app user ID in the Stripe checkout session and subscription metadata. The key `_sw_app_user_id` contains the user ID you set via `Superwall.shared.identify(userId:)`.
This allows you to correlate Stripe subscriptions with your users directly in Stripe or through webhooks.
## Related
* [Post-Checkout Redirecting](/sdk/guides/web-checkout/post-checkout-redirecting)
* [How do I disable the activation link email for web checkout?](/support/web-checkout/3969573187-how-do-i-disable-the-activation-link-email-for-web-checkout)
* [Web Checkout FAQ](/web-checkout/web-checkout-faq)
---
# Video: Web Checkout Tour on iOS
Source: https://superwall.com/docs/support/web-checkout/1872595046-web-checkout-tour-on-ios
undefined
Join developer advocate Jordan as he walks you through how to web checkout works in Superwall. Learn how to create a new Stripe app, configure it, and then show a paywall via web checkout links. Understand how campaigns and placements work, and watch the redemption flow.
---
# Web Checkout
Source: https://superwall.com/docs/support/web-checkout
Learn how to use the Superwall Web Checkout to integrate Web Checkout into your app.
import { SupportFolderList } from '@/components/SupportFolderList'
---
# How to Transfer Your App to a New Owner
Source: https://superwall.com/docs/support/faq/1379595978-how-to-transfer-app-to-a-new-owner
undefined
When selling or transferring your app to a new owner, you'll need to transfer the associated Superwall account as well. Here's how the transfer process works:
## Transfer Process
1. Contact Superwall support when you're ready to transfer ownership
2. Provide the email address of the new owner (they must have a Superwall account)
3. A Superwall team member will transfer the app to the new owner's account
4. The new owner then has full access to the app
Note: The transfer must be performed by Superwall support staff - there is no self-service option for account transfers.
## What Gets Transferred
The transfer includes:
* App configuration and settings
* Historical data and analytics
* All associated paywalls and campaigns
After the transfer is complete, the previous owner will no longer have access to the app in their Superwall account.
---
# Are Paywall Events and Urgency Messaging App Store Compliant?
Source: https://superwall.com/docs/support/faq/app-store-compliance-paywall-events
Learn about Apple App Store compliance for paywall events like Paywall Dismissed and Transaction Abandoned, as well as urgency-style messaging.
This guide covers common App Store compliance questions about paywall interaction tracking and urgency-based messaging.
## Paywall Events Compliance
**Paywall Dismissed** and **Transaction Abandoned** events are compliant with Apple App Store guidelines. Tracking paywall interactions and purchase flow analytics is standard practice across the industry.
### Follow-up Flows
Re-engagement flows triggered by these events are also compliant, such as:
* Showing a different paywall with a discount after a transaction is abandoned
* Presenting alternative offers when a paywall is dismissed
* Push notifications to users who showed purchase intent
Push notification follow-ups require that users have opted into notifications. Always respect user notification preferences.
## Urgency Messaging Compliance
Apple does not explicitly ban urgency-style messaging on paywalls. Phrases like:
* "One-time offer"
* "You'll never see this again"
* "Limited time discount"
These are permitted, but with one key rule: **the offer must be genuine**.
### What to Avoid
Apple prohibits deceptive practices under their bait-and-switch guidelines. If your "one-time offer" keeps reappearing to the same user, Apple may flag this as deceptive marketing.
If you advertise an offer as exclusive or time-limited, ensure it actually is. Showing the same "one-time offer" repeatedly to users who declined it previously could result in App Store rejection or removal.
### Best Practices
1. **Be honest** - If an offer truly won't return, you can say so
2. **Use genuine scarcity** - Time-limited offers should have real deadlines
3. **Track offer history** - Use user attributes to avoid showing "one-time" offers repeatedly
4. **Document your logic** - Be prepared to explain your offer strategy if Apple requests clarification
## Resources
For the complete App Store Review Guidelines, visit:
* [Apple App Store Review Guidelines](https://developer.apple.com/app-store/review/guidelines/)
---
# Why is my transaction failure rate high?
Source: https://superwall.com/docs/support/faq/why-is-my-transaction-failure-rate-high
undefined
## What is a "Failed Checkout"?
A failed checkout occurs when a user taps to purchase, the payment sheet appears (Apple Pay or Google Pay), but the payment system returns an error before the transaction completes.
## Common Causes
Failed checkouts are typically caused by:
* **Declined payment methods**: Insufficient funds, expired cards, or invalid payment details
* **Fraud prevention**: Apple or Google's systems blocking suspicious transactions
* **Network issues**: Connectivity problems during the payment flow
* **User cancellation**: User dismissing the payment sheet after it appears
## What's a Normal Failure Rate?
A transaction failure rate of **5-6%** is within industry standards. Some variance is expected depending on your audience demographics and geographic distribution.
## What You Can and Can't Control
### Can't control
These failures happen entirely within Apple's or Google's payment infrastructure, between the user and their payment provider. Neither Superwall nor your app can influence these outcomes.
### Can control
While you can't prevent payment-side failures, you can optimize:
* **Paywall UX**: Clear pricing and value proposition
* **Audience targeting**: Showing paywalls to users more likely to convert
* **Timing**: Presenting offers at optimal moments in the user journey
---
# How do I migrate my existing purchases to RevenueCat?
Source: https://superwall.com/docs/support/faq/how-do-i-migrate-my-existing-purchases-to-revenuecat
undefined
## Overview
If you're migrating to RevenueCat, Superwall can help export your existing user and purchase data to facilitate the transition.
## What We Can Export
* **User IDs**: Your Superwall app user identifiers
* **Original Transaction IDs**: Apple's unique subscription identifiers
Note: We don't have access to receipts or receipt-type metadata, but RevenueCat has historically accepted original transaction IDs for migration purposes.
## The Process
1. **Open a support ticket with RevenueCat**: They'll provide specific requirements for the data import
2. **Contact Superwall support**: Once RevenueCat confirms what they need, let us know and we'll coordinate the export
3. **Receive your CSV**: We'll provide a CSV with `app_user_id` and `store_transaction_id` columns
RevenueCat recommends excluding sandbox transactions if appropriate, as sandbox volume can be very large.
## Pricing
* **First 1,000 users:** Free
* **Additional users:** $0.20 per exported subscription
---
# Why is my Android app missing historical revenue data after setting up the Google Play integration?
Source: https://superwall.com/docs/support/faq/why-is-my-android-app-missing-historical-revenue-data
undefined
## The Issue
After setting up the Google Play integration for your Android app, you may notice that historical subscriber data, ARR, and MRR from before the integration aren't showing up. This is different from iOS, where historical data appears after connecting App Store Connect.
## Why This Happens
This is due to a fundamental platform difference between Apple and Google:
### iOS (App Store Connect)
Apple provides a **Transaction History API** that allows Superwall to retrieve historical purchases retroactively. This is why your iOS app shows data from before the integration was set up.
### Android (Google Play)
Google Play **does not offer an equivalent API**. Their system only sends real-time notifications going forward from when the integration is configured. There is no way to pull historical transaction data.
## What You Can Expect
* This is a Google platform limitation, not something Superwall can work around
* All new Android subscription events from the integration point forward will be tracked correctly
* Your metrics will become more complete over time as new events come in
---
# How do I migrate to Superwall from another provider?
Source: https://superwall.com/docs/support/faq/how-to-migrate-from-another-provider-to-superwall
Guide for migrating from Adapty, Qonversion, Glassfy, or other subscription SDKs to Superwall
# How do I migrate to Superwall from another subscription provider?
If you're currently using a subscription management provider like Adapty, Qonversion, Glassfy, or another SDK and want to migrate to Superwall, here's what you need to know.
## Will My Existing Subscribers Keep Their Access?
**Yes.** Superwall reads subscription status directly from the device's App Store (iOS) or Google Play (Android) records. This means:
* Existing subscribers are automatically recognized when you switch SDKs
* No manual migration of subscription data is required
* Users won't experience any interruption to their access
When a user opens your app with the new Superwall SDK, their active subscriptions are detected automatically, regardless of which SDK was used to originally make the purchase.
## What Gets Migrated Automatically
| Data | Migrated? |
| ------------------------------------------------ | ------------------------------------- |
| Active subscription status | ✅ Yes - read directly from the device |
| Entitlement access | ✅ Yes - based on active subscriptions |
| Cross-device sync (same Apple ID/Google account) | ✅ Yes |
## What Does NOT Migrate
| Data | Migrated? |
| ---------------------------------------- | --------------------------------------- |
| Historical analytics and metrics | ❌ No |
| Paywall designs and configurations | ❌ No - must be recreated in Superwall |
| A/B test history and experiment data | ❌ No |
| Custom user attributes from previous SDK | ❌ No - must be re-set via Superwall SDK |
## Migration Steps
1. Remove your current subscription SDK from your project
2. Follow the [Superwall installation guide](/docs/getting-started-with-our-sdks) for your platform
## Troubleshooting
### Subscription status not detected
If an existing subscriber isn't being recognized:
1. Have them tap "Restore Purchases" on any paywall
2. Ensure they're signed into the same App Store/Google Play account used for the original purchase
3. Check that the subscription hasn't expired
---
# How does Superwall's pricing work?
Source: https://superwall.com/docs/support/faq/2801653905-how-does-superwalls-pricing-work
undefined
# Overview
Superwall is changing it's pricing from being based on conversions to being based on MAR (monthly *attributed* revenue).
If you're an **existing customer** you can **choose** to stay on the legacy plan or upgrade
# New Pricing (MAR-based)
See our [pricing page](https://superwall.com/pricing) for the breakdown of our pricing tiers.
The new Superwall pricing offers different tiers of service for a monthly subscription, and charges based on a percentage of MAR, where under $10k MAR is free.
* **Indie**: $0 / month
* **Startup**: $49 / month
* **Scale**: $199 / month
* **Enterprise**: Custom, [contact us!](https://superwall.com/contact/book-a-demo)
Read more about our thinking with our CEO Jake's [post on X](https://x.com/jakemor/status/1981921724934361510).
## What is MAR?
MAR is **Monthly Attributed Revenue**, which is *not* the same as Monthly Revenue. MAR is only revenue that is attributed to a Superwall paywall.
TL;DR: you only pay for revenue that Superwall has directly helped you get.
# Legacy (Conversion-based)
Legacy pricing is only available for existing customers
Superwall offers different pricing tiers based on the number of paywall conversions. Understanding what counts as a conversion and how pricing works is important for choosing the right plan.
Superwall offers three pricing tiers:
* **Indie (Free):** Up to 250 free conversions per month
* **Startup ($0.20/conversion):** Pay-as-you-go pricing, with first 250 conversions free each month
* **Growth (Flat-Rate):** Custom flat-rate pricing with unlimited conversions
## What is a Conversion?
A "conversion" in Superwall's pricing refers to when a user makes a purchase through a Superwall paywall. Here are specific examples of what counts as a conversion:
* A user starting a free trial for a subscription
* A user making a paid one-time in-app purchase through a paywall
* A user subscribing to a monthly plan directly through a paywall
Subscription renewals and trials converting to paid subscriptions do NOT count as conversions.
## Pricing for High-Volume Apps
For apps using the Startup tier ($0.20/conversion) that exceed 5,000 conversions per month:
* You **can continue using the Startup plan** at the same rate of $0.20 per conversion
* However, at this volume it may make sense to explore to our flat-rate Growth plan. When you reach this size [we'd love to talk](https://superwall.com/contact/book-a-demo)!
---
# Can I pre-authenticate users on the subscription management page?
Source: https://superwall.com/docs/support/faq/can-i-pre-authenticate-users-on-subscription-management-page
undefined
## Short Answer
No: for security reasons, users always need to verify their email by clicking a magic link sent to their inbox.
## Pre-filling the Email Field
While full pre-authentication isn't possible, you can pre-fill the email field by passing it as a query parameter:
```
https://{your-app}.superwall.app/manage?email=user@example.com
```
This way, when users open the subscription management page from within your app, their email will already be populated. They just need to tap "Continue" and then click the link in their inbox to access their subscription details.
## Why Magic Link Verification is Required
The subscription management page gives users access to sensitive account information and the ability to modify their subscription. Email verification via magic link ensures that only the actual account owner can access these controls, even if someone else has access to the device.
---
# FAQ
Source: https://superwall.com/docs/support/faq
Common questions and answers about Superwall.
import { SupportFolderList } from '@/components/SupportFolderList'
---
# Sandbox Free Trial Isn’t Appearing
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-sandbox-free-trial-not-showing
Why free trials sometimes don’t show up in sandbox testing and what to do about it.
This can happen when you've previously purchased a subscription and then reinstall the app during sandbox testing. The issue:
* The on-device receipt is used to determine trial availability.
* In sandbox, this receipt isn’t retrieved until after a purchase or restore.
* So the SDK can’t determine if a free trial is available at app start.
**Fix:**
Restore purchases first, then try again. This won’t happen in production.
---
# Why does my entitlement show "Missing App ID" after connecting App Store Connect API?
Source: https://superwall.com/docs/support/troubleshooting/9207773532-why-does-my-entitlement-show-missing-app-id-after-connecting-app-store-connect-api
undefined
When setting up App Store Connect API integration with Superwall, you may see a "Missing App ID" warning next to your products even after connecting the API and adding product identifiers. This occurs when the Apple App ID hasn't been properly configured in your Superwall settings.
To resolve the "Missing App ID" warning:
1. Go to Settings / General in your Superwall dashboard
2. Locate the Apple App ID field
3. Add your app's Apple App ID
This step is required for Superwall to properly fetch and verify your product status from App Store Connect. Once you've added the Apple App ID, the warning should be resolved and your products will be properly linked.
Note: Even if your App Store Connect API is properly configured and your product identifiers match exactly with App Store Connect, the "Missing App ID" warning will persist until you complete this configuration step.
---
# TestFlight Subscriptions
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-testflight-subscriptions
Learn why subscriptions behave differently in TestFlight, including identity resets and accelerated renewal schedules.
When testing your app via TestFlight, subscription behavior differs from production in a few key ways that can lead to confusion. Here’s what to expect:
**Reinstalling the app resets your identity:**
In TestFlight, reinstalling the app (or clearing data) resets the app’s local state. Until the user attempts a purchase, they’ll appear as a **new anonymous user**—even if they’ve already purchased a subscription in a previous session.
Once the user taps the purchase button:
* StoreKit will attempt to purchase the subscription.
* If they’re already subscribed, the system will **restore** the existing subscription.
* Superwall will then receive the updated entitlement info and reflect the user as “subscribed.”
This is expected behavior in TestFlight and is **not how things work in production**, where the app’s receipt is usually preserved across reinstalls from the App Store.
## Subscription renewals are accelerated
Apple speeds up renewals in TestFlight to help test subscription logic faster:
* All subscription durations (weekly, monthly, yearly, etc.) renew **once per day**, up to 6 times.
* After the 6th renewal, auto-renewal is disabled.
For example, if a user starts a 1-month subscription on February 1:
* It will renew every 24 hours through February 7.
* On February 8, the subscription will no longer auto-renew.
> Use [Sandbox Apple Accounts](https://developer.apple.com/documentation/xcode/configuring-sandbox-environment) in TestFlight to simulate renewal failures or billing retry scenarios.
## Summary
| Behavior | TestFlight | Production |
| --------------------------------- | ----------------------- | ---------------------- |
| Reinstall resets identity | ✅ Yes | 🚫 No |
| Purchase triggers restore | ✅ Yes | 🚫 No |
| Subscription renewal | 🔁 Every 24 hrs (max 6) | Based on plan duration |
| Receipt persists between installs | ❌ No | ✅ Yes |
If you see unexpected subscription behavior in TestFlight, it’s often due to this accelerated lifecycle and reset state.
---
# How to Debug Paywall Issues in Production
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-debug-paywalls-production
Learn how to use the dashboard’s event logs to debug paywall behavior for real users.
If you're seeing unexpected behavior in production and know the `userId`, here's how to debug:
1. **Search for the user in the dashboard.**
Go to the Users tab and enter their `userId`. Click the result to see their event log.
2. **Check the `paywallPresentationRequest` event.**
Look for this event in the log. It includes a `status` and `status_reason` that explains why a paywall did or didn’t show.
3. **Common error: `subscription_status_timeout`**
This means it took longer than 5 seconds to retrieve the subscription status. Check if `Superwall.shared.subscriptionStatus` is being set correctly or if there's an internet issue.
4. **Tip:** Use the same `userId` across analytics and Superwall via `identify(userId:)`.
---
# Why aren't my transactions attributing to a placement/paywall?
Source: https://superwall.com/docs/support/troubleshooting/3920414585-why-aren-t-my-revenuecat-transactions-attributing-to-a-placement-paywall
undefined
Only if you're using a PurchaseController, if you are using Superwall for subscription handling logic, this does not apply
## Symptoms
* In the Overview tab under recent transactions, you see transactions like the above, where "Placement" and "Paywall" are missing and not set
* On a user page you see no "Transaction Complete"
This means that Superwall can't **attribute** this purchase event we received from the App Store / RevenueCat back to a purchase made through a Superwall paywall. If the purchase was made through a Superwall paywall, then it signals some disconnect between Superwall and App Store / RevenueCat.
## Debugging Steps
* Update to the latest SDKs, we're always fixing bugs and improving features
* Make sure only offering subscriptions/products through superwall paywalls. if available elsewhere then we won't be able to attribute back to placement/paywall
* Check that you have Revenue Tracking properly set up, and you see events in Settings
* Check that your PurchaseController code matches our example code [here](https://superwall.com/docs/sdk/guides/using-revenuecat)
### If Using RevenueCat:
* Check that all of your products are listed on both the Superwall and RevenueCat dashboards, and they all have entitlements, and the entitlements match **exactly**
* Check that you're calling `Superwall.shared.identify` with the same user id that RevenueCat has
---
# Why are my webhook events not triggering?
Source: https://superwall.com/docs/support/troubleshooting/5990752866-why-are-my-webhook-events-not-triggering
undefined
## Context
Webhook events may not trigger if certain requirements aren't met or if the configuration isn't properly set up. This article explains the common reasons and how to resolve them.
## Answer
The primary requirement for Webhooks to function properly is that they need to be configured with App Store events. Here's how to set this up and troubleshoot common issues:
1. Configure App Store Integration: - Go to Settings / Revenue Tracking
2. Switch to App Store Connect for events and set up the integration
3. Once events from the App Store are sending, you can then switch back to your preferred revenue tracking service (e.g., RevenueCat)
When testing on iOS using local StoreKit transactions (StoreKit Configuration file or StoreKitTest in Xcode), webhook events won't trigger as these don't generate App Store Server Notifications. Use TestFlight or a sandbox Apple ID for testing webhook delivery.
---
# Why am I seeing 520 errors from the events API endpoint?
Source: https://superwall.com/docs/support/troubleshooting/7581794451-why-am-i-seeing-520-errors-from-the-events-api-endpoint
undefined
## Context
When implementing Superwall's SDK, you may notice 520 error responses from the events API endpoint ([https://collector.superwall.me/api/v1/events](https://collector.superwall.me/api/v1/events)) appearing in your error tracking system.
## Answer
The 520 errors you're seeing from the events API endpoint are part of the expected behavior of the SDK's retry mechanism. Here's what you need to know:
* These errors are used by the SDK to identify which events need to be resent
* The SDK implements a retry policy that ensures all events are eventually delivered successfully
* No data is lost during this process, even when you see 520 errors
These errors commonly occur during high-traffic situations, such as when push notifications trigger multiple devices to wake up simultaneously, causing temporary rate limiting on the endpoint.
If these errors are filling up your error tracking quota, you can safely configure your error tracking system to ignore 520 errors from the Superwall events endpoint, as they are handled automatically by the SDK's retry mechanism.
---
# Troubleshooting: iOS SDK
Source: https://superwall.com/docs/support/troubleshooting/8881818609-troubleshooting-ios-sdk
undefined
# Common Issues
* [Products or Prices Not Loading](/support/troubleshooting/products-not-loading)
* [Paywall Not Showing](/support/troubleshooting/6381986971-paywall-not-showing)
# Support
We are always improving our SDKs and documentation. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
If you have any issues **not** covered here please [contact Support](https://superwall.com/docs/support) or [open an issue on GitHub](https://github.com/superwall/superwall-ios/issues)**.**
---
# Why isn't my free trial showing up in my paywall?
Source: https://superwall.com/docs/support/troubleshooting/1205343891-why-isn-t-my-free-trial-showing-up-in-my-paywall-preview
undefined
When a free trial or introductory offer isn't appearing in your paywall, this is typically related to either offer eligibility or App Store Connect setup.
## Offer Eligibility
If you've already subscribed to any subscription in a Subscription Group, then you will no longer be eligible for that Introductory Offer.
To clear your state and continue testing the offer, you need to reset your eligibility in settings, follow Apple's guide here: [**Testing introductory offers**](https://developer.apple.com/documentation/storekit/testing-introductory-offers)
## App Store Connect Setup
Verify that the introductory offer is correctly set up in App Store Connect for your product ID.
To check this, go to **App Store Connect → My Apps → Your App → In-App Purchases → \[Your Subscription] → Subscription Prices → Introductory Offers**.
Make sure the offer is active, properly configured for the right **base plan**, and that your app’s build uses the same **product identifier**.
Superwall does not control whether a product has a free trial or not, Introductory offers are handled directly by Apple
---
# Troubleshooting
Source: https://superwall.com/docs/support/troubleshooting/6022066375-troubleshooting
undefined
## **My paywall has unexpected presentation behavior**
If you are seeing a paywall when you think you shouldn't or vice versa, we recommend running through the following list to debug:
1\. If you're [implementing subscription-related logic yourself](https://superwall.com/docs/advanced-configuration), check when you're setting `Superwall.shared.subscriptionStatus`. It's important that the variable here is kept in sync with the subscription status of the user. If it isn't, the paywall won't display when it is supposed to. If the status is `.unknown` or `.active(_)`, the paywall won't show (unless you're specifically overriding that). [See here](https://superwall.com/docs/advanced-configuration) for more information about that.
2\. Check your device. If you have already purchased a subscription on your device, your paywall wouldn't show again. If on iOS and you're using a local StoreKit file in your app for testing purposes, deleting and reinstalling your app will reset your device's subscription status.
3\. Check your [campaign](https://superwall.com/docs/campaigns). Are you sending the necessary properties along with your placement to match the audience filter? Is your placement name spelt correctly? If you have a holdout group in your campaign double check that this isn't the reason your paywall isn't displaying.
4\. Check that the products on your paywall are available and their identifiers are correct. If not, you'll see an error printed to the console. On iOS, if you're using a StoreKit configuration file to test, make sure to add your products before trying to present the paywall.
## **How can I debug paywall presentation in production?**
If you know the userId of an account that's having trouble with paywalls, search for it in the Users tab on the dashboard. Clicking on it will reveal the user's events log. Whenever a paywall is or isn't shown, you'll see a `paywallPresentationRequest` event. Expanding that will give you a `status` and `status_reason` from which you can figure out what the issue is. If you're seeing `subscription_status_timeout` as a reason, it means that it took longer than 5 seconds to get the subscription status. This could be because you're not setting `Superwall.shared.subscriptionStatus` correctly or there's an issue with internet.
We recommend calling `identify(userId:)` in your app with the same userId that you use in your analytics to make life easier.
## **In iOS, a transaction appeared active when it wasn't**
This can sometimes be related to a target membership issue. To resolve it, try removing all transactions or re-adding the [StoreKit testing file](https://superwall.com/docs/testing-purchases). Here's how:
1\. Open Xcode and navigate to **Debug → StoreKit → Manage Transactions**.
2\. Delete any existing transactions.
3\. If the issue persists, remove your StoreKit configuration file from the project.
4\. Build the project, then re-add the StoreKit file.
## **In sandbox on iOS, my paywall shows free trial text but when I go to purchase, it doesn't show a free trial**
If you've previously purchased a product within a subscription group and then deleted and reinstalled the app while testing in sandbox, this could happen. To fix this, restore products and try again. This is because we use the on-device receipt to determine whether a free trial is available. In sandbox, the app's receipt isn't retrieved until a purchase or restore is made. Therefore, the SDK won't be able to accurately determine whether the free trial is available. Fortunately, this won't happen in production.
## **My products aren't loading or aren't working in production**
If your products haven't loaded you'll get an error message printed to the console. A common symptom of products not loading is payment buttons on your paywall becoming unresponsive when tapped. Run through the following list to solve this:
1. On the Superwall dashboard:
1. Check that you have added products to all paywalls in the paywall editor. If any paywall doesn't contain a valid identifier you will see a error message in the console.
2. For iOS apps:
1. In Xcode:
1. If you're using a StoreKit configuration file locally, make sure your products have been added to it, either manually or by syncing with App Store Connect.
2. Make sure your app's bundle ID is the same as your app in App Store Connect.
3. Check you've added in-app purchase capability to your app's Xcode project.
2. On App Store Connect:
1. Make sure your free and paid apps agreements status are active.
2. Make sure that your tax and banking information has been added.
3. Make sure your product status is 'Ready to Submit'.
4. Check that the IDs of your products match those in the paywall.
5. Make sure you've waited at least 15 minutes after creating a product.
3. In Production:
1. Make sure you have waited for at least 72 hours after the release of a new app for your products to appear in your app. As soon as they appear on your App Store page, you'll know they're available in-app.
3. For Android apps:
1. Users in Russia and Belarus don't have access to Google Billing. In this instance, products won't load and paywalls won't show. The `onError` PaywallPresentationHandler handler will get called.
2. Make sure the device or emulator you're running on has the Play Store app and that you are signed in to your Google account on the Play Store.
3. Make sure your applicationId matches the applicationId on the Play Store.
4. If you're using RevenueCat:
1. Check that your product IDs are added to RevenueCat and associated with an entitlement.
2. If you're using offerings, make sure your product is associated with one.
---
# Troubleshooting: Flutter SDK
Source: https://superwall.com/docs/support/troubleshooting/6999598520-troubleshooting-flutter-sdk
undefined
# Common Issues
* [Products or Prices Not Loading](/support/troubleshooting/products-not-loading)
* [Paywall Not Showing](/support/troubleshooting/6381986971-paywall-not-showing)
# Support
We are always improving our SDKs and documentation. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
If you have any issues **not** covered here please [contact Support](https://superwall.com/docs/support) or [open an issue on GitHub](https://github.com/superwall/superwall-flutter/issues)**.**
---
# Why does my subscription status remain INACTIVE after successful purchase?
Source: https://superwall.com/docs/support/troubleshooting/8569105587-why-does-my-subscription-status-remain-inactive-after-successful-purchase
undefined
## Context
When implementing subscriptions in your iOS app with Superwall, you might notice that the subscription status remains INACTIVE even after a successful purchase transaction. This can affect your app's flow and user access to premium features.
## Answer
If you are using Superwall for purchase handling:
* You need to configure [Entitlements](https://superwall.com/docs/dashboard/products#entitlements) for all of your products in the Superwall dashboard:
* Navigate to the Products tab in your Superwall dashboard
* Add Entitlements to all of your products
If you are **not** using Superwall for purchase handling, and you're using a [PurchaseController](https://superwall.com/docs/using-revenuecat#using-revenuecat):
* Your PurchaseController is in charge of setting the user's subscription status
* Check that your implementation matches our [example code](https://superwall.com/docs/using-revenuecat#using-revenuecat)
* Check that syncSubscriptionStatus is called on launch
* Check that all of your products are listed on both the Superwall and RevenueCat dashboards, and they all have entitlements, and the entitlements match **exactly**
---
# Why is my paywall not updating after publishing?
Source: https://superwall.com/docs/support/troubleshooting/why-is-my-paywall-not-updating-after-publishing
Troubleshoot why users may still see an outdated paywall after you've made and published updates in the Superwall dashboard
## Quick Checklist
Before diving into detailed troubleshooting, verify these common causes:
* [ ] Have you **published** the paywall after making changes?
* [ ] Is the user **assigned to a different paywall** in an A/B test?
* [ ] Are you using **conditional visibility** (e.g., `hasIntroductoryOffer`) that shows different content?
* [ ] Has the user's **trial eligibility** changed, showing a different UI state?
***
## Step 1: Verify the Paywall is Published
Changes made in the paywall editor are saved locally but not live until published.
**To check:**
1. Open the paywall in the editor
2. Look for the **Publish** button in the top-right
3. If it's clickable, your changes haven't been published yet
**Note:** Publishing a paywall doesn't automatically update users who have already been assigned to it in an experiment.
***
## Step 2: Check Campaign and Experiment Setup
### Multiple Paywalls in a Campaign
If your campaign has multiple paywalls (an A/B test), users are randomly assigned to one variant. The user seeing an "outdated" paywall may simply be assigned to a different variant than the one you updated.
**To check:**
1. Go to **Campaigns** → Select your campaign
2. Look at the **Paywalls** tab for the relevant audience
3. Verify which paywalls are active and their distribution percentages
### Sticky Assignments
**Important:** Superwall assignments are "sticky." Once a user is assigned to a paywall variant, they continue seeing that same paywall regardless of:
* Changes you make to presentation percentages
* Updates you publish to other paywalls
* App reinstalls or calling `Superwall.reset()`
This is by design. It ensures experiment integrity and allows you to keep existing users on an old pricing while testing new pricing with new users.
***
## Step 3: Check Conditional Visibility and Dynamic Values
Paywalls often use **dynamic values** to show different content based on conditions. The most common scenario is **trial eligibility**.
### Trial Eligibility (`products.hasIntroductoryOffer`)
If your paywall has components with visibility controlled by `products.hasIntroductoryOffer`:
* **True:** User is eligible for a free trial/intro offer
* **False:** User has already used their trial (or the product has no trial)
**Common issue:** Apple App Store reviewers often test with accounts that have already used trials, so `hasIntroductoryOffer` is `false` for them, showing different UI than you expect.
**To check in the editor:**
1. Open your paywall in the editor
2. Click **Variables** in the floating toolbar
3. Toggle `products.hasIntroductoryOffer` between true/false
4. Observe which components appear/disappear
### Other Dynamic Conditions
Check if any components have visibility rules based on:
* Selected product index
* Device type
* User attributes
* Custom parameters
Look for components that have the **gear icon** indicating dynamic values are set.
***
## Step 4: Verify Products Are Correctly Configured
### Product Approval Status
Products must be approved in App Store Connect before they can be properly displayed:
* Products in "Waiting for Review" may not load correctly
* Sandbox testing uses different product states than production
**To check:**
1. Go to App Store Connect → Your App → Subscriptions
2. Verify all products show "Ready to Submit" or "Approved"
### Product Assignment on Paywall
Ensure the correct products are assigned to your paywall:
1. Open the paywall in the editor
2. Check the **Products** section on the left sidebar
3. Verify the intended products are selected as Primary, Secondary, etc.
***
## Step 5: Understand Caching Behavior
### Server-Side Caching
Superwall's static configuration is cached by CDN for up to **1 hour**. After publishing changes:
* New users get the update immediately (fresh cache)
* Existing users may see cached content for up to 1 hour
### Device-Side Caching
If your paywall has **Cache on Device** enabled in settings:
* The SDK stores the paywall locally for faster presentation
* Reinstalling the app clears this cache
* `Superwall.reset()` clears on-device data but NOT server-side assignments
***
## Step 6: Testing Checklist
When testing paywall updates, follow this process:
### For Fresh Testing
1. Wait a few minutes for cache propagation
2. Use a **new user ID** or test account
3. Delete and reinstall the app
4. Trigger the placement that shows the paywall
### For App Store Review
1. Remember reviewers may not be eligible for trials (trial already used)
2. Test your paywall with `hasIntroductoryOffer = false` in the editor
3. Ensure all UI states look correct for non-trial-eligible users
***
## Common Scenarios and Solutions
| Scenario | Likely Cause | Solution |
| ---------------------------------------------- | --------------------------------------------- | ------------------------------------------ |
| User sees old paywall copy | Sticky assignment to old variant | Wait for new users or use new test account |
| User sees different products | Assigned to different A/B variant | Check which variant user is assigned to |
| Trial text showing when user isn't eligible | `hasIntroductoryOffer` conditional visibility | Check dynamic values on text components |
| Non-trial text showing for trial-eligible user | Same as above, inverted | Verify conditional logic in editor |
| Changes not visible after publishing | CDN cache or device cache | Wait up to 1 hour, or reinstall app |
| App Store reviewer sees wrong content | Reviewer's trial eligibility differs | Design for both trial/non-trial states |
***
## Related Documentation
* [Publishing Paywalls](https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-publishing)
* [A/B Testing and Experiments](https://superwall.com/docs/campaigns/campaigns-starting-an-experiment)
* [Dynamic Values](https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-dynamic-values)
* [Variables Reference](https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-variables)
* [Campaign Audiences](https://superwall.com/docs/campaigns/campaigns-audience)
---
# Why are my trials still showing as pending after they should have converted?
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-pending-trials-not-converting
undefined
## Understanding Pending Trials
If you're seeing trials that remain in "pending" status long after the trial period should have ended, this is usually expected behavior related to how Apple handles billing.
## Common Causes
### Billing Retry Period
When a user has a billing issue (e.g., expired card, insufficient funds), Apple doesn't immediately cancel the subscription. Instead, Apple will **retry billing for up to 16 days**. During this entire period, the trial remains in "pending" status in Superwall.
### Billing Grace Period
Your billing grace period setting in App Store Connect affects how long users stay in pending status. This is configurable and can be tuned based on your preferences.
## What You Can Do
* **Check App Store Connect** — Review your billing grace period settings and adjust if needed
* **Expect some delay** — It's normal to see a significant number of pending trials due to billing retries
* **Wait for resolution** — Most pending trials will resolve within 16 days as either converted or cancelled
---
# Why is my webhook's originalAppUserId different from the user ID I set?
Source: https://superwall.com/docs/support/troubleshooting/5131096404-why-is-my-webhook-s-originalappuserid-different-from-the-user-id-i-set
undefined
## Context
When receiving webhook events from Superwall, you may notice that the originalAppUserId in the webhook payload doesn't match the user ID you set using the identify API. This is important for tracking user transactions and attributing payments correctly.
## Answer
To ensure the correct user ID appears in webhook events, you need to use a compatible SDK version:
* For iOS: SDK version 4.6.0 or higher
* For Android: Use the latest SDK version and configure `passIdentifiersToPlayStore` in your `SuperwallOptions`
* For Expo: expo-superwall version 0.2.7 or higher
**Timing Requirement:** You must call `identify()` with your custom user ID **before** any transactions are made. If you call `identify()` after a purchase has already occurred, the webhook will still contain the original alias ID (starting with `$superwallAlias:`) rather than your custom user ID.
**Best Practice:** Call `identify()` immediately after user login or authentication in your app, before presenting any paywalls or allowing purchases. This ensures all subsequent transactions will be attributed to your custom user ID in webhook events.
Important: For users who have already made transactions on a lower SDK version, the originalAppUserId will remain incorrect even after updating. This only affects historical transactions - new transactions from new users will show the correct ID after updating to the compatible SDK version.
## Additional Android Configuration
For Android apps, you must also configure the SDK to pass user identifiers to the Play Store:
val options = SuperwallOptions()
options.passIdentifiersToPlayStore = true
Superwall.configure(applicationContext, "YOUR\_API\_KEY", options)
Ensure your user IDs do not contain personally identifiable information (PII), as this could prevent transmission to the Play Store.
---
# Why is my paywall not loading on Android with Billing Service Unavailable?
Source: https://superwall.com/docs/support/troubleshooting/9619927130-why-is-my-paywall-not-loading-on-android-with-billing-service-unavailable-error
undefined
## Context
When implementing Superwall paywalls in Android, you may encounter issues where paywalls fail to show with the error `The entitlement status failed to change from "unknown"`.
In order to properly evaluate your paywall presentation logic, the Superwall SDK **must** know the exact subscription status of the user, without it we cannot show paywalls.
## Answer
### If you're using a [PurchaseController](https://superwall.com/docs/ios/sdk-reference/PurchaseController) (advanced):
When using a `PurchaseController`, you become responsible for setting the subscription status in the Superwall SDK on launch, and updating during the app session. This error means that the subscription status was never updated on launch.
### If you're not using a [PurchaseController](https://superwall.com/docs/ios/sdk-reference/PurchaseController) (default):
Android: Check that your device has access to Google Play Billing and is properly configured
* The Superwall SDK requires access to billing services to determine subscription status. When this service is unavailable, the subscription status remains "unknown," preventing paywalls from displaying.
---
# StoreKit Transactions Not Clearing in Xcode
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-storekit-transaction-stuck
Fix for when a test transaction seems stuck or active when it shouldn’t be.
Sometimes StoreKit test transactions appear active when they’re not. This is often due to a target membership issue or StoreKit config issue. To fix:
1. Open Xcode → **Debug → StoreKit → Manage Transactions**.
2. Delete all existing transactions.
3. If it still fails, remove the StoreKit config file from the project.
4. Build and run the project again.
5. Re-add the StoreKit config file.
---
# Paywall Memory Usage on iOS
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-paywall-memory-usage-on-iOS
Investigate why your paywall might look like it's using more memory than you expect in Instruments.
When inspecting memory usage in Instruments, you might notice your paywall appears to be using over, or around, 512MB of memory. That can seem concerning, but in almost all cases, it's nothing to worry about.
Whenever a `WKWebView` is created, WebKit reserves a chunk of memory (typically 512MB) for virtual machine allocation. That memory is reserved by iOS, and most apps using WebKit on iOS will see similar readings during profiling within Instruments. In short, this is just how `WKWebView` is designed to work under the hood.
## Can I reduce this memory usage?
If your app creates a lot of paywalls or manages many `WKWebView` instances, you can reduce memory usage by turning off paywall preloading:
```swift
let options = SuperwallOptions()
options.paywalls.shouldPreload = false
Superwall.configure(apiKey: "MY_API_KEY", options: options)
```
This prevents Superwall from creating webviews ahead of time, which reduces memory pressure. However, the tradeoff is that the paywall will take slightly longer to show and users will briefly see the loading view as the paywall is initialized on demand.
We recommend leaving preloading on unless you're noticing real performance issues or memory warnings.
---
# Products Not Loading: iOS
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading/1253018505-products-not-loading-ios
undefined
This is a guide to getting products to load on a real iOS device, meaning:
* ✅ From TestFlight
* ✅ From App Store
* ✅ Built from Xcode **without** [a StoreKit config file](https://superwall.com/docs/ios/guides/testing-purchases)
* ❌ Built from Xcode **with** [a StoreKit config file](https://superwall.com/docs/ios/guides/testing-purchases)
* ❌ [**iOS simulator**](/support/troubleshooting/products-not-loading/4739776203-products-not-loading-ios-simulator)
If you're having issues with products loading elsewhere please reference the [Products Not Loading: Troubleshooting Guide](/support/troubleshooting/products-not-loading).
***
# Symptoms
* Prices not showing on paywall
* Tapping purchase button on paywall doesn't do anything
* Error logs saying products not loading
# Debugging Steps
Products not loading is a common issue when first setting up any app with subscriptions. This is a tried and true, all encompassing list of steps to debug.
Please double check every step, they are all required and *any* misconfiguration can cause your products to not load.
## Xcode
* Your app’s bundle ID **exactly** matches to App Store Connect
* In-App Purchase capability is added to the project
## Superwall Dashboard
* The paywall you're trying to open has a product added to it
* All of your products are added in the [products tab](https://superwall.com/applications/\:applicationId/products/v2), and have an Active status
## App Store Connect
* No products are in **“Missing Metadata”** status
* You have valid Localization set for all your subscription products and the subscription group(s)
* Product IDs match your paywall on the Superwall Dashboard **exactly**
* All agreements are active, there are no unsigned agreements (Business -> Agreements)
* Tax and banking info is completely set up
* You've waited at least 15 minutes after creating the products
After first releasing your app with in-app products or subscriptions, it can take up to 72 hours for them to appear. This is a limitation on Apple's end we cannot override.
# Support
We have covered all known causes for this issue, and aim to make this a completely comprehensive guide. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
Please check **all** steps before contacting support.
---
# Products Not Loading: iOS Device with StoreKit config file
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading/4845457144-products-not-loading-ios-device-with-storekit-config-file
undefined
This is a guide to getting products to load in:
* ✅ Built from Xcode **with a StoreKit config file**
* ❌ [Built from Xcode, **without a StoreKit config file**](/support/troubleshooting/products-not-loading/1253018505-products-not-loading-ios)
* ❌ [From TestFlight or App Store](/support/troubleshooting/products-not-loading/1253018505-products-not-loading-ios)
* ❌ [**iOS simulator**](/support/troubleshooting/products-not-loading/4739776203-products-not-loading-ios-simulator)
If you're having issues with products loading elsewhere please reference the [Products Not Loading: Troubleshooting Guide](/support/troubleshooting/products-not-loading).
***
Because StoreKit config files supply products *directly* and not from Apple servers, we recommend checking that your products are set up correctly at least once by running from **TestFlight**.
# Not Working?
When using a StoreKit config file, products are loaded *directly* from there into the app based on the product id, not from Apple or Superwall servers. If your products are still not loading, it is because one of these two issues
1. Double check that the scheme being run has a StoreKit config correctly set
2. Check that the product ids on your paywall in the Superwall Dashboard **exactly** match what's in your StoreKit config file
# Support
Please check **all** steps before contacting support.
We have covered all known causes for this issue, and aim to make this a completely comprehensive guide. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
---
# Products Not Loading: iOS Simulator
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading/4739776203-products-not-loading-ios-simulator
undefined
This is a guide to getting products to load in:
* ✅ iOS Simulator
* ❌ [Real iOS device](/support/troubleshooting/products-not-loading/1253018505-products-not-loading-ios)
If you're having issues with products loading elsewhere please reference the [Products Not Loading: Troubleshooting Guide](/support/troubleshooting/products-not-loading).
***
# Problem
The iOS simulator **cannot** load products directly from Apple like real devices do.
# Solution
In order to load products in an iOS simulator you **have** to set up a [local StoreKit config file](https://superwall.com/docs/ios/guides/testing-purchases). Without it, your products will not load.
This is true regardless of SDK type, native iOS, Flutter, and Expo all need to configure a StoreKit config file **in Xcode** in order to load products on iOS simulator.
Because StoreKit config files supply products *directly* and not from Apple servers, we recommend checking that your products are set up correctly at least once by running from **TestFlight**.
# Still Not Working?
When using a StoreKit config file, products are loaded *directly* from there into the app based on the product id, not from Apple or Superwall servers. If your products are still not loading, it is because one of these two issues
1. Double check that the scheme being run has a StoreKit config correctly set
2. Check that the product ids on your paywall in the Superwall Dashboard **exactly** match what's in your StoreKit config file
# Support
Please check **all** steps before contacting support.
We have covered all known causes for this issue, and aim to make this a completely comprehensive guide. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
---
# Products Not Loading: Android
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading/3716347779-products-not-loading-android
undefined
This is a guide to getting products to load on Android, if you're having issues with products loading elsewhere please reference the [Products Not Loading: Troubleshooting Guide](/support/troubleshooting/products-not-loading).
***
# Symptoms
* Prices not showing on paywall
* Tapping purchase button on paywall doesn't do anything
* Error logs saying products not loading
# Debugging Steps
Products not loading is a common issue when first setting up any app with subscriptions. This is a tried and true, all encompassing list of steps to debug.
Please double check every step, they are all required and *any* misconfiguration can cause your products to not load.
## Superwall Dashboard
* The paywall you're trying to open has a product added to it
* All of your products are added in the [products tab](https://superwall.com/applications/\:applicationId/products/v2)
## Google Play Store
* Ensure the device/emulator has the Play Store and is signed in.
* Check that your `applicationId` matches what’s set in your project.
* You've pushed at least one build with `com.android.vending.BILLING` to at least to one of your test tracks
* You’ve linked a Google payments merchant account in the Play Console
* Users in Russia and Belarus don’t have access to Google Billing.
* In this instance, products won’t load and paywalls won’t show. The `onErrorPaywallPresentationHandler` handler will get called.
# Support
We have covered all known causes for this issue, and aim to make this a completely comprehensive guide. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
Please check **all** steps before contacting support.
---
# Products Not Loading: Browser Preview
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading/9984011656-products-not-loading-safari-preview
undefined
This is a guide to getting products to load in the browser preview if you're having issues with products loading elsewhere please reference the [Products Not Loading: Troubleshooting Guide](/support/troubleshooting/products-not-loading).
***
# Problem
Browser previews of paywalls do not load products, so they don't have product-related info like prices, durations, or introductory offer eligibility states. **This is the expected behavior**
# Solution
Products and prices cannot load in browser previews, they will only work on a real device. We recommend using browser previews for testing all UI *besides* product-info, and to test products in-app on a real device.
---
# Products Not Loading: Troubleshooting Guide
Source: https://superwall.com/docs/support/troubleshooting/products-not-loading
undefined
Products not loading is a common issue when first setting up any subscription app. This is the starting point for Superwall's comprehensive guide to troubleshooting this issue.
## Symptoms
* Prices not showing on paywall
* Tapping purchase button on paywall doesn't do anything
* Error logs saying products not loading
## Guides
Depending on where you are seeing this issue, can change how to debug a lot. Please check the guide for your device type:
* [iOS Simulator](/support/troubleshooting/products-not-loading/4739776203-products-not-loading-ios-simulator)
* [iOS (real device)](/support/troubleshooting/products-not-loading/1253018505-products-not-loading-ios)
* [Android](/support/troubleshooting/products-not-loading/3716347779-products-not-loading-android)
* [Browser Preview](/support/troubleshooting/products-not-loading/9984011656-products-not-loading-safari-preview)
## Support
Please check **all** the steps of the relevant guide before contacting support.
We have covered all known causes for this issue, and aim to make this a completely comprehensive guide. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
---
# Why am I getting PlacementNotFound errors for active placements in Expo?
Source: https://superwall.com/docs/support/troubleshooting/8550351416-why-am-i-getting-placementnotfound-errors-for-active-placements-in-expo
undefined
## Answer
If you're seeing PlacementNotFound errors for placements that are active in your dashboard while using Expo, this is because the SDK doesn't automatically update to reflect your latest dashboard changes during development.
To resolve this issue:
1. Completely quit your Expo development app
2. Relaunch the app to load the updated placement configuration
The SDK requires a full restart to sync with any changes made in the dashboard, including newly created or modified placements.
Hot reloading support is planned for future releases, but currently a full app restart is required after making any placement changes in the dashboard.
---
# Troubleshooting: Android SDK
Source: https://superwall.com/docs/support/troubleshooting/3578026824-troubleshooting-android-sdk
undefined
# Common Issues
* [Products or Prices Not Loading](/support/troubleshooting/products-not-loading)
* [Paywall Not Showing](/support/troubleshooting/6381986971-paywall-not-showing)
# Support
We are always improving our SDKs and documentation. If you have any thoughts on how to improve or know of any other causes, please leave feedback below!
If you have any issues **not** covered here please [contact Support](https://superwall.com/docs/support) or [open an issue on GitHub](https://github.com/superwall/superwall-android/issues)**.**
---
# Why am I seeing a billing issue after my free trial ends?
Source: https://superwall.com/docs/support/troubleshooting/4741512872-why-am-i-seeing-a-billing-issue-after-my-free-trial-ends
undefined
When a free trial ends and there is a billing issue during the conversion to a paid subscription, this is handled entirely by Apple's/Google's billing system. This is a common scenario that can occur for various reasons on their end, such as expired credit cards or insufficient funds.
## Here's what happens in this situation:
* Apple will automatically attempt to resolve the billing issue on their end
* If successful, the user will be converted to a paid subscription
* No action is required from you or within the Superwall dashboard
## How can I fix or prevent this?
Unfortunately as this is handled by the App Stores themselves, neither app developers nor Superwall can directly address or resolve these billing issues.
---
# Sandbox Entitlements Persist After Reset
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-sandbox-entitlements-persist
Why Apple sandbox entitlements remain active after clearing purchase history and reinstalling, and how to work around this limitation.
When testing subscriptions using Apple's Sandbox environment (via TestFlight or Xcode), you may find that entitlements persist even after taking all the typical reset steps:
* Clearing purchase history from the Sandbox Apple ID
* Removing and re-adding the Sandbox account
* Deleting and reinstalling the app
* Calling `Superwall.shared.reset()`
* Restarting the device
This is expected behavior caused by how Apple's sandbox infrastructure caches subscription state. It is not a Superwall issue.
## Why this happens
Apple's sandbox environment maintains entitlement state at the server level, not just on the device. Even when you clear local data and purchase history, the sandbox server may still report the subscription as active. This state can persist for an unpredictable amount of time.
The `Superwall.shared.reset()` method clears Superwall-specific data (user ID, paywall assignments, and cached data), but it cannot clear Apple's StoreKit entitlement state because that state is managed entirely by Apple's systems.
## The solution: Use fresh sandbox accounts
The most reliable way to test a clean subscription flow is to use a new sandbox account for each test. Apple allows up to 10,000 sandbox test accounts per developer account, so you can create them freely.
**Quick tip for creating multiple accounts:**
Sandbox accounts do not require email verification. Use email aliases with the `+` syntax to create multiple accounts from a single email address:
* `youremail+test1@gmail.com`
* `youremail+test2@gmail.com`
* `youremail+test3@gmail.com`
Each alias creates a distinct sandbox account while all emails still arrive at your main inbox.
When you need a guaranteed clean slate for testing subscriptions, always use a fresh sandbox account.
---
# Why are my products showing "Unknown" status in Superwall?
Source: https://superwall.com/docs/support/troubleshooting/9558513118-why-are-my-products-showing-unknown-status-in-superwall
undefined
Products showing an "Unknown" status in the Products tab indicates an issue with Superwall's connection to App Store Connect, here's how to resolve it.
# Debugging Steps
* Set up the App Store Connect API configuration in your Superwall dashboard
* **Product IDs**: check that they match **exactly** across Superwall and App Store Connect
* **IDs in Settings / General**: check that the following are set correctly in the Superwall dashboard and match what's in App Store connect exactly:
* App ID
* Bundle ID
* Team ID
* **App Store Connect API Key permissions**: check that your API key has the "App Manager" role and access to your app
* **Unsigned agreements**: Check if your developer agreement needs to be re-approved in App Store Connect. Even with proper API configuration, products may show "Unknown" status if your developer agreement has expired or needs re-approval
**Important**: This is not *required* for Superwall to work, but is strongly recommended to help keep track of your products status.
---
# Paywall Not Showing
Source: https://superwall.com/docs/support/troubleshooting/6381986971-paywall-not-showing
undefined
## Issue
Any unexpected paywall presentation behavior, including:
* Paywall is not showing when it should
* Paywall is showing when it shouldn't
* Paywall is showing but loading indefinitely
## Debugging Steps
### Check your subscription status logic.
This only applies if you're using a PurchaseController. If you're using Superwall to handle all purchase logic (the default) you can skip this
* Important: When using a `PurchaseController` (such as with RevenueCat), the subscription status starts as `.unknown` by default. Your app must manually set it to either `.active()` or `.inactive()` on app launch - the SDK will not automatically determine this for you. Paywalls will not show if the subscription status is unknown
### Test device considerations.
If you’ve previously purchased a subscription, the paywall won’t show again. On iOS, if you’re using a local StoreKit config file, delete and reinstall the app to reset the device’s subscription state.
When basic app deletion doesn't resolve test subscription persistence, consider the following:
* Cross-account subscription persistence: Test subscription status persists at the device level even when switching between different app accounts within the same app. If you've made a test purchase on one account, it affects paywall presentation for all accounts on that device.
* Hidden test purchases: Test purchases made through StoreKit may not appear in your iPhone's standard Settings > Apple ID > Subscriptions list, making them impossible to cancel manually. This is normal behavior for sandbox/test purchases.
* Alternative reset methods: For production App Store testing when app deletion isn't sufficient, use a different physical device or fresh simulator instance that hasn't made the test purchase.
### Review your campaign configuration.
Confirm your placement name is spelled correctly and that all necessary properties are passed to match the audience filter. Also check for any holdout groups that might block the paywall.
If you've recently updated your campaign, make sure to quit and re-open your app to fetch the latest configuration
### Specific Campaign Configuration Considerations
Be aware of the default entitlement settings for new campaigns. By default, campaigns are set to "For Unsubscribed Users Only" in the entitlements section. If you want to test paywalls while having an active subscription, change the entitlement dropdown to "For All Users."
When encountering console errors, specifically "Skipped paywall presentation: no\_rule\_match," it indicates the user doesn't match the audience filters for that placement. This helps distinguish between configuration issues versus subscription status problems.
For `noAudienceMatch` errors, systematically verify that your audience configuration includes the current user's specific attributes, subscription status, and any custom properties you're tracking.
### Verify product configuration.
If your paywall references unavailable or invalid product identifiers, you’ll see a console error. When using a StoreKit file, be sure to add your products before testing paywall presentation.
## Paywall Loading Indefinitely
Your paywall shows a white screen with gray placeholder boxes that never finish loading. This typically occurs on iOS when using Apple's `WKAppBoundDomains` feature in your app's `Info.plist`.
### Cause
WKAppBoundDomains is an iOS 14+ privacy feature that restricts WebView capabilities. When enabled, it disables WebView message handlers that Superwall requires for bridge communication between the native SDK and the paywall content. You may see this warning in the WebView console:
```
[Warning] [WebKit] Unable to send message - WebKit message handler not available.
```
### Solution
Remove the `WKAppBoundDomains` key from your app's `Info.plist` file:
```
WKAppBoundDomainsexample.com
```
After removing this configuration, rebuild and relaunch your app. The paywall should now load correctly. If you require WKAppBoundDomains for other parts of your app, please contact Superwall support to discuss alternative integration options.
---
# Fixing Unexpected Paywall Behavior
Source: https://superwall.com/docs/support/troubleshooting/troubleshooting-unexpected-paywall-behavior
Step-by-step checklist when a paywall shows up when it shouldn’t—or doesn’t when it should.
If you're seeing a paywall when you think you shouldn't—or not seeing one when you should—run through this checklist:
1. **Check your subscription status logic.**
If you're [implementing subscription-related logic yourself](/advanced-configuration), make sure `Superwall.shared.subscriptionStatus` is kept in sync with the actual subscription status. If it's `.unknown` or `.active(_)`, the paywall won’t show unless explicitly overridden.
2. **Test device considerations.**
If you’ve previously purchased a subscription, the paywall won’t show again. On iOS, if you’re using a local StoreKit config file, delete and reinstall the app to reset the device’s subscription state.
3. **Review your campaign configuration.**
Confirm your placement name is spelled correctly and that all necessary properties are passed to match the audience filter. Also check for any holdout groups that might block the paywall.
4. **Verify product configuration.**
If your paywall references unavailable or invalid product identifiers, you’ll see a console error. When using a StoreKit file, be sure to add your products before testing paywall presentation.
---
# Why am I seeing "Sign in to Apple Account" when testing in-app purchases?
Source: https://superwall.com/docs/support/troubleshooting/6204964383-why-am-i-seeing-sign-in-to-apple-account-when-testing-in-app-purchases
undefined
The cause for this alert depends on the type of device you're using to test:
## iOS Simulator
iOS simulators cannot make real purchases or sign into real Apple accounts, you have to use a [local StoreKit configuration file](https://superwall.com/docs/ios/guides/testing-purchases). If you're seeing this alert on a simulator it means you're either not using a StoreKit config or it's not set on your current scheme correctly.
## Real Device
When testing in-app purchases in a development environment on a physical iOS device, you'll need to use a Sandbox Account to process test purchases.
1. Go to your device's Settings
2. Navigate to App Store
3. Select Sandbox Account
4. Sign in with your Apple Sandbox Account credentials
---
# Why am I not receiving webhook events?
Source: https://superwall.com/docs/support/troubleshooting/5316844925-why-am-i-not-receiving-webhook-events-when-using-revenuecat
undefined
## Context
When using Superwall alongside RevenueCat, you may encounter situations where webhook events are not being received or displayed in the webhooks dashboard.
## Answer
There are two main scenarios where webhook events may not work correctly:
* Using RevenueCat in observer mode while relying on it for events
* Testing with a StoreKit configuration file
To ensure webhook events are working properly:
1. Make sure you're sending real App Store events rather than only RevenueCat events
2. Avoid using StoreKit configuration files for webhook testing
For accurate webhook testing, use real App Store transactions instead of RevenueCat events or StoreKit configuration files.
---
# Troubleshooting: Expo SDK
Source: https://superwall.com/docs/support/troubleshooting/4780985851-troubleshooting-expo-sdk
undefined
**Important: Expo SDK 53+ Required**
This SDK is exclusively compatible with Expo SDK version 53 and newer. For projects using older Expo versions, please use our [**legacy React Native SDK**](https://github.com/superwall/react-native-superwall).
## Common Issues
* [Products or Prices Not Loading](/support/troubleshooting/products-not-loading)
* [Paywall Not Showing](/support/troubleshooting/6381986971-paywall-not-showing)
* [Paywall Autorotates on Android](#paywall-autorotates-on-android)
## Paywall Autorotates on Android
If your app is locked to portrait in `app.json` but the Superwall paywall still rotates on Android, Expo may not be writing the orientation to the `SuperwallPaywallActivity` in `AndroidManifest.xml`. Add a config plugin that sets `android:screenOrientation` for that activity, then run `prebuild`/EAS build so the manifest is regenerated.
```js
const { withAndroidManifest } = require("@expo/config-plugins");
module.exports = function withSuperwallLockedOrientation(config) {
return withAndroidManifest(config, (config) => {
const app = config.modResults.manifest.application[0];
if (!app.activity) {
app.activity = [];
}
// Look for SuperwallPaywallActivity
const paywallActivity = app.activity.find(
(activity) =>
activity.$["android:name"] ===
"com.superwall.sdk.paywall.view.SuperwallPaywallActivity",
);
if (paywallActivity) {
// Override orientation if activity already exists
paywallActivity.$["android:screenOrientation"] = "portrait";
} else {
// Inject if missing
app.activity.push({
$: {
"android:name":
"com.superwall.sdk.paywall.view.SuperwallPaywallActivity",
"android:theme": "@style/Theme.MaterialComponents.DayNight.NoActionBar",
"android:configChanges": "orientation|screenSize|keyboardHidden",
"android:screenOrientation": "portrait",
},
});
}
return config;
});
};
```
## Support
We are always improving our SDKs and documentation! The Expo SDK is being actively developed, and we're committed to making it the best way to integrate paywalls into your Expo projects!
If you have any thoughts on how to improve or know of any other causes, please leave feedback below! If you have any issues **not** covered here please [contact Support](https://superwall.com/docs/support) or [open an issue on GitHub](https://github.com/superwall/expo-superwall/issues)**.**
---
# Why does my user show active subscription but no data in the dashboard?
Source: https://superwall.com/docs/support/troubleshooting/subscription-status-active-but-no-dashboard-data
Understanding why a user may have an active subscription on device but no entitlements, Apple events, or webhooks in the Superwall dashboard
## Understanding How Superwall Tracks Subscriptions
Superwall uses two different sources of truth for subscription data:
### 1. On-Device Subscription Status (SDK)
The SDK determines subscription status by reading the **local Apple receipt** directly from StoreKit. This receipt is tied to the user's **Apple ID**, not their Superwall user ID.
If there's a valid subscription receipt on the device, the SDK will report `subscriptionStatus = active`, regardless of which Superwall user ID is currently active.
### 2. Dashboard Attribution (Server-Side)
The dashboard displays subscription data (entitlements, Apple server events, webhooks, receipts) that is attributed to a specific **Superwall user ID**. This attribution happens at the time of purchase. Whichever user ID was active when the transaction occurred is the one that gets linked to the subscription data.
## The Most Common Cause
When you see an active subscription on device but nothing in the dashboard, it almost always means:
**The subscription was purchased under a different Superwall user ID than the one you're currently looking at.**
This can happen when a user:
* Reinstalls the app (generates a new anonymous user ID)
* Logs out and back in (may generate a new user ID depending on your implementation)
* Switches accounts
* Had their identity reset for any reason
The subscription remains valid because Apple validates it against the user's Apple ID. But all the purchase events, webhooks, and server notifications are attributed to the **original** user ID that was active at purchase time.
## Example Scenario
1. User installs your app and gets assigned anonymous user ID `abc-123`
2. User purchases a subscription. All events are attributed to `abc-123`
3. User deletes and reinstalls the app
4. User gets assigned a new anonymous user ID `xyz-789`
5. The subscription is still valid (same Apple ID), so the SDK shows `active`
6. But the dashboard shows nothing for `xyz-789` because the subscription belongs to `abc-123`
## How to Verify This
If you suspect this is happening:
1. Check the "Customer Info" section in the dashboard for the user. If it shows subscription status as active but no entitlements, this confirms the SDK is reading a valid receipt
2. The subscription data exists, it's just linked to a different user ID
3. If you have access to your server logs or Apple's App Store Connect, you can try to find the original transaction and trace it back to the original user ID
## How to Prevent This
To maintain consistent attribution across user sessions:
* Call `Superwall.shared.identify(userId:)` with a stable user ID from your own authentication system as early as possible, ideally before any purchases occur
* Use the same user ID consistently across reinstalls and devices
* If your app supports account creation, identify users immediately after they sign up or log in
## Key Takeaways
* **Active subscription + no dashboard data = purchased under a different user ID**
* The subscription is valid and working correctly
* This is expected behavior, not a Superwall bug
* The SDK uses the Apple receipt (tied to Apple ID) for access control
* The dashboard uses attribution data (tied to Superwall user ID) for reporting
* These are intentionally separate to ensure users never lose access to their purchases
---
# Troubleshooting
Source: https://superwall.com/docs/support/troubleshooting
undefined
import { SupportFolderList } from '@/components/SupportFolderList'
---
# Video: How to Install and Configure the Superwall SDK in Flutter (In Under 2 Minutes!)
Source: https://superwall.com/docs/support/sdk/3422417486-how-to-install-and-configure-the-superwall-sdk-in-flutter-in-under-2-minutes
undefined
In this quick tutorial, I'll walk you through:
1. Installing the Superwall SDK in your Flutter project.
2. Configuring it with your project's API key.
3. And, registering a placement to display your paywall—all in under two minutes!
---
# Video: Using Xcode's Transaction Manager
Source: https://superwall.com/docs/support/sdk/4506454639-using-xcode-s-transaction-manager
undefined
Using Transaction Manager, you can easily test just about any subscription state for your apps. You can manually cancel existing subscriptions, test price increases, refunds, and literally any other state that's possible within the App Store.
---
# Video: Presenting a Paywall in an iOS App Using Superwall
Source: https://superwall.com/docs/support/sdk/4341680566-presenting-a-paywall-in-an-ios-app-using-superwall
undefined
Presenting a paywall using Superwall's SDK revolves around registering events from campaigns. Learn how events work, and how they associate back to an app, to better understand how paywall presentation works with Superwall. This video covers iOS, but the idea applies to any platform Superwall supports.
---
# How do I disable Streamlined Purchasing for iOS apps?
Source: https://superwall.com/docs/support/sdk/5896158743-how-do-i-disable-streamlined-purchasing-for-ios-apps
undefined
## Context
Streamlined Purchasing is an iOS feature that allows users to manage their subscriptions and switch between subscription tiers directly through the App Store. Some developers may want to disable this feature to maintain more control over subscription changes, particularly when running A/B tests with different pricing tiers.
## Answer
The Superwall SDK does not currently include built-in support for the StoreKit APIs required to [disable Streamlined Purchasing](https://developer.apple.com/help/app-store-connect/manage-subscriptions/manage-streamlined-purchasing/?utm_source=chatgpt.com). If you want to disable this feature, you will need to implement the necessary StoreKit APIs directly in your iOS app.
Note: Disabling Streamlined Purchasing is generally uncommon among Superwall customers, as most end users rarely attempt to switch to cheaper subscriptions outside of the app.
---
# Video: How to Install Superwall's SDK into your iOS App
Source: https://superwall.com/docs/support/sdk/6889849185-how-to-install-superwall-s-sdk-into-your-ios-app
undefined
Here's how to install Superwall's SDK into your iOS app. This video walks through how to do it using Swift Package Manager and Cocoap
---
# Video: How to present a paywall from the first touch in app
Source: https://superwall.com/docs/support/sdk/3165338058-how-to-present-a-paywall-from-the-first-touch-in-app
undefined
Here's how to use the `touches_began` placement to present a paywall.
One of the most important metrics to track is app installs to paywall views. Instead of presenting a paywall right when the app launches, you can achieve the same thing by showing it once the user taps on something.
---
# Video: Making a Purchase with Superwall
Source: https://superwall.com/docs/support/sdk/8208368408-making-a-purchase-with-superwall
undefined
Here's how to make the first purchase of a product using Superwall any our iOS app.
---
# How to Setup Web Restoration Alert Options
Source: https://superwall.com/docs/support/sdk/3677919065-how-to-setup-web-restoration-alert-options
undefined
# Setup Web Restoration Alert
To configure the web restoration alert behavior in your Superwall integration:
1. Access your application's PaywallOptions configuration
2. Set the `shouldShowWebRestorationAlert` property to control when the alert appears:
PaywallOptions.shouldShowWebRestorationAlert = false
Setting this property to false will suppress the web restoration alert, which is particularly useful when users already have an active StoreKit subscription.
# Usage
The web restoration alert is designed to check for web-based subscriptions during the restore purchase flow. By default, this alert may appear even when users have an existing StoreKit subscription. To optimize the user experience:
* Disable the web restoration alert if your app primarily uses StoreKit subscriptions
* Enable the alert only in scenarios where checking for web-based subscriptions is necessary
Note: The alert button text currently displays as "Okay" and cannot be customized. This is a standard part of the SDK's interface.
---
# How to setup sandbox testing without affecting production metrics
Source: https://superwall.com/docs/support/sdk/3107042948-how-to-setup-sandbox-testing-without-affecting-production-metrics
undefined
# Setup Sandbox Testing
Superwall automatically detects whether your app is running in sandbox mode (Xcode, Simulator, TestFlight) vs production (App Store) without requiring separate API keys or projects. Here's how to set it up properly:
1. Use the same single API key for both sandbox and production environments
2. Create a "Sandbox Users" audience in your Superwall dashboard with the filter:
* `isSandbox` → `is` → `true`
3. Place this sandbox audience above your production audiences in the campaign list (Superwall evaluates audiences from top to bottom)
4. Assign a test paywall to the sandbox audience
5. Configure your production audiences below the sandbox audience
Note: Only create separate dashboard projects if you have different bundle IDs (e.g., `com.myapp` vs `com.myapp.dev`). If you're using the same bundle ID for TestFlight and production, stick with one project.
# Usage
With this setup:
* Users on TestFlight, Xcode, or Simulator will automatically match the sandbox audience and see your test paywalls
* Production App Store users will skip the sandbox audience and see your live campaigns
* Your conversion rates and analytics remain clean and unaffected by test data
* You can safely test different paywall configurations without impacting production metrics
The SDK handles the sandbox detection automatically at initialization, so no additional code changes are required on your end.
---
# SDK
Source: https://superwall.com/docs/support/sdk
Learn how to use the Superwall SDK to integrate Superwall into your app.
import { SupportFolderList } from '@/components/SupportFolderList'
---
# Support Center
Source: https://superwall.com/docs/support
Need help with anything Superwall-related? We're here to help.
## Common Issues
* [Troubleshooting: Products not loading or prices not showing](/support/troubleshooting/products-not-loading)
* [Troubleshooting: Paywall not showing or showing unexpectedly](/support/troubleshooting/6381986971-paywall-not-showing)
* [FAQ: How does Superwall's pricing work?](/support/faq/2801653905-how-does-superwalls-pricing-work)
## Need Help?
Try using [Ask AI](/ai) or searching for your issue to get an instant answer.
We listen to all feedback! If Ask AI can't answer your question or a guide is not helpful, please leave feedback with 👍/👎 and we will improve it.
If additional help is required, you can create a new Support ticket by using the **💬 Support button** in the bottom-right corner of the screen.
**Please provide all relevant details to help us resolve your issue quickly:**
* A detailed description of the issue
* User IDs if the issue is affecting specific users
* Any and all relevant screenshots, links, logs, etc.
You will need to [log into your Superwall account](https://superwall.com/api/auth/login) first
---
# SuperwallLoading
Source: https://superwall.com/docs/expo/sdk-reference/components/SuperwallLoading
undefined
`` is a component that renders its children only when Superwall is loading or not yet configured. This component can be used to display a loading indicator or a placeholder while the Superwall SDK is initializing.
Once Superwall is configured and no longer in a loading state, this component will render `null`.
**Note:** This component will not render if there's a configuration error. Use `` to handle error states.
## Props
| Name | Type | Description | Required |
| -------- | --------------- | ------------------------------------------------------------------- | -------- |
| children | React.ReactNode | Content to render while Superwall is loading or not yet configured. | yes |
## Example
```tsx
import {
SuperwallProvider,
SuperwallLoading,
SuperwallLoaded,
SuperwallError,
} from "expo-superwall";
import { ActivityIndicator, View, Text } from "react-native";
const API_KEY = "YOUR_SUPERWALL_API_KEY";
export default function App() {
return (
Failed to load Superwall
{/* Your main app screen or component */}
);
}
function MainAppScreen() {
return (
Superwall SDK is ready!
{/* Rest of your app's UI */}
);
}
```
## Related Components
* [``](/expo/sdk-reference/components/SuperwallLoaded) - Renders children when Superwall is ready
* [``](/expo/sdk-reference/components/SuperwallError) - Renders children when Superwall configuration fails
---
# SuperwallLoaded
Source: https://superwall.com/docs/expo/sdk-reference/components/SuperwallLoaded
undefined
`` is a component that renders its children only when Superwall has finished loading and is configured. This component is useful for conditionally rendering parts of your UI that depend on Superwall being ready.
If Superwall is still loading, has not been configured, or has a configuration error, this component will render `null`.
## Props
| Name | Type | Description | Required |
| -------- | --------------- | ---------------------------------------------------------- | -------- |
| children | React.ReactNode | Content to render once Superwall is loaded and configured. | yes |
## Example
```tsx
import {
SuperwallProvider,
SuperwallLoading,
SuperwallLoaded,
SuperwallError,
} from "expo-superwall";
import { ActivityIndicator, View, Text } from "react-native";
const API_KEY = "YOUR_SUPERWALL_API_KEY";
export default function App() {
return (
Failed to load Superwall
{/* Your main app screen or component */}
);
}
function MainAppScreen() {
return (
Superwall SDK is ready!
{/* Rest of your app's UI */}
);
}
```
## Notes
* This component will not render if there's a configuration error. Use `` to handle error states.
* This component will not render while Superwall is loading. Use `` to show loading states.
* Use this component alongside `` and `` to provide a complete loading/error/success UI flow.
---
# CustomPurchaseControllerProvider
Source: https://superwall.com/docs/expo/sdk-reference/components/CustomPurchaseControllerProvider
A modern, hooks-based approach to handling purchases and purchase restores with the Superwall SDK.
The `CustomPurchaseControllerProvider` component allows you to integrate your own purchase handling logic with the Superwall SDK. It provides a modern, hooks-based approach to handling purchases and purchase restores.
## Usage
```tsx
import { CustomPurchaseControllerProvider } from 'expo-superwall'
import { SuperwallProvider } from 'expo-superwall'
export default function App() {
return (
{
if (params.platform === "ios") {
console.log("iOS purchase:", params)
// Handle iOS purchase with StoreKit
} else {
console.log("Android purchase:", params.productId)
// Handle Android purchase with Google Play Billing
}
},
onPurchaseRestore: async () => {
console.log("Restore purchases requested")
// Handle restore purchases logic
},
}}
>
{/* Your app content */}
)
}
```
**Important:** The `onPurchase` and `onPurchaseRestore` callbacks communicate the outcome through the resolved value or an error:
* **Return/resolve `void` or a success result** → Superwall records a successful purchase or restore
* **Return a failure/cancelled result or throw** → Superwall records a failed or cancelled outcome
If your purchase function returns a status like `"cancelled"` or `"error"`, return a `PurchaseResult` with that type (or throw) so Superwall records the correct outcome:
```tsx
onPurchase: async (params) => {
const result = await yourPurchaseFunction(params.productId);
if (result !== "success") {
return { type: "failed", error: `Purchase ${result}` };
}
// Only reaches here on success
},
```
**Why this matters:** If your callback resolves without signaling failure, Superwall will count it as a conversion.
## Props
| Name | Type | Description | Required |
| ---------- | ------------------------------- | ----------------------------------------------------- | -------- |
| controller | CustomPurchaseControllerContext | Object that implements purchase and restore handlers. | yes |
| children | React.ReactNode | Child components wrapped by this provider. | yes |
### CustomPurchaseControllerContext
| Name | Type | Description |
| ----------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------ |
| onPurchase | (params: OnPurchaseParams) => Promise\ | Handle a purchase and return a result or throw to signal failure. |
| onPurchaseRestore | () => Promise\ | Handle restore purchases and return a result or throw to signal failure. |
### OnPurchaseParams (iOS)
| Name | Type | Description | Required |
| --------- | ------ | -------------------------------------- | -------- |
| platform | "ios" | Platform identifier for iOS purchases. | yes |
| productId | string | App Store product identifier. | yes |
### OnPurchaseParams (Android)
| Name | Type | Description | Required |
| ---------- | --------- | ------------------------------------------ | -------- |
| platform | "android" | Platform identifier for Android purchases. | yes |
| productId | string | Google Play product identifier. | yes |
| basePlanId | string | Subscription base plan ID. | yes |
| offerId | string? | Optional promotional offer ID. | no |
### PurchaseResult
| Name | Type | Description | Required |
| ----- | --------------------------------------------------- | ------------------------------------------- | -------- |
| type | "cancelled" \| "failed" \| "purchased" \| "pending" | Outcome of the purchase flow. | yes |
| error | string? | Optional error message when type is failed. | no |
### RestoreResult
| Name | Type | Description | Required |
| ----- | ---------------------- | ------------------------------------------- | -------- |
| type | "restored" \| "failed" | Outcome of the restore flow. | yes |
| error | string? | Optional error message when type is failed. | no |
## Hook
### `useCustomPurchaseController()`
A hook that provides access to the custom purchase controller context from child components.
```tsx
import { useCustomPurchaseController } from 'expo-superwall'
function MyComponent() {
const controller = useCustomPurchaseController()
if (!controller) {
// Not within a CustomPurchaseControllerProvider
return null
}
const handlePurchase = async () => {
// Access controller methods if needed
}
return
}
```
| Name | Type | Description |
| ----- | --------------------------------------- | --------------------------------------------------------------------------- |
| value | CustomPurchaseControllerContext \| null | Controller object passed to the provider, or null if not within a provider. |
## How It Works
The `CustomPurchaseControllerProvider` listens for purchase events from the Superwall SDK using the `useSuperwallEvents` hook internally. When a purchase or restore event occurs:
1. It calls your provided `onPurchase` or `onPurchaseRestore` method
2. After your method completes, it notifies the Superwall SDK that the purchase was successful
3. Superwall then dismisses the paywall and continues with the user flow
## Integration with RevenueCat
For a complete RevenueCat integration with error handling, subscription status synchronization, and working examples, see the [Using RevenueCat](/docs/expo/guides/using-revenuecat) guide.
## Notes
* The provider must wrap your app at a level where both the Superwall SDK and your purchase logic can access it
* Purchase success/failure handling is automatic - you just need to perform the actual purchase
---
# SuperwallError
Source: https://superwall.com/docs/expo/sdk-reference/components/SuperwallError
undefined
`` is a component that renders its children only when Superwall configuration has failed. This component was added in v0.7.0 to help handle SDK initialization errors gracefully.
The component can accept either static React nodes or a render function that receives the error message string.
## Props
| Name | Type | Description | Required |
| -------- | ------------------------------------------------------- | --------------------------------------------------------------- | -------- |
| children | React.ReactNode \| ((error: string) => React.ReactNode) | Static UI or a render function that receives the error message. | yes |
## Example
### Static Error UI
```tsx
import {
SuperwallProvider,
SuperwallError,
SuperwallLoading,
SuperwallLoaded,
} from "expo-superwall";
import { View, Text, Button } from "react-native";
export default function App() {
return (
Failed to load SuperwallPlease check your internet connection and try again.
{/* Your main app content */}
);
}
```
### Dynamic Error UI with Error Message
```tsx
import {
SuperwallProvider,
SuperwallError,
SuperwallLoading,
SuperwallLoaded,
} from "expo-superwall";
import { View, Text, Button } from "react-native";
export default function App() {
const handleRetry = () => {
// Implement retry logic
};
return (
{(error) => (
Failed to initialize Superwall{error}
)}
{/* Your main app content */}
);
}
```
### Using with onConfigurationError Callback
You can also use the `onConfigurationError` prop on `SuperwallProvider` to handle errors programmatically:
```tsx
import { SuperwallProvider } from "expo-superwall";
export default function App() {
return (
{
console.error("Superwall configuration failed:", error);
// Track error in analytics, show toast, etc.
}}
>
{/* Your app content */}
);
}
```
## Notes
* This component only renders when there's a configuration error. It will render `null` if Superwall is loading or has successfully configured.
* Use this component alongside `` and `` to provide a complete loading/error/success UI flow.
* The error state is automatically cleared when the SDK successfully configures on retry.
---
# SuperwallProvider
Source: https://superwall.com/docs/expo/sdk-reference/components/SuperwallProvider
undefined
`` is the root component for the Superwall SDK. It is used to initialize the SDK with your API key.
## Props
| Name | Type | Description | Required |
| -------------------- | ----------------------------------- | ---------------------------------------------------------------------------------- | -------- |
| apiKeys | \{ ios?: string; android?: string } | API keys for each platform (use the platform you ship). | yes |
| options | PartialSuperwallOptions? | Optional configuration options. See /expo/guides/configuring for available fields. | no |
| onConfigurationError | (error: Error) => void | Optional callback invoked when SDK configuration fails. | no |
| children | React.ReactNode | App content to render once configuration succeeds. | yes |
### apiKeys
| Name | Type | Description |
| ------- | ------- | ---------------- |
| ios | string? | iOS API key. |
| android | string? | Android API key. |
```tsx
{
console.error("Superwall configuration failed:", error);
// Handle error, show UI, or retry
}}
>
{/* Your app content */}
```
## Example
```tsx
import { SuperwallProvider } from "expo-superwall";
// Replace with your actual Superwall API key
export default function App() {
return (
{/* Your app content goes here */}
);
}
```
## Consume rerouted Android back buttons
If the **Reroute back button** toggle is enabled on a paywall (/dashboard/dashboard-creating-paywalls/paywall-editor-settings#reroute-back-button), Superwall can hand control back to your app. Provide `options.paywalls.onBackPressed` to intercept the event and return `true` to consume it.
```tsx
{
if (paywallInfo.identifier === "survey") {
showExitConfirmation();
return true; // Prevent Superwall from dismissing automatically
}
return false; // Keep the default dismissal behavior
},
},
}}
/>
```
This callback only fires on Android and only when rerouting is enabled in the paywall editor. Use it to show confirmation modals, capture analytics, or resume gameplay before closing the paywall.
---
# getPresentationResult()
Source: https://superwall.com/docs/expo/sdk-reference/getPresentationResult
Check the outcome of a placement without presenting a paywall.
## Purpose
Retrieves the presentation result for a placement without presenting the paywall. Call this when you need to know whether a placement would show a paywall, send the user to a holdout, or fail due to missing configuration before you decide how to render UI.
## Signature
Hook usage:
```ts
const { getPresentationResult } = useSuperwall()
await getPresentationResult(
placement: string,
params?: Record
): Promise
```
Compat API usage:
```ts
import Superwall from "expo-superwall/compat"
await Superwall.getPresentationResult({
placement: string,
params?: Map
}): Promise
```
Both variants return a promise that resolves to a `PresentationResult` object from `expo-superwall/compat`.
## Parameters
| Name | Type | Description | Default | Required |
| --------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------- |
| placement | string | Placement to evaluate. Always await \`Superwall.configure\` before calling. | | yes |
| params | Record\ or Map\ | Optional parameters that feed audience filters. Keys beginning with \`$\` are reserved and removed. Nested maps or arrays are not supported. | omitted | no |
## Returns / State
The promise resolves to one of the `PresentationResult` subclasses exported from `expo-superwall/compat`:
| Name | Type | Description |
| ------------------------------------- | ------------------------------------- | --------------------------------------------------------------------------------- |
| PresentationResultPaywall | PresentationResultPaywall | A paywall would be shown. Includes an experiment field (id, groupId, etc.). |
| PresentationResultHoldout | PresentationResultHoldout | The user is placed in a holdout for the experiment. |
| PresentationResultNoAudienceMatch | PresentationResultNoAudienceMatch | No matching audience rules. |
| PresentationResultPlacementNotFound | PresentationResultPlacementNotFound | The placement name is not attached to any campaign. |
| PresentationResultUserIsSubscribed | PresentationResultUserIsSubscribed | The SDK determined the user is already active, so no paywall will show. |
| PresentationResultPaywallNotAvailable | PresentationResultPaywallNotAvailable | The paywall could not be displayed (no activity, already showing, offline, etc.). |
If configuration fails or the native module throws, the promise rejects—catch and handle these errors as you would any async call.
## Usage
```tsx
import {
PresentationResultPaywall,
PresentationResultHoldout,
PresentationResultNoAudienceMatch,
PresentationResultPlacementNotFound,
} from "expo-superwall/compat"
import { useSuperwall } from "expo-superwall"
export function FeatureGate() {
const { getPresentationResult } = useSuperwall()
const checkAccess = async () => {
const result = await getPresentationResult("premium_feature", { source: "settings" })
if (result instanceof PresentationResultPaywall) {
setExperiment(result.experiment)
setState("locked")
} else if (result instanceof PresentationResultHoldout) {
setState("holdout")
} else if (result instanceof PresentationResultNoAudienceMatch) {
unlockFeature()
} else if (result instanceof PresentationResultPlacementNotFound) {
console.warn("Placement missing from dashboard")
} else {
fallbackFlow()
}
}
return
}
```
```tsx
import Superwall, {
PresentationResultPaywall,
PresentationResultPaywallNotAvailable,
} from "expo-superwall/compat"
async function inspectPlacement() {
const result = await Superwall.getPresentationResult({
placement: "premium_feature",
params: new Map([["source", "home"]]),
})
if (result instanceof PresentationResultPaywallNotAvailable) {
// Show offline UI
return
}
if (result instanceof PresentationResultPaywall) {
console.log("Experiment group:", result.experiment.groupId)
}
}
```
## Related
* [`useSuperwall`](/expo/sdk-reference/hooks/useSuperwall) – Provides the hook variant shown above.
* [`SuperwallProvider`](/expo/sdk-reference/components/SuperwallProvider) – Configure the SDK before calling this method.
* [Feature gating quickstart](/expo/quickstart/feature-gating) – Shows the full flow of gating UI with placements.
---
# useSuperwallEvents
Source: https://superwall.com/docs/expo/sdk-reference/hooks/useSuperwallEvents
undefined
## Purpose
The `useSuperwallEvents` hook provides a low-level way to subscribe to *any* native Superwall event. This is useful for advanced use cases or for events not covered by the more specific hooks. Listeners are automatically cleaned up when the component using this hook unmounts.
## Parameters
| Name | Type | Description |
| --------- | ------------------------ | -------------------------------------------------------------------- |
| callbacks | SuperwallEventCallbacks? | Object of event callbacks to subscribe to. Omit any you do not need. |
### SuperwallEventCallbacks
| Name | Type | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| onPaywallPresent | (paywallInfo: PaywallInfo) => void | Called when a paywall is presented. |
| onPaywallDismiss | (paywallInfo: PaywallInfo, result: PaywallResult) => void | Called when a paywall is dismissed. |
| onPaywallSkip | (reason: PaywallSkippedReason) => void | Called when a paywall is skipped. |
| onPaywallError | (error: string) => void | Called when paywall presentation fails or another SDK error occurs. |
| onSubscriptionStatusChange | (status: SubscriptionStatus) => void | Called when the user's subscription status changes. |
| onUserAttributesChange | (newAttributes: Record\) => void | Called when user attributes change outside your app (for example via the \`Set Attribute\` paywall action). |
| onSuperwallEvent | (eventInfo: SuperwallEventInfo) => void | Called for generic Superwall events with payload metadata. |
| onCustomPaywallAction | (name: string) => void | Called when a custom action is triggered from a paywall. |
| willDismissPaywall | (paywallInfo: PaywallInfo) => void | Called just before a paywall is dismissed. |
| willPresentPaywall | (paywallInfo: PaywallInfo) => void | Called just before a paywall is presented. |
| didDismissPaywall | (paywallInfo: PaywallInfo) => void | Called after a paywall has been dismissed. |
| didPresentPaywall | (paywallInfo: PaywallInfo) => void | Called after a paywall has been presented. |
| onPaywallWillOpenURL | (url: string) => void | Called when the paywall attempts to open a URL. |
| onPaywallWillOpenDeepLink | (url: string) => void | Called when the paywall attempts to open a deep link. |
| onLog | (params: \{ level: LogLevel; scope: LogScope; message: string \| null; info: Record\