Variables

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 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.

​

Using Variables

You primarily use variables in the component editor and with 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 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 to learn more.

​

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.

• Device
• Product
• User

​

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. Parameter variables are similar, but initial values can be passed in from your app.
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 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.

Example Usage:

{{ "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.

Example Usage:

{{ "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.

Example Usage:

{{ "2024-08-06T07:16:26.802Z" | countdown_days_total: "2024-08-16T07:16:26.802Z" }}

Output: 10

​

Snippets with variables

If you create a group of components built off of variables and conditions, save it as a snippet 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: