Display flows & paywalls - React Native

Display flows and paywalls
✦
Flows Built in the Flow & Paywall Builder — renders natively on device, no WebView
✦
Old Paywall Builder paywalls All content built in the old Paywall Builder

If you’ve created a flow, or a paywall in the old Paywall Builder, you don’t need to worry about rendering it in your mobile app code to display it to the user. Such a flow contains both what should be shown within it and how it should be shown.

Before you start, ensure that:

  1. You have created a flow or a paywall.
  2. You have added it to a placement.
  3. You have fetched the flow and prepared the view.
Warning

This guide is for flows and paywalls rendered by Adapty only, which require SDK v4.0 or later. The process for presenting flows differs for custom paywalls.

Adapty React Native SDK provides two ways to present flows and paywalls:

  • React component: Embedded component allows you to integrate it into your app’s architecture and navigation system.

  • Modal presentation

React component

To embed a flow within your existing component tree, use the AdaptyFlowView component directly in your React Native component hierarchy. Embedded component allows you to integrate it into your app’s architecture and navigation system.

Tip

The AdaptyFlowView component creates its view when it renders, which is when the configuration and images load. To preload them, call createFlowView for the same flow earlier in your app. The component then reuses the cached data and renders without waiting for downloads.

import React, { useCallback, useMemo } from 'react';
import { AdaptyFlowView } from 'react-native-adapty';
import type { FlowEventHandlers } from 'react-native-adapty';

function MyFlow({ flow }) {
  const flowParams = useMemo(() => ({
    loadTimeoutMs: 3000,
    locale: 'en', // The localization to render the flow with
  }), []);

  const onCloseButtonPress = useCallback<FlowEventHandlers['onCloseButtonPress']>(() => {}, []);
  const onProductSelected = useCallback<FlowEventHandlers['onProductSelected']>((productId) => {}, []);
  const onPurchaseStarted = useCallback<FlowEventHandlers['onPurchaseStarted']>((product) => {}, []);
  const onPurchaseCompleted = useCallback<FlowEventHandlers['onPurchaseCompleted']>((purchaseResult, product) => {}, []);
  const onPurchaseFailed = useCallback<FlowEventHandlers['onPurchaseFailed']>((error, product) => {}, []);
  const onRestoreStarted = useCallback<FlowEventHandlers['onRestoreStarted']>(() => {}, []);
  const onRestoreCompleted = useCallback<FlowEventHandlers['onRestoreCompleted']>((profile) => {}, []);
  const onRestoreFailed = useCallback<FlowEventHandlers['onRestoreFailed']>((error) => {}, []);
  const onAppeared = useCallback<FlowEventHandlers['onAppeared']>((view) => {}, []);
  const onError = useCallback<FlowEventHandlers['onError']>((error) => {}, []);
  const onLoadingProductsFailed = useCallback<FlowEventHandlers['onLoadingProductsFailed']>((error) => {}, []);
  const onUrlPress = useCallback<FlowEventHandlers['onUrlPress']>((url) => {}, []);
  const onCustomAction = useCallback<FlowEventHandlers['onCustomAction']>((actionId) => {}, []);
  const onWebPaymentNavigationFinished = useCallback<FlowEventHandlers['onWebPaymentNavigationFinished']>(() => {}, []);

  return (
    <AdaptyFlowView
      flow={flow}
      params={flowParams}
      style={styles.flow}
      onCloseButtonPress={onCloseButtonPress}
      onProductSelected={onProductSelected}
      onPurchaseStarted={onPurchaseStarted}
      onPurchaseCompleted={onPurchaseCompleted}
      onPurchaseFailed={onPurchaseFailed}
      onRestoreStarted={onRestoreStarted}
      onRestoreCompleted={onRestoreCompleted}
      onRestoreFailed={onRestoreFailed}
      onAppeared={onAppeared}
      onError={onError}
      onLoadingProductsFailed={onLoadingProductsFailed}
      onCustomAction={onCustomAction}
      onUrlPress={onUrlPress}
      onWebPaymentNavigationFinished={onWebPaymentNavigationFinished}
    />
  );
}

To display a flow as a standalone screen, use the view.present() method on the view created by the createFlowView method. If you need to display the flow again, call createFlowView one more time to create a new view instance, or keep the closed view to present it again.

Warning

After view.dismiss() with default options, the view is released, and calling present() on it again fails. Calling present() while a flow is already on the screen also fails. In both cases, you get an AdaptyError with code 3001 (wrongParam), and its message names the cause: AdaptyUIError.viewNotFound or AdaptyUIError.viewAlreadyPresented.

import { createFlowView } from 'react-native-adapty';

const view = await createFlowView(flow);

// Optional: handle flow events (close, purchase, restore, etc)
// view.setEventHandlers({ ... });

try {
  await view.present();
} catch (error) {
  // handle the error
}
Important

Calling setEventHandlers multiple times will override the handlers you provide, replacing both default and previously set handlers for those specific events.

Configure iOS presentation style

Configure how the flow is presented on iOS by passing the iosPresentationStyle parameter to the present() method. The parameter accepts 'full_screen' (default) or 'page_sheet' values.

try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}

Keep a closed flow for later

Info

The destroy option and the destroy() method are available starting from SDK version 4.3.0.

By default, view.dismiss() closes the flow and destroys its native view, so the view can’t be presented again. To present the same flow again later, pass destroy: false. The next present() call opens the flow on the screen where the user closed it, with the state the user left it in, and your event handlers stay set:

// Close the flow and keep its native view in memory
await view.dismiss({ destroy: false });

// Later: open the flow again on the same screen
await view.present();

The native view stays in memory until you release it. When you no longer need the flow, call destroy():

await view.dismiss({ destroy: false });
// ...
await view.destroy();

Call destroy() only for a view that you closed with destroy: false. A regular dismiss() releases the view on its own.

An event handler that returns true closes the flow with a regular dismiss(), which destroys the native view even if you kept it earlier. The default onCloseButtonPress and onError handlers return true. To keep the flow when the user closes it, close the flow yourself and return false:

view.setEventHandlers({
  onCloseButtonPress() {
    view.dismiss({ destroy: false }).catch(error => {
      // handle the error
    });
    return false;
  },
});

Use developer-defined timer

Use this section for a timer with the Developer defined behavior in the Flow & Paywall Builder. In the builder, each such timer has a Timer ID (see Let your app set the end date), and your app sets the end date for it. Use the same Timer ID in your code as in the builder, character for character, including letter case and spaces. If the IDs differ, the timer gets no end date from your app.

To set the end dates, pass the customTimers parameter: an object that maps each Timer ID to a Date, the end date of the timer.

In this example, CUSTOM_TIMER_NY is the Timer ID of a Developer defined timer in the builder. The timer shows the time left until the next New Year’s Day, for example 13d 09h 03m 34s.

The SDK reads customTimers once, when it creates the view, so a date that you compute, such as 6 hours from now, counts from that moment. If the date is in the past, the timer shows zero at once and its On timer end trigger runs. If customTimers has no key for a Timer ID, the timer counts down one hour from the screen open.

Show dialog

Use this method instead of native alert dialogs when a flow view is presented on Android. On Android, regular RN alerts appear behind the flow view, which makes them invisible to users. This method ensures proper dialog presentation above the flow on all platforms.

try {
  const action = await view.showDialog({
    title: 'Close paywall?',
    content: 'You will lose access to exclusive offers.',
    primaryActionTitle: 'Stay',
    secondaryActionTitle: 'Close',
  });

  if (action === 'secondary') {
    // User confirmed - close the flow
    await view.dismiss();
  }
  // If primary - do nothing, user stays
} catch (error) {
  // handle error
}

Replace one subscription with another

When a user attempts to purchase a new subscription while another subscription is active on Android, you can control how the new purchase should be handled by passing subscription update parameters when creating the flow view. To replace the current subscription with the new one, use productPurchaseParams in createFlowView with the oldSubVendorProductId and prorationMode parameters.

import { Platform } from 'react-native';
import { createFlowView } from 'react-native-adapty';

const productPurchaseParams = flow.paywalls
  .flatMap((variation) => variation.productIdentifiers)
  .map((productId) => {
    let params = {};
    if (Platform.OS === 'android') {
      params.android = {
        subscriptionUpdateParams: {
          oldSubVendorProductId: 'PRODUCT_ID_OF_THE_CURRENT_ACTIVE_SUBSCRIPTION',
          prorationMode: 'with_time_proration',
        },
      };
    }
    return { productId, params };
  });

const view = await createFlowView(flow, { productPurchaseParams });

If you’ve customized a paywall using the Paywall Builder, you don’t need to worry about rendering it in your mobile app code to display it to the user. Such a paywall contains both what should be shown within the paywall and how it should be shown.

Before you start, ensure that:

  1. You have created a paywall.
  2. You have added the paywall to a placement.
  3. You have fetched the paywall and prepared the view.
Warning

This guide covers only paywalls built in the old Paywall Builder for Adapty SDK 3.x. They require SDK v3.0 or later. Presenting a paywall built for SDK 2.x or earlier, or a custom paywall, works differently.

Adapty React Native SDK provides two ways to present paywalls:

  • React component: Embedded component allows you to integrate it into your app’s architecture and navigation system.

  • Modal presentation

React component

Note

The React component approach requires SDK 3.14.0 or later.

To embed a paywall within your existing component tree, use the AdaptyPaywallView component directly in your React Native component hierarchy. Embedded component allows you to integrate it into your app’s architecture and navigation system.

Note

On Android, if the paywall does not extend behind the status bar, a visual overlay may appear at its top. We recommend you to turn it off for your paywalls. See Visual overlay at the top of the paywall (Android).

import React, { useCallback, useMemo } from 'react';
import { AdaptyPaywallView } from 'react-native-adapty';
import type { EventHandlers } from 'react-native-adapty';

function MyPaywall({ paywall }) {
  const paywallParams = useMemo(() => ({
    loadTimeoutMs: 3000,
  }), []);

  const onCloseButtonPress = useCallback<EventHandlers['onCloseButtonPress']>(() => {}, []);
  const onProductSelected = useCallback<EventHandlers['onProductSelected']>((productId) => {}, []);
  const onPurchaseStarted = useCallback<EventHandlers['onPurchaseStarted']>((product) => {}, []);
  const onPurchaseCompleted = useCallback<EventHandlers['onPurchaseCompleted']>((purchaseResult, product) => {}, []);
  const onPurchaseFailed = useCallback<EventHandlers['onPurchaseFailed']>((error, product) => {}, []);
  const onRestoreStarted = useCallback<EventHandlers['onRestoreStarted']>(() => {}, []);
  const onRestoreCompleted = useCallback<EventHandlers['onRestoreCompleted']>((profile) => {}, []);
  const onRestoreFailed = useCallback<EventHandlers['onRestoreFailed']>((error) => {}, []);
  const onPaywallShown = useCallback<EventHandlers['onPaywallShown']>(() => {}, []);
  const onRenderingFailed = useCallback<EventHandlers['onRenderingFailed']>((error) => {}, []);
  const onLoadingProductsFailed = useCallback<EventHandlers['onLoadingProductsFailed']>((error) => {}, []);
  const onUrlPress = useCallback<EventHandlers['onUrlPress']>((url) => {}, []);
  const onCustomAction = useCallback<EventHandlers['onCustomAction']>((actionId) => {}, []);
  const onWebPaymentNavigationFinished = useCallback<EventHandlers['onWebPaymentNavigationFinished']>(() => {}, []);

  return (
    <AdaptyPaywallView
      paywall={paywall}
      params={paywallParams}
      style={styles.paywall}
      onCloseButtonPress={onCloseButtonPress}
      onProductSelected={onProductSelected}
      onPurchaseStarted={onPurchaseStarted}
      onPurchaseCompleted={onPurchaseCompleted}
      onPurchaseFailed={onPurchaseFailed}
      onRestoreStarted={onRestoreStarted}
      onRestoreCompleted={onRestoreCompleted}
      onRestoreFailed={onRestoreFailed}
      onPaywallShown={onPaywallShown}
      onRenderingFailed={onRenderingFailed}
      onLoadingProductsFailed={onLoadingProductsFailed}
      onCustomAction={onCustomAction}
      onUrlPress={onUrlPress}
      onWebPaymentNavigationFinished={onWebPaymentNavigationFinished}
    />
  );
}

To display a paywall as a standalone screen, use the view.present() method on the view created by the createPaywallView method. Each view can only be used once. If you need to display the paywall again, call createPaywallView one more time to create a new view instance.

Warning

Reusing the same view without recreating it is forbidden. It will result in an AdaptyUIError.viewAlreadyPresented error.

import { createPaywallView } from 'react-native-adapty';

const view = await createPaywallView(paywall);

// Optional: handle paywall events (close, purchase, restore, etc)
// view.setEventHandlers({ ... });

try {
  await view.present();
} catch (error) {
  // handle the error
}
Important

Calling setEventHandlers multiple times will override the handlers you provide, replacing both default and previously set handlers for those specific events.

Configure iOS presentation style

Configure how the paywall is presented on iOS by passing the iosPresentationStyle parameter to the present() method. The parameter accepts 'full_screen' (default) or 'page_sheet' values.

try {
  await view.present({ iosPresentationStyle: 'page_sheet' });
} catch (error) {
  // handle the error
}

Use developer-defined timer

To use developer-defined timers in your mobile app, use the timerId, in this example, CUSTOM_TIMER_NY, the Timer ID of the developer-defined timer you set in the Adapty dashboard. It ensures your app dynamically updates the timer with the correct value—like 13d 09h 03m 34s (calculated as the timer’s end time, such as New Year’s Day, minus the current time).

In this example, CUSTOM_TIMER_NY is the Timer ID of the developer-defined timer you set in the Adapty dashboard. The timerResolver ensures your app dynamically updates the timer with the correct value—like 13d 09h 03m 34s (calculated as the timer’s end time, such as New Year’s Day, minus the current time).

Show dialog

Use this method instead of native alert dialogs when a paywall view is presented on Android. On Android, regular RN alerts appear behind the paywall view, which makes them invisible to users. This method ensures proper dialog presentation above the paywall on all platforms.

try {
  const action = await view.showDialog({
    title: 'Close paywall?',
    content: 'You will lose access to exclusive offers.',
    primaryActionTitle: 'Stay',
    secondaryActionTitle: 'Close',
  });

  if (action === 'secondary') {
    // User confirmed - close the paywall
    await view.dismiss();
  }
  // If primary - do nothing, user stays
} catch (error) {
  // handle error
}

Replace one subscription with another

When a user attempts to purchase a new subscription while another subscription is active on Android, you can control how the new purchase should be handled by passing subscription update parameters when creating the paywall view. To replace the current subscription with the new one, use productPurchaseParams in createPaywallView with the oldSubVendorProductId and prorationMode parameters.

import { Platform } from 'react-native';
import { createPaywallView } from 'react-native-adapty';

const productPurchaseParams = paywall.productIdentifiers.map((productId) => {
  let params = {};
  if (Platform.OS === 'android') {
    params.android = {
      subscriptionUpdateParams: {
        oldSubVendorProductId: 'PRODUCT_ID_OF_THE_CURRENT_ACTIVE_SUBSCRIPTION',
        prorationMode: 'with_time_proration',
      },
    };
  }
  return { productId, params };
});

const view = await createPaywallView(paywall, { productPurchaseParams });

Troubleshooting

Visual overlay at the top of the paywall (Android)

Note

This setting is supported starting from React Native SDK 3.15.5 and is only available in bare React Native projects.

If you are using an Expo managed workflow, you cannot add this Android resource directly. To apply this setting, you must create a custom Expo config plugin that adds the corresponding Android resource and register it in app.config.js. This is required because Expo manages the native Android project for you.

If AdaptyPaywallView does not extend behind the status bar, a visual overlay may still appear at its top. To remove it, add the following boolean resource to your app:

  1. Go to android/app/src/main/res/values. If there is no bools.xml file, create it.

  2. Add the following resource:

<resources>
    <bool name="adapty_paywall_enable_safe_area_paddings">false</bool>
</resources>

Note that the changes apply globally for all paywalls in your app.