Respond to flow actions - Capacitor

If you are building flows or paywalls using the Adapty Flow Builder or Paywall Builder, it’s crucial to set up buttons properly:

Add a button in the builder and assign it either a pre-existing action or create a custom action ID.
Write code in your app to handle each action you’ve assigned.

This guide shows how to handle custom and pre-existing actions in your code.

Purchases, restorations, flow and paywall closures, and URL opening are handled automatically. You can configure their default behavior or implement responses for custom actions.

Setting a handler for an event replaces its default behavior entirely. Handlers you don’t set keep their defaults.

Close flows and paywalls

To add a button that will close your flow or paywall:

In the builder, add a button and assign it the Close action.
In your app code, implement a handler for the close action that dismisses the flow or paywall.

In the Capacitor SDK, the close action triggers closing the flow or paywall by default. However, you can override this behavior in your code if needed. For example, closing one flow might trigger opening another.

import { adapty, createFlowView } from '@adapty/capacitor';

const view = await createFlowView(flow);

const unsubscribe = await view.setEventHandlers({
  onCloseButtonPress() {
    return true; // allow the flow to close
  },
});

On Android, the system Back button and back gesture trigger a separate onAndroidSystemBack event. In SDK v4, it no longer closes the flow by default. Return true from the handler if you want the Back button to close the flow:

const unsubscribe = await view.setEventHandlers({
  onAndroidSystemBack() {
    return true; // close the flow when the Back button is pressed
  },
});

Open URLs from flows and paywalls

If you want to add a group of links (e.g., terms of use and purchase restoration), add a Link element in the builder and handle it the same way as buttons with the Open URL action.

To add a button that opens a link from your flow or paywall (e.g., Terms of use or Privacy policy):

In the builder, add a button, assign it the Open URL action, and enter the URL you want to open.
If needed, in your app code, implement a handler for the openUrl action that opens the received URL your own way.

In the Capacitor SDK, tapping a URL opens it in the native browser by default: the SDK calls adapty.openWebUrl({ url, openIn }), honoring the Open in option you set in the builder, and keeps the flow open. However, you can override this behavior in your code if needed.

import { Browser } from '@capacitor/browser';

const unsubscribe = await view.setEventHandlers({
  onUrlPress(url) {
    // Open the URL your own way, e.g. with the Capacitor Browser plugin
    Browser.open({ url });
    return false; // keep the flow open
  },
});

Handle custom actions

To add a button that handles any other actions:

In the builder, add a button, assign it the Custom action, and assign it an ID.
In your app code, implement a handler for the action ID you’ve created.

For example, if you have another set of subscription offers or one-time purchases, you can add a button that will display another flow or paywall:

const unsubscribe = await view.setEventHandlers({
  onCustomAction(actionId) {
    if (actionId === 'openNewPaywall') {
      // Display another flow or paywall
    }
  },
});

If you are building paywalls using the Adapty paywall builder, it’s crucial to set up buttons properly:

Add a button in the paywall builder and assign it either a pre-existing action or create a custom action ID.
Write code in your app to handle each action you’ve assigned.

This guide shows how to handle custom and pre-existing actions in your code.

Close paywalls

To add a button that will close your paywall:

In the paywall builder, add a button and assign it the Close action.
In your app code, implement a handler for the close action that dismisses the paywall.

In the Capacitor SDK, the close action triggers closing the paywall by default. However, you can override this behavior in your code if needed. For example, closing one paywall might trigger opening another.

import { adapty, createPaywallView } from '@adapty/capacitor';

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCloseButtonPress() {
    console.log('User closed paywall');
    return true; // Allow the paywall to close
  }
});

Open URLs from paywalls

If you want to add a group of links (e.g., terms of use and purchase restoration), add a Link element in the paywall builder and handle it the same way as buttons with the Open URL action.

To add a button that opens a link from your paywall (e.g., Terms of use or Privacy policy):

In the paywall builder, add a button, assign it the Open URL action, and enter the URL you want to open.
In your app code, implement a handler for the openUrl action that opens the received URL in a browser.

In the Capacitor SDK, the window.open action triggers opening the URL by default. However, you can override this behavior in your code if needed.

import { adapty, createPaywallView } from '@adapty/capacitor';

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onUrlPress(url) {
    window.open(url, '_blank');
    return false; // Don't close the paywall
  },
});

Log into the app

To add a button that logs users into your app:

In the paywall builder, add a button and assign it the Login action.
In your app code, implement a handler for the login action that identifies your user.

import { adapty, createPaywallView } from '@adapty/capacitor';

const view = await createPaywallView(paywall);

const unsubscribe = view.setEventHandlers({
  onCustomAction(actionId) {
    if (actionId === 'login') {
      // Navigate to login screen
      console.log('User requested login');
    }
  }
});

Handle custom actions

To add a button that handles any other actions:

In the paywall builder, add a button, assign it the Custom action, and assign it an ID.
In your app code, implement a handler for the action ID you’ve created.

For example, if you have another set of subscription offers or one-time purchases, you can add a button that will display another paywall:

const unsubscribe = view.setEventHandlers({
  onCustomAction(actionId) {
    if (actionId === 'openNewPaywall') {
      // Display another paywall
    }
  },
});