Skills cover SDK integration, building flows and paywalls, pre-publish audits, placement migration, and more. Describe the task in plain language and your agent picks the skill.
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.
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:
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()
Required if you set a restore handler. Invoke it to notify AdaptyUI that the restore is finished: until then, the flow ignores further restore taps and doesn’t run the When restore completed actions.
After onFinishPurchase(), the flow runs the When succeededoutcome actions whatever happened, a canceled purchase included. Show any screen that depends on the purchase result, such as a thank-you screen, from your code: only your code knows the result. After onFinishRestore(), the flow runs the When restore completed actions, whatever happened.
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 = AdaptyFlowView(activity) // or retrieve it from xml ... with(flowView) { showFlow( 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);
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
An AdaptyUiTagResolver that returns your app’s values for the flow’s custom tags. For details, read Pass data to flows.
observerModeHandler
required for Observer mode
The AdaptyUiObserverModeHandler you’ve implemented in the previous step.
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.
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 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 = AdaptyPaywallView(activity) // or retrieve it from xml ... with(paywallView) { showPaywall( 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);
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.
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.
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:
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);
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.