Nuxie/Docs
Cookbook

Feature Gating

Gate premium features behind product purchases

Feature Gating

Use features and entitlements to control access to premium capabilities. Check entitlements from the SDK, show an upgrade paywall when users lack access, and handle metered usage for consumption-based features.

Prerequisites:

  • A Nuxie account with an app and at least one product configured
  • The iOS SDK installed and configured (see Quickstart)
  • A purchase delegate set up (see Purchases)

Step 1: Define a feature

Navigate to Features in your app's dashboard. Click Create Feature and configure:

  • Name -- "Premium Export"
  • External ID -- premium_export
  • Type -- Boolean

Boolean features are simple on/off access checks. The user either has the feature or does not. No additional configuration is needed.

Step 2: Add an entitlement to a product

Open your product (e.g., "Pro Monthly") and go to the Entitlements tab. Click Add Entitlement and select the premium_export feature.

For boolean features, the entitlement is straightforward: owning the product grants access. The interval is automatically set to lifetime.

Now any user who purchases the Pro Monthly product receives the premium_export entitlement.

Step 3: Check the feature in your app

Use entitled(feature:) to check access at runtime:

swift
let result = Nuxie.shared.entitled(feature: "premium_export")
if result.allowed {
    performExport()
} else {
    showUpgradePrompt()
}

The SDK evaluates entitlements using the user's cached profile, so checks are fast and work offline. No network call is required for boolean features.

Step 4: Show an upgrade paywall when not entitled

When the feature check returns allowed: false, trigger a paywall. There are two approaches:

Approach A: Trigger a campaign

Fire a named event that your campaign is configured to respond to:

swift
func showUpgradePrompt() {
    NuxieSDK.shared.trigger("feature_locked")
}

In the dashboard, create a campaign with an event trigger for feature_locked and a re-entry policy of Every time. This way, tapping the locked feature always presents the paywall.

Approach B: Show a flow directly

If you want explicit control without a campaign trigger, present the flow by ID:

swift
func showUpgradePrompt() {
    Task {
        try await NuxieSDK.shared.showFlow(with: "flow_abc123")
    }
}

Approach A is more flexible because you can change the paywall without an app update. Approach B gives you deterministic control when you need it.

Step 5: Handle the purchase and verify access

After the user purchases from the paywall, the SDK syncs the transaction with the server. The entitlement updates immediately, and the feature check returns allowed: true:

swift
// After purchase completes, re-check
let result = Nuxie.shared.entitled(feature: "premium_export")
// result.allowed is now true

For SwiftUI apps, observe the reactive feature map to update your UI automatically:

swift
struct ExportButton: View {
    @ObservedObject var features = NuxieSDK.shared.featureInfo
 
    var body: some View {
        Button("Export") {
            if features.isAllowed("premium_export") {
                performExport()
            } else {
                showUpgradePrompt()
            }
        }
    }
}

FeatureInfo is an ObservableObject that updates whenever feature access changes -- after purchases, profile refreshes, or real-time entitlement checks.

Metered features: track and limit usage

For consumption-based features like API calls or credits, use metered features instead of boolean features.

Create a metered feature

In the dashboard, click Create Feature with:

  • Name -- "API Calls"
  • External ID -- api_calls
  • Type -- Metered (single use)
  • Event name (optional) -- the event that triggers automatic usage tracking

Add a metered entitlement

On your product's Entitlements tab, add the api_calls feature with:

  • Allowance type -- Fixed
  • Allowance -- 1000
  • Reset interval -- Month
  • Carry from previous -- No

This grants 1,000 API calls per month. The balance resets at the start of each billing period.

Check balance before consuming

swift
let result = Nuxie.shared.entitled(feature: "api_calls", requiredBalance: 1)
if result.allowed {
    // Sufficient balance
    performApiCall()
} else {
    // Balance exhausted -- show upgrade prompt
    showUpgradePrompt()
}

Report usage

After consuming a unit, report it with useFeature:

swift
NuxieSDK.shared.useFeature("api_calls", amount: 1)

This decrements the local balance immediately for responsive UI feedback and sends a usage event to the server. The authoritative balance reconciles on the next profile refresh.

For operations where you need confirmation that the server accepted the usage, use the blocking variant:

swift
let result = try await NuxieSDK.shared.useFeatureAndWait("api_calls", amount: 1)
if result.success {
    // Server confirmed usage
}

Next steps