# PaywallPresentationHandler

A handler class that provides status updates for paywall presentation in registerPlacement() calls.

> **Info**

Use this handler when you need fine-grained control over paywall events for a specific [`registerPlacement()`](/docs/flutter/sdk-reference/register) call, rather than global events via [`SuperwallDelegate`](/docs/flutter/sdk-reference/SuperwallDelegate).



> **Note**

This handler is specific to the individual `registerPlacement()` call. For global paywall events across your app, use [`SuperwallDelegate`](/docs/flutter/sdk-reference/SuperwallDelegate) instead.



Purpose [#purpose]

Provides callbacks for paywall lifecycle events when using [`registerPlacement()`](/docs/flutter/sdk-reference/register) with a specific handler instance.

Signature [#signature]

```dart
class PaywallPresentationHandler {
  void onPresent(Function(PaywallInfo) handler);
  void onDismiss(Function(PaywallInfo, PaywallResult) handler);
  void onSkip(Function(PaywallSkippedReason) handler);
  void onError(Function(String) handler);
  void onCustomCallback(
    Future<CustomCallbackResult> Function(CustomCallback) handler,
  );
}
```

Parameters [#parameters]

<TypeTable
  type="{
  onPresent: {
    type: &#x22;handler: (PaywallInfo) -> void&#x22;,
    description: &#x22;Sets a handler called when the paywall is presented.&#x22;,
    required: true,
  },
  onDismiss: {
    type: &#x22;handler: (PaywallInfo, PaywallResult) -> void&#x22;,
    description: &#x22;Sets a handler called when the paywall is dismissed.&#x22;,
    required: true,
  },
  onSkip: {
    type: &#x22;handler: (PaywallSkippedReason) -> void&#x22;,
    description: &#x22;Sets a handler called when paywall presentation is skipped.&#x22;,
    required: true,
  },
  onError: {
    type: &#x22;handler: (String) -> void&#x22;,
    description: &#x22;Sets a handler called when an error occurs during presentation.&#x22;,
    required: true,
  },
  onCustomCallback: {
    type: &#x22;handler: (CustomCallback) -> Future<CustomCallbackResult>&#x22;,
    description: &#x22;Sets an async handler called when the paywall requests a custom callback. Available in 2.4.8+.&#x22;,
    required: false,
  },
}"
/>

Returns / State [#returns--state]

Each method returns `void` and configures the handler for the specific paywall lifecycle event.

CustomCallback (2.4.8+) [#customcallback-248]

The `onCustomCallback` handler receives a `CustomCallback` object.

<TypeTable
  type="{
  name: {
    type: &#x22;String&#x22;,
    description: &#x22;The callback name configured in the paywall editor.&#x22;,
    required: true,
  },
  variables: {
    type: &#x22;Map<String, Object>?&#x22;,
    description: &#x22;Optional key-value pairs sent from the paywall.&#x22;,
    required: false,
  },
}"
/>

CustomCallbackResult (2.4.8+) [#customcallbackresult-248]

Return a `CustomCallbackResult` from your callback handler to control paywall flow:

```dart
CustomCallbackResult.success([Map<String, Object>? data])
CustomCallbackResult.failure([Map<String, Object>? data])
```

Use `data` to send values back to the paywall, available as `callbacks.<name>.data.<key>`.

PaywallInfo State (2.4.8+) [#paywallinfo-state-248]

`PaywallInfo` now includes `state`, a `Map<String, Object>?` with current paywall state values.

Usage [#usage]

Basic handler setup:

```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();
    },
  );
}
```

Handle skip, error, and custom callbacks:

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

  handler.onSkip((reason) {
    print('Paywall skipped: $reason');

    switch (reason) {
      case PaywallSkippedReason.userIsSubscribed:
        _proceedToFeature();
        break;
      case PaywallSkippedReason.holdout:
        _proceedToFeature();
        break;
      default:
        break;
    }
  });

  handler.onError((error) {
    print('Paywall error: $error');
    _showErrorDialog(error);
  });

  handler.onCustomCallback((callback) async {
    switch (callback.name) {
      case 'validate_email':
        final email = callback.variables?['email'] as String?;
        if (email != null && email.contains('@')) {
          return CustomCallbackResult.success({'validated': true});
        }
        return CustomCallbackResult.failure({'error': 'Invalid email'});
      default:
        return CustomCallbackResult.failure({'error': 'Unknown callback'});
    }
  });

  await Superwall.shared.registerPlacement(
    'remove_ads',
    handler: handler,
    feature: () {
      _hideAdsFromUI();
    },
  );
}
```