Superwall Flutter SDK

https://superwall.com/docs/flutter
Admin
The Superwall Flutter SDK provides tools to integrate Superwall's in-app paywall and subscription...
Tokens:63,452
Snippets:783
Trust Score:9.5
Update:3 months ago
Show doc for...
Tokens:
Raw
### Redirect Mode URL Example

Source: https://superwall.com/docs/flutter/guides/web-checkout/post-checkout-redirecting

Example of the URL structure with query parameters received when using Redirect Mode.

```text
https://yourapp.com/success?
  app_user_id=user_123&
  email=user@example.com&
  stripe_subscription_id=sub_1234567890&
  campaign_id=summer_sale
```

--------------------------------

### Install via command line

Source: https://superwall.com/docs/flutter/quickstart/install

Use the Flutter CLI to add the dependency.

```bash
$ flutter pub add superwallkit_flutter
```

--------------------------------

### Syncing with Multiple Providers

Source: https://superwall.com/docs/flutter/sdk-reference/setIntegrationAttribute

Example of updating multiple integration attributes sequentially.

```dart
// Mixpanel
await Superwall.shared.setIntegrationAttribute(
  IntegrationAttribute.mixpanelDistinctId,
  mixpanelUserId,
);

// Amplitude
await Superwall.shared.setIntegrationAttribute(
  IntegrationAttribute.amplitudeUserId,
  amplitudeUserId,
);

// Adjust
await Superwall.shared.setIntegrationAttribute(
  IntegrationAttribute.adjustId,
  adjustId,
);
```

--------------------------------

### Basic Paywall Handler Setup

Source: https://superwall.com/docs/flutter/sdk-reference/PaywallPresentationHandler

Configure presentation and dismissal handlers to track paywall state and handle purchase results.

```dart
Future<void> _registerFeatureWithHandler() async {
  final handler = PaywallPresentationHandler();

  handler.onPresent((paywallInfo) {
    print('Paywall presented: ${paywallInfo.identifier}');
    print('Paywall state: ${paywallInfo.state}');
  });

  handler.onDismiss((paywallInfo, result) {
    print('Paywall dismissed with result: $result');

    switch (result) {
      case PaywallResult.purchased:
        _showSuccessMessage();
        break;
      case PaywallResult.cancelled:
        _showPromotionalOffer();
        break;
      case PaywallResult.restored:
        _updateUIForActiveSubscription();
        break;
    }
  });

  await Superwall.shared.registerPlacement(
    'premium_feature',
    params: {'source': 'feature_screen'},
    handler: handler,
    feature: () {
      _unlockPremiumFeature();
    },
  );
}
```

--------------------------------

### Implementing SuperwallDelegate

Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallDelegate

Example of extending the SuperwallDelegate class to handle specific SDK events and custom actions.

```dart
class MySuperwallDelegate extends SuperwallDelegate {
  @override
  void subscriptionStatusDidChange(SubscriptionStatus newValue) {
    print('Subscription status changed to: $newValue');
    // Update user interface, send analytics, etc.
  }
  
  @override
  void handleSuperwallEvent(SuperwallEventInfo eventInfo) {
    print('Superwall event: ${eventInfo.event}');
    // Send to your analytics platform
    Analytics.track(eventInfo.event.rawName, eventInfo.params);
  }
  
  @override
  void willPresentPaywall(PaywallInfo paywallInfo) {
    print('About to present paywall: ${paywallInfo.identifier}');
    // Pause video, hide overlays, etc.
  }
  
  @override
  void didDismissPaywall(PaywallInfo paywallInfo) {
    print('Paywall dismissed: ${paywallInfo.identifier}');
    // Resume video, show overlays, etc.
  }
  
  @override
  void handleCustomPaywallAction(String name) {
    print('Custom action triggered: $name');
    
    switch (name) {
      case 'contact_support':
        _openSupportChat();
        break;
      case 'share_app':
        _shareApp();
        break;
    }
  }
  
  @override
  void handleSuperwallDeepLink(Uri fullURL, List<String> pathComponents, Map<String, String> queryParameters) {
    print('Superwall deep link: $fullURL');
    print('Path: $pathComponents');
    print('Query: $queryParameters');
    // Handle deep link navigation
  }
  
  @override
  void customerInfoDidChange(CustomerInfo from, CustomerInfo to) {
    print('Customer info changed');
    // Sync with your backend, update UI, etc.
  }

  @override
  void userAttributesDidChange(Map<String, Object> newAttributes) {
    print('User attributes updated: $newAttributes');
    // Sync with analytics or update in-memory state.
  }
}
```

--------------------------------

### Setting an Integration Attribute

Source: https://superwall.com/docs/flutter/sdk-reference/setIntegrationAttribute

Example of setting a specific integration attribute for a user.

```dart
await Superwall.shared.setIntegrationAttribute(
  IntegrationAttribute.mixpanelDistinctId,
  'user_123',
);
```

--------------------------------

### Configure PaywallOptions in Flutter

Source: https://superwall.com/docs/flutter/sdk-reference/PaywallOptions

Initialize PaywallOptions and pass them into the Superwall configuration during SDK setup.

```dart
final paywallOptions = PaywallOptions()
  ..isHapticFeedbackEnabled = true
  ..shouldShowPurchaseFailureAlert = false
  ..shouldPreload = true
  ..automaticallyDismiss = true
  ..transactionBackgroundView = TransactionBackgroundView.spinner
  ..overrideProductsByName = {
    'primary': 'com.example.premium_monthly',
    'tertiary': 'com.example.premium_annual',
  }
  ..shouldShowWebRestorationAlert = true
  ..shouldShowWebPurchaseConfirmationAlert = true
  ..onBackPressed = (paywallInfo) {
    // Android-only callback
    Superwall.shared.dismiss();
  };

final options = SuperwallOptions(
  paywalls: paywallOptions,
);

await Superwall.configure(
  'pk_your_api_key',
  options: options,
);
```

--------------------------------

### app_install Event

Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/tracking-analytics

The app_install event is triggered when the Superwall SDK is configured for the first time. It provides metadata regarding the installation session.

