Showing Paywalls

This allows you to register a placement to access a feature that may or may not be paywalled later in time. It also allows you to choose whether the user can access the feature even if they don’t make a purchase.

Here’s an example.

​

With Superwall

​

Without Superwall

​

How it works:

You can configure "StartWorkout" to present a paywall by creating a campaign, adding the placement, and adding a rule in the dashboard.

1. The SDK retrieves your campaign settings from the dashboard on app launch.
2. When a placement is called that belongs to a campaign, rules are evaluated on device and the user enters an experiment — this means there’s no delay between registering a placement and presenting a paywall.
3. If it’s the first time a user is entering an experiment, a paywall is decided for the user based on the percentages you set in the dashboard
4. Once a user is assigned a paywall for a rule, they will continue to see that paywall until you remove the paywall from the rule or reset assignments to the paywall.
5. After the paywall is closed, the Superwall SDK looks at the Feature Gating value associated with your paywall, configurable from the paywall editor under General > Feature Gating (more on this below)
   1. If the paywall is set to Non Gated, the feature: closure on register(event: ...) gets called when the paywall is dismissed (whether they paid or not)
   2. If the paywall is set to Gated, the feature: closure on register(event: ...) gets called only if the user is already paying or if they begin paying.
6. If no paywall is configured, the feature gets executed immediately without any additional network calls.

Given the low cost nature of how register works, we strongly recommend registering all core functionality in order to remotely configure which features you want to gate – without an app update.

​

Placement Parameters

You can send parameters along with any placement you create. For example, if you had a caffeine logging app — perhaps you’d have a placement for logging caffeine:

Superwall.shared.register(event: "caffeineLogged") {
    store.log(amountToLog)
}

Now, imagine you could log caffeine from several different touch points in your app. You may wish to know where the user tried to log caffeine from, and you could tie a parameter to the caffeineLogged placement to do this:

Superwall.shared.register(event: "caffeineLogged", params: ["via":"logging_page"]) {
  store.log(amountToLog)
}

The via parameter could now be used all throughout Superwall. You could create a new audience which has filters for each place users logged caffeine from, and unique paywalls for each of them.

Parameter placements can be used in three primary ways:

1. Audience Filtering: As mentioned above, you can filter against parameters when creating audiences. Following our example, you’d create a placement parameter named via and then choose how to filter off of the parameter’s value:

2. Templating in Text: Parameters are available in our paywall editor, so you can easily use them in text components too:

Hey {{user.firstName}}! FitnessAI offers tons of {{user.fitnessGoal}} workouts to help you reach your goals :)

3. Interfacing with Analytics: Another common scenario is cohorting with your own analytics. See this doc for more.

​

Feature Gating from the Paywall Editor

Paywall Editor > General > Settings > Feature Gating

Feature gating allows your team to retroactively decide if this paywall is Gated or Non Gated

Remember, the feature is always executed if:

1. No campaign is configured for the placement
2. The user is already paying

​

Using the Handler

You can provide a PaywallPresentationHandler to register, whose functions provide status updates for a paywall:

• onDismiss: Called when the paywall is dismissed. Accepts a PaywallInfo object containing info about the dismissed paywall.
• onPresent: Called when the paywall did present. Accepts a PaywallInfo object containing info about the presented paywall.
• onError: Called when an error occurred when trying to present a paywall. Accepts an Error indicating why the paywall could not present.
• onSkip: Called when a paywall is skipped. Accepts a PaywallSkippedReason enum indicating why the paywall was skipped.

​

Automatically Registered Placements

The SDK automatically registers some internal placements which can be used to present paywalls:

• app_install
• app_launch
• deepLink_open
• session_start
• transaction_abandon
• transaction_fail
• paywall_close

​

Register. Everything.

To provide your team with ultimate flexibility, we recommend registering all of your analytics events, even if you don’t pass feature blocks through. This way you can retroactively add a paywall almost anywhere – without an app update!

If you’re already set up with an analytics provider, you’ll typically have an Analytics.swift singleton (or similar) to disperse all your events from. Here’s how that file might look:

import SuperwallKit
import Mixpanel
import Firebase

final class Analytics {
  static var shared = Analytics()

  func track(
    event: String,
    properties: [String: Any]
  ) {
    // Superwall
    Superwall.shared.register(event: event, params: properties)

    // Firebase (just an example)
    Firebase.Analytics.logEvent(event, parameters: properties)

    // Mixpanel (just an example)
    Mixpanel.mainInstance().track(event: event, properties: properties)
  }
}


// And thus ...

Analytics.shared.track(
  event: "workout_complete",
  properties: ["total_workouts": 17]
)

// ... can now be turned into a paywall moment :)

​

Handling Network Issues

Superwall’s SDK handles network issues as gracefully as possible, but there are still some scenarios to consider. The behavior will be different based on if subscriptionStatus evaluates to .active or not.

If it is .active and Superwall has already fetched or cached its configuration, then paywall presentation proceeds as it normally would. If Superwall was unable to fetch its configuration, the SDK waits one second to give it a chance to be retrieved. After that time, if it’s not available — then a timeout event is tracked and the onSkip handler will be invoked with a reason of userIsSubscribed. The “feature” block or closure will then be invoked:

Superwall.shared.register(event: "foo") {
  // Your feature logic
}

If it’s not .active then Superwall will retry network calls until we have retrieved the necessary data for up to one minute. If it’s still unavailable, then the SDK fires the onError handler with the error type of noConfig.