There are two primary ways to use referral codes or promo codes with Superwall:

  1. Using Superwall’s Mobile SDKs: By using custom actions along with a campaign for referrals, you can create a flow to handle referral codes and see their resulting conversions and other data. You create the products that each referral should unlock within the respective app storefront.
  2. Web Checkout: Here, you can use Superwall’s web checkout feature to easily offer referrals. With this approach, you could create a checkout link for each referral you need. Unlike the previous option, you create the products in Stripe.

​
Understanding Superwall’s role

Before you continue, it’s critical to understand Superwall’s role in this process. Most referral flows usually call for two things:

  1. A way to enter in a referral code and validate it.
  2. And, a resulting discounted offer that the user can redeem.

Your app must provide the referral code entry and validation. In addition, you’ll want to create discounted products in either App Store Connect, Google Play Console, or Stripe. Superwall offers products from these sources on paywalls. Remember, Superwall does not create or manage the products — it shows the ones you’ve imported from one of those places.

​
Referral flows

Given that information, here is how most referral flows can work:

Now, let’s go through each step in detail. We’ll assume that you’re triggering this flow from a paywall that’s already presented, but if that’s not the case — just skip to the step where you present your referral entry UI (step four):

1

Create a new campaign for your referrals.

Create a campaign for your referrals. Here, you’d add the discounted product(s) you’ve made to a paywall. You can add in as many placements as you need. Maybe there’s one for each influencer, or seasonal discount offer, etc. You’ll register one of these placements later on if the referral code entry was successful.

2

Referral code is tapped.

A paywall is shown. On it, this button that reads “Referral Code” has a custom tap action called “showPromoRedeem” which gets tapped:

3

SuperwallDelegate handles custom action

This app has a SuperwallDelegate:

@main
struct Caffeine_PalApp: App {
    @State private var delegate: SWDelegate = .init()
    
    init() {
        Superwall.configure(apiKey: "api_key")
        // Delegate configured here
        Superwall.shared.delegate = delegate
    }
    
    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Using the SuperwallDelegate, the app responds to the custom action. It presents a customized referral redemption interface on top of the existing paywall. This is optional, but presenting over the paywall means that the user will be taken back to it if the redemption code entry fails:

@Observable
class SWDelegate: SuperwallDelegate {
    enum CustomActions: String, Identifiable {
        case showPromoRedeem
        var id: Self { self }
    }

    func handleCustomPaywallAction(withName name: String) {
        guard let action: CustomActions = .init(rawValue: name) else {
            print("Unexpected custom action: \(name)")
            return
        }
        
        switch action {
        case .showPromoRedeem:
            let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
                // TODO: Implement placement on success
            }))
            if let paywallVC = Superwall.shared.presentedViewController {
                paywallVC.present(referralUI, animated: true)
            } else {
                // Present either using SwiftUI .sheet or other means
            }
        }
    }
}
4

Referral UI is shown.

Now that your referral interface is showing, you’d validate the code on your server or by some other means.

5

If it's successful, register a placement for referrals

Now, if the code succeeds, you’d dismiss the referral UI and the existing paywall. In our callback, we…

  1. Dismiss the existing views.
  2. And, we register a placement that corresponds to a campaign you’ve setup for referral codes:
// This...
let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
    // TODO: Implement placement on success
}))

// Might look similar to this...
let referralUI = UIHostingController(rootView: ReferralRedeemView(callback: {
    // Dismiss the referral UI
    referralUI.dismiss(animated: true)
    // Dismiss the existing paywall
    Superwall.shared.presentedViewController?.dismiss(animated: true)
    
    // This shows the paywall with the discounted product.
    // It should be gated, which means the closure only fires if they convert.
    Superwall.shared.register(placement: "referral",
                            params: ["influencer":"Jordan"]) {
        MyAnalyticsService.shared.log("referral_code_redeemed",
                                    properties: ["referral_code": "Jordan", "result": "trial_started"])
    }
}))
6

The discounted product is presented.

Finally, your paywall and discounted product that you setup in step #1 is shown. If they convert, you’ll see all of the details in your campaign that you built for referrals, just like you would any other campaign. You can also forward events to your third party analytics service as well, as shown in the previous step.

And that’s it! It’s a matter of creating discounted products, using them in a campaign, showing a referral UI and validating it, and then registering a placement to show those paywalls within a campaign.