```APIDOC
## Event: app_install

### Description
Triggered when the SDK is configured for the first time.

### Properties
- **is_superwall** (boolean) - Indicates if the event is tracked by Superwall.
- **app_session_id** (string) - The unique identifier for the current application session.
- **using_purchase_controller** (boolean) - Indicates whether a custom purchase controller is being used.
```

--------------------------------

### Add Superwall Skill

Source: https://superwall.com/docs/flutter/guides/vibe-coding

Installs the Superwall Skill to provide AI agents with documentation, API access, and integration guidance.

```bash
npx skills add superwall/skills
```

--------------------------------

### Setting User Attributes After Signup

Source: https://superwall.com/docs/flutter/sdk-reference/setUserAttributes

Example of mapping user object properties to Superwall attributes upon registration.

```dart
Future<void> _setUserProfile(User user) async {
  await Superwall.shared.setUserAttributes({
    'email': user.email,
    'name': user.name,
    'signupDate': user.createdAt.toIso8601String(),
    'referralSource': user.referralSource ?? 'direct',
    'trialEndDate': user.trialEndDate?.toIso8601String(),
    'isFirstTimeUser': user.isFirstTimeUser,
  });
}
```

--------------------------------

### Identify After Login

Source: https://superwall.com/docs/flutter/sdk-reference/identify

Example of identifying a user and setting attributes immediately after a successful login flow.

```dart
Future<void> _onUserLogin(String email, String password) async {
  // Authenticate user
  final user = await AuthService.login(email, password);
  
  // Identify user to Superwall
  await Superwall.shared.identify(user.id);
  
  // Set additional user attributes
  await Superwall.setUserAttributes({
    'email': user.email,
    'plan': user.subscriptionPlan,
    'signupDate': user.createdAt.toIso8601String(),
  });
}
```

--------------------------------

### Handling Presentation Results

Source: https://superwall.com/docs/flutter/sdk-reference/PresentationResult

Examples of how to handle different presentation outcomes using type checking or pattern matching.

```dart
final result = await Superwall.shared.getPresentationResult('premium_feature');

if (result is PaywallPresentationResult) {
  // Paywall would be shown
  final experimentId = result.experiment.id;
  final groupId = result.experiment.groupId;
  print('Experiment: $experimentId, Group: $groupId');
} else if (result is HoldoutPresentationResult) {
  // User is in holdout
  print('User in holdout for experiment ${result.experiment.id}');
} else if (result is NoAudienceMatchPresentationResult) {
  // No audience match
  print('No audience match for placement');
} else if (result is PlacementNotFoundPresentationResult) {
  // Placement not found
  print('Placement not found');
} else if (result is PaywallNotAvailablePresentationResult) {
  // Paywall not available
  print('Paywall not available');
}
```

```dart
final result = await Superwall.shared.getPresentationResult('premium_feature');

switch (result) {
  case PaywallPresentationResult(experiment: final exp):
    // Handle paywall presentation
    print('Paywall for experiment ${exp.id}');
  case HoldoutPresentationResult(experiment: final exp):
    // Handle holdout
    print('Holdout for experiment ${exp.id}');
  case NoAudienceMatchPresentationResult():
    // Handle no match
    print('No audience match');
  case PlacementNotFoundPresentationResult():
    // Handle not found
    print('Placement not found');
  case PaywallNotAvailablePresentationResult():
    // Handle not available
    print('Paywall not available');
}
```

--------------------------------

### Configure with Options

Source: https://superwall.com/docs/flutter/sdk-reference/configure

Initialize the SDK with custom paywall and logging settings.

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final options = SuperwallOptions(
    paywalls: PaywallOptions(
      shouldPreload: true,
      automaticallyDismiss: false,
    ),
    logging: Logging(
      level: LogLevel.debug,
    ),
  );
  
  Superwall.configure(
    'pk_your_api_key_here',
    options: options,
  );
  
  runApp(MyApp());
}
```

--------------------------------

### Updating Subscription Attributes

Source: https://superwall.com/docs/flutter/sdk-reference/setUserAttributes

Example of updating subscription-related attributes for a user.

```dart
Future<void> _updateSubscriptionAttributes(Subscription subscription) async {
  await Superwall.shared.setUserAttributes({
    'subscriptionTier': subscription.tier,
    'subscriptionStartDate': subscription.startDate.toIso8601String(),
    'subscriptionStatus': subscription.status,
    'monthlySpend': subscription.monthlyAmount,
  });
}
```

--------------------------------

### Basic SDK Configuration

Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallOptions

Initialize the SDK with basic paywall and logging options.

```dart
final options = SuperwallOptions()
  ..paywalls = PaywallOptions()
  ..logging = (Logging()..level = LogLevel.debug);

await Superwall.configure(
  'pk_your_api_key',
  options: options,
);
```

--------------------------------

### Get Entitlements Signature

Source: https://superwall.com/docs/flutter/sdk-reference/getEntitlements

The method signature for retrieving user entitlements.

```dart
Future<Entitlements> getEntitlements()
```

--------------------------------

### configure(apiKey, purchaseController, options, completion)

Source: https://superwall.com/docs/flutter/sdk-reference/configure

Initializes the Superwall SDK. This method should be called once during app initialization.

```APIDOC
## configure(apiKey, purchaseController, options, completion)

### Description
Configures the Superwall SDK with your API key and optional configuration settings. This method is typically called once in your app's initialization.

### Signature
- **apiKey** (String) - Required - Your Superwall API key from the dashboard.
- **purchaseController** (PurchaseController?) - Optional - Optional custom purchase controller. Defaults to null.
- **options** (SuperwallOptions?) - Optional - Optional configuration options. Defaults to null.
- **completion** (Function?) - Optional - Optional callback called when configuration completes.

