Using ContextSDK with Superwall

Learn how to use ContextSDK with Superwall to optimize paywall timing and log conversion revenue from in-app purchases.

ContextSDK integrates seamlessly with Superwall to help you show paywalls at the perfect moment. This integration leverages ContextSDK's ML-powered recommendations to optimize when Superwall displays paywalls, improving conversion rates.

How it works

ContextSDK provides real-world context about whether it's a good moment to show a paywall through the shouldUpsell property - a boolean indicating whether it's a good moment to show a paywall.

This value is passed to Superwall as a parameter (contextGoodMoment), allowing you to:

• Use it in paywall display rules

• Track it in your analytics

• A/B test different timing strategies

Integration Guide

Step 1: Capture Context and Show Paywall

Before showing a paywall, capture the user's context using instantContext and pass it to Superwall:

import ContextSDK
import SuperwallKit

class OnboardingViewController: UIViewController {

    func showPaywall() {
        // 1. Capture the user's context
        let context = ContextManager.instantContext(flowName: "superwall_onboarding_step", duration: 3)

        // 2. Create handler for paywall callbacks
        let handler = PaywallPresentationHandler()
        handler.onDismiss { paywallInfo, result in
            switch result {
            case .purchased(let product):
                // User completed a purchase
                context.logRevenueOutcome(from: product)

            case .declined:
                // User declined the paywall by pressing close button
                context.log(.negative)

            case .restored:
                // User restored their purchases
                context.log(.skipped)

            default:
                context.log(.skipped)
            }
        }
        handler.onSkip { reason in
            // Paywall was skipped (no paywall configured, user already subscribed, etc.)
            context.log(.skipped)
        }

        // 3. Register Superwall placement with context
        Superwall.shared.register(
            placement: "onboarding_step",
            params: ["contextGoodMoment": context.shouldUpsell],
            handler: handler
        )
    }
}

Step 2: Use Context in Superwall Rules

You can use the context parameter in Superwall's display rules to control when paywalls appear:

In Superwall Dashboard:

1. Go to your paywall configuration

2. Add display rules using the parameter:

   • contextGoodMoment (Boolean)

Example rule:

• Show paywall only when contextGoodMoment is true

This gives you the flexibility to A/B test different strategies and adjust timing logic without code changes.

Best Practices

Choose a Flow Name

Select a descriptive flow name that represents your use case. Use a consistent naming pattern with the superwall_ prefix:

// Examples of good flow names:
ContextManager.instantContext(flowName: "superwall_onboarding_step", duration: 3)
ContextManager.instantContext(flowName: "superwall_premium_upgrade", duration: 3)
ContextManager.instantContext(flowName: "superwall_feature_unlock", duration: 3)

Always Log Outcomes

Critical: Always log an outcome for every context you create. This data trains the ML model:

let handler = PaywallPresentationHandler()

// Log outcomes in onDismiss
handler.onDismiss { paywallInfo, result in
    switch result {
    case .purchased(let product):
        context.logRevenueOutcome(from: product)
    case .declined:
        context.log(.negative)
    case .restored:
        context.log(.skipped)
    default:
        context.log(.skipped)
    }
}

// Always log skipped when paywall doesn't show
handler.onSkip { reason in
    context.log(.skipped)
}

Handle Multiple Placements

You can use this pattern across multiple placements in your app:

func showOnboardingPaywall() {
    let context = ContextManager.instantContext(flowName: "superwall_onboarding", duration: 3)
    showSuperwall(placement: "onboarding_step", context: context)
}

func showSettingsPaywall() {
    let context = ContextManager.instantContext(flowName: "superwall_settings", duration: 3)
    showSuperwall(placement: "settings", context: context)
}

private func showSuperwall(placement: String, context: Context) {
    let handler = PaywallPresentationHandler()
    handler.onDismiss { paywallInfo, result in
        switch result {
        case .purchased(let product):
            context.logRevenueOutcome(from: product)
        case .declined:
            context.log(.negative)
        case .restored:
            context.log(.skipped)
        default:
            context.log(.skipped)
        }
    }
    handler.onSkip { reason in
        context.log(.skipped)
    }

    Superwall.shared.register(
        placement: placement,
        params: ["contextGoodMoment": context.shouldUpsell],
        handler: handler
    )
}

Related Documentation

• Revenue Outcomes - Learn more about logging revenue outcomes

• Logging Conversions - General guide to logging outcomes

• Custom Outcome Metadata - Track additional purchase context

ContextSDK's ML models learn from your outcome data. The more purchases you log with logRevenueOutcome(), the better the model becomes at predicting optimal moments to show paywalls.