Triggering Paywalls

While Paywall.track(::) enables you to trigger a paywall when certain events are fired, you may want to use completion handlers to create more bespoke experiences based on whether a user converts, or whether the trigger is enabled. Paywall.trigger(event:params:onSkip:onPresent:onDismiss) gives you this functionality.

Triggering a Paywall via the SDK

First, on the Superwall dashboard create a campaign and add a trigger. Once you've done this, triggering an event in your app is simple.

Triggers in UIKit

When you want to show a paywall, call Paywall.trigger(event:params:onSkip:onPresent:onDismiss):

Paywall.trigger(
  event: "workout_complete", 
  params: ["total_workouts": 17], 
  onSkip: { error in }, 
  onPresent: { paywallInfo in }, 
  onDismiss: { didPurchase, productId, paywallInfo in }
)

In this example, you're sending the event workout_complete to the dashboard along with some parameters. You can then utilize completion handlers to respond accordingly.

Parameter

Type

Notes

event

String

Name of the event that can be used as a trigger

params

[String: Any]

Parameters passed through along with the event that can be referenced in rules configured in the dashboard

onSkip

(NSError?) → Void

Called if there is no paywall set up to show when this event is triggered

onPresent

(PaywallInfo?) → Void

Called when the paywall is done presenting. PaywallInfo? contains things like the paywall's name, identifier and product_ids

onDismiss

(didPurchase: Bool, productId: String?, info: PaywallInfo?) → Void

Called when the paywall is dismissed (either by the user or because a purchase occurred).
If didPurchase is true, productId contains the id of the purchased product.

Triggers in SwiftUI

For SwiftUI, attach the view modifier .triggerPaywall(forEvent:withParams:shouldPresent:onPresent:onDismiss:onFail:) to a view.

The example below triggers a paywall when the user toggles the showPaywall variable by tapping on the Complete Workout button. The paywall will only show if the trigger for the workout_complete event is active in the Superwall Dashboard and the user doesn’t have an active subscription:

struct ContentView: View {
  @State private var showPaywall = false

  var body: some View {
    Button(
      action: {
        showPaywall.toggle()
      },
      label: {
        Text("Complete Workout")
      }
    )
    .triggerPaywall(
      forEvent: "workout_complete",
      withParams: ["total_workouts": 17],
      shouldPresent: $showPaywall,
      onPresent: { paywallInfo in
        print("paywall info is", paywallInfo)
      },
      onDismiss: { result in
        switch result.state {
        case .closed:
          print("User dismissed the paywall.")
        case .purchased(productId: let productId):
          print("Purchased a product with id \(productId), then dismissed.")
        case .restored:
          print("Restored purchases, then dismissed.")
        }
      },
      onFail: { error in
        print("did fail", error)
      }
    )
  }
}

In this example, you're sending the event workout_complete to the dashboard along with some parameters. You can then utilize completion handlers associated with the paywall presentation state.

Parameter

Type

Notes

forEvent

String

Name of the event that can be used as a trigger

withParams

[String: Any]

Parameters passed through along with the event that can be referenced in rules configured in the dashboard

shouldPresent

Bool

Boolean that triggers the event when true.

onPresent

(PaywallInfo?) → Void

A closure that’s called after the paywall is presented. Accepts a PaywallInfo? object containing information about the paywall. Defaults to nil.

onDismiss

(PaywallDismissalResult) -> Void

The closure to execute after the paywall is dismissed by the user, by way of purchasing, restoring or manually dismissing.
Accepts a PaywallDismissalResult object. This has a paywallInfo property containing information about the paywall and a state that tells you why the paywall was dismissed. This closure will not be called if you programmatically set isPresented to false to dismiss the paywall.
Defaults to nil.

onFail

(NSError) -> Void

A closure that’s called when the paywall fails to present, either because an error occured or because all paywalls are off in the Superwall Dashboard. You should typically fallback to your previous paywall if this happens. Accepts an NSError with more details. Defaults to nil.

📘

Attach triggerPaywall to a top-level view

Sometimes, state changes can cause your SwiftUI views to redraw and have unexpected consequences. We recommend attaching the triggerPaywall view modifier to a top-level view to prevent this.


What’s Next
Did this page help you?