# 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:
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:
---
# 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! π
---
# 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. |
---
# 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 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
To match your campaign to specific entitlement, **click** the entitlements button and choose an option:
1. **Show to unsubscribed users (default):** Users without an active entitlement match.
2. **All users**: All users match.
3. **Specify entitlement**: 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
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.
---
# 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.
### 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).
---
# 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_launch`
* `deepLink_open`
* `session_start`
* `paywall_decline`
* `transaction_fail`
* `transaction_abandon`
* `survey_response`
* `touches_began`
Visit [Superwall Events](/tracking-analytics) to see a full list of parameters that you can use with these events. Here are a few examples of how they might be used:
#### Using the `paywall_decline` event
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`.
#### Using the `survey_response` event
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.
#### Using the `deepLink_open` event
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. Just [add](/campaigns-placements#adding-a-placement) the standard placement `deepLink_open` to a campaign. Then, you could set up a filter that fires based off of its parameters along with a `params.path` rule to see if its a certain path you've setup.
For example, you could make three conditions to match this deep link: `myapp://paywall?offer=July20`. Here's how:
1. Add the a rule to see if the event is `deepLink_open`. See the [first example](/campaigns-placements#using-the-paywall-decline-event) above using `paywall_decline` to see how to do this.
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`.
---
# 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.**
---
# 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:
---
# 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).
---
# 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).
---
# 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:
---
# 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:
---
# 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.
---
# 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:
---
# 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:
---
# 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.
---
# 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.
* **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.
---
# 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.
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.
---
# 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:
---
# 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.
### 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:
---
# 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.
---
# Notifications
Source: https://superwall.com/docs/dashboard/dashboard-creating-paywalls/paywall-editor-notifications
undefined
To configure a notification which displays before a free trials ends, click the **Notifications** button from the **sidebar**
You can add a local notification that fires after a number of days when a free trial has been purchased. After the user starts a free trial, it 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**: Any delay you'd like to apply after the free trial begins.
Here's where those values show up on a notification:
Also, keep in mind that these will be scheduled as a local notification as soon as they are configured.
---
# 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:
---
# 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.
```
```
---
# 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.
### 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).
---
# 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.
---
# 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**:
---
# 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.
### 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.
---
# 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.
---
# 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)
---
# 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.
* **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.
* **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.
---
# 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).
---
# 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:
---
# 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, do *not* localize automatically. This is because different languages
use varying orders and sentence structures for such terms. If you need them localized, add them as
you would any other term and enter localized values for each. Learn more about localization
[here](/paywall-editor-localization).
### 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:
---
# Amplitude
Source: https://superwall.com/docs/dashboard/dashboard-integrations/inegrations-amplitude
The Amplitude integration automatically sends Superwall subscription and payment events to your Amplitude project. Track subscription lifecycle events, analyze revenue metrics, and understand user behavior with automatic event mapping and revenue tracking.
In the **Analytics** section within **Integrations**, you can connect your Amplitude account to Superwall:
### Required fields
Fill out the following fields and **click** the **Enable Amplitude** button at the bottom right to save your changes:
* **Region:** Data residency region for your Amplitude project.
* **Api Key:** Your Amplitude API key.
* **Sandbox Api Key:** Optional API key for sandbox events (leave blank to opt out).
* **Sales Reporting:** Which revenue value to report in Amplitude. Choose between **Proceeds** (after store taxes & fees) or **Revenue**.
### Features
* **Automatic Event Mapping**: Converts Superwall events to Amplitude-friendly format
* **Revenue Tracking**: Automatic revenue attribution with LTV tracking
* **Multi-Region Support**: Works with US and EU data residency
* **Sandbox Isolation**: Separate tracking for production and sandbox events
* **Human-Readable Events**: Events prefixed with `[Superwall]` for easy identification
* **Session Tracking**: Automatic session ID generation
* **Platform Attribution**: Tracks which store (App Store, Play Store, Stripe) generated revenue
### Configuration
#### Required settings
| Field | Description | Example |
| ----------------- | ---------------------------- | --------------------------- |
| `integration_id` | Must be set to `"amplitude"` | `"amplitude"` |
| `region` | Data residency region | `"US (Default)"` or `"EU"` |
| `api_key` | Your Amplitude API key | `"abc123def456..."` |
| `sales_reporting` | Which value to report | `"Revenue"` or `"Proceeds"` |
#### Optional settings
| Field | Description | Example |
| ----------------- | ------------------------------------------------ | ------------- |
| `sandbox_api_key` | API key for sandbox events (leave blank to skip) | `"xyz789..."` |
#### Example configuration
```json
{
"integration_id": "amplitude",
"region": "US (Default)",
"api_key": "your_production_api_key_here",
"sandbox_api_key": "your_sandbox_api_key_here",
"sales_reporting": "Revenue"
}
```
### Event mapping
Superwall events are transformed into human-readable Amplitude events:
#### Event name format
All events are prefixed with `[Superwall]` followed by a descriptive name:
* Example: `[Superwall] Trial Start`
* Example: `[Superwall] Subscription Renewal`
#### Complete event mapping
| Superwall Event | Amplitude Event | Description |
| ---------------------------- | ----------------------------------------- | ------------------------- |
| `initial_purchase` + TRIAL | `[Superwall] Trial Start` | Trial begins |
| `initial_purchase` + INTRO | `[Superwall] Intro Offer Start` | Intro offer begins |
| `initial_purchase` + NORMAL | `[Superwall] Subscription Start` | Paid subscription begins |
| `renewal` + trial conversion | `[Superwall] Trial Conversion` | Trial converts to paid |
| `renewal` + INTRO | `[Superwall] Intro Offer Conversion` | Intro converts to regular |
| `renewal` + NORMAL | `[Superwall] Subscription Renewal` | Regular renewal |
| `cancellation` + TRIAL | `[Superwall] Trial Cancellation` | Trial cancelled |
| `cancellation` + INTRO | `[Superwall] Intro Offer Cancellation` | Intro cancelled |
| `cancellation` + NORMAL | `[Superwall] Subscription Cancellation` | Subscription cancelled |
| `uncancellation` + TRIAL | `[Superwall] Trial Uncancellation` | Trial reactivated |
| `uncancellation` + INTRO | `[Superwall] Intro Offer Uncancellation` | Intro reactivated |
| `uncancellation` + NORMAL | `[Superwall] Subscription Uncancellation` | Subscription reactivated |
| `expiration` + TRIAL | `[Superwall] Trial Expiration` | Trial ended |
| `expiration` + INTRO | `[Superwall] Intro Offer Expiration` | Intro ended |
| `expiration` + NORMAL | `[Superwall] Subscription Expiration` | Subscription ended |
| `billing_issue` | `[Superwall] Billing Issue` | Payment failed |
| `subscription_paused` | `[Superwall] Subscription Paused` | Subscription paused |
| `product_change` | `[Superwall] Product Change` | Plan changed |
| `non_renewing_purchase` | `[Superwall] Non-Renewing Purchase` | One-time purchase |
| Any with `price < 0` | `[Superwall] Refund` | Refund processed |
| `test` | `[Superwall] Test` | Test event |
### Event properties
Every Amplitude event includes comprehensive properties:
#### Core Amplitude fields
* `user_id`: User identifier (uses `originalAppUserId` or `originalTransactionId`)
* `event_type`: Human-readable event name with `[Superwall]` prefix
* `time`: Event timestamp (milliseconds)
* `session_id`: Same as timestamp (groups related events)
* `platform`: Store name (APP\_STORE, PLAY\_STORE, STRIPE, PADDLE)
* `insert_id`: Unique event ID prefixed with `sw_`
#### Revenue fields (when applicable)
* `revenue`: Transaction amount (based on sales\_reporting setting)
* `price`: Same as revenue
* `quantity`: Always 1
* `productId`: Product identifier
* `revenueType`: Same as event type (for revenue categorization)
#### Event properties object
All Superwall webhook data fields are included:
* `id`, `name`, `cancelReason`, `exchangeRate`
* `isSmallBusiness`, `periodType`, `countryCode`
* `price`, `proceeds`, `priceInPurchasedCurrency`
* `taxPercentage`, `commissionPercentage`, `takehomePercentage`
* `offerCode`, `isFamilyShare`, `expirationAt`
* `transactionId`, `originalTransactionId`, `originalAppUserId`
* `store`, `purchasedAt`, `currencyCode`, `productId`
* `environment`, `isTrialConversion`, `newProductId`
* `bundleId`, `ts`
### Revenue tracking
#### Automatic revenue attribution
Revenue is automatically tracked for events with non-zero amounts:
* **Positive revenue**: Purchases, renewals, conversions
* **Negative revenue**: Refunds (automatically deducted)
* **Zero revenue**: Cancellations, expirations, billing issues
#### Revenue reporting options
The `sales_reporting` setting determines which value is used:
| Setting | Value Used | Description |
| ------------ | ---------- | ------------------------------- |
| `"Revenue"` | `price` | Gross revenue before store fees |
| `"Proceeds"` | `proceeds` | Net revenue after store fees |
#### Revenue examples
**Initial Purchase ($9.99):**
```json
{
"event_type": "[Superwall] Subscription Start",
"revenue": 9.99,
"price": 9.99,
"productId": "com.example.premium",
"revenueType": "[Superwall] Subscription Start"
}
```
**Refund (-$9.99):**
```json
{
"event_type": "[Superwall] Refund",
"revenue": -9.99,
"price": -9.99,
"productId": "com.example.premium",
"revenueType": "[Superwall] Refund"
}
```
### User identification
The integration uses this hierarchy for user identification:
1. **Primary**: `originalAppUserId` (if available)
2. **Fallback**: `originalTransactionId` (always present)
This ensures consistent user tracking across:
* Multiple devices
* App reinstalls
* Legacy users without app user IDs
#### Platform tracking
The `platform` field identifies the payment source:
* `APP_STORE`: iOS App Store
* `PLAY_STORE`: Google Play Store
* `STRIPE`: Stripe web payments
* `PADDLE`: Paddle payments (coming soon)
This helps analyze:
* Revenue by platform
* Platform-specific retention
* Cross-platform users
### Sandbox handling
#### With sandbox API key
If `sandbox_api_key` is configured:
* Production events β Production project
* Sandbox events β Sandbox project
#### Without sandbox API key
If `sandbox_api_key` is empty:
* Production events β Production project
* Sandbox events β **Skipped** (not sent)
This prevents test data from polluting production analytics.
### Data residency
Amplitude supports two data residency regions:
| Region | API Endpoint | Use Case |
| -------------- | -------------------- | --------------- |
| `US (Default)` | api2.amplitude.com | Global, default |
| `EU` | api.eu.amplitude.com | GDPR compliance |
Choose based on:
* Your data privacy requirements
* User location
* Compliance needs
### Session management
Sessions are automatically managed:
* `session_id` = Event timestamp
* Groups rapid events together
* New session for each subscription action
* Helps track user journey
### Testing the integration
#### 1. Validate credentials
The integration validates credentials by sending a test event when configured.
#### 2. Verify in Amplitude
Check your Amplitude project:
1. **User Lookup**: Find test user by ID
2. **Event Stream**: Verify events arriving
3. **Revenue Chart**: Confirm revenue tracking
4. **User Properties**: Check LTV calculation
#### 3. Test different scenarios
* Purchase event β Positive revenue
* Refund event β Negative revenue
* Cancellation β No revenue
* Trial start β Event without revenue
### Best practices
1. **Consistent User IDs**: Send user IDs to app stores for better tracking
2. **Separate Environments**: Use sandbox API key for testing
3. **Revenue Model**: Choose gross vs net consistently
4. **Event Naming**: Use `[Superwall]` prefix to identify source
5. **Platform Analysis**: Segment by platform for insights
6. **Cohort Analysis**: Use trial conversion events for cohorts
### Common use cases
#### Revenue analytics
```
Events: [Superwall] Subscription Start, [Superwall] Subscription Renewal
Metric: Sum of revenue
Segment by: platform, productId, countryCode
```
#### Conversion funnel
```
1. [Superwall] Trial Start
2. [Superwall] Trial Conversion
Conversion Rate: Step 2 / Step 1
```
#### Churn analysis
```
Events: [Superwall] Subscription Cancellation
Segment by: cancelReason, periodType, price tier
```
#### LTV calculation
```
Revenue Events: All [Superwall] events with revenue > 0
Group by: user_id
Calculate: Sum of revenue per user
```
### Troubleshooting
#### Events not appearing
1. **Check API Key**: Verify key is correct for your project
2. **Check Region**: Ensure region matches your Amplitude project
3. **Check Environment**: Sandbox events need sandbox API key
4. **Check User ID**: Must have valid identifier
#### Revenue not tracking
1. **Check Amount**: Only non-zero amounts create revenue
2. **Check Event Type**: Revenue fields only for purchase/renewal events
3. **Check Settings**: Verify Revenue vs Proceeds selection
4. **Check Refunds**: Negative amounts should decrease revenue
#### Duplicate events
The integration uses `insert_id` to prevent duplicates:
* Format: `sw_eventId-eventName`
* Amplitude automatically deduplicates by `insert_id`
#### User attribution issues
1. **Check User ID**: Verify originalAppUserId is being sent
2. **Check Fallback**: originalTransactionId should always exist
3. **Platform Mismatch**: Ensure platform field is correct
### Rate limits
Amplitude HTTP API v2 limits:
* **Events per batch**: 1000 (we send 1 at a time)
* **Request size**: 1MB (well within limit)
* **Rate limit**: 1000 events/second per device
* **Daily limit**: Based on your plan
### Integration with Amplitude features
#### User properties
While this integration sends events, consider:
* Setting user properties separately
* Using Identify API for user traits
* Enriching profiles with app data
#### Revenue verification
Amplitude's revenue verification requires:
* Receipt data (not included in webhooks)
* Direct integration with app stores
* This integration complements but doesn't replace revenue verification
#### Predictive analytics
Use Superwall events for:
* Churn prediction models
* LTV forecasting
* Conversion probability scoring
### Data privacy
* **User IDs**: Pseudonymous by default
* **GDPR**: Use EU region for European users
* **Data Retention**: Follows Amplitude project settings
* **Deletion**: Handle via Amplitude's User Privacy API
* **PII**: Avoid sending PII in event properties
---
# Mixpanel
Source: https://superwall.com/docs/dashboard/dashboard-integrations/inegrations-mixpanel
The Mixpanel integration allows you to automatically send Superwall subscription and payment events to your Mixpanel project.
In the **Analytics** section within **Integrations**, you can connect your Mixpanel account to Superwall:
This integration provides two-way data flow:
1. **Event Tracking**: Sends detailed subscription lifecycle events to Mixpanel.
2. **User Profile Updates**: Updates user profiles with revenue data and transaction history.
### Required Fields
Fill out the following fields and **click** the **Enable Mixpanel** button at the bottom right to save your changes:
* **Region:** Data residency region for your Mixpanel project.
* **Project Token:** Your Mixpanel project token (Mixpanel β Settings β Project Settings β Project Token).
* **Total Spend Property:** The name of the user property to track cumulative spend.
* **Sales Reporting:** Whether to report Proceeds after store taxes & fees or Revenue. Choose between **Proceeds** (after store taxes & fees) or **Revenue**.
### Features
* **Automatic Event Mapping**: Converts Superwall events to Mixpanel-friendly event names
* **Revenue Tracking**: Tracks both price (gross) and proceeds (net after fees)
* **User Profile Enrichment**: Maintains cumulative spend and transaction history
* **Multi-Region Support**: Works with US, EU, and IN data residency regions
* **Sandbox Isolation**: Separate tracking for production and sandbox events
* **Refund Handling**: Automatically adjusts revenue metrics for refunds
## Configuration
### Required Settings
| Field | Description | Example |
| ---------------------- | --------------------------------------- | --------------------------- |
| `integration_id` | Must be set to `"mixpanel"` | `"mixpanel"` |
| `region` | Data residency region | `"US"`, `"EU"`, or `"IN"` |
| `project_token` | Your Mixpanel project token | `"abc123def456..."` |
| `total_spend_property` | User property name for cumulative spend | `"lifetime_revenue"` |
| `sales_reporting` | Which value to report | `"Revenue"` or `"Proceeds"` |
### Optional Settings
| Field | Description | Example |
| ----------------------- | ---------------------------------------------- | ------------- |
| `sandbox_project_token` | Token for sandbox events (leave blank to skip) | `"xyz789..."` |
### Example Configuration
```json
{
"integration_id": "mixpanel",
"region": "US",
"project_token": "your_production_token_here",
"sandbox_project_token": "your_sandbox_token_here",
"total_spend_property": "lifetime_revenue",
"sales_reporting": "Proceeds"
}
```
## Event Mapping
Superwall events are transformed into standardized Mixpanel events with the `sw_` prefix:
### Trial Events
| Superwall Event | Mixpanel Event | Description |
| ---------------------------------------- | ---------------------- | ----------------------- |
| `initial_purchase` + `periodType: TRIAL` | `sw_trial_start` | Trial period begins |
| `cancellation` + `periodType: TRIAL` | `sw_trial_cancelled` | Trial cancelled |
| `uncancellation` + `periodType: TRIAL` | `sw_trial_uncancelled` | Trial reactivated |
| `expiration` + `periodType: TRIAL` | `sw_trial_expired` | Trial ended |
| `renewal` + `isTrialConversion: true` | `sw_trial_converted` | Trial converted to paid |
### Intro Offer Events
| Superwall Event | Mixpanel Event | Description |
| ---------------------------------------- | ---------------------------- | -------------------------- |
| `initial_purchase` + `periodType: INTRO` | `sw_intro_offer_start` | Intro offer begins |
| `cancellation` + `periodType: INTRO` | `sw_intro_offer_cancelled` | Intro offer cancelled |
| `uncancellation` + `periodType: INTRO` | `sw_intro_offer_uncancelled` | Intro offer reactivated |
| `expiration` + `periodType: INTRO` | `sw_intro_offer_expired` | Intro offer ended |
| `renewal` + `periodType: INTRO` | `sw_intro_offer_converted` | Intro converted to regular |
### Subscription Events
| Superwall Event | Mixpanel Event | Description |
| ----------------------------------------- | ----------------------------- | ------------------------ |
| `initial_purchase` + `periodType: NORMAL` | `sw_subscription_start` | Subscription begins |
| `renewal` + `periodType: NORMAL` | `sw_renewal` | Subscription renewed |
| `cancellation` + `periodType: NORMAL` | `sw_subscription_cancelled` | Subscription cancelled |
| `uncancellation` + `periodType: NORMAL` | `sw_subscription_uncancelled` | Subscription reactivated |
| `expiration` + `periodType: NORMAL` | `sw_subscription_expired` | Subscription ended |
| `subscription_paused` | `sw_subscription_paused` | Subscription paused |
| `billing_issue` | `sw_billing_issue` | Payment failed |
### Other Events
| Superwall Event | Mixpanel Event | Description |
| -------------------------- | -------------------------- | ----------------- |
| `product_change` | `sw_product_change` | Plan changed |
| `non_renewing_purchase` | `sw_non_renewing_purchase` | One-time purchase |
| Any event with `price < 0` | `sw_refund` | Refund processed |
| `test` | `sw_test` | Test event |
## Event Properties
Every Mixpanel event includes all fields from the Superwall webhook data object as properties:
### Core Properties
* `distinct_id`: User identifier (uses `originalAppUserId` or falls back to `originalTransactionId`)
* `time`: Unix timestamp in seconds
* `$insert_id`: Unique event ID (prevents duplicates)
* `token`: Your Mixpanel project token
### Webhook Data Properties
All fields from the webhook are included:
* `id`, `name`, `cancelReason`, `exchangeRate`
* `isSmallBusiness`, `periodType`, `countryCode`
* `price`, `proceeds`, `priceInPurchasedCurrency`
* `taxPercentage`, `commissionPercentage`, `takehomePercentage`
* `offerCode`, `isFamilyShare`, `expirationAt`
* `transactionId`, `originalTransactionId`, `originalAppUserId`
* `store`, `purchasedAt`, `currencyCode`, `productId`
* `environment`, `isTrialConversion`, `newProductId`
* `bundleId`, `ts`
## User Profile Updates
The integration performs two profile updates for revenue events:
### 1. Transaction History
Appends transaction details to the `$transactions` array:
```json
{
"$transactions": {
"$amount": 9.99,
"$time": "2025-01-01T12:00:00.000Z",
// Plus all webhook data fields
}
}
```
### 2. Cumulative Spend
Updates the total spend property (configurable):
```json
{
"lifetime_revenue": 129.99 // Incremented by transaction amount
}
```
## Revenue Reporting Options
### Price vs Proceeds
The `sales_reporting` setting determines which value is used for revenue:
| Setting | Value Used | Description |
| ------------ | ---------- | ----------------------------------------- |
| `"Revenue"` | `price` | Gross revenue before store fees and taxes |
| `"Proceeds"` | `proceeds` | Net revenue after store fees and taxes |
### Examples
**Gross Revenue (Price):**
* Transaction price: $9.99
* Store commission (30%): $3.00
* Your proceeds: $6.99
* Reported to Mixpanel: **$9.99**
**Net Revenue (Proceeds):**
* Transaction price: $9.99
* Store commission (30%): $3.00
* Your proceeds: $6.99
* Reported to Mixpanel: **$6.99**
## Sandbox Handling
### With Sandbox Token
If `sandbox_project_token` is configured:
* Production events β Production project
* Sandbox events β Sandbox project
### Without Sandbox Token
If `sandbox_project_token` is empty:
* Production events β Production project
* Sandbox events β **Skipped** (not sent to Mixpanel)
## Refund Handling
Refunds are automatically detected when `price < 0`:
* Event type: `sw_refund`
* Transaction amount: Negative value
* Cumulative spend: Decremented by refund amount
Example:
* Original purchase: +$9.99
* Refund event: -$9.99
* Net effect on lifetime revenue: $0.00
## Data Residency
Mixpanel supports three data residency regions:
| Region | API Endpoint | Use Case |
| ------ | ------------------- | -------------------- |
| `US` | api.mixpanel.com | Default, global |
| `EU` | api-eu.mixpanel.com | GDPR compliance |
| `IN` | api-in.mixpanel.com | India data residency |
## User Identification
The integration uses the following hierarchy for user identification:
1. **Primary**: `originalAppUserId` (if available)
2. **Fallback**: `originalTransactionId` (always present)
This ensures consistent user tracking even for:
* Legacy users without app user IDs
* Family sharing scenarios
* Cross-platform subscriptions
## Testing the Integration
### 1. Validate Credentials
The integration automatically validates your credentials by sending a test event when configured.
### 2. Test Event Properties
Test events include:
* Event: `sw_test`
* Basic properties to verify connection
* No revenue impact
### 3. Verify in Mixpanel
Check your Mixpanel project:
1. Live View β Verify events arriving
2. Users β Check profile updates
3. Reports β Confirm revenue tracking
## Troubleshooting
### Events Not Appearing
1. **Check Token**: Verify project token is correct
2. **Check Region**: Ensure region matches your Mixpanel project
3. **Check Environment**: Sandbox events need sandbox token
4. **Check Distinct ID**: User must have valid identifier
### Revenue Not Tracking
1. **Check Sales Reporting**: Verify Price vs Proceeds setting
2. **Check Property Name**: Confirm `total_spend_property` exists
3. **Check Event Type**: Only revenue events update spend
4. **Check Refunds**: Negative amounts decrease total
### Duplicate Events
The integration uses `$insert_id` to prevent duplicates:
* Format: `eventId-eventName`
* Example: `abc123-renewal`
Mixpanel automatically deduplicates events with the same `$insert_id`.
## Best Practices
1. **Use Consistent User IDs**: Send user IDs to app stores for better tracking
2. **Set Up Both Tokens**: Configure sandbox token for complete testing
3. **Choose Revenue Model**: Decide between gross (Price) vs net (Proceeds)
4. **Monitor Both Projects**: Check production and sandbox regularly
5. **Handle Refunds**: Ensure your analytics account for negative revenue
## Rate Limits
Mixpanel has the following limits:
* **Events**: 2,000 requests/second
* **Profile Updates**: 2,000 requests/second
* **Batch Size**: 2MB per request
The integration sends events individually, well within these limits.
## Data Privacy
* **PII Handling**: User IDs are pseudonymous by default
* **GDPR Compliance**: Use EU region for European users
* **Data Retention**: Follows your Mixpanel project settings
* **Deletion Requests**: Handle via Mixpanel's privacy tools
---
# Slack
Source: https://superwall.com/docs/dashboard/dashboard-integrations/inegrations-slack
The Slack integration sends real-time notifications about subscription events to your Slack channels. Get instant updates about new subscribers, cancellations, renewals, and revenue changes with rich, color-coded messages and contextual emojis.
In the **Communication** section within **Integrations**, you can connect your Slack account to Superwall:
### Required Fields
Fill out the following fields and **click** the **Enable Slack** button at the bottom right to save your changes:
* **Webhook Url:** Your Slack webhook URL for sending messages to a channel.
* **Include Sandbox:** Whether to include sandbox events in Slack notifications.
* **Event Type:** Type of events to send: revenue only or all lifecycle (includes trials, cancellations).
### Features
* **Real-time Notifications**: Instant Slack messages for subscription events
* **Smart Filtering**: Choose between revenue events only or all subscription lifecycle events
* **Visual Design**: Color-coded messages with contextual emojis for quick scanning
* **Revenue Insights**: See price, proceeds, and currency information at a glance
* **Sandbox Control**: Optional inclusion of test/sandbox events
* **Rich Context**: Includes user ID, product, country, and transaction details
## Configuration
### Required Settings
| Field | Description | Example |
| ----------------- | --------------------------------- | ------------------------------------------------------ |
| `integration_id` | Must be set to `"slack"` | `"slack"` |
| `webhook_url` | Your Slack incoming webhook URL | `"https://hooks.slack.com/services/..."` |
| `include_sandbox` | Whether to include sandbox events | `"Production Only"` or `"Production & Sandbox"` |
| `event_type` | Types of events to send | `"Revenue Events Only"` or `"All Subscription Events"` |
### Example Configuration
```json
{
"integration_id": "slack",
"webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXX",
"include_sandbox": "Production Only",
"event_type": "Revenue Events Only"
}
```
## Setting Up Slack Webhooks
1. **Create Incoming Webhook**:
* Go to [api.slack.com/apps](https://api.slack.com/apps)
* Create a new app or select existing
* Enable "Incoming Webhooks"
* Add new webhook to workspace
* Select target channel
2. **Copy Webhook URL**:
* Format: `https://hooks.slack.com/services/T.../B.../...`
* Keep this URL secure
3. **Test Connection**:
* The integration sends a test message on setup
* Verify it appears in your selected channel
## Event Filtering
### Revenue Events Only
Sends notifications for events with monetary impact:
* β
Initial purchases (paid)
* β
Renewals
* β
Refunds (negative amounts)
* β
Trial/intro conversions (when paid)
* β Cancellations (no immediate revenue impact)
* β Expirations
* β Billing issues
### All Subscription Events
Sends notifications for all lifecycle events:
* β
All revenue events (above)
* β
Trial starts
* β
Cancellations
* β
Uncancellations
* β
Expirations
* β
Billing issues
* β
Product changes
* β
Subscription pauses
## Message Format
### Visual Indicators
Messages use colors and emojis for quick scanning:
#### Colors
* π’ **Green** (#36a64f): Positive events (purchases, renewals, uncancellations)
* π΄ **Red** (#FA6A6A): Negative events (cancellations, expirations, refunds)
* β« **Gray** (#666666): Neutral events (product changes, pauses)
#### Emojis by Event Type
**Trial Events:**
* π€© Trial start
* π° Trial conversion
* π Trial cancelled
* π Trial expired
* π€© Trial uncancelled
* π€¬ Trial refunded
**Intro Offer Events:**
* π°/π€© Intro offer start
* π° Intro offer conversion
* π Intro offer cancelled
* π Intro offer expired
* π€© Intro offer uncancelled
* π€¬ Intro offer refunded
**Subscription Events:**
* π° New subscriber
* π° Renewal
* π Subscription cancelled
* π Subscription expired
* π€© Subscription uncancelled
* π€¬ Subscription refunded
**Special Events:**
* π΅βπ« Product change
* π« Billing issue
* βΈοΈ Subscription paused
* πΈ Non-renewing purchase
### Message Structure
Each Slack message includes:
```
[Emoji] [Event Description]
βββββββββββββββββββββ
π΅ $9.99 USD (Proceeds: $6.99)
π¦ com.example.premium.monthly
π United States
π€ User123
πͺ APP_STORE
π Transaction: 700001234567890
```
### Field Descriptions
| Field | Description | Example |
| --------------- | --------------------- | --------------------------- |
| **Header** | Event type with emoji | "π° renewal" |
| **Price** | Transaction amount | "$9.99 USD" |
| **Proceeds** | Net after fees | "Proceeds: $6.99" |
| **Product** | Product identifier | "com.example.premium" |
| **Country** | User's country | "United States" |
| **User** | User identifier | "User123" or transaction ID |
| **Store** | Payment provider | "APP\_STORE" |
| **Transaction** | Transaction ID | "700001234567890" |
## Sandbox Handling
### Production Only
* Production events β Sent to Slack
* Sandbox events β **Skipped**
### Production & Sandbox
* Production events β Sent to Slack
* Sandbox events β Sent to Slack with π§ͺ indicator
Sandbox events include a note in the message to differentiate from production.
## Special Event Handling
### Refunds
Identified by negative price values:
* Header changes to "refunded \[type]"
* Emoji changes to π€¬
* Color remains red
* Shows negative amount
### Family Sharing
Events with `isFamilyShare: true`:
* Shows shared subscription indicator
* Price may be $0 for family members
* Original purchaser shows full price
### Trial Conversions
Renewals with `isTrialConversion: true`:
* Header shows "trial conversion"
* Indicates successful trial-to-paid transition
* Always green/positive color
### Product Changes
Shows when users switch plans:
* Displays old and new product IDs
* Neutral gray color
* May have $0 price
## Use Cases
### Revenue Monitoring
Track real-time revenue with "Revenue Events Only":
* Monitor daily subscription revenue
* Get alerts for high-value purchases
* Track refund activity
* Celebrate trial conversions
### Customer Success
Track lifecycle with "All Subscription Events":
* Monitor cancellation trends
* Identify billing issues quickly
* Track trial-to-paid conversion
* Spot at-risk subscribers
### Team Celebrations
Share wins with your team:
* New subscriber notifications
* Trial conversion celebrations
* Renewal milestones
* Recovery from cancellations
## Best Practices
1. **Dedicated Channels**: Create specific channels for different event types
2. **Filter Appropriately**: Use "Revenue Only" for finance, "All Events" for customer success
3. **Include Context**: User IDs help connect events to support tickets
4. **Monitor Patterns**: Watch for unusual cancellation or refund spikes
5. **Sandbox Separation**: Consider separate webhooks for production vs testing
## Troubleshooting
### Messages Not Appearing
1. **Check Webhook URL**: Ensure URL is valid and not revoked
2. **Check Channel**: Verify bot has access to target channel
3. **Check Filters**: Confirm event type and sandbox settings
4. **Check Slack Limits**: Webhook rate limits (1 per second)
### Incorrect Information
1. **Check Timezone**: Timestamps are in UTC
2. **Check Currency**: Amounts in USD, original currency shown
3. **Check User ID**: Falls back to transaction ID if not available
### Test the Integration
Send a test event to verify setup:
1. Configure the integration
2. A test message is automatically sent
3. Check your Slack channel
4. Look for "π§ͺ Test event" message
## Rate Limits
Slack incoming webhooks have a rate limit of 1 message per second. The integration sends events individually as they occur, typically well within this limit.
## Security Considerations
* **Webhook URLs are sensitive**: Treat like passwords
* **Rotate if compromised**: Generate new webhook URL if leaked
* **Channel permissions**: Ensure appropriate team members have access
* **PII considerations**: User IDs may be visible to channel members
## Advanced Configuration
### Multiple Channels
Set up multiple integrations for different channels:
* Revenue events β #revenue-alerts
* Cancellations β #customer-success
* All events β #subscription-monitoring
### Custom Filtering
While the integration offers two preset filters, you can:
* Use Slack workflows for additional filtering
* Set up multiple integrations with different settings
* Use Slack's notification preferences per channel
## Message Examples
### New Paid Subscription
```
π° new subscriber
βββββββββββββββββββββ
π΅ $49.99 USD (Proceeds: $34.99)
π¦ com.example.premium.yearly
π United States
π€ user_abc123
πͺ APP_STORE
π Transaction: 700001234567890
```
### Trial Start
```
π€© Trial start
βββββββββββββββββββββ
π΅ $0.00 USD
π¦ com.example.premium.monthly
π Germany
π€ user_xyz789
πͺ PLAY_STORE
π Transaction: GPA.1234-5678-9012
```
### Refund
```
π€¬ refunded subscription
βββββββββββββββββββββ
π΅ -$9.99 USD (Proceeds: -$6.99)
π¦ com.example.premium.monthly
π United Kingdom
π€ user_def456
πͺ STRIPE
π Transaction: sub_1234567890
```
### Billing Issue
```
π« Billing issue
βββββββββββββββββββββ
π΅ $0.00 USD
π¦ com.example.premium.monthly
π Canada
π€ user_ghi789
πͺ APP_STORE
π Transaction: 700009876543210
β Payment failed - subscription at risk
```
---
# Statsig
Source: https://superwall.com/docs/dashboard/dashboard-integrations/inegrations-statsig
The Statsig integration allows you to automatically send Superwall subscription and payment events to your Statsig project. This integration provides comprehensive event tracking with user properties for experimentation and analytics.
In the **Analytics** section within **Integrations**, you can connect your Statsig account to Superwall:
### Required fields
Fill out the following fields and **click** the **Enable Statsig** button at the bottom right to save your changes:
* **Client SDK Key:** Your Statsig client SDK key from Statsig β Project Settings β Keys & Environments.
* **Environment:** Which environments to send events from.
* **Sales Reporting:** Whether to report Proceeds after store taxes & fees or Revenue. Choose between **Proceeds** (after store taxes & fees) or **Revenue**.
### Features
* **Automatic Event Mapping**: Converts Superwall events to Statsig-friendly event names with `sw_` prefix
* **Revenue Tracking**: Tracks both price (gross) and proceeds (net after fees)
* **User Property Enrichment**: Attaches store, product, and transaction metadata to user objects
* **Environment Tier Separation**: Uses Statsig's tier system to separate production and staging data
* **Sandbox Isolation**: Optional tracking for sandbox/test events
* **Transaction ID Tracking**: Maintains transaction IDs as custom IDs for reconciliation
* **Custom Event Metadata**: Includes all Superwall event data as metadata for deep analysis
### Configuration
#### Required settings
| Field | Description | Example |
| ----------------- | -------------------------------------- | ------------------------------------------ |
| `client_sdk_key` | Your Statsig client SDK key | `"client-abc123def456..."` |
| `environment` | Which environments to send events from | `"Production"` or `"Production & Sandbox"` |
| `sales_reporting` | Which value to report | `"Revenue"` or `"Proceeds"` |
### Event mapping
Superwall events are transformed into standardized Statsig events with the `sw_` prefix:
#### Trial events
| Superwall Event | Statsig Event | Description |
| ---------------------------------------- | ---------------------- | ----------------------- |
| `initial_purchase` + `periodType: TRIAL` | `sw_trial_start` | Trial period begins |
| `cancellation` + `periodType: TRIAL` | `sw_trial_cancelled` | Trial cancelled |
| `uncancellation` + `periodType: TRIAL` | `sw_trial_uncancelled` | Trial reactivated |
| `expiration` + `periodType: TRIAL` | `sw_trial_expired` | Trial ended |
| `renewal` + `isTrialConversion: true` | `sw_trial_converted` | Trial converted to paid |
#### Intro offer events
| Superwall Event | Statsig Event | Description |
| ---------------------------------------- | ---------------------------- | -------------------------- |
| `initial_purchase` + `periodType: INTRO` | `sw_intro_offer_start` | Intro offer begins |
| `cancellation` + `periodType: INTRO` | `sw_intro_offer_cancelled` | Intro offer cancelled |
| `uncancellation` + `periodType: INTRO` | `sw_intro_offer_uncancelled` | Intro offer reactivated |
| `expiration` + `periodType: INTRO` | `sw_intro_offer_expired` | Intro offer ended |
| `renewal` + `periodType: INTRO` | `sw_intro_offer_converted` | Intro converted to regular |
#### Subscription events
| Superwall Event | Statsig Event | Description |
| ----------------------------------------- | ----------------------------- | ------------------------ |
| `initial_purchase` + `periodType: NORMAL` | `sw_subscription_start` | Subscription begins |
| `renewal` + `periodType: NORMAL` | `sw_renewal` | Subscription renewed |
| `cancellation` + `periodType: NORMAL` | `sw_subscription_cancelled` | Subscription cancelled |
| `uncancellation` + `periodType: NORMAL` | `sw_subscription_uncancelled` | Subscription reactivated |
| `expiration` + `periodType: NORMAL` | `sw_subscription_expired` | Subscription ended |
| `subscription_paused` | `sw_subscription_paused` | Subscription paused |
| `billing_issue` | `sw_billing_issue` | Payment failed |
#### Other events
| Superwall Event | Statsig Event | Description |
| -------------------------- | -------------------------- | ----------------- |
| `product_change` | `sw_product_change` | Plan changed |
| `non_renewing_purchase` | `sw_non_renewing_purchase` | One-time purchase |
| Any event with `price < 0` | `sw_refund` | Refund processed |
| `test` | `sw_test` | Test event |
### Event properties
Every Statsig event includes the following structure:
#### Core event fields
* `eventName`: The mapped event name with `sw_` prefix
* `value`: Revenue amount (when applicable)
* `time`: Unix timestamp in milliseconds
* `user`: User object with identity and properties
* `metadata`: All webhook data fields
#### User object
The user object contains:
* **userID**: User identifier (uses `originalAppUserId` or falls back to `originalTransactionId`)
* **country**: Two-letter country code (e.g., "US", "GB")
* **custom**: Transaction properties attached to the user
* `isFamilyShare`: Whether the latest transaction is a family share
* `store`: The store of the latest transaction (APP\_STORE, PLAY\_STORE, STRIPE, PADDLE)
* `productId`: The product ID of the latest transaction
* `bundleId`: The bundle ID of the latest transaction
* **customIDs**: Additional identifiers
* `originalTransactionId`: Store transaction ID (when available)
* **statsigEnvironment**: Environment tier configuration
* `tier: "production"` for production events
* `tier: "staging"` for sandbox events
#### Event metadata
All fields from the webhook are included as metadata:
* `id`, `name`, `cancelReason`, `exchangeRate`
* `isSmallBusiness`, `periodType`, `countryCode`
* `price`, `proceeds`, `priceInPurchasedCurrency`
* `taxPercentage`, `commissionPercentage`, `takehomePercentage`
* `offerCode`, `isFamilyShare`, `expirationAt`
* `transactionId`, `originalTransactionId`, `originalAppUserId`
* `store`, `purchasedAt`, `currencyCode`, `productId`
* `environment`, `isTrialConversion`, `newProductId`
* `bundleId`, `ts`
### Revenue reporting options
#### Price vs proceeds
The `sales_reporting` setting determines which value is used for the `value` field:
| Setting | Value Used | Description |
| ------------ | ---------- | ----------------------------------------- |
| `"Revenue"` | `price` | Gross revenue before store fees and taxes |
| `"Proceeds"` | `proceeds` | Net revenue after store fees and taxes |
#### Examples
**Gross Revenue (Price):**
* Transaction price: $9.99
* Store commission (30%): $3.00
* Your proceeds: $6.99
* Reported to Statsig: **$9.99**
**Net Revenue (Proceeds):**
* Transaction price: $9.99
* Store commission (30%): $3.00
* Your proceeds: $6.99
* Reported to Statsig: **$6.99**
### Sandbox handling
#### With sandbox enabled
If `environment` is set to `"Production & Sandbox"`:
* Production events β Tagged with `tier: "production"`
* Sandbox events β Tagged with `tier: "staging"`
#### Without sandbox enabled
If `environment` is set to `"Production"`:
* Production events β Tagged with `tier: "production"`
* Sandbox events β **Skipped** (not sent to Statsig)
This allows you to:
* Filter events by environment tier in Statsig dashboards
* Create separate metrics for production vs. test
* Validate integration without polluting production data
### Refund handling
Refunds are automatically detected when `price < 0`:
* Event type: `sw_refund`
* Value field: Negative amount
* All metadata preserved for analysis
Example:
* Original purchase: +$9.99
* Refund event: -$9.99
* Net effect on metrics: $0.00
### User identification
The integration uses the following hierarchy for user identification:
1. **Primary**: `originalAppUserId` (if available)
2. **Fallback**: `originalTransactionId` (always present)
This ensures consistent user tracking even for:
* Legacy users without app user IDs
* Family sharing scenarios
* Cross-platform subscriptions
### Testing the integration
#### 1. Validate credentials
The integration automatically validates your credentials by sending a test event when configured.
#### 2. Test event properties
Test events include:
* Event: `sw_test`
* Basic properties to verify connection
* No revenue impact
#### 3. Verify in Statsig
Check your Statsig project:
1. Navigate to **Metrics** β **Events Stream**
2. Look for events with `sw_` prefix
3. Click on an event to view properties and metadata
4. Verify the `statsigEnvironment.tier` matches your configuration
### Troubleshooting
#### Events not appearing
1. **Check API Key**: Ensure you're using the client SDK key (starts with "client-")
2. **Check Environment**: Confirm sandbox events are enabled if testing with sandbox data
3. **Check Events Stream**: Look in Metrics β Events Stream, not just dashboards
4. **Wait for Processing**: Events may take a few seconds to appear
#### Authentication errors
* **Invalid Key Format**: Client SDK keys must start with "client-"
* **Wrong Project**: Verify the key belongs to the correct Statsig project
* **Key Permissions**: Ensure the key has event logging permissions
#### Missing or incorrect data
* **Check Event Properties**: Use Statsig's Events Stream to inspect raw event data
* **Verify User ID**: Ensure `originalAppUserId` is being set in your app
* **Environment Mismatch**: Production events won't appear if filtered for staging tier
### Best practices
1. **Use Consistent User IDs**: Send the same user IDs to both Superwall and Statsig for proper correlation
2. **Choose Revenue Model**: Decide between gross (Revenue) vs net (Proceeds) and use consistently
3. **Set Up Environment Tiers**: Use staging tier for testing without affecting production metrics
4. **Monitor Events Stream**: Regularly check the Events Stream for data quality
5. **Create Custom Metrics**: Build metrics based on subscription events for experimentation
6. **Handle Refunds**: Account for negative revenue events in your analysis
### Rate limits
Statsig has the following limits:
* **Events**: 10,000 requests/second per project
* **Batch Size**: 500 events per batch (this integration sends one at a time)
* **Request Size**: 1MB maximum per request
The integration sends events individually, well within these limits.
### Data privacy
* **PII Handling**: User IDs are pseudonymous by default
* **HTTPS Only**: All events sent over encrypted connections
* **Data Retention**: Follows your Statsig project settings
* **Deletion Requests**: Handle via Statsig's privacy tools
---
# Apple Search Ads
Source: https://superwall.com/docs/dashboard/dashboard-integrations/integrations-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.
---
# Webhooks
Source: https://superwall.com/docs/dashboard/dashboard-integrations/integrations-webhooks
Use webhooks to get real-time notifications about your app's subscription and payment events.
In the **Webhooks** section within **Integrations**, you can manage your webhooks with Superwall:
## Webhooks
Superwall sends webhooks to notify your application about important subscription and payment events in real-time. These webhooks are designed to closely match App Store and other revenue provider events, minimizing migration difficulty.
**Important Design Principle**: Webhook events are structured so that summing `proceeds` or `price` across all events (without filtering) accurately represents total revenue net of refunds. To calculate gross revenue, filter out events with negative proceeds.
### Webhook Payload Structure
Every webhook sent by Superwall contains the following structure:
```json
{
"object": "event",
"type": "renewal",
"projectId": 3827,
"applicationId": 1,
"timestamp": 1754067715103,
"data": {
"id": "42fc6339-dc28-470b-a0fa-0d13c92d8b61:renewal",
"name": "renewal",
"cancelReason": null,
"exchangeRate": 1.0,
"isSmallBusiness": false,
"periodType": "NORMAL",
"countryCode": "US",
"price": 9.99,
"proceeds": 6.99,
"priceInPurchasedCurrency": 9.99,
"taxPercentage": 0,
"commissionPercentage": 0.3,
"takehomePercentage": 0.7,
"offerCode": null,
"isFamilyShare": false,
"expirationAt": 1756659704000,
"transactionId": "700002054157982",
"originalTransactionId": "700002050981465",
"originalAppUserId": "$SuperwallAlias:7152E89E-60A6-4B2E-9C67-D7ED8F5BE372",
"store": "APP_STORE",
"purchasedAt": 1754067704000,
"currencyCode": "USD",
"productId": "com.example.premium.monthly",
"environment": "PRODUCTION",
"isTrialConversion": false,
"newProductId": null,
"bundleId": "com.example.app",
"ts": 1754067710106
}
}
```
### Webhook Payload Fields
| Field | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------- |
| `object` | string | Always "event" |
| `type` | string | The event type (e.g., "initial\_purchase", "renewal", "cancellation") |
| `projectId` | number | Your Superwall project ID |
| `applicationId` | number | Your Superwall application ID |
| `timestamp` | number | Event timestamp in milliseconds since epoch |
| `data` | object | Event-specific data (see below) |
## Event Data Object
The `data` field contains detailed information about the subscription or payment event:
### Event Data Fields
| Field | Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------------------------- |
| `id` | string | Unique identifier for this event |
| `name` | string | Event name (see [Event Names](#event-names)) |
| `cancelReason` | string or null | Reason for cancellation (see [Cancel Reasons](#cancelexpiration-reasons)) |
| `exchangeRate` | number | Exchange rate used to convert to USD |
| `isSmallBusiness` | boolean | Small business program participant |
| `periodType` | string | Period type: `TRIAL`, `INTRO`, or `NORMAL` |
| `countryCode` | string | ISO country code (e.g., "US") |
| `price` | number | Transaction price in USD (negative for refunds) |
| `proceeds` | number | Net proceeds in USD after taxes and fees |
| `priceInPurchasedCurrency` | number | Price in original currency |
| `taxPercentage` | number or null | Tax percentage applied |
| `commissionPercentage` | number | Store commission percentage |
| `takehomePercentage` | number | Your percentage after commission |
| `offerCode` | string or null | Promotional offer code used |
| `isFamilyShare` | boolean | Family sharing purchase |
| `expirationAt` | number or null | Expiration timestamp (milliseconds) |
| `transactionId` | string | Current transaction ID |
| `originalTransactionId` | string | Original transaction ID (subscription ID) |
| `originalAppUserId` | string or null | Original app user ID (see [details](#understanding-originalappuserid)) |
| `store` | string | Store: `APP_STORE`, `PLAY_STORE`, `STRIPE`, or `PADDLE` (see note below) |
| `purchasedAt` | number | Purchase timestamp (milliseconds) |
| `currencyCode` | string | ISO currency code for priceInPurchasedCurrency |
| `productId` | string | Product identifier |
| `environment` | string | `PRODUCTION` or `SANDBOX` |
| `isTrialConversion` | boolean | Trial to paid conversion |
| `newProductId` | string or null | New product ID (for product changes) |
| `bundleId` | string | App bundle identifier |
| `ts` | number | Event timestamp (milliseconds) |
| `expirationReason` | string (optional) | Reason for expiration (see [Cancel Reasons](#cancelexpiration-reasons)) |
| `checkoutContext` | object (optional) | Stripe-specific checkout context |
**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` or `PADDLE` events when users purchase through Superwall's App2Web features, which allow web-based checkout flows within mobile apps. The `store` field indicates where the payment was processed, not which platform the app runs on.
## Event Names
| Event Name | Value | Description |
| --------------------- | ----------------------- | ----------------------------------- |
| Initial Purchase | `initial_purchase` | First-time subscription or purchase |
| Renewal | `renewal` | Subscription renewal |
| Cancellation | `cancellation` | Subscription cancelled |
| Uncancellation | `uncancellation` | Subscription reactivated |
| Expiration | `expiration` | Subscription expired |
| Billing Issue | `billing_issue` | Payment processing failed |
| Product Change | `product_change` | User changed subscription tier |
| Subscription Paused | `subscription_paused` | Subscription temporarily paused |
| Non-Renewing Purchase | `non_renewing_purchase` | One-time purchase |
| Test | `test` | Test event for webhook verification |
## Period Types
| Period Type | Value | Description |
| ----------- | -------- | ------------------------------------------- |
| Trial | `TRIAL` | Free trial period |
| Intro | `INTRO` | Introductory offer period (discounted rate) |
| Normal | `NORMAL` | Regular subscription period (full price) |
## Stores
| Store | Value | Description |
| ---------- | ------------ | ----------------------------- |
| App Store | `APP_STORE` | Apple App Store |
| Play Store | `PLAY_STORE` | Google Play Store |
| Stripe | `STRIPE` | Stripe payments |
| Paddle | `PADDLE` | Paddle payments (coming soon) |
## Environments
| Environment | Value | Description |
| ----------- | ------------ | ---------------------------------- |
| Production | `PRODUCTION` | Live production transactions |
| Sandbox | `SANDBOX` | Test transactions (not real money) |
## Cancel/Expiration Reasons
| Reason | Value | Description |
| ------------------- | --------------------- | ----------------------------- |
| Billing Error | `BILLING_ERROR` | Payment method failed |
| Customer Support | `CUSTOMER_SUPPORT` | Cancelled via support |
| Unsubscribe | `UNSUBSCRIBE` | User-initiated cancellation |
| Price Increase | `PRICE_INCREASE` | Cancelled due to price change |
| Developer Initiated | `DEVELOPER_INITIATED` | Cancelled programmatically |
| Unknown | `UNKNOWN` | Reason not specified |
## Common Use Cases
### Detecting Trial Starts
```javascript
if (
event.data.periodType === "TRIAL" &&
event.data.name === "initial_purchase"
) {
// New trial started
}
```
### Detecting Trial Conversions
```javascript
if (
event.data.name === "renewal" &&
(event.data.isTrialConversion ||
event.data.periodType === "TRIAL" ||
event.data.periodType === "INTRO")
) {
// Trial or intro offer converted to paid subscription
}
```
### Detecting Trial Cancellations
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "cancellation") {
// Trial cancelled
}
```
### Detecting Trial Uncancellations (Reactivations)
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "uncancellation") {
// Trial reactivated after cancellation
}
```
### Detecting Trial Expirations
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "expiration") {
// Trial expired
}
```
### Detecting Intro Offer Starts
```javascript
if (
event.data.periodType === "INTRO" &&
event.data.name === "initial_purchase"
) {
// Intro offer started
}
```
### Detecting Intro Offer Cancellations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "cancellation") {
// Intro offer cancelled
}
```
### Detecting Intro Offer Uncancellations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "uncancellation") {
// Intro offer reactivated
}
```
### Detecting Intro Offer Expirations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "expiration") {
// Intro offer expired
}
```
### Detecting Intro Offer Conversions
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "renewal") {
// Intro offer converted to regular subscription
}
```
### Detecting Subscription Starts
```javascript
if (
event.data.periodType === "NORMAL" &&
event.data.name === "initial_purchase"
) {
// New paid subscription started
}
```
### Detecting Renewals
```javascript
if (
event.data.name === "renewal" &&
event.data.periodType === "NORMAL" &&
!event.data.isTrialConversion
) {
// Regular subscription renewal
}
```
### Detecting Refunds
```javascript
if (event.data.price < 0) {
// Refund processed
const refundAmount = Math.abs(event.data.price);
}
```
### Detecting Cancellations
```javascript
if (event.data.name === "cancellation") {
// Subscription cancelled
// Check cancelReason for details
const reason = event.data.cancelReason;
}
```
### Detecting Subscription Expirations
```javascript
if (event.data.name === "expiration") {
// Subscription expired
// Check expirationReason for details
}
```
### Detecting Billing Issues
```javascript
if (event.data.name === "billing_issue") {
// Payment failed - subscription at risk
}
```
### Detecting Subscription Pauses
```javascript
if (event.data.name === "subscription_paused") {
// Subscription has been paused
}
```
### Detecting Product Changes
```javascript
if (event.data.name === "product_change") {
// User changed subscription plan
const oldProduct = event.data.productId;
const newProduct = event.data.newProductId;
}
```
### Detecting Subscription Reactivations
```javascript
if (event.data.name === "uncancellation") {
// Previously cancelled subscription was reactivated
}
```
### Detecting Non-Renewing Purchases
```javascript
if (event.data.name === "non_renewing_purchase") {
// One-time purchase completed
}
```
### Detecting Revenue Events
```javascript
if (event.data.price !== 0 || event.data.name === "non_renewing_purchase") {
// This event involves revenue (positive or negative)
}
```
### Detecting Test Events
```javascript
if (event.data.name === "test") {
// Test webhook for endpoint verification
}
```
## Revenue Calculation
### Total Net Revenue (Including Refunds)
```javascript
// Sum all proceeds - automatically accounts for refunds
const netRevenue = events.reduce((sum, event) => sum + event.data.proceeds, 0);
```
### Gross Revenue (Excluding Refunds)
```javascript
// Only sum positive proceeds
const grossRevenue = events.reduce(
(sum, event) => (event.data.proceeds > 0 ? sum + event.data.proceeds : sum),
0
);
```
### Refund Total
```javascript
// Sum negative proceeds
const refunds = events.reduce(
(sum, event) =>
event.data.proceeds < 0 ? sum + Math.abs(event.data.proceeds) : sum,
0
);
```
### Revenue by Product
```javascript
const revenueByProduct = {};
events.forEach((event) => {
const productId = event.data.productId;
if (!revenueByProduct[productId]) {
revenueByProduct[productId] = 0;
}
revenueByProduct[productId] += event.data.proceeds;
});
```
## Webhook Security
All webhooks are signed using HMAC-SHA256. Verify the signature before processing:
1. Extract the signature from the `X-Webhook-Signature` header
2. Compute HMAC-SHA256 of the raw request body using your webhook secret
3. Compare the computed signature with the received signature
## Testing Webhooks
iOS local StoreKit transactions (using a StoreKit Configuration file or StoreKitTest
in Xcode) do not generate App Store Server Notifications. As a result, Superwall
webhooks will not fire for these local test purchases. To verify webhook delivery on iOS,
use Sandbox via TestFlight/a sandbox Apple ID.
Test events can be identified by:
* `event.data.name === "test"`
* These events have minimal data and are used for webhook endpoint verification
## Best Practices
1. **Always verify webhook signatures** to ensure authenticity
2. **Handle duplicate events** - Use `event.id` for idempotency
3. **Process webhooks asynchronously** - Return 200 immediately, then process
4. **Store raw webhook data** for debugging and reconciliation
5. **Handle all event types** - Even if you don't process them immediately
6. **Monitor webhook failures** - Implement retry logic for critical events
7. **Use timestamps** - All timestamps are in milliseconds since epoch
## Store-Specific Behaviors
### Commission Rates by Store
**APP\_STORE:**
* Standard rate: 30%
* Small Business Program rate: 15% (for eligible developers)
* Clean, predictable commission structure
**PLAY\_STORE:**
* Variable rates from 11.8% to 15%
* Most common rate: 15%
* Rates can vary based on region and other factors
**STRIPE:**
* Variable rates from 0% to \~7.2%
* Generally lower than mobile app stores
* Depends on Stripe pricing plan and transaction type
### Price = 0 Events
Events commonly have `price = 0` for non-revenue scenarios:
* `billing_issue` - Payment failed, no money collected
* `cancellation` - Subscription cancelled, no charge
* `expiration` - Subscription expired, no charge
* `uncancellation` - Reactivation, no immediate charge
* `product_change` - Plan change notification
* `subscription_paused` - Pause event, no charge
Revenue events (initial\_purchase, renewal, non\_renewing\_purchase) typically have non-zero prices unless:
* Family sharing scenario (some cases)
* Special promotional offers
* Test transactions
### Cancel/Expiration Reasons by Store
**APP\_STORE:**
* `CUSTOMER_SUPPORT` - Cancelled via Apple support
* `UNSUBSCRIBE` - User-initiated cancellation
* `BILLING_ERROR` - Payment failure
**PLAY\_STORE:**
* All APP\_STORE reasons plus:
* `UNKNOWN` - Reason not specified or unavailable
**STRIPE:**
* `UNKNOWN` - Stripe typically doesn't provide detailed cancellation reasons
### Trial Conversions
**Expected behavior:** `isTrialConversion` should only be `true` for `renewal` events
### Offer Codes Support
| Store | Support | Notes |
| ----------- | --------------- | -------------------------------------------------------------- |
| APP\_STORE | β
Supported | Rarely used (1.3% of events), typically for win-back campaigns |
| PLAY\_STORE | β
Supported | Heavily used (72.1% of events), complex promotional system |
| STRIPE | β Not supported | Offer codes not available in webhook data |
| PADDLE | π Coming soon | Support planned |
### Environment Field
All stores support both PRODUCTION and SANDBOX environments:
* **PRODUCTION**: Live, real-money transactions
* **SANDBOX**: Test transactions (TestFlight on iOS, test mode on Stripe, test purchases on Play Store)
The environment field helps you filter out test transactions from production analytics.
## Store Event Compatibility Matrix
Not all events are available for all stores. This table shows which events you can expect from each store based on real webhook data:
### Event Support by Store
| Event Name | APP\_STORE | PLAY\_STORE | STRIPE | PADDLE |
| ----------------------- | ---------- | ----------- | ------ | ------ |
| `billing_issue` | β
| β
| β
| π |
| `cancellation` | β
| β
| β
| π |
| `expiration` | β
| β
| β
| π |
| `initial_purchase` | β
| β
| β
| π |
| `non_renewing_purchase` | β
| β
| β | π |
| `product_change` | β
| β
| β | π |
| `renewal` | β
| β
| β
| π |
| `subscription_paused` | β | β
| β | π |
| `uncancellation` | β
| β
| β
| π |
β
= Supported | β = Not supported | π = Coming soon
### Period Type Availability by Store
Different stores support different period types for events:
#### APP\_STORE
* Supports all period types (TRIAL, INTRO, NORMAL) for most events
* `non_renewing_purchase` only occurs with NORMAL period type
#### PLAY\_STORE
* Supports all period types (TRIAL, INTRO, NORMAL) for most events
* `renewal` only occurs with NORMAL period type
* `subscription_paused` only occurs with INTRO and NORMAL period types
* **Unique**: Only store that supports `subscription_paused` events
#### STRIPE
* Limited period type support compared to mobile app stores
* No INTRO period type support observed
* `expiration` and `renewal` only occur with NORMAL period type
* Does not support `non_renewing_purchase` or `product_change` events
#### PADDLE
* Coming soon - full support planned!
### Store-Specific Considerations
**Universal Events** (available across APP\_STORE, PLAY\_STORE, and STRIPE):
* `billing_issue`
* `cancellation`
* `expiration`
* `initial_purchase`
* `renewal`
* `uncancellation`
**Store-Specific Events**:
* `subscription_paused` - Only available from PLAY\_STORE
* `non_renewing_purchase` - Not available from STRIPE
* `product_change` - Not available from STRIPE
### Understanding originalAppUserId
The `originalAppUserId` field represents the first app user ID associated with a subscription. This field has specific behavior depending on your integration:
### Key Points:
* **What it represents**: The first user ID we saw associated with this subscription (originalTransactionId)
* **Cross-account subscriptions**: Since subscriptions are tied to Apple/Google accounts (not app accounts), users can create multiple accounts in your app while using the same subscription
* **We only store the first one**: If a user creates multiple accounts, we only track the original user ID
### When this field is populated:
* **iOS/App Store**:
* If your user ID has been sent to the stores on-device (via StoreKit)
* If your user IDs are UUIDv4 format
* This field will be consistently present for these cases
* **Stripe**: Always populated (we create one for you if not provided)
* **Play Store**: Depends on the integration and user tracking
### When this field is null:
* **Legacy users**: Users on old SDK versions
* **Pre-Superwall purchases**: Users who purchased before integrating Superwall
* **No user ID sent**: If user ID was never sent to the store
### Understanding originalTransactionId
The `originalTransactionId` is Apple's terminology that acts like a subscription ID. For simplicity and consistency with iOS and other revenue tracking platforms, we use this nomenclature and populate it accordingly for all platforms (Play Store, Stripe, Paddle, etc.).
* **One per subscription group**: Each user subscription gets one `originalTransactionId`
* **Persists across renewals**: The same `originalTransactionId` is used for all renewals in that subscription
* **Multiple IDs per user**: A single user can have multiple `originalTransactionId` if they:
* Subscribe to products in different subscription groups
* Let a subscription fully expire and re-subscribe later
* **Cross-platform consistency**: While originally an Apple concept, we generate and maintain equivalent IDs for all payment providers to ensure consistent subscription tracking
### Notes
* **Currency handling**:
* `price` and `proceeds` are always in USD
* `priceInPurchasedCurrency` is in the currency specified by `currencyCode`
* `exchangeRate` was used to convert from original currency to USD
* **Family Sharing** (App Store only):
* When `isFamilyShare` is true with `price > 0`: These are events for the **family organizer** who pays for the subscription (initial\_purchase, renewal, non\_renewing\_purchase)
* When `isFamilyShare` is true with `price = 0`: These are events for **family members** who use the shared subscription without paying (renewal, uncancellation, billing\_issue, etc.)
* **Refunds**: Negative values in `price`, `proceeds`, or `priceInPurchasedCurrency` indicate refunds
* **Transaction IDs**:
* `transactionId`: Unique ID for this specific transaction
* `originalTransactionId`: Subscription ID (first transaction in the subscription group)
* Commission and tax percentages help you understand the revenue breakdown
* **Timestamps**:
* `timestamp` (root level): When the webhook was created
* `ts` (in data): When the actual event occurred
* `purchasedAt`: When the transaction was originally purchased
---
# 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.
---
# 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.
---
# 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.
---
# Audit Log
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-audit-log
undefined
In the **Audit Log** section within **Settings**, you can view virtually any action taken by users within Superwall:
This is useful to see all of the actions you, or others within your team, have made:
To view details about any of the actions, simply click on the row to expand it:
---
# 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.
---
# 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.
---
# Localization
Source: https://superwall.com/docs/dashboard/dashboard-settings/overview-settings-localization
undefined
Todo.
---
# 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:
---
# 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.
---
# 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 in private beta.
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.
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. Under "Notification content", select "Subscriptions, voided purchases, and all one-time products"
6. Copy the "Topic Name" from Superwall and paste it into the "Topic name" field
in the Google Play Console.
7. Click "Save"
---
# 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:
---
# 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**.
### Renaming your team
To rename your team, enter in a new value name under the **Team Name** section, and **click** the **Save** button:
---
# 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**.
---
# 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:
---
# 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
---
# 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
---
# 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
---
# 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
---
# 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
---
# Welcome
Source: https://superwall.com/docs/dashboard/index
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.
---
# Integrations
Source: https://superwall.com/docs/dashboard/integrations
Use webhooks to get real-time notifications about your app's subscription and payment events. Integrate Superwall with other services.
The integrations page is where you can manage your webhooks and other integrations with Superwall:
## Webhooks
Superwall sends webhooks to notify your application about important subscription and payment events in real-time. These webhooks are designed to closely match App Store and other revenue provider events, minimizing migration difficulty.
**Important Design Principle**: Webhook events are structured so that summing `proceeds` or `price` across all events (without filtering) accurately represents total revenue net of refunds. To calculate gross revenue, filter out events with negative proceeds.
### Webhook Payload Structure
Every webhook sent by Superwall contains the following structure:
```json
{
"object": "event",
"type": "renewal",
"projectId": 3827,
"applicationId": 1,
"timestamp": 1754067715103,
"data": {
"id": "42fc6339-dc28-470b-a0fa-0d13c92d8b61:renewal",
"name": "renewal",
"cancelReason": null,
"exchangeRate": 1.0,
"isSmallBusiness": false,
"periodType": "NORMAL",
"countryCode": "US",
"price": 9.99,
"proceeds": 6.99,
"priceInPurchasedCurrency": 9.99,
"taxPercentage": 0,
"commissionPercentage": 0.3,
"takehomePercentage": 0.7,
"offerCode": null,
"isFamilyShare": false,
"expirationAt": 1756659704000,
"transactionId": "700002054157982",
"originalTransactionId": "700002050981465",
"originalAppUserId": "$SuperwallAlias:7152E89E-60A6-4B2E-9C67-D7ED8F5BE372",
"store": "APP_STORE",
"purchasedAt": 1754067704000,
"currencyCode": "USD",
"productId": "com.example.premium.monthly",
"environment": "PRODUCTION",
"isTrialConversion": false,
"newProductId": null,
"bundleId": "com.example.app",
"ts": 1754067710106
}
}
```
### Webhook Payload Fields
| Field | Type | Description |
| --------------- | ------ | --------------------------------------------------------------------- |
| `object` | string | Always "event" |
| `type` | string | The event type (e.g., "initial\_purchase", "renewal", "cancellation") |
| `projectId` | number | Your Superwall project ID |
| `applicationId` | number | Your Superwall application ID |
| `timestamp` | number | Event timestamp in milliseconds since epoch |
| `data` | object | Event-specific data (see below) |
## Event Data Object
The `data` field contains detailed information about the subscription or payment event:
### Event Data Fields
| Field | Type | Description |
| -------------------------- | ----------------- | ------------------------------------------------------------------------- |
| `id` | string | Unique identifier for this event |
| `name` | string | Event name (see [Event Names](#event-names)) |
| `cancelReason` | string or null | Reason for cancellation (see [Cancel Reasons](#cancelexpiration-reasons)) |
| `exchangeRate` | number | Exchange rate used to convert to USD |
| `isSmallBusiness` | boolean | Small business program participant |
| `periodType` | string | Period type: `TRIAL`, `INTRO`, or `NORMAL` |
| `countryCode` | string | ISO country code (e.g., "US") |
| `price` | number | Transaction price in USD (negative for refunds) |
| `proceeds` | number | Net proceeds in USD after taxes and fees |
| `priceInPurchasedCurrency` | number | Price in original currency |
| `taxPercentage` | number or null | Tax percentage applied |
| `commissionPercentage` | number | Store commission percentage |
| `takehomePercentage` | number | Your percentage after commission |
| `offerCode` | string or null | Promotional offer code used |
| `isFamilyShare` | boolean | Family sharing purchase |
| `expirationAt` | number or null | Expiration timestamp (milliseconds) |
| `transactionId` | string | Current transaction ID |
| `originalTransactionId` | string | Original transaction ID (subscription ID) |
| `originalAppUserId` | string or null | Original app user ID (see [details](#understanding-originalappuserid)) |
| `store` | string | Store: `APP_STORE`, `PLAY_STORE`, `STRIPE`, or `PADDLE` (see note below) |
| `purchasedAt` | number | Purchase timestamp (milliseconds) |
| `currencyCode` | string | ISO currency code for priceInPurchasedCurrency |
| `productId` | string | Product identifier |
| `environment` | string | `PRODUCTION` or `SANDBOX` |
| `isTrialConversion` | boolean | Trial to paid conversion |
| `newProductId` | string or null | New product ID (for product changes) |
| `bundleId` | string | App bundle identifier |
| `ts` | number | Event timestamp (milliseconds) |
| `expirationReason` | string (optional) | Reason for expiration (see [Cancel Reasons](#cancelexpiration-reasons)) |
| `checkoutContext` | object (optional) | Stripe-specific checkout context |
**Note on Store field:** iOS and Android apps can receive events from any payment provider. For example, an iOS app can receive `STRIPE` or `PADDLE` events when users purchase through Superwall's App2Web features, which allow web-based checkout flows within mobile apps. The `store` field indicates where the payment was processed, not which platform the app runs on.
## Event Names
| Event Name | Value | Description |
| --------------------- | ----------------------- | ----------------------------------- |
| Initial Purchase | `initial_purchase` | First-time subscription or purchase |
| Renewal | `renewal` | Subscription renewal |
| Cancellation | `cancellation` | Subscription cancelled |
| Uncancellation | `uncancellation` | Subscription reactivated |
| Expiration | `expiration` | Subscription expired |
| Billing Issue | `billing_issue` | Payment processing failed |
| Product Change | `product_change` | User changed subscription tier |
| Subscription Paused | `subscription_paused` | Subscription temporarily paused |
| Non-Renewing Purchase | `non_renewing_purchase` | One-time purchase |
| Test | `test` | Test event for webhook verification |
## Period Types
| Period Type | Value | Description |
| ----------- | -------- | ------------------------------------------- |
| Trial | `TRIAL` | Free trial period |
| Intro | `INTRO` | Introductory offer period (discounted rate) |
| Normal | `NORMAL` | Regular subscription period (full price) |
## Stores
| Store | Value | Description |
| ---------- | ------------ | ----------------------------- |
| App Store | `APP_STORE` | Apple App Store |
| Play Store | `PLAY_STORE` | Google Play Store |
| Stripe | `STRIPE` | Stripe payments |
| Paddle | `PADDLE` | Paddle payments (coming soon) |
## Environments
| Environment | Value | Description |
| ----------- | ------------ | ---------------------------------- |
| Production | `PRODUCTION` | Live production transactions |
| Sandbox | `SANDBOX` | Test transactions (not real money) |
## Cancel/Expiration Reasons
| Reason | Value | Description |
| ------------------- | --------------------- | ----------------------------- |
| Billing Error | `BILLING_ERROR` | Payment method failed |
| Customer Support | `CUSTOMER_SUPPORT` | Cancelled via support |
| Unsubscribe | `UNSUBSCRIBE` | User-initiated cancellation |
| Price Increase | `PRICE_INCREASE` | Cancelled due to price change |
| Developer Initiated | `DEVELOPER_INITIATED` | Cancelled programmatically |
| Unknown | `UNKNOWN` | Reason not specified |
## Common Use Cases
### Detecting Trial Starts
```javascript
if (
event.data.periodType === "TRIAL" &&
event.data.name === "initial_purchase"
) {
// New trial started
}
```
### Detecting Trial Conversions
```javascript
if (
event.data.name === "renewal" &&
(event.data.isTrialConversion ||
event.data.periodType === "TRIAL" ||
event.data.periodType === "INTRO")
) {
// Trial or intro offer converted to paid subscription
}
```
### Detecting Trial Cancellations
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "cancellation") {
// Trial cancelled
}
```
### Detecting Trial Uncancellations (Reactivations)
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "uncancellation") {
// Trial reactivated after cancellation
}
```
### Detecting Trial Expirations
```javascript
if (event.data.periodType === "TRIAL" && event.data.name === "expiration") {
// Trial expired
}
```
### Detecting Intro Offer Starts
```javascript
if (
event.data.periodType === "INTRO" &&
event.data.name === "initial_purchase"
) {
// Intro offer started
}
```
### Detecting Intro Offer Cancellations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "cancellation") {
// Intro offer cancelled
}
```
### Detecting Intro Offer Uncancellations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "uncancellation") {
// Intro offer reactivated
}
```
### Detecting Intro Offer Expirations
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "expiration") {
// Intro offer expired
}
```
### Detecting Intro Offer Conversions
```javascript
if (event.data.periodType === "INTRO" && event.data.name === "renewal") {
// Intro offer converted to regular subscription
}
```
### Detecting Subscription Starts
```javascript
if (
event.data.periodType === "NORMAL" &&
event.data.name === "initial_purchase"
) {
// New paid subscription started
}
```
### Detecting Renewals
```javascript
if (
event.data.name === "renewal" &&
event.data.periodType === "NORMAL" &&
!event.data.isTrialConversion
) {
// Regular subscription renewal
}
```
### Detecting Refunds
```javascript
if (event.data.price < 0) {
// Refund processed
const refundAmount = Math.abs(event.data.price);
}
```
### Detecting Cancellations
```javascript
if (event.data.name === "cancellation") {
// Subscription cancelled
// Check cancelReason for details
const reason = event.data.cancelReason;
}
```
### Detecting Subscription Expirations
```javascript
if (event.data.name === "expiration") {
// Subscription expired
// Check expirationReason for details
}
```
### Detecting Billing Issues
```javascript
if (event.data.name === "billing_issue") {
// Payment failed - subscription at risk
}
```
### Detecting Subscription Pauses
```javascript
if (event.data.name === "subscription_paused") {
// Subscription has been paused
}
```
### Detecting Product Changes
```javascript
if (event.data.name === "product_change") {
// User changed subscription plan
const oldProduct = event.data.productId;
const newProduct = event.data.newProductId;
}
```
### Detecting Subscription Reactivations
```javascript
if (event.data.name === "uncancellation") {
// Previously cancelled subscription was reactivated
}
```
### Detecting Non-Renewing Purchases
```javascript
if (event.data.name === "non_renewing_purchase") {
// One-time purchase completed
}
```
### Detecting Revenue Events
```javascript
if (event.data.price !== 0 || event.data.name === "non_renewing_purchase") {
// This event involves revenue (positive or negative)
}
```
### Detecting Test Events
```javascript
if (event.data.name === "test") {
// Test webhook for endpoint verification
}
```
## Revenue Calculation
### Total Net Revenue (Including Refunds)
```javascript
// Sum all proceeds - automatically accounts for refunds
const netRevenue = events.reduce((sum, event) => sum + event.data.proceeds, 0);
```
### Gross Revenue (Excluding Refunds)
```javascript
// Only sum positive proceeds
const grossRevenue = events.reduce(
(sum, event) => (event.data.proceeds > 0 ? sum + event.data.proceeds : sum),
0
);
```
### Refund Total
```javascript
// Sum negative proceeds
const refunds = events.reduce(
(sum, event) =>
event.data.proceeds < 0 ? sum + Math.abs(event.data.proceeds) : sum,
0
);
```
### Revenue by Product
```javascript
const revenueByProduct = {};
events.forEach((event) => {
const productId = event.data.productId;
if (!revenueByProduct[productId]) {
revenueByProduct[productId] = 0;
}
revenueByProduct[productId] += event.data.proceeds;
});
```
## Webhook Security
All webhooks are signed using HMAC-SHA256. Verify the signature before processing:
1. Extract the signature from the `X-Webhook-Signature` header
2. Compute HMAC-SHA256 of the raw request body using your webhook secret
3. Compare the computed signature with the received signature
## Testing Webhooks
Test events can be identified by:
* `event.data.name === "test"`
* These events have minimal data and are used for webhook endpoint verification
## Best Practices
1. **Always verify webhook signatures** to ensure authenticity
2. **Handle duplicate events** - Use `event.id` for idempotency
3. **Process webhooks asynchronously** - Return 200 immediately, then process
4. **Store raw webhook data** for debugging and reconciliation
5. **Handle all event types** - Even if you don't process them immediately
6. **Monitor webhook failures** - Implement retry logic for critical events
7. **Use timestamps** - All timestamps are in milliseconds since epoch
## Store-Specific Behaviors
### Commission Rates by Store
**APP\_STORE:**
* Standard rate: 30%
* Small Business Program rate: 15% (for eligible developers)
* Clean, predictable commission structure
**PLAY\_STORE:**
* Variable rates from 11.8% to 15%
* Most common rate: 15%
* Rates can vary based on region and other factors
**STRIPE:**
* Variable rates from 0% to \~7.2%
* Generally lower than mobile app stores
* Depends on Stripe pricing plan and transaction type
### Price = 0 Events
Events commonly have `price = 0` for non-revenue scenarios:
* `billing_issue` - Payment failed, no money collected
* `cancellation` - Subscription cancelled, no charge
* `expiration` - Subscription expired, no charge
* `uncancellation` - Reactivation, no immediate charge
* `product_change` - Plan change notification
* `subscription_paused` - Pause event, no charge
Revenue events (initial\_purchase, renewal, non\_renewing\_purchase) typically have non-zero prices unless:
* Family sharing scenario (some cases)
* Special promotional offers
* Test transactions
### Cancel/Expiration Reasons by Store
**APP\_STORE:**
* `CUSTOMER_SUPPORT` - Cancelled via Apple support
* `UNSUBSCRIBE` - User-initiated cancellation
* `BILLING_ERROR` - Payment failure
**PLAY\_STORE:**
* All APP\_STORE reasons plus:
* `UNKNOWN` - Reason not specified or unavailable
**STRIPE:**
* `UNKNOWN` - Stripe typically doesn't provide detailed cancellation reasons
### Trial Conversions
**Expected behavior:** `isTrialConversion` should only be `true` for `renewal` events
### Offer Codes Support
| Store | Support | Notes |
| ----------- | --------------- | -------------------------------------------------------------- |
| APP\_STORE | β
Supported | Rarely used (1.3% of events), typically for win-back campaigns |
| PLAY\_STORE | β
Supported | Heavily used (72.1% of events), complex promotional system |
| STRIPE | β Not supported | Offer codes not available in webhook data |
| PADDLE | π Coming soon | Support planned |
### Environment Field
All stores support both PRODUCTION and SANDBOX environments:
* **PRODUCTION**: Live, real-money transactions
* **SANDBOX**: Test transactions (TestFlight on iOS, test mode on Stripe, test purchases on Play Store)
The environment field helps you filter out test transactions from production analytics.
## Store Event Compatibility Matrix
Not all events are available for all stores. This table shows which events you can expect from each store based on real webhook data:
### Event Support by Store
| Event Name | APP\_STORE | PLAY\_STORE | STRIPE | PADDLE |
| ----------------------- | ---------- | ----------- | ------ | ------ |
| `billing_issue` | β
| β
| β
| π |
| `cancellation` | β
| β
| β
| π |
| `expiration` | β
| β
| β
| π |
| `initial_purchase` | β
| β
| β
| π |
| `non_renewing_purchase` | β
| β
| β | π |
| `product_change` | β
| β
| β | π |
| `renewal` | β
| β
| β
| π |
| `subscription_paused` | β | β
| β | π |
| `uncancellation` | β
| β
| β
| π |
β
= Supported | β = Not supported | π = Coming soon
### Period Type Availability by Store
Different stores support different period types for events:
#### APP\_STORE
* Supports all period types (TRIAL, INTRO, NORMAL) for most events
* `non_renewing_purchase` only occurs with NORMAL period type
#### PLAY\_STORE
* Supports all period types (TRIAL, INTRO, NORMAL) for most events
* `renewal` only occurs with NORMAL period type
* `subscription_paused` only occurs with INTRO and NORMAL period types
* **Unique**: Only store that supports `subscription_paused` events
#### STRIPE
* Limited period type support compared to mobile app stores
* No INTRO period type support observed
* `expiration` and `renewal` only occur with NORMAL period type
* Does not support `non_renewing_purchase` or `product_change` events
#### PADDLE
* Coming soon - full support planned!
### Store-Specific Considerations
**Universal Events** (available across APP\_STORE, PLAY\_STORE, and STRIPE):
* `billing_issue`
* `cancellation`
* `expiration`
* `initial_purchase`
* `renewal`
* `uncancellation`
**Store-Specific Events**:
* `subscription_paused` - Only available from PLAY\_STORE
* `non_renewing_purchase` - Not available from STRIPE
* `product_change` - Not available from STRIPE
### Understanding originalAppUserId
The `originalAppUserId` field represents the first app user ID associated with a subscription. This field has specific behavior depending on your integration:
### Key Points:
* **What it represents**: The first user ID we saw associated with this subscription (originalTransactionId)
* **Cross-account subscriptions**: Since subscriptions are tied to Apple/Google accounts (not app accounts), users can create multiple accounts in your app while using the same subscription
* **We only store the first one**: If a user creates multiple accounts, we only track the original user ID
### When this field is populated:
* **iOS/App Store**:
* If your user ID has been sent to the stores on-device (via StoreKit)
* If your user IDs are UUIDv4 format
* This field will be consistently present for these cases
* **Stripe**: Always populated (we create one for you if not provided)
* **Play Store**: Depends on the integration and user tracking
### When this field is null:
* **Legacy users**: Users on old SDK versions
* **Pre-Superwall purchases**: Users who purchased before integrating Superwall
* **No user ID sent**: If user ID was never sent to the store
### Understanding originalTransactionId
The `originalTransactionId` is Apple's terminology that acts like a subscription ID. For simplicity and consistency with iOS and other revenue tracking platforms, we use this nomenclature and populate it accordingly for all platforms (Play Store, Stripe, Paddle, etc.).
* **One per subscription group**: Each user subscription gets one `originalTransactionId`
* **Persists across renewals**: The same `originalTransactionId` is used for all renewals in that subscription
* **Multiple IDs per user**: A single user can have multiple `originalTransactionId` if they:
* Subscribe to products in different subscription groups
* Let a subscription fully expire and re-subscribe later
* **Cross-platform consistency**: While originally an Apple concept, we generate and maintain equivalent IDs for all payment providers to ensure consistent subscription tracking
### Notes
* **Currency handling**:
* `price` and `proceeds` are always in USD
* `priceInPurchasedCurrency` is in the currency specified by `currencyCode`
* `exchangeRate` was used to convert from original currency to USD
* **Family Sharing** (App Store only):
* When `isFamilyShare` is true with `price > 0`: These are events for the **family organizer** who pays for the subscription (initial\_purchase, renewal, non\_renewing\_purchase)
* When `isFamilyShare` is true with `price = 0`: These are events for **family members** who use the shared subscription without paying (renewal, uncancellation, billing\_issue, etc.)
* **Refunds**: Negative values in `price`, `proceeds`, or `priceInPurchasedCurrency` indicate refunds
* **Transaction IDs**:
* `transactionId`: Unique ID for this specific transaction
* `originalTransactionId`: Subscription ID (first transaction in the subscription group)
* Commission and tax percentages help you understand the revenue breakdown
* **Timestamps**:
* `timestamp` (root level): When the webhook was created
* `ts` (in data): When the actual event occurred
* `purchasedAt`: When the transaction was originally purchased
## Integrations
Currently, we support the following integrations:
* **Mixpanel**: Track events and user properties in Mixpanel.
* **Slack**: Send notifications to Slack channels.
* **Amplitude**: Product analytics for your app.
To set up any of these, click on them and fill in the required fields:
Once you've done that, **click** the **Enable** button at the bottom right to save your changes.
### Mixpanel Integration - Required Fields
The following fields are required to configure the Mixpanel integration:
#### Region \*
* **Description**: Data residency region for your Mixpanel project
* **Type**: Dropdown selection
* **Required**: Yes
#### Project Token \*
* **Description**: Your Mixpanel project token
* **Type**: Text input
* **Required**: Yes
* **Location**: Mixpanel β Settings β Project Settings β Project Token
#### Total Spend Property \*
* **Description**: The name of the user property to track cumulative spend
* **Type**: Text input
* **Required**: Yes
#### Sales Reporting \*
* **Description**: Whether to report Proceeds after store taxes & fees or Revenue
* **Type**: Dropdown selection
* **Required**: Yes
* **Options**:
* Proceeds (after store taxes & fees)
* Revenue
### Optional Configuration
#### Sandbox Project Token
* **Description**: Optional project token for sandbox events
* **Type**: Text input
* **Required**: No
* **Note**: Leave blank to opt out of sandbox event tracking
### Slack Integration - Required Fields
The following fields are required to configure the Slack integration:
#### Required Configuration
**Webhook Url** \*
* **Description**: Your Slack webhook URL for sending messages to a channel
* **Type**: Text input
* **Required**: Yes
#### Optional Configuration
**Include Sandbox**
* **Description**: Whether to include sandbox events in Slack notifications
* **Type**: Dropdown selection
* **Required**: No
**Event Type**
* **Description**: Type of events to send: revenue only or all lifecycle (includes trials, cancellations)
* **Type**: Dropdown selection
* **Required**: No
* **Options**:
* Revenue only
* All lifecycle (includes trials, cancellations)
### Amplitude Integration - Required Fields
The following fields are required to configure the Amplitude integration:
#### Required Configuration
**Region** \*
* **Description**: Data residency region for your Amplitude project
* **Type**: Dropdown selection
* **Required**: Yes
**Api Key** \*
* **Description**: Your Amplitude API key
* **Type**: Text input
* **Required**: Yes
**Sales Reporting** \*
* **Description**: Which revenue value to report in Amplitude
* **Type**: Dropdown selection
* **Required**: Yes
#### Optional Configuration
**Sandbox Api Key**
* **Description**: Optional API key for sandbox events
* **Type**: Text input
* **Required**: No
* **Note**: Leave blank to opt out of sandbox event tracking
---
# 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.
---
# 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.
When you log in for the first time or add a new app, the Overview page will reflect a "Quickstart"
wizard to help you get up and running. Complete the interactive checklist to finish your Superwall
integration:
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.
---
# Users
Source: https://superwall.com/docs/dashboard/overview-users
Get a snapshot view of users who recently triggered a placement in your app.
To view information about users who've recently triggered a placement in your app, **click** on the **Users** button in the sidebar:
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 declined a paywall within the last 24 hours:
Once you've chosen a placement, **click** the **refresh icon** to view the matched users.
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:
It's divided into four main sections:
1. **Profile:** This houses basic information about the user, such as their install date, user seed and more.
2. **Device:** Details about the device the user was on when the last placement was matched. View the version of the app they were on, the bundle id, install timestamps and more.
3. **Aliases:** Any alias that Superwall has assigned the user will show here. Read more about how user aliases are created [here](/identity-management).
4. **Event Browser:** Browse all of the recent placements the user has matched against. Search and filter by them, and click on any one of them to see more details about it.
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. **Integration Events:** If you've integrated any 3rd party services, such as Revenue Cat, those events will show here.
5. **All Events:** Displays every single event that's occurred today.
Events from App Store Connect do not currently show here yet.
To learn more about any specific event, just click on it and you'll be presented with extra details:
---
# 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).
---
# 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 your 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.
**If you don't have multiple tiers of service, then you don't need to make 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 and 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), you can add the tag sw-ignore-offer to that offer.
That means that if your eligiblitiy 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.
---
# 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!
---
# Creating Stripe Products
Source: https://superwall.com/docs/dashboard/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 in Stripe to show on your web paywalls. To get started, **click** on **Products** from the overview page:
You will need to complete Stripe configuration first. If you're seeing a message to finish this
step, follow the steps outlined [here](/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 products already created in Stripe**
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 use 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 [this doc](/web-checkout-testing-products).
### 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.
---
# Configuring Stripe Keys and Settings
Source: https://superwall.com/docs/dashboard/web-checkout/web-checkout-configuring-stripe-keys-and-settings
Create your Stripe keys to connect Superwall to Stripe. Fill out some settings to configure your app.
Once you've created a [Stripe app](/web-checkout-creating-an-app), you'll need to configure it with your Stripe keys 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.
### 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
This section allows you to connect Stripe keys with Superwall. You will need:
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.
To access these, click on the **[API Keys](https://dashboard.stripe.com/apikeys)** link:
Under **Restricted Keys**, click on **+ Create restricted key**:
Choose "Providing this key to another website" and click **Continue ->**:
Use "Superwall" as the name and "superwall.com" as the URL, then click **Create restricted key**:
You'll get a modal of your restricted key, **copy this to your clipboard**, you won't be able to view it again:
From there, copy your **Publishable Key** and **copied key** from the Stripe dashboard to Superwall:
Once you've provided those two keys, **click** on **Update Configuration** to save your changes. This section should say "Configured" at the top right if setup was successful:
### Stripe Sandbox Configuration
For the sandbox configuration, you'll follow the same previous steps, **except you retrieve the keys from this link**: [Stripe Sandbox API Keys](https://dashboard.stripe.com/test/apikeys).
You should see something similar to this:
Paste the both the **Publishable Key** and **Secret Key** into Superwall for each respective field and **click** on the **Update Configuration** button. As before, 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.
---
# Creating an App
Source: https://superwall.com/docs/dashboard/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 Checkout Links
Source: https://superwall.com/docs/dashboard/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) 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
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`
---
# App2Web
Source: https://superwall.com/docs/dashboard/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 setting up your Stripe keys and configuring 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).
---
# Web Checkout FAQ
Source: https://superwall.com/docs/dashboard/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.
### 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.
---
# Restoring & Managing Purchases
Source: https://superwall.com/docs/dashboard/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
```
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).
---
# Overview
Source: https://superwall.com/docs/dashboard/web-checkout/web-checkout-overview
Let customers purchase products online via Stripe, and them 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 and Stripe products. 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 Stripe app is added to an existing iOS project in Superwall.
2. Stripe is configured with Superwall.
3. iOS app details are configured in the Stripe app's settings page (within Superwall).
4. Products are created *in* Stripe, 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 to download the app.
8. *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 Stripe account and a Superwall account. If you don't have a Stripe account, you can sign up for one [here](https://dashboard.stripe.com/register).
To opt yourself into the beta, please visit ["Public Beta
Settings"](https://superwall.com/applications/\:app/settings/experiments).
1. **[Creating a Stripe App](/web-checkout-creating-an-app):** First, you'll add a Stripe app to an existing project within Superwall.
2. **[Configuration](/web-checkout-configuring-stripe-keys-and-settings):** Next, you'll need to perform a one-time setup to connect Stripe with Superwall.
3. **[Creating Stripe products](/web-checkout-configuring-stripe-keys-and-settings):** Create your products in Stripe 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.
---
# Sandbox Purchases
Source: https://superwall.com/docs/dashboard/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.