Present flows in Observer mode in Android SDK

If you use Observer mode, you are responsible for your own purchase logic. But you can delegate the paywall UI to the Flow & Paywall Builder.

Design the screen in the builder, and the Adapty SDK renders it natively. Update its copy, layout, and pricing whenever you want, without an app release. When a user taps a purchase button, the SDK calls your code to complete the purchase.

This guide shows how to present that screen and handle the purchase call. If Adapty completes purchases for you, see Display flows & paywalls instead.

Before you start

You need:

Adapty Android SDK v4 or later: Earlier versions can’t render flows. To move an existing app from v3, see the migration guide.
observerMode set to true: See the Android SDK installation guide.
Initial store integration: Set up Adapty with Google Play.
A published flow with products: Build it in the Flow & Paywall Builder and assign products to it.
A flow placement: Create a placement and assign your flow to it.
The flow fetched in your app: Get the flow and its configuration before you present it.

Implementation

Implement the AdaptyUiObserverModeHandler.

The onPurchaseInitiated event will inform you that the user has initiated a purchase. You can trigger your custom purchase flow in response to this callback:

val observerModeHandler =
 AdaptyUiObserverModeHandler { product, onStartPurchase, onFinishPurchase ->
    onStartPurchase()
    yourBillingClient.makePurchase(
        product,
        onSuccess = { purchase ->
            onFinishPurchase()
            //handle success
        },
        onError = {
            onFinishPurchase()
            //handle error
        },
        onCancel = {
            onFinishPurchase()
            //handle cancel
        }
    )
}

AdaptyUiObserverModeHandler observerModeHandler = (product, onStartPurchase, onFinishPurchase) -> {
    onStartPurchase.invoke();
    yourBillingClient.makePurchase(
        product,
        purchase -> {
            onFinishPurchase.invoke();
            //handle success
        },
        error -> {
            onFinishPurchase.invoke();
            //handle error
        },
        () -> { //cancellation
            onFinishPurchase.invoke();
            //handle cancel
        }
    );
};

To handle restores in Observer mode, override getRestoreHandler(). By default it returns null, which uses Adapty’s built-in Adapty.restorePurchases() flow. To provide your own restore implementation:

val observerModeHandler = object : AdaptyUiObserverModeHandler {
    override fun onPurchaseInitiated(
        product: AdaptyPaywallProduct,
        onStartPurchase: AdaptyUiObserverModeHandler.PurchaseStartCallback,
        onFinishPurchase: AdaptyUiObserverModeHandler.PurchaseFinishCallback,
    ) {
        // the same body as the purchase example above
    }

    override fun getRestoreHandler() =
        AdaptyUiObserverModeHandler.RestoreHandler { onStartRestore, onFinishRestore ->
            onStartRestore()
            yourBillingClient.restorePurchases(
                onSuccess = { restoredPurchases ->
                    onFinishRestore()
                    //handle successful restore
                },
                onError = {
                    onFinishRestore()
                    //handle error
                }
            )
        }
}

AdaptyUiObserverModeHandler observerModeHandler = new AdaptyUiObserverModeHandler() {
    @Override
    public void onPurchaseInitiated(
        AdaptyPaywallProduct product,
        PurchaseStartCallback onStartPurchase,
        PurchaseFinishCallback onFinishPurchase
    ) {
        // the same body as the purchase example above
    }

    @Override
    public RestoreHandler getRestoreHandler() {
        return (onStartRestore, onFinishRestore) -> {
            onStartRestore.invoke();
            yourBillingClient.restorePurchases(
                restoredPurchases -> {
                    onFinishRestore.invoke();
                    //handle successful restore
                },
                error -> {
                    onFinishRestore.invoke();
                    //handle error
                }
            );
        };
    }
};

Remember to invoke the following callbacks to notify AdaptyUI about the purchase or restore process. This is necessary for proper flow behavior, such as showing the loader:

Callback	Description
onStartPurchase()	The callback should be invoked to notify AdaptyUI that the purchase is started.
onFinishPurchase()	The callback should be invoked to notify AdaptyUI that the purchase is finished.
onStartRestore()	Optional. The callback can be invoked to notify AdaptyUI that the restore is started.
onFinishRestore()	Optional. The callback can be invoked to notify AdaptyUI that the restore is finished.

In order to display the visual flow on the device screen, you must first configure it.