### Returns
Returns a `Superwall` instance that is immediately configured and ready to use.
```

--------------------------------

### Basic SDK Configuration

Source: https://superwall.com/docs/flutter/sdk-reference/configure

Initialize the SDK with a required API key during app startup.

```dart
import 'package:superwallkit_flutter/superwallkit_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  Superwall.configure('pk_your_api_key_here');
  
  runApp(MyApp());
}
```

--------------------------------

### Basic User Identification

Source: https://superwall.com/docs/flutter/sdk-reference/identify

A simple example of identifying a user with a unique ID.

```dart
await Superwall.shared.identify('user_123');
```

--------------------------------

### Get current overrides

Source: https://superwall.com/docs/flutter/sdk-reference/overrideProductsByName

Retrieve the currently active product override mapping.

```dart
final overrides = await Superwall.shared.getOverrideProductsByName();
if (overrides != null) {
  print('Current overrides: $overrides');
} else {
  print('No overrides set');
}
```

--------------------------------

### restoreStart

Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/tracking-analytics

The restoreStart event is triggered when a user initiates a restore process within the application.

```APIDOC
## restoreStart

### Description
This event is triggered when a restore process is initiated by the user.

### Parameters
- None
```

--------------------------------

### Configure with Completion Callback

Source: https://superwall.com/docs/flutter/sdk-reference/configure

Execute logic once the SDK configuration process has finished.

```dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  Superwall.configure(
    'pk_your_api_key_here',
    completion: () {
      print('Superwall configuration completed');
    },
  );
  
  runApp(MyApp());
}
```

--------------------------------

### Sync Analytics IDs

Source: https://superwall.com/docs/flutter/sdk-reference/IntegrationAttribute

Example of retrieving identifiers from third-party SDKs and syncing them with Superwall.

```dart
void _syncAnalyticsIds() async {
  // Get IDs from your analytics SDKs
  final mixpanelId = await MixpanelSDK.getDistinctId();
  final amplitudeId = await AmplitudeSDK.getUserId();
  
  // Sync with Superwall
  await Superwall.shared.setIntegrationAttributes({
    IntegrationAttribute.mixpanelDistinctId: mixpanelId,
    IntegrationAttribute.amplitudeUserId: amplitudeId,
  });
}
```

--------------------------------

### paywallProductsLoad_start

Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/tracking-analytics

This event is triggered when the request to load a paywall's products begins.

```APIDOC
## Event: paywallProductsLoad_start

### Description
Triggered when the SDK initiates the request to load products for a paywall.

### Notes
This event shares the same context and behavior as the `paywallResponseLoad_start` event.
```

--------------------------------

### Initialize Superwall in Flutter

Source: https://superwall.com/docs/flutter/quickstart/configure

Configure the SDK within the main entrypoint of your application. Ensure the correct API key is provided for the target platform.

```dart
// main.dart

void initState() {
  // Determine Superwall API Key for platform
  String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";

  Superwall.configure(apiKey);
}
```

--------------------------------

### Configure Android build.gradle

Source: https://superwall.com/docs/flutter/quickstart/install

Set the compile and minimum SDK versions.

```groovy
android {
    ...
    compileSdkVersion 34
    ...
    defaultConfig {
        ...
        minSdkVersion 26
        ...
    }
}
```

--------------------------------

### Configure Superwall with RCPurchaseController

Source: https://superwall.com/docs/flutter/guides/using-revenuecat

Initializes the purchase controller and configures the Superwall SDK.

```dart
RCPurchaseController purchaseController = RCPurchaseController();

Superwall.configure(
  apiKey,
  purchaseController: purchaseController
);

await purchaseController.configureAndSyncSubscriptionStatus();
```

--------------------------------

### Handle Purchased Products via SuperwallDelegate

Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products

Implement the SuperwallDelegate to listen for transaction completion events and extract product information from placement parameters.

```typescript
import {
  PaywallInfo,
  SubscriptionStatus,
  SuperwallDelegate,
  SuperwallPlacementInfo,
  PlacementType,
} from '../../src';

export class MySuperwallDelegate extends SuperwallDelegate {
  handleSuperwallPlacement(placementInfo: SuperwallPlacementInfo) {
    console.log('Handling Superwall placement:', placementInfo);

    switch (placementInfo.placement.type) {
      case PlacementType.transactionComplete:
        const product = placementInfo.params?.["product"];
        if (product) {
          console.log(`Product: ${product}`);
        } else {
          console.log("Product not found in params.");
        }
        break;
      default:
        break;
    }
  }
}

export default function App() {
  const delegate = new MySuperwallDelegate();

  React.useEffect(() => {
    const setupSuperwall = async () => {
      const apiKey =
        Platform.OS === 'ios'
          ? 'ios_api_project_key'
          : 'android_api_project_key';

      Superwall.configure({
        apiKey: apiKey,
      });

      Superwall.shared.setDelegate(delegate);
    };
  }
}
```

--------------------------------

### Identify with Error Handling

Source: https://superwall.com/docs/flutter/sdk-reference/identify

Example of wrapping the identify call in a try-catch block to handle potential identification failures.

```dart
Future<void> _identifyUser(String userId) async {
  try {
    await Superwall.shared.identify(userId);
    print('User identified successfully');
  } catch (e) {
    print('Failed to identify user: $e');
  }
}
```

--------------------------------

### Stream<SubscriptionStatus> get subscriptionStatus

Source: https://superwall.com/docs/flutter/sdk-reference/subscriptionStatus

A reactive stream that emits SubscriptionStatus values whenever the user's subscription status changes.

```APIDOC
## Stream<SubscriptionStatus> get subscriptionStatus

### Description
A Stream that emits the user's current subscription status whenever it changes. Use this to reactively update your UI based on the user's subscription state.

### Signature
`Stream<SubscriptionStatus> get subscriptionStatus`

### Returns
Returns a `Stream<SubscriptionStatus>` that emits values whenever the subscription status changes.

### Usage Example
```dart
_subscription = Superwall.shared.subscriptionStatus.listen((status) {
  setState(() {
    _currentStatus = status;
  });
});
```
```

--------------------------------

### shimmerViewStart

Source: https://superwall.com/docs/flutter/guides/3rd-party-analytics/tracking-analytics

An event triggered when the shimmer view begins displaying.

```APIDOC
## shimmerViewStart

### Description
This event is triggered when the shimmer view starts showing in the Superwall interface.

### Parameters
- None
```

--------------------------------

### PaywallOptions Configuration

Source: https://superwall.com/docs/flutter/sdk-reference/PaywallOptions

Configuring paywall behavior by instantiating PaywallOptions and passing it to the Superwall configuration.

```APIDOC
## PaywallOptions

### Description
Defines the configuration options for paywalls within the Superwall SDK. These options are passed during the initialization of the Superwall instance.

### Properties
- **isHapticFeedbackEnabled** (bool) - Whether haptic feedback is enabled for paywall interactions.
- **shouldShowPurchaseFailureAlert** (bool) - Whether to show an alert when a purchase fails.
- **shouldPreload** (bool) - Whether to preload paywall content.
- **automaticallyDismiss** (bool) - Whether the paywall should dismiss automatically after a successful purchase.
- **transactionBackgroundView** (TransactionBackgroundView) - The view to display during a transaction (e.g., spinner).
- **overrideProductsByName** (Map<String, String>) - A map to override product identifiers by their assigned names.
- **shouldShowWebRestorationAlert** (bool) - Whether to show an alert for web restoration.
- **shouldShowWebPurchaseConfirmationAlert** (bool) - Whether to show an alert for web purchase confirmation.
- **onBackPressed** (Function(PaywallInfo)) - Callback triggered when the back button is pressed (Android-only).

### Usage Example
```dart
final paywallOptions = PaywallOptions()
  ..isHapticFeedbackEnabled = true
  ..shouldShowPurchaseFailureAlert = false
  ..shouldPreload = true
  ..automaticallyDismiss = true
  ..transactionBackgroundView = TransactionBackgroundView.spinner
  ..overrideProductsByName = {
    'primary': 'com.example.premium_monthly',
    'tertiary': 'com.example.premium_annual',
  }
  ..shouldShowWebRestorationAlert = true
  ..shouldShowWebPurchaseConfirmationAlert = true
  ..onBackPressed = (paywallInfo) {
    Superwall.shared.dismiss();
  };

final options = SuperwallOptions(
  paywalls: paywallOptions,
);

await Superwall.configure(
  'pk_your_api_key',
  options: options,
);
```
```

--------------------------------

### Implement PurchaseController in Android

Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products

Define a custom PurchaseController to handle purchase logic and configure it during application startup.

```kotlin
class MyPurchaseController(val context: Context): PurchaseController {
    override suspend fun purchase(
        activity: Activity,
        productDetails: ProductDetails,
        basePlanId: String?,
        offerId: String?
    ): PurchaseResult {
        println("Kicking off purchase of $basePlanId")
        return PurchaseResult.Purchased()
    }

    override suspend fun restorePurchases(): RestorationResult {
        TODO("Not yet implemented")
    }
}

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Superwall.configure(this, "my_api_key", purchaseController = MyPurchaseController(this))
    }
}
```

--------------------------------

### Hardcoded Deep Link Routing in Flutter

Source: https://superwall.com/docs/flutter/guides/handling-deep-links

An example of the manual, hardcoded approach to deep link routing that requires app updates for every change.

```dart
void handleUrl(Uri url) {
  final placement = switch (url.path) {
    '/promo' => 'promoPlacement',
    '/onboarding' => 'onboardingPlacement',
    '/upgrade' => 'upgradePlacement',
    '/special-offer' => 'specialOfferPlacement',
    _ => null,
  };

  if (placement != null) {
    Superwall.shared.register(placement: placement);
  }
}
```

--------------------------------

### Basic Usage of setUserAttributes

Source: https://superwall.com/docs/flutter/sdk-reference/setUserAttributes

Demonstrates setting simple key-value pairs for user attributes.

```dart
await Superwall.shared.setUserAttributes({
  'plan': 'premium',
  'age': 25,
  'hasCompletedOnboarding': true,
});
```

--------------------------------

### Handle Purchase Events in Objective-C

Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products

Implements the SWKSuperwallDelegate protocol and configures the Superwall instance within the AppDelegate.

```objective-c
// SWDelegate.h...
#import <Foundation/Foundation.h>
@import SuperwallKit;

NS_ASSUME_NONNULL_BEGIN

@interface SWDelegate : NSObject <SWKSuperwallDelegate>

@end

NS_ASSUME_NONNULL_END

// SWDelegate.m...
@implementation SWDelegate

- (void)handleSuperwallEventWithInfo:(SWKSuperwallEventInfo *)eventInfo {
  switch(eventInfo.event) {
    case SWKSuperwallEventTransactionComplete:
      NSLog(@"Transaction complete: %@", eventInfo.params[@"primary_product_id"]);
  }
}

// In AppDelegate.m...
#import "AppDelegate.h"
#import "SWDelegate.h"
@import SuperwallKit;

@interface AppDelegate ()

@property (strong, nonatomic) SWDelegate *delegate;

@end

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    self.delegate = [SWDelegate new];
    [Superwall configureWithApiKey:@"my_api_key"];
    [Superwall sharedInstance].delegate = self.delegate;

    return YES;
}
```

--------------------------------

### Implement PurchaseController logic

Source: https://superwall.com/docs/flutter/guides/using-revenuecat

Handles product category identification and initiates the appropriate purchase flow for subscriptions or non-subscription products.

```dart
// If no product is found (either matching or the first one), return a failed purchase result.
    if (storeProduct == null) {
      return PurchaseResult.failed("Product not found");
    }

    switch (storeProduct.productCategory) {
      case ProductCategory.subscription:
        SubscriptionOption? subscriptionOption =
            await _fetchGooglePlaySubscriptionOption(
                storeProduct, basePlanId, offerId);
        if (subscriptionOption == null) {
          return PurchaseResult.failed(
              "Valid subscription option not found for product.");
        }
        return await _purchaseSubscriptionOption(subscriptionOption);
      case ProductCategory.nonSubscription:
        return await _purchaseStoreProduct(storeProduct);
      case null:
        return PurchaseResult.failed("Unable to determine product category");
    }
  }
```

--------------------------------

### Superwall.shared

Source: https://superwall.com/docs/flutter/sdk-reference/Superwall

The shared Superwall instance provides access to all SDK methods. It must be initialized via configure() before use.

```APIDOC
## Superwall.shared

### Description
Provides access to the configured Superwall instance. Must be called after `configure()`.

### Signature
`static Superwall get shared`

