presentPaywallIfNeeded static method

Future<PaywallResult> presentPaywallIfNeeded(
  1. String requiredEntitlementIdentifier, {
  2. Offering? offering,
  3. bool displayCloseButton = false,
  4. Map<String, CustomVariableValue>? customVariables,
  5. PaywallPresentationConfiguration? presentationConfiguration,
  6. dynamic onPurchaseStarted(
    1. Package rcPackage
    )?,
  7. dynamic onPurchaseCompleted(
    1. CustomerInfo customerInfo,
    2. StoreTransaction storeTransaction
    )?,
  8. dynamic onPurchaseCancelled()?,
  9. dynamic onPurchaseError(
    1. PurchasesError
    )?,
  10. dynamic onRestoreCompleted(
    1. CustomerInfo customerInfo
    )?,
  11. dynamic onRestoreError(
    1. PurchasesError
    )?,
  12. dynamic onWebCheckoutOpened()?,
  13. dynamic onUrlOpened(
    1. String url
    )?,
  14. dynamic onInteraction(
    1. Map<String, dynamic> event
    )?,
})

Presents the paywall as an activity on android or a modal in iOS as long as the user does not have the given entitlement identifier active. Returns a PaywallResult indicating the result of the paywall presentation.

@param requiredEntitlementIdentifier Entitlement identifier to check if the user has access to before presenting the paywall. @param offering If set, will present the paywall associated to the given Offering. @param displayCloseButton Optionally present the paywall with a close button. Only available for original template paywalls. Ignored for V2 Paywalls. @param customVariables A map of custom variable names to their values. These values can be used for text substitution in paywalls using the {{ custom.variable_name }} syntax. @param presentationConfiguration Optional configuration for how the paywall is presented on each platform. @param onPurchaseStarted Called when a purchase is started. @param onPurchaseCompleted Called when a purchase is completed. @param onPurchaseCancelled Called when a purchase is cancelled. @param onPurchaseError Called when a purchase fails. @param onRestoreCompleted Called when a restore completes, even if no entitlements were granted. @param onRestoreError Called when a restore fails. @param onWebCheckoutOpened Called when the user leaves the app for web checkout. @param onUrlOpened Called when the paywall opens a URL. Not called for web checkout URLs. @param onInteraction Called when the user interacts with a paywall control (tab, package, purchase button, ...), with the paywall_component_interacted event as a map of snake_case keys; keys that do not apply are absent.

Implementation

static Future<PaywallResult> presentPaywallIfNeeded(
  String requiredEntitlementIdentifier, {
  Offering? offering,
  bool displayCloseButton = false,
  Map<String, CustomVariableValue>? customVariables,
  PaywallPresentationConfiguration? presentationConfiguration,
  Function(Package rcPackage)? onPurchaseStarted,
  Function(CustomerInfo customerInfo, StoreTransaction storeTransaction)?
      onPurchaseCompleted,
  Function()? onPurchaseCancelled,
  Function(PurchasesError)? onPurchaseError,
  Function(CustomerInfo customerInfo)? onRestoreCompleted,
  Function(PurchasesError)? onRestoreError,
  Function()? onWebCheckoutOpened,
  Function(String url)? onUrlOpened,
  Function(Map<String, dynamic> event)? onInteraction,
}) async {
  final presentedOfferingContext = offering?.availablePackages
      .elementAtOrNull(0)
      ?.presentedOfferingContext;
  final handler = PaywallViewMethodHandler(
    onPurchaseStarted,
    onPurchaseCompleted,
    onPurchaseCancelled,
    onPurchaseError,
    onRestoreCompleted,
    onRestoreError,
    null,
    onWebCheckoutOpened: onWebCheckoutOpened,
    onUrlOpened: onUrlOpened,
    onInteraction: onInteraction,
  );
  return _presentPaywall(
    'presentPaywallIfNeeded',
    {
      'requiredEntitlementIdentifier': requiredEntitlementIdentifier,
      'offeringIdentifier': offering?.identifier,
      'presentedOfferingContext': presentedOfferingContext?.toJson(),
      'displayCloseButton': displayCloseButton,
      'customVariables': convertCustomVariablesToNative(customVariables),
      // Only send when fullScreen is explicitly requested; omitting the key
      // lets the native SDK use its default (sheet). This avoids ambiguity
      // between "key absent" and "key present with false".
      if (presentationConfiguration?.ios ==
          IOSPaywallPresentationStyle.fullScreen)
        'useFullScreenPresentation': true,
    },
    handler,
  );
}