To do this, call the method AdaptyUI.getFlowView() or create the AdaptyFlowView directly:

   val flowView = AdaptyUI.getFlowView(
       activity,
       flowConfiguration,
       products,
       eventListener,
       insets,
       customAssets,
       tagResolver,
       timerResolver,
       observerModeHandler, 
   )

   val flowView =
        AdaptyFlowView(activity) // or retrieve it from xml
   ...
   with(flowView) {
       showFlow(
           flowConfiguration,
           products,
					 eventListener,
           insets,
           customAssets,
           tagResolver,
           timerResolver,
					 observerModeHandler,
       )
   }

AdaptyFlowView flowView = AdaptyUI.getFlowView(
        activity,
        flowConfiguration,
        products,
        eventListener,
        insets,
        customAssets,
        tagResolver,
        timerResolver,
        observerModeHandler
);

AdaptyFlowView flowView =
  new AdaptyFlowView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
flowView.showFlow(flowConfiguration, products, eventListener, insets, customAssets, tagResolver, timerResolver, observerModeHandler);

<com.adapty.ui.AdaptyFlowView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

After the view has been successfully created, you can add it to the view hierarchy and display it.

To do this, use this composable function:

AdaptyFlowScreen(
    flowConfiguration,
    products,
    eventListener,
    insets,
    customAssets,
    tagResolver,
    timerResolver,
    observerModeHandler,
)

Request parameters:

Parameter	Presence	Description
flowConfiguration	required	Supply an `AdaptyUI.FlowConfiguration` object containing visual details of the flow. Use the `AdaptyUI.getFlowConfiguration(flow)` method to load it. Refer to Fetch the view configuration topic for more details.
products	optional	Provide an array of `AdaptyPaywallProduct` to optimize the display timing of products on the screen. If `null` is passed, AdaptyUI will automatically fetch the required products.
eventListener	optional	Provide an `AdaptyFlowEventListener` to observe flow events. Extending `AdaptyFlowDefaultEventListener` is recommended for ease of use. Refer to Handle flow & paywall events topic for more details.
insets	optional	Insets are the spaces around the flow that prevent tapable elements from getting hidden behind system bars. Default: `Unspecified`, which lets Adapty adjust the insets automatically. See Change flow insets.
customAssets	optional	Pass an `AdaptyCustomAssets` object to replace images and videos in your flow at runtime. Refer to Customize assets for more details.
tagResolver	optional	Use `AdaptyUiTagResolver` to resolve custom tags within the flow text. This resolver takes a tag parameter and resolves it to a corresponding string.
observerModeHandler	required for Observer mode	The `AdaptyUiObserverModeHandler` you’ve implemented in the previous step.

Warning

Don’t forget to associate paywalls to purchase transactions. Otherwise, Adapty will not determine the source flow of the purchase.

Before you start presenting paywalls (Click to Expand)

Set up initial integration of Adapty with the Google Play and with the App Store.
Install and configure Adapty SDK. Make sure to set the observerMode parameter to true. Refer to our framework-specific instructions for Android.
Create products in the Adapty Dashboard.
Configure paywalls, assign products to them, and customize them using Paywall Builder in the Adapty Dashboard.
Create placements and assign your paywalls to them in the Adapty Dashboard.
Fetch Paywall Builder paywalls and their configuration in your mobile app code.

Implement the AdaptyUiObserverModeHandler.

The onPurchaseInitiated event will inform you that the user has initiated a purchase. You can trigger your custom purchase flow in response to this callback:

Note

Adapty Android SDK versions before 3.15.0 also passed the paywall and the paywall view to this callback. Drop those two parameters when you upgrade to 3.15.0 or later.

val observerModeHandler =
 AdaptyUiObserverModeHandler { product, onStartPurchase, onFinishPurchase ->
    onStartPurchase()
    yourBillingClient.makePurchase(
        product,
        onSuccess = { purchase ->
            onFinishPurchase()
            //handle success
        },
        onError = {
            onFinishPurchase()
            //handle error
        },
        onCancel = {
            onFinishPurchase()
            //handle cancel
        }
    )
}

AdaptyUiObserverModeHandler observerModeHandler = (product, onStartPurchase, onFinishPurchase) -> {
    onStartPurchase.invoke();
    yourBillingClient.makePurchase(
        product,
        purchase -> {
            onFinishPurchase.invoke();
            //handle success
        },
        error -> {
            onFinishPurchase.invoke();
            //handle error
        },
        () -> { //cancellation
            onFinishPurchase.invoke();
            //handle cancel
        }
    );
};

val observerModeHandler = object : AdaptyUiObserverModeHandler {
    override fun onPurchaseInitiated(
        product: AdaptyPaywallProduct,
        onStartPurchase: AdaptyUiObserverModeHandler.PurchaseStartCallback,
        onFinishPurchase: AdaptyUiObserverModeHandler.PurchaseFinishCallback,
    ) {
        // the same body as the purchase example above
    }

    override fun getRestoreHandler() =
        AdaptyUiObserverModeHandler.RestoreHandler { onStartRestore, onFinishRestore ->
            onStartRestore()
            yourBillingClient.restorePurchases(
                onSuccess = { restoredPurchases ->
                    onFinishRestore()
                    //handle successful restore
                },
                onError = {
                    onFinishRestore()
                    //handle error
                }
            )
        }
}

AdaptyUiObserverModeHandler observerModeHandler = new AdaptyUiObserverModeHandler() {
    @Override
    public void onPurchaseInitiated(
        AdaptyPaywallProduct product,
        PurchaseStartCallback onStartPurchase,
        PurchaseFinishCallback onFinishPurchase
    ) {
        // the same body as the purchase example above
    }

    @Override
    public RestoreHandler getRestoreHandler() {
        return (onStartRestore, onFinishRestore) -> {
            onStartRestore.invoke();
            yourBillingClient.restorePurchases(
                restoredPurchases -> {
                    onFinishRestore.invoke();
                    //handle successful restore
                },
                error -> {
                    onFinishRestore.invoke();
                    //handle error
                }
            );
        };
    }
};

Remember to invoke the following callbacks to notify AdaptyUI about the purchase or restore process. This is necessary for proper paywall behavior, such as showing the loader:

Callback	Description
onStartPurchase()	The callback should be invoked to notify AdaptyUI that the purchase is started.
onFinishPurchase()	The callback should be invoked to notify AdaptyUI that the purchase is finished.
onStartRestore()	Optional. The callback can be invoked to notify AdaptyUI that the restore is started.
onFinishRestore()	Optional. The callback can be invoked to notify AdaptyUI that the restore is finished.

In order to display the visual paywall on the device screen, you must first configure it.

To do this, call the method AdaptyUI.getPaywallView() or create the AdaptyPaywallView directly:

   val paywallView = AdaptyUI.getPaywallView(
       activity,
       viewConfiguration,
       products,
       eventListener,
       personalizedOfferResolver,
       tagResolver,
       timerResolver,
       observerModeHandler, 
   )

   val paywallView =
        AdaptyPaywallView(activity) // or retrieve it from xml
   ...
   with(paywallView) {
       showPaywall(
           viewConfiguration,
           products,
					 eventListener,
           personalizedOfferResolver,
           tagResolver,
           timerResolver,
					 observerModeHandler,
       )
   }

AdaptyPaywallView paywallView = AdaptyUI.getPaywallView(
        activity,
        viewConfiguration,
        products,
        eventListener,
        personalizedOfferResolver,
        tagResolver,
        timerResolver,
        observerModeHandler
);

AdaptyPaywallView paywallView =
  new AdaptyPaywallView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
paywallView.showPaywall(viewConfiguration, products, eventListener, personalizedOfferResolver, tagResolver, timerResolver, observerModeHandler);

<com.adapty.ui.AdaptyPaywallView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

After the view has been successfully created, you can add it to the view hierarchy and display it.

To do this, use this composable function:

AdaptyPaywallScreen(
    viewConfiguration,
    products,
    eventListener,
    personalizedOfferResolver,
    tagResolver,
    timerResolver,
)

Request parameters:

Parameter	Presence	Description
Products	optional	Provide an array of `AdaptyPaywallProduct` to optimize the display timing of products on the screen. If `null` is passed, AdaptyUI will automatically fetch the required products.
ViewConfiguration	required	Supply an `AdaptyViewConfiguration` object containing visual details of the paywall. Use the `Adapty.getViewConfiguration(paywall)` method to load it. Refer to Fetch the visual configuration of paywall topic for more details.
EventListener	optional	Provide an `AdaptyUiEventListener` to observe paywall events. Extending AdaptyUiDefaultEventListener is recommended for ease of use. Refer to Handling paywall events topic for more details.
PersonalizedOfferResolver	optional	To indicate personalized pricing (read more ), implement `AdaptyUiPersonalizedOfferResolver` and pass your own logic that maps `AdaptyPaywallProduct` to true if the product’s price is personalized, otherwise false.
TagResolver	optional	Use `AdaptyUiTagResolver` to resolve custom tags within the paywall text. This resolver takes a tag parameter and resolves it to a corresponding string. Refer to Custom tags in Paywall Builder topic for more details.
ObserverModeHandler	required for Observer mode	The `AdaptyUiObserverModeHandler` you’ve implemented in the previous step.
variationId	required	The string identifier of the variation. You can get it using `variationId` property of the `AdaptyPaywall` object.
transaction	required	For iOS, StoreKit1: an `SKPaymentTransaction` object. For iOS, StoreKit 2: Transaction object. For Android: String identifier (`purchase.getOrderId()`) of the purchase, where the purchase is an instance of the billing library Purchase class.

Before you start presenting paywalls (Click to Expand)

Set up initial integration of Adapty with the Google Play and with the App Store.
Install and configure Adapty SDK. Make sure to set the observerMode parameter to true. Refer to our framework-specific instructions for Android, React Native, Flutter, and Unity.
Create products in the Adapty Dashboard.
Configure paywalls, assign products to them, and customize them using Paywall Builder in the Adapty Dashboard.
Create placements and assign your paywalls to them in the Adapty Dashboard.
Fetch Paywall Builder paywalls and their configuration in your mobile app code.

Implement the AdaptyUiObserverModeHandler. The AdaptyUiObserverModeHandler’s callback (onPurchaseInitiated) informs you when the user initiates a purchase. You can trigger your custom purchase flow in response to this callback like this:

val observerModeHandler =
AdaptyUiObserverModeHandler { product, paywall, paywallView, onStartPurchase, onFinishPurchase ->
    onStartPurchase()
    yourBillingClient.makePurchase(
        product,
        onSuccess = { purchase ->
            onFinishPurchase()
            //handle success
        },
        onError = {
            onFinishPurchase()
            //handle error
        },
        onCancel = {
            onFinishPurchase()
            //handle cancel
        }
    )
}

AdaptyUiObserverModeHandler observerModeHandler = (product, paywall, paywallView, onStartPurchase, onFinishPurchase) -> {
    onStartPurchase.invoke();
    yourBillingClient.makePurchase(
        product,
        purchase -> {
            onFinishPurchase.invoke();
            //handle success
        },
        error -> {
            onFinishPurchase.invoke();
            //handle error
        },
        () -> { //cancellation
            onFinishPurchase.invoke();
            //handle cancel
        }
    );
};

Also, remember to invoke these callbacks to AdaptyUI. This is necessary for proper paywall behavior, such as showing the loader, among other things:

Callback in Kotlin	Callback in Java	Description
onStartPurchase()	onStartPurchase.invoke()	The callback should be invoked to notify AdaptyUI that the purchase is started.
onFinishPurchase()	onFinishPurchase.invoke()	The callback should be invoked to notify AdaptyUI that the purchase is finished successfully or not, or the purchase is canceled.

In order to display the visual paywall, you must first initialize it. To do this, call the method AdaptyUI.getPaywallView() or create the AdaptyPaywallView directly:

val paywallView = AdaptyUI.getPaywallView(
    activity,
    viewConfiguration,
    products,
    AdaptyPaywallInsets.of(topInset, bottomInset),
    eventListener,
    personalizedOfferResolver,
    tagResolver,
    observerModeHandler,
)

//======= OR =======

val paywallView =
     AdaptyPaywallView(activity) // or retrieve it from xml
...
with(paywallView) {
    setEventListener(eventListener)
    setObserverModeHandler(observerModeHandler)
    showPaywall(
        viewConfiguration,
        products,
        AdaptyPaywallInsets.of(topInset, bottomInset),
        personalizedOfferResolver,
        tagResolver,
    )
}

AdaptyPaywallView paywallView = AdaptyUI.getPaywallView(
        activity,
        viewConfiguration,
        products,
        AdaptyPaywallInsets.of(topInset, bottomInset),
        eventListener,
        personalizedOfferResolver,
        tagResolver,
        observerModeHandler
);

//======= OR =======

AdaptyPaywallView paywallView =
  new AdaptyPaywallView(activity); //add to the view hierarchy if needed, or you receive it from xml
...
paywallView.setEventListener(eventListener);
paywallView.setObserverModeHandler(observerModeHandler);
paywallView.showPaywall(viewConfiguration, products, AdaptyPaywallInsets.of(topInset, bottomInset), personalizedOfferResolver);

<com.adapty.ui.AdaptyPaywallView xmlns:android="http://schemas.android.com/apk/res/android"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

After the view has been successfully created, you can add it to the view hierarchy and display it.

Request parameters:

Parameter	Presence	Description
Products	optional	Provide an array of `AdaptyPaywallProduct` to optimize the display timing of products on the screen. If `null` is passed, AdaptyUI will automatically fetch the required products.
ViewConfiguration	required	Supply an `AdaptyViewConfiguration` object containing visual details of the paywall. Use the `Adapty.getViewConfiguration(paywall)` method to load it. Refer to Fetch the visual configuration of paywall topic for more details.
Insets	required	Define an `AdaptyPaywallInsets` object containing information about the area overlapped by system bars, creating vertical margins for content. If neither the status bar nor the navigation bar overlaps the `AdaptyPaywallView`, pass `AdaptyPaywallInsets.NONE`. For fullscreen mode where system bars overlap part of your UI, obtain insets as shown under the table.
EventListener	optional	Provide an `AdaptyUiEventListener` to observe paywall events. Extending AdaptyUiDefaultEventListener is recommended for ease of use. Refer to Handling paywall events topic for more details.
PersonalizedOfferResolver	optional	To indicate personalized pricing (read more ), implement `AdaptyUiPersonalizedOfferResolver` and pass your own logic that maps `AdaptyPaywallProduct` to true if the product’s price is personalized, otherwise false.
TagResolver	optional	Use `AdaptyUiTagResolver` to resolve custom tags within the paywall text. This resolver takes a tag parameter and resolves it to a corresponding string. Refer to Custom tags in Paywall Builder topic for more details.
ObserverModeHandler	required for Observer mode	The `AdaptyUiObserverModeHandler` you’ve implemented in the previous step.
variationId	required	The string identifier of the variation. You can get it using `variationId` property of the `AdaptyPaywall` object.
transaction	required	For iOS, StoreKit1: an `SKPaymentTransaction` object. For iOS, StoreKit 2: Transaction object. For Android: String identifier (`purchase.getOrderId()`) of the purchase, where the purchase is an instance of the billing library Purchase class.

For fullscreen mode where system bars overlap part of your UI, obtain insets in the following way:

import androidx.core.graphics.Insets
import androidx.core.view.ViewCompat
import androidx.core.view.WindowInsetsCompat

//create extension function
fun View.onReceiveSystemBarsInsets(action: (insets: Insets) -> Unit) {
    ViewCompat.setOnApplyWindowInsetsListener(this) { _, insets ->
        val systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars())
        ViewCompat.setOnApplyWindowInsetsListener(this, null)
        action(systemBarInsets)
        insets
    }
}
//and then use it with the view
paywallView.onReceiveSystemBarsInsets { insets ->
    val paywallInsets = AdaptyPaywallInsets.of(insets.top, insets.bottom)
    paywallView.setEventListener(eventListener)
    paywallView.setObserverModeHandler(observerModeHandler)
    paywallView.showPaywall(viewConfig, products, paywallInsets, personalizedOfferResolver, tagResolver)
}

import androidx.core.graphics.Insets;
import androidx.core.view.ViewCompat;
import androidx.core.view.WindowInsetsCompat;

...

ViewCompat.setOnApplyWindowInsetsListener(paywallView, (view, insets) -> {
    Insets systemBarInsets = insets.getInsets(WindowInsetsCompat.Type.systemBars());
    ViewCompat.setOnApplyWindowInsetsListener(paywallView, null);
  
    AdaptyPaywallInsets paywallInsets =
                 AdaptyPaywallInsets.of(systemBarInsets.top, systemBarInsets.bottom);
    paywallView.setEventListener(eventListener);
    paywallView.setObserverModeHandler(observerModeHandler);
    paywallView.showPaywall(viewConfiguration, products, paywallInsets, personalizedOfferResolver, tagResolver);
            
    return insets;
});

Returns:

Object	Description
`AdaptyPaywallView`	object, representing the requested paywall screen.

Warning

Don’t forget to Associate paywalls to purchase transactions. Otherwise, Adapty will not determine the source paywall of the purchase.