### Usage
```dart
// Accessing the shared instance
await Superwall.shared.registerPlacement('premium_feature');
await Superwall.shared.identify('user_123');

// Resetting the user
await Superwall.shared.reset();

// Listening to subscription status
Superwall.shared.subscriptionStatus.listen((status) {
  // Handle status change
});
```
```

--------------------------------

### Configure Method Signatures

Source: https://superwall.com/docs/flutter/sdk-reference/configure

The method signatures for initializing the SDK across different platforms.

```dart
static Superwall configure(
  String apiKey, {
  PurchaseController? purchaseController,
  SuperwallOptions? options,
  Function? completion,
})
```

```swift
static func configure(
  apiKey: String,
  purchaseController: PurchaseController? = nil,
  options: SuperwallOptions? = nil,
  completion: ((Result<Void, Error>) -> Void)? = nil
)
```

```kotlin
fun configure(
  application: Application,
  apiKey: String,
  purchaseController: PurchaseController? = null,
  options: SuperwallOptions? = null,
  completion: ((Result<Unit>) -> Unit)? = null
)
```

--------------------------------

### Configure experimental flags in Swift

Source: https://superwall.com/docs/flutter/guides/experimental-flags

Enable experimental features by setting properties on the SuperwallOptions struct before calling configure.

```swift
let options = SuperwallOptions()
options.enableExperimentalDeviceVariables = true
Superwall.configure(apiKey: "my_api_key",
                    options: options)
```

--------------------------------

### Production Configuration

Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallOptions

Configure the SDK for a production environment with release network settings and data collection enabled.

```dart
final productionOptions = SuperwallOptions()
  ..paywalls = (PaywallOptions()
    ..shouldPreload = true
    ..automaticallyDismiss = true)
  ..networkEnvironment = NetworkEnvironment.release
  ..isExternalDataCollectionEnabled = true
  ..logging = (Logging()..level = LogLevel.warn);
```

--------------------------------

### Implement SuperwallDelegate with async/await

Source: https://superwall.com/docs/flutter/guides/web-checkout/using-revenuecat

Handles redemption results by spawning an asynchronous task to link Stripe subscriptions to RevenueCat.

```dart
class MySuperwallDelegate extends SuperwallDelegate {
  @override
  void willRedeemLink() {
    print('[!] willRedeemLink');
    // Show loading indicator
  }

  @override
  void didRedeemLink(RedemptionResult result) {
    // Don't use async here directly, spawn a separate task
    _handleRedemption(result);
  }
  
  Future<void> _handleRedemption(RedemptionResult result) async {
    if (result is! RedemptionResultSuccess) {
      print('[!] Redemption did not succeed');
      return;
    }

    final storeIdentifiers = result.redemptionInfo.purchaserInfo.storeIdentifiers;
    if (storeIdentifiers is! StripeStoreIdentifiers) {
      print('[!] Redemption did not come from Stripe');
      return;
    }

    final stripeSubscriptionIds = storeIdentifiers.subscriptionIds;
    if (stripeSubscriptionIds.isEmpty) {
      print('[!] No Stripe subscription IDs found');
      return;
    }

    const revenueCatStripePublicAPIKey = 'strp.....';
    final appUserId = await Purchases.appUserID;

    // Link each subscription to RevenueCat
    await Future.wait(
      stripeSubscriptionIds.map((stripeSubscriptionId) async {
        try {
          await _linkSubscriptionToRevenueCat(
            stripeSubscriptionId,
            appUserId,
            revenueCatStripePublicAPIKey,
          );
        } catch (e) {
          print('[!] Failed to link $stripeSubscriptionId: $e');
        }
      }),
    );

    // Refresh customer info
    try {
      await Purchases.getCustomerInfo();
      print('[!] Successfully refreshed customer info');
    } catch (e) {
      print('[!] Failed to refresh customer info: $e');
    }
  }
  
  Future<void> _linkSubscriptionToRevenueCat(
    String stripeSubscriptionId,
    String appUserId,
    String apiKey,
  ) async {
    final url = Uri.parse('https://api.revenuecat.com/v1/receipts');
    final response = await http.post(
      url,
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
        'X-Platform': 'stripe',
        'Authorization': 'Bearer $apiKey',
      },
      body: jsonEncode({
        'app_user_id': appUserId,
        'fetch_token': stripeSubscriptionId,
      }),
    );

    if (response.statusCode != 200) {
      throw Exception(
        'RevenueCat responded with ${response.statusCode}: ${response.body}',
      );
    }

    print('[!] Successfully linked $stripeSubscriptionId to $appUserId');
  }
}
```

--------------------------------

### SuperwallOptions

Source: https://superwall.com/docs/flutter/sdk-reference/SuperwallOptions

The SuperwallOptions class provides a set of configuration properties to tailor the SDK's functionality to your application's needs.

```APIDOC
## SuperwallOptions

### Description
Configuration object used to initialize and customize the Superwall SDK behavior.

