iOS: Migrating from v3 to v4

Migration guide for Helium iOS SDK v4

Breaking Changes in v4:

• presentUpsell() renamed to presentPaywall() with required onPaywallNotShown handler
• Initialize parameters moved to Helium.identify and Helium.config namespaces
• Fallback views removed - use fallback bundles only

What’s New:

• Simplified initialize() - just pass your API key
• Automatic fallback bundle detection (helium-fallbacks.json)
• Cleaner namespaced APIs: Helium.identify, Helium.config, Helium.experiments, Helium.entitlements
• New HeliumPaywall SwiftUI component for embedded paywalls
• HeliumRevenueCat is now a separate SPM package (CocoaPods unchanged)

Installation Update

Update your version constraint to ~> 4.0:

Swift Package Manager

Update the Dependency Rule in Xcode to allow 4.x versions, or remove and re-add the package with the new version constraint.

RevenueCat users: HeliumRevenueCat is now a separate SPM package. After updating to v4, you may see a build error:

Product 'HeliumRevenueCat' not found in package 'helium-swift'

To fix this:

1. In your target’s Frameworks, Libraries, and Embedded Content, remove the broken HeliumRevenueCat reference
2. Go to Package Dependencies and add the new package:
   https://github.com/cloudcaptainai/helium-swift-revenuecat.git
   
3. Add the HeliumRevenueCat product from the new package to your app’s main target

Cocoapods

Update your Podfile:

# Core only
pod 'Helium', '~> 4.0'

# Or with RevenueCat
pod 'Helium/RevenueCat', '~> 4.0'

Then run:

pod install

Initialize Migration

The biggest change in v4 is the simplified initialization. Configuration that was previously passed to initialize() is now set on dedicated namespaces beforehand.

v3 (many parameters):

// Deprecated v3 initialize
Helium.shared.initialize(
    apiKey: "...",
    heliumPaywallDelegate: RevenueCatDelegate(),
    customUserId: "user-123",
    customUserTraits: HeliumUserTraits(["plan": "free"]),
    fallbackConfig: .withFallbackBundle(bundleURL)
)

v4 (simplified):

// Set up user identification
Helium.identify.userId = "user-123"
Helium.identify.setUserTraits(HeliumUserTraits(["plan": "free"]))
// If using RevenueCat
Helium.identify.revenueCatAppUserId = Purchases.shared.appUserID 

// Set up advanced configuration (if needed)
Helium.config.customFallbacksURL = Bundle.main.url(
    forResource: "fallback-bundle-2026-01-25",
    withExtension: "json"
)
Helium.config.purchaseDelegate = RevenueCatDelegate()

// Initialize with just API key
Helium.shared.initialize(apiKey: "...")

Set identity and configuration values before calling initialize() for best results.

See the quickstart for more details.

presentUpsell to presentPaywall

The method has been renamed and now requires an onPaywallNotShown handler.

v3

Helium.shared.presentUpsell(trigger: "premium")

Helium.shared.presentPaywall(trigger: "premium") { notShownReason in
    // handle paywall not shown
}

Full Example with All Parameters

v4:

Helium.shared.presentPaywall(
    trigger: "premium",
    config: PaywallPresentationConfig(
        presentFromViewController: viewController,
        customPaywallTraits: ["source": "settings"],
        dontShowIfAlreadyEntitled: true,
        loadingBudget: nil, // use default
    ),
    eventHandlers: PaywallEventHandlers()
        .onPurchaseSucceeded { event in
            print("Purchased!")
        },
    onEntitled: {
        // User is now entitled (purchased or restored)
    }
) { paywallNotShownReason in
    switch paywallNotShownReason {
    case .targetingHoldout:
        break
    case .alreadyEntitled:
        // User already has access
        break
    default:
        // Handle rare failure cases
        break
    }
}

API Namespace Migration

Helium.identify

v3	v4
initialize(customUserId:)	Helium.identify.userId = ...
overrideUserId()	Helium.identify.userId = ...
getHeliumUserId()	Helium.identify.userId
setAppAttributionToken()	Helium.identify.appAccountToken = ...
setRevenueCatAppUserId()	Helium.identify.revenueCatAppUserId = ...

Helium.config

v3	v4
initialize(heliumPaywallDelegate:)	Helium.config.purchaseDelegate = ...
setLightDarkModeOverride()	Helium.config.lightDarkModeOverride = ...
Helium.restorePurchaseConfig	Helium.config.restorePurchasesDialog

Helium.experiments

v3	v4
getExperimentInfoForTrigger()	Helium.experiments.infoForTrigger()
enrolledExperiments()	Helium.experiments.enrolled()
allExperiments()	Helium.experiments.all()

Helium.entitlements

v3	v4
hasAnyEntitlement()	Helium.entitlements.hasAny()
hasAnyActiveSubscription()	Helium.entitlements.hasAnyActiveSubscription()
hasEntitlementForPaywall()	Helium.entitlements.hasForPaywall()
hasActiveEntitlementFor()	Helium.entitlements.hasActiveFor()
purchasedProductIds()	Helium.entitlements.purchasedProductIds()
activeSubscriptions()	Helium.entitlements.activeSubscriptions()

Fallback Changes

v4 removes fallback views and simplifies fallback configuration.

What’s Changed

• No more fallback views - Use fallback bundles exclusively
• Automatic detection - SDK auto-detects helium-fallbacks.json in your main bundle
• Optional override - Use Helium.config.customFallbacksURL if needed

Migration

v3:

let fallbackConfig = HeliumFallbackConfig(
    fallbackView: YourFallbackView(),
    fallbackBundle: Bundle.main.url(
        forResource: "fallback-bundle",
        withExtension: "json"
    )
)

Helium.shared.initialize(
    apiKey: "...",
    fallbackConfig: fallbackConfig
)

v4:

// Option 1: Automatic (recommended)
// Just add helium-fallbacks.json to your bundle - SDK finds it automatically

// Option 2: Custom location
Helium.config.customFallbacksURL = Bundle.main.url(
    forResource: "my-fallbacks",
    withExtension: "json"
)

Helium.shared.initialize(apiKey: "...")

Download your fallbacks from the Helium dashboard. See the Fallback Bundle Guide for details.

Embedded Paywall Views

The SwiftUI view for embedding paywalls has been replaced.

v3 (deprecated)

let paywallView = Helium.shared.upsellViewForTrigger("premium")

HeliumPaywall(
    trigger: "premium",
    onPaywallNotShown: { reason in
        // Handle paywall not shown
    }
)

See ways to show a paywall for more information.

Removed APIs

The following APIs have been removed in v4:

Removed API	Replacement
getHeliumExperimentInfo() (map version)	Helium.experiments.all()
HeliumFallbackConfig class	Use Helium.config.customFallbacksURL
All fallback* parameters from initialize	Add helium-fallbacks.json to bundle
upsellViewForTrigger()	HeliumPaywall component

Quick Migration Checklist

Use this checklist to ensure you’ve covered all migration steps:

• Update SDK to 4.x (~> 4.0)
• Move user ID/traits to Helium.identify.* before initialize()
• Move delegate/config to Helium.config.* before initialize()
• Replace presentUpsell() with presentPaywall() and add required handler
• Set up fallback bundle (download from dashboard, add as helium-fallbacks.json)
• Update experiment calls to Helium.experiments.*
• Update entitlement calls to Helium.entitlements.*
• Replace upsellViewForTrigger() with HeliumPaywall component
• Test paywall presentation and purchases

Need Help?

• Review the iOS SDK Quickstart
• Contact support via Slack or [e-mail]