Ways to Show a Paywall

Overview

Most of the time you’ll want to use presentPaywall() (or presentUpsell() depending on your SDK version) to show paywalls. This approach is covered in each platform’s quickstart guide (see navigation menu on the left). But if you need more control over how and where paywalls appear in your app, there are a few other options.

iOS

Embedded View

HeliumPaywall(
    trigger: "onboarding"
) { paywallNotShownReason in
    Text("Paywall failed to show")
}

The iOS SDK will attempt to handle dismissal for embedded views but may not be able to depending on where you place it. You can dismissal yourself with PaywallEventHandlers.

Example with PaywallEventHandlers

HeliumPaywall(
    trigger: "post_onboarding",
    eventHandlers: PaywallEventHandlers()
        .onOpen { event in
            print("open for trigger \(event.triggerName)")
        }
        .onClose { event in
            print("close for trigger \(event.triggerName)")
        }
        .onDismissed { event in
            // handle user dismissal here (i.e. navigate to another screen)
            print("dismiss for trigger \(event.triggerName)")
        }
        .onPurchaseSucceeded { event in
            print("purchase made for trigger \(event.triggerName)")
        }
        .onCustomPaywallAction { event in
            print("Custom action: \(event.actionName) with params: \(event.params)")
        }
) { paywallNotShownReason in
    Text("Paywall failed to show")
}

Keeping customPaywallTraits current when hosting in UIKit

customPaywallTraits are captured when the paywall displays and then stay fixed for that presentation. In SwiftUI this is handled for you as long as the traits come from state that re-renders the view. This is the normal way you’d pass dynamic values into a view.When you host HeliumPaywall in UIKit with a UIHostingController, UIKit won’t refresh the view for you. If you build the hosting controller ahead of time and update traits before showing it, drive the view from an ObservableObject so the latest traits reach the paywall before display:

final class PaywallTraitsStore: ObservableObject {
    @Published var traits: HeliumUserTraits?
}

struct PaywallHost: View {
    @ObservedObject var store: PaywallTraitsStore
    let trigger: String
    var body: some View {
        HeliumPaywall(
            trigger: trigger,
            config: PaywallPresentationConfig(customPaywallTraits: store.traits)
        ) { paywallNotShownReason in
            Text("Paywall failed to show")
        }
    }
}

// UIKit
let store = PaywallTraitsStore()
store.traits = initialTraits
let vc = UIHostingController(rootView: PaywallHost(store: store, trigger: "onboarding"))

// Later, before the paywall is displayed:
store.traits = freshTraits // reaches the paywall via the refreshed config

This applies before the paywall is on screen. Once displayed, traits are locked for that presentation. Updating the store afterward won’t change an already-shown paywall.

SwiftUI ViewModifier

Attach a paywall to any SwiftUI view using the .heliumPaywall view modifier:

struct ContentView: View {
    @State var isPresented: Bool = false
    var body: some View {
        VStack {
            Button {
                isPresented = true
            } label: {
                Text("Show paywall")
            }
        }.heliumPaywall(
            isPresented: $isPresented,
            trigger: "post_onboarding") { paywallNotShownReason in
                Text("Paywall failed to show")
            }
    }
}

If you are using UIKit, you can use a UIHostingController.

Android

Embedded Paywall (Compose)

Make sure to add com.tryhelium.paywall:compose-ui:4.0.0 to your dependencies.

HeliumPaywall(
    trigger = "onboarding",
    onPaywallNotShown = { reason ->
        Text("Paywall failed to show")
    }
)

Flutter

Flutter embedded widget currently only works for iOS. Android support is in the works.

Embed a paywall directly in your widget tree using HeliumFlutter.getUpsellWidget:

class ExamplePageWithEmbeddedPaywall extends StatelessWidget {
  const ExamplePageWithEmbeddedPaywall({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: HeliumPaywall(
        trigger: "insert-trigger-here",
        paywallNotShownBuilder: (context, reason) => Text("Paywall failed to show"),
      ),
    );
  }
}

You will have to handle your own dismissal. You can do so by passing in PaywallEventHandlers and using the onDismissed handler.

GETTING STARTED

SDK QUICKSTARTS

GUIDES

SDK REFERENCE

MIGRATIONS

Ways to Show a Paywall

Overview

iOS

Embedded View

SwiftUI ViewModifier

Android

Embedded Paywall (Compose)

Flutter

Widget Integration

​Overview

​iOS

​Embedded View

​SwiftUI ViewModifier

​Android

​Embedded Paywall (Compose)

​Flutter

​Widget Integration

Overview

iOS

Embedded View

SwiftUI ViewModifier

Android

Embedded Paywall (Compose)

Flutter

Widget Integration