### Properties
- **paywalls** (PaywallOptions) - Required - Configuration for paywall presentation behavior.
- **networkEnvironment** (NetworkEnvironment) - Required - Network environment for API calls (release/releaseCandidate/developer).
- **isExternalDataCollectionEnabled** (bool) - Optional - Enables external analytics collection. Default: true.
- **localeIdentifier** (String?) - Optional - Override locale for paywall localization. Default: device locale.
- **isGameControllerEnabled** (bool) - Optional - Enables game controller support. Default: false.
- **logging** (Logging) - Required - Configuration for SDK logging levels and behavior.
- **passIdentifiersToPlayStore** (bool) - Optional - When true, Android builds send the plain appUserId to Google Play. Default: false.
- **testModeBehavior** (TestModeBehavior) - Optional - Controls when the SDK enters test mode. Default: TestModeBehavior.automatic.
- **shouldObservePurchases** (bool) - Optional - When true, Superwall observes transactions made outside of Superwall. Default: false.
- **shouldBypassAppTransactionCheck** (bool) - Optional - Disables the app transaction check on SDK launch. iOS only. Default: false.
- **maxConfigRetryCount** (int) - Optional - Number of times the SDK will attempt to get the Superwall configuration after a network failure. iOS only. Default: 6.
- **useMockReviews** (bool) - Optional - Enables mock review functionality. Android only. Default: false.
```

--------------------------------

### Manual feature gating without Superwall

Source: https://superwall.com/docs/flutter/quickstart/feature-gating

Standard implementation requiring manual checks for active subscriptions and paywall presentation logic.

```dart
void pressedWorkoutButton() {
  if (user.hasActiveSubscription) {
    navigation.startWorkout();
  } else {
    navigation.presentPaywall().then((result) {
      if (result) {
        navigation.startWorkout();
      } else {
        // user didn't pay, developer decides what to do
      }
    });
  }
}
```

--------------------------------

### Handle Purchase Events in Swift

Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products

Implements the SuperwallDelegate to monitor transaction events and configures the SDK in the App struct.

```swift
class SWDelegate: SuperwallDelegate {
  func handleSuperwallEvent(withInfo eventInfo: SuperwallEventInfo) {
    switch eventInfo.event {
    case .transactionComplete(_, let product, _, _):
      print("Transaction complete: product: \(product.productIdentifier)")
    case .subscriptionStart(let product, _):
      print("Subscription start: product: \(product.productIdentifier)")
    case .freeTrialStart(let product, _):
      print("Free trial start: product: \(product.productIdentifier)")
    case .transactionRestore(_, _):
      print("Transaction restored")
    case .nonRecurringProductPurchase(let product, _):
      print("Consumable product purchased: \(product.id)")
    default:
      print("Unhandled event.")
    }
  }
}

@main
struct Caffeine_PalApp: App {
  @State private var swDelegate: SWDelegate = .init()

  init() {
    Superwall.configure(apiKey: "my_api_key")
    Superwall.shared.delegate = swDelegate
  }

  var body: some Scene {
    WindowGroup {
      ContentView()
    }
  }
}
```

--------------------------------

### Registering a PaywallPresentationHandler in Swift

Source: https://superwall.com/docs/flutter/guides/advanced/using-the-presentation-handler

Configure a handler with lifecycle callbacks and pass it to the register method to monitor paywall events.

```swift
let handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result in
  print("The paywall dismissed. PaywallInfo: \(paywallInfo). Result: \(result)")
}
handler.onPresent { paywallInfo in
  print("The paywall presented. PaywallInfo:", paywallInfo)
}
handler.onError { error in
  print("The paywall presentation failed with error \(error)")
}
handler.onSkip { reason in
  switch reason {
  case .holdout(let experiment):
    print("Paywall not shown because user is in a holdout group in Experiment: \(experiment.id)")
  case .noAudienceMatch:
    print("Paywall not shown because user doesn't match any audiences.")
  case .placementNotFound:
    print("Paywall not shown because this placement isn't part of a campaign.")
  }
}

Superwall.shared.register(placement: "campaign_trigger", handler: handler) {
  // Feature launched
}
```

--------------------------------

### Configure Presentation Handler in Objective-C

Source: https://superwall.com/docs/flutter/guides/advanced/using-the-presentation-handler

Use the SWKPaywallPresentationHandler to define callbacks for paywall lifecycle events in Objective-C.

```Objective-C
SWKPaywallPresentationHandler *handler = [[SWKPaywallPresentationHandler alloc] init];

[handler onDismiss:^(SWKPaywallInfo * _Nonnull paywallInfo,
                         enum SWKPaywallResult result,
                         SWKStoreProduct * _Nullable product) {
  NSLog(@"The paywall presented. PaywallInfo: %@ - result: %ld", paywallInfo, (long)result);
}];

[handler onPresent:^(SWKPaywallInfo * _Nonnull paywallInfo) {
  NSLog(@"The paywall presented. PaywallInfo: %@", paywallInfo);
}];

[handler onError:^(NSError * _Nonnull error) {
  NSLog(@"The paywall presentation failed with error %@", error);
}];

[handler onSkip:^(enum SWKPaywallSkippedReason reason) {
  switch (reason) {
    case SWKPaywallSkippedReasonUserIsSubscribed:
      NSLog(@"Paywall not shown because user is subscribed.");
      break;
    case SWKPaywallSkippedReasonHoldout:
      NSLog(@"Paywall not shown because user is in a holdout group.");
      break;
    case SWKPaywallSkippedReasonNoAudienceMatch:
      NSLog(@"Paywall not shown because user doesn't match any audiences.");
      break;
    case SWKPaywallSkippedReasonPlacementNotFound:
      NSLog(@"Paywall not shown because this placement isn't part of a campaign.");
      break;
    case SWKPaywallSkippedReasonNone:
      // The paywall wasn't skipped.
      break;
  }
}];

[[Superwall sharedInstance] registerWithPlacement:@"campaign_trigger" params:nil handler:handler feature:^{
  // Feature launched.
}];
```

--------------------------------

### Create a PurchaseController for RevenueCat

Source: https://superwall.com/docs/flutter/guides/using-revenuecat

Implement the PurchaseController to sync subscription status and handle purchase logic for iOS and Android.

```dart
import 'dart:io';

import 'package:flutter/services.dart';
import 'package:purchases_flutter/purchases_flutter.dart';
import 'package:superwallkit_flutter/superwallkit_flutter.dart' hide LogLevel;

class RCPurchaseController extends PurchaseController {
  // MARK: Configure and sync subscription Status
  /// Makes sure that Superwall knows the customers subscription status by
  /// changing `Superwall.shared.subscriptionStatus`
  Future<void> configureAndSyncSubscriptionStatus() async {
    // Configure RevenueCat
    await Purchases.setLogLevel(LogLevel.debug);
    final configuration = Platform.isIOS
        ? PurchasesConfiguration('ios_rc_key')
        : PurchasesConfiguration('android_rc_key');
    await Purchases.configure(configuration);

    // Listen for changes
    Purchases.addCustomerInfoUpdateListener((customerInfo) async {
      // Gets called whenever new CustomerInfo is available
      final entitlements = customerInfo.entitlements.active.keys
          .map((id) => Entitlement(id: id))
          .toSet();

      final hasActiveEntitlementOrSubscription = customerInfo
          .hasActiveEntitlementOrSubscription(); // Why? -> https://www.revenuecat.com/docs/entitlements#entitlements

      if (hasActiveEntitlementOrSubscription) {
        await Superwall.shared.setSubscriptionStatus(
            SubscriptionStatusActive(entitlements: entitlements));
      } else {
        await Superwall.shared
            .setSubscriptionStatus(SubscriptionStatusInactive());
      }
    });
  }

  // MARK: Handle Purchases

  /// Makes a purchase from App Store with RevenueCat and returns its
  /// result. This gets called when someone tries to purchase a product on
  /// one of your paywalls from iOS.
  @override
  Future<PurchaseResult> purchaseFromAppStore(String productId) async {
    // Find products matching productId from RevenueCat
    final products = await PurchasesAdditions.getAllProducts([productId]);

    // Get first product for product ID (this will properly throw if empty)
    final storeProduct = products.firstOrNull;

    if (storeProduct == null) {
      return PurchaseResult.failed(
          'Failed to find store product for $productId');
    }

    final purchaseResult = await _purchaseStoreProduct(storeProduct);
    return purchaseResult;
  }

  /// Makes a purchase from Google Play with RevenueCat and returns its
  /// result. This gets called when someone tries to purchase a product on
  /// one of your paywalls from Android.
  @override
  Future<PurchaseResult> purchaseFromGooglePlay(
      String productId, String? basePlanId, String? offerId) async {
    // Find products matching productId from RevenueCat
    List<StoreProduct> products =
        await PurchasesAdditions.getAllProducts([productId]);

    // Choose the product which matches the given base plan.
    // If no base plan set, select first product or fail.
    String storeProductId = "$productId:$basePlanId";

    // Try to find the first product where the googleProduct's basePlanId matches the given basePlanId.
    StoreProduct? matchingProduct;

    // Loop through each product in the products list.
    for (final product in products) {
      // Check if the current product's basePlanId matches the given basePlanId.
      if (product.identifier == storeProductId) {
        // If a match is found, assign this product to matchingProduct.
        matchingProduct = product;
        // Break the loop as we found our matching product.
        break;
      }
    }

    // If a matching product is not found, then try to get the first product from the list.
    StoreProduct? storeProduct =
        matchingProduct ?? (products.isNotEmpty ? products.first : null);
```

--------------------------------

### Build Subscription Option ID Helper

Source: https://superwall.com/docs/flutter/guides/using-revenuecat

Constructs a subscription option ID string from base plan and offer identifiers.

```dart
String _buildSubscriptionOptionId(String? basePlanId, String? offerId) {
  String result = '';

  if (basePlanId != null) {
    result += basePlanId;
  }

  if (offerId != null) {
    if (basePlanId != null) {
      result += ':';
    }
    result += offerId;
  }

  return result;
}
```

--------------------------------

### Basic Deep Link Handling

Source: https://superwall.com/docs/flutter/sdk-reference/handleDeepLink

Standard implementation for passing incoming links to Superwall and falling back to app-specific logic if unhandled.

```dart
Future<void> _handleIncomingLink(String link) async {
  final uri = Uri.parse(link);
  
  // Let Superwall handle the link first
  final handled = await Superwall.shared.handleDeepLink(uri);
  
  if (!handled) {
    // Handle non-Superwall deep links
    _handleAppDeepLink(uri);
  }
}
```

--------------------------------

### Presenting a Paywall and Handling Results in Objective-C

Source: https://superwall.com/docs/flutter/guides/advanced/presenting-paywalls

Use this implementation to fetch a paywall for a specific event and handle the resulting view controller or error states. The delegate method manages post-purchase logic and feature gating behavior.

```Objective-C
@interface MyViewController : UIViewController

- (void)presentPaywall;

@end

@interface MyViewController () <SWKPaywallViewControllerDelegate>

@end

@implementation MyViewController

- (void)presentPaywall {
  // 1
  [[Superwall sharedInstance] getPaywallForEvent:@"campaign_trigger" params:nil paywallOverrides:nil delegate:self completion:^(SWKGetPaywallResult * _Nonnull result) {
    if (result.paywall != nil) {
      [self presentViewController:result.paywall animated:YES completion:nil];
    } else if (result.skippedReason != SWKPaywallSkippedReasonNone) {
      switch (result.skippedReason) {
      // 2
        case SWKPaywallSkippedReasonHoldout:
        case SWKPaywallSkippedReasonUserIsSubscribed:
        case SWKPaywallSkippedReasonEventNotFound:
        case SWKPaywallSkippedReasonNoRuleMatch:
        case SWKPaywallSkippedReasonNone:
          break;
      };
    } else if (result.error) {
      // 3
      NSLog(@"%@", result.error);
    }
  }];
}

-(void)launchFeature {
  // Insert code to launch a feature that's behind your paywall.
}

// 4
- (void)paywall:(SWKPaywallViewController *)paywall didFinishWithResult:(enum SWKPaywallResult)result shouldDismiss:(BOOL)shouldDismiss {
  if (shouldDismiss) {
    [paywall dismissViewControllerAnimated:true completion:nil];
  }

  SWKPaywallCloseReason closeReason;
  SWKFeatureGatingBehavior featureGating;

  switch (result) {
  case SWKPaywallResultPurchased:
  case SWKPaywallResultRestored:
    [self launchFeature];
    break;
  case SWKPaywallResultDeclined:
    closeReason = paywall.info.closeReason;
    featureGating = paywall.info.featureGatingBehavior;

    if (closeReason != SWKPaywallCloseReasonForNextPaywall && featureGating == SWKFeatureGatingBehaviorNonGated) {
        [self launchFeature];
    }
    break;
  }
}

@end
```

--------------------------------

### Registering a Placement with a Handler

Source: https://superwall.com/docs/flutter/sdk-reference/register

Use this pattern to track paywall lifecycle events using a PaywallPresentationHandler.

```dart
await Superwall.shared.registerPlacement(
  "onboarding_complete",
  params: {"source": "onboarding"},
  handler: myHandler,
);
```

--------------------------------

### Consume Purchase Token in Kotlin

Source: https://superwall.com/docs/flutter/guides/consumable-products

Implement the SuperwallDelegate to listen for TransactionComplete events, grant the product benefit, and call the consume method.

```kotlin
import androidx.lifecycle.lifecycleScope
import com.superwall.sdk.Superwall
import com.superwall.sdk.analytics.superwall.SuperwallEvent
import com.superwall.sdk.analytics.superwall.SuperwallEventInfo
import com.superwall.sdk.delegate.SuperwallDelegate
import kotlinx.coroutines.launch

class MainActivity : AppCompatActivity(), SuperwallDelegate {
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    Superwall.instance.delegate = this
  }

  override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
    val event = eventInfo.event
    if (event !is SuperwallEvent.TransactionComplete) {
      return
    }

    if (event.product.productIdentifier != "coins_100") {
      return
    }

    val purchaseToken = event.transaction?.purchaseToken ?: return

    lifecycleScope.launch {
      ConsumablesService.grantCoins(
        count = 100,
        productId = event.product.productIdentifier,
        purchaseToken = purchaseToken,
      )

      Superwall.instance.consume(purchaseToken)
        .onFailure { error ->
          // Retry consumption after confirming the benefit was granted.
          println("Failed to consume purchase: ${error.message}")
        }
    }
  }
}
```

--------------------------------

### Set product overrides

Source: https://superwall.com/docs/flutter/sdk-reference/overrideProductsByName

Assign a map of product names to identifiers to globally override paywall configurations.

```dart
// Override products globally
Superwall.shared.overrideProductsByName = {
  'primary': 'com.example.premium_monthly',
  'secondary': 'com.example.premium_annual',
  'tertiary': 'com.example.premium_lifetime',
};

// All paywalls will now use these product identifiers
// instead of the ones configured in the dashboard
```

--------------------------------

### Handle Transaction Events in Android

Source: https://superwall.com/docs/flutter/guides/advanced/viewing-purchased-products

Implement the SuperwallDelegate to capture TransactionComplete events and configure the Superwall instance.

```kotlin
class SWDelegate : SuperwallDelegate {
  override fun handleSuperwallEvent(eventInfo: SuperwallEventInfo) {
    when (eventInfo.event) {
        is SuperwallPlacement.TransactionComplete -> {
          val transaction = (eventInfo.event as SuperwallPlacement.TransactionComplete).transaction
          val product = (eventInfo.event as SuperwallPlacement.TransactionComplete).product
          val paywallInfo = (eventInfo.event as SuperwallPlacement.TransactionComplete).paywallInfo
          println("Transaction Complete: $transaction, Product: $product, Paywall Info: $paywallInfo")
        }
        else -> {
          // Handle other cases
        }
    }
  }
}

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Superwall.configure(this, "my_api_key")
        Superwall.instance.delegate = SWDelegate()
    }
}
```

--------------------------------

### Configure Superwall with a custom PurchaseController

Source: https://superwall.com/docs/flutter/guides/advanced-configuration

Pass an instance of your custom controller to the Superwall configuration method during app initialization.

```dart
// main.dart

void initState() {
  // Determine Superwall API Key for platform
  String apiKey = Platform.isIOS ? "MY_IOS_API_KEY" : "MY_ANDROID_API_KEY";

  // Create the purchase controller
  MyPurchaseController purchaseController = MyPurchaseController();

  Superwall.configure(apiKey, purchaseController);
}
```

--------------------------------

### Configure Presentation Handler in Kotlin

Source: https://superwall.com/docs/flutter/guides/advanced/using-the-presentation-handler

Use the PaywallPresentationHandler to define callbacks for paywall lifecycle events in Kotlin.

```Kotlin
val handler = PaywallPresentationHandler()
handler.onDismiss { paywallInfo, result ->
  println("The paywall dismissed. PaywallInfo: ${it}")
}
handler.onPresent {
  println("The paywall presented. PaywallInfo: ${it}")
}
handler.onError {
  println("The paywall errored. Error: ${it}")
}
handler.onSkip {
  when (it) {
    is PaywallSkippedReason.PlacementNotFound -> {
      println("The paywall was skipped because the placement was not found.")
    }
    is PaywallSkippedReason.Holdout -> {
      println("The paywall was skipped because the user is in a holdout group.")
    }
    is PaywallSkippedReason.NoAudienceMatch -> {
      println("The paywall was skipped because no audience matched.")
    }
  }
}

Superwall.instance.register(placement = "campaign_trigger", handler = handler) {
    // Feature launched
}
```

--------------------------------

### Configure AndroidManifest.xml

Source: https://superwall.com/docs/flutter/quickstart/install

Register the required activities within the application tag.

```xml
   <!-- ... inside your <application> tag  -->
  <activity
    android:name="com.superwall.sdk.paywall.view.SuperwallPaywallActivity"
    android:theme="@style/Theme.MaterialComponents.DayNight.NoActionBar"
    android:configChanges="orientation|screenSize|keyboardHidden">
  </activity>

  <!-- Optional -->
  <activity android:name="com.superwall.sdk.debug.DebugViewActivity" />
  <activity android:name="com.superwall.sdk.debug.localizations.SWLocalizationActivity" />
  <activity android:name="com.superwall.sdk.debug.SWConsoleActivity" />
```

--------------------------------

### CustomerInfo and Purchases Extensions

Source: https://superwall.com/docs/flutter/guides/using-revenuecat

Provides helper methods for checking active entitlements and fetching all products from RevenueCat.

```dart
extension CustomerInfoAdditions on CustomerInfo {
  bool hasActiveEntitlementOrSubscription() {
    return (activeSubscriptions.isNotEmpty || entitlements.active.isNotEmpty);
  }
}

extension PurchasesAdditions on Purchases {
  static Future<List<StoreProduct>> getAllProducts(
      List<String> productIdentifiers) async {
    final subscriptionProducts = await Purchases.getProducts(productIdentifiers,
        productCategory: ProductCategory.subscription);
    final nonSubscriptionProducts = await Purchases.getProducts(
        productIdentifiers,
        productCategory: ProductCategory.nonSubscription);
    final combinedProducts = [
      ...subscriptionProducts,
      ...nonSubscriptionProducts
    ];
    return combinedProducts;
  }
}
```
Tokens:
Raw