Display custom elements with the Android SDK
When a screen with a custom element opens, the Adapty SDK passes the element’s Type and ID to a resolver in your app code. The resolver returns one of the following:
- The view that matches the Type and ID: Users see the native view, such as a Lottie animation, an interactive chart, or a camera preview.
- No view: Users see the fallback, which is the content inside the custom element in the Flow & Paywall Builder.
Users of app versions without the resolver also see the fallback. Therefore, you can publish the flow before you release the app.
Before you start
You need:
- Adapty Android SDK 4.4 or later: Earlier versions show the fallback for every custom element.
- A native Android app: The Adapty SDKs for cross-platform frameworks, such as Flutter, show the fallback for every custom element.
- A naming scheme for custom elements: Give each native view a Type, such as
lottie_animation. Use only lowercase letters, numbers, and underscores in Types. To distinguish between custom elements of the same Type, give each one an ID, such aswelcome_wave. The Types and IDs in your code must match the ones in the Flow & Paywall Builder.
If your iOS app already displays custom elements, reuse its Types and IDs. Unless you set up a separate audience for each platform, iOS and Android users see the same flows.
Create views for custom elements
For each Type, create or reuse a composable/Android View. The following views of the lottie_animation Type play a Lottie animation from the assets folder of your app. The Kotlin example is a composable that uses the com.airbnb.android:lottie-compose library. The Java example creates an Android View from the com.airbnb.android:lottie library:
Requirements and best practices
-
Sizing:
- Padding and alignment: Make sure the native view fits the container you allocated for it in the Flow & Paywall Builder, minus the padding. If the view doesn’t take up the entire area, it appears in the top start corner of that area by default. To move it, change the alignment in the Layout section of the custom element.
- Hug height: If the height of the custom element is set to Hug, a view that stretches to fill the available space (like a lazy list) will collapse, or stretch to the height of the screen. Give the custom element a Fixed height instead.
-
Theme: To display a composable in the colors and fonts of your app on a screen built with Views, wrap it in your Compose theme.
-
Flow actions: The native view can’t trigger flow actions, such as a transition to the next screen. Keep navigation buttons, purchase buttons, and other buttons with flow actions outside the custom element.
-
Selectable elements: Keep the custom element outside product cards and other selectable elements. When the selection changes, the native view can lose its state.
-
Navigation handling: When the user moves to the next screen, the SDK removes the native view from the screen. Stop what the view started, such as camera sessions, players, and location updates:
- Composable: Use the
onDisposeblock of aDisposableEffect. For async work, useLaunchedEffect: Compose cancels it when the composable leaves the composition. - Android
View: OverrideonDetachedFromWindowin yourViewsubclass, or add aView.OnAttachStateChangeListenerto theView.
When the user comes back, or after a configuration change such as a rotation, the SDK calls the resolver again, and creates a new native view without the state of the previous one.
- Composable: Use the
-
Carousels: In a carousel, the native views on all slides stay active while the screen is open, not only the view on the visible slide. Keep camera previews and players with sound out of carousels.
Write a resolver to match custom elements and views
To write a resolver, implement the AdaptyCustomElementsResolver interface. Its resolve method receives the Type and ID of a custom element, and returns the matching view in one of the following forms:
- A composable: Return
AdaptyCustomElementContent.compose, with the composable inside its lambda. - An Android
View: ReturnAdaptyCustomElementContent.view, with a function that creates theView. In Kotlin, name thefactoryparameter:AdaptyCustomElementContent.view(factory = { context, _ -> ChartView(context) }). Without the name, Kotlin passes a trailing lambda to the optionalupdateparameter, and the code doesn’t compile.
For the lottie_animation Type, the following resolver returns the Lottie view. The ID names the animation file in the assets folder, such as welcome_wave for welcome_wave.json:
For any other Type, return null. If you add a custom element with a new Type after you release the app, users of the released version see its fallback.
The resolver has the following requirements:
-
Network data and players: Keep network data and players in the state of the native view, not in the resolver. The SDK calls the resolver many times while the screen is open. Code in the resolver runs again on each call, so network requests repeat and players start over. The SDK doesn’t recreate the native view between these calls, so the data loads once and the players keep playing. Create players, sessions, and network requests inside the native view:
- Composable: Create players and sessions in
remember, and network requests inLaunchedEffect. - Android
View: Create players, sessions, and network requests inonAttachedToWindow.
- Composable: Create players and sessions in
-
One native view per custom element: Some native views change while the screen is open, for example, when their data loads or when the user taps them. Implement this logic in the native view itself, not in the resolver. If the resolver returns a different composable for the same custom element, Compose resets the state of the view.
-
A new
Viewfor each appearance: Create a newViewin each call offactory. The SDK callsfactoryeach time the custom element appears, such as when the screen opens, when the user returns to the screen, or after a rotation. -
App data: Store an object that holds the data, such as a
StateFlowor aLiveDatawith a daily streak, in a property of the resolver. Pass the object to the native view, and observe the object there:- Composable: Collect a
StateFlowwithcollectAsState, or observe aLiveDatawithobserveAsState. - Android
View: Observe the object inonAttachedToWindow, and stop inonDetachedFromWindow.
A value that you copy into the resolver, such as the streak number, stays as it was when you created the resolver.
- Composable: Collect a
Set conditions for fallback content
To show users the fallback content instead of an empty custom element, return no view in the following situations:
- Nothing to visualize — the necessary animation file or data file is missing.
- Nothing to process — the user skipped a quiz question, and the data is incomplete.
- Access prohibited — a denied permission prevents the view from accessing a resource.
For example, the resolver returns no view when the animation file is missing.
For a permission, return null only when the user denied it before the screen opened. ContextCompat.checkSelfPermission returns the same value, PERMISSION_DENIED, in two cases: before your app first asks the user for the permission, and after the user denies it. To tell these cases apart, save the result of the permission request, and read the saved result in the resolver. If your app hasn’t requested the permission yet, return the native view instead of null, and request the permission inside the view. For example, request location access when a map view appears, and show the map as soon as the user grants access. If you return null and the user grants access afterwards, they still see the fallback. A permission change doesn’t make the SDK call the resolver again. The native view appears only after the SDK calls the resolver again, such as when the user returns to the screen.
Pass the resolver to the SDK
Start with an app-wide resolver. The SDK calls it in every flow without a resolver of its own. Users see your native views in new flows and A/B tests without an app release. These views still show each user their own data, such as a daily streak, because they read that data from your app.
Attach a resolver to one flow when the flow requires data that your app only has when it opens that flow. For example, a paywall displays the weight that the user entered in a previous flow, or previews the document that the user wants to export. You can also attach a resolver to one flow to show a different view for a Type in that flow.
Display views in every flow
To use the resolver in every flow, call AdaptyUI.setCustomElementsResolver once, such as in the onCreate method of your Application class:
To show the same view in every custom element of a Type, pass a map of Types and views to AdaptyCustomElementsResolver.of. A map demands less code than a resolver class, but you cannot set conditions for fallback content.
val appWideViews = mapOf(
"confetti" to AdaptyCustomElementContent.compose { LottieElement("confetti.json") },
)
AdaptyUI.setCustomElementsResolver(AdaptyCustomElementsResolver.of(appWideViews))Display data for one flow, such as a document to export
A resolver that you pass to a flow view replaces the app-wide resolver in that flow view.
To keep the app-wide views in this flow, pass the app-wide resolver to this resolver, and call the app-wide resolver for the other Types and IDs. The following resolver previews the document that the user wants to export, and calls the app-wide resolver for every other custom element:
Pass the resolver in the customElementsResolver parameter of AdaptyUI.getFlowView:
If you create AdaptyFlowView yourself, pass the resolver to its showFlow method. In Java, showFlow takes the same arguments as getFlowView, except activity. In Jetpack Compose, pass the resolver to AdaptyFlowScreen. For an example of each call, read Display flows & paywalls.
If you use AdaptyCustomElementsResolver.of instead of resolver classes, merge the map of app-wide views with a map for this flow: AdaptyCustomElementsResolver.of(appWideViews + flowViews). Pass the result to the flow view. For a Type in both maps, this code keeps the view for this flow.
Test on a device
The Flow & Paywall Builder can’t run your app code, so its canvas only shows the fallback. An error in the native view can crash the app. Before you release the app, test every screen that has a custom element on a device:
-
To see the latest published version of each flow instead of a cached one, register the device as a test device.
-
To see the warnings of the Adapty SDK in Logcat, set the log level to
AdaptyLogLevel.WARNor a more detailed level. With the default level,AdaptyLogLevel.NONE, the SDK logs nothing. -
On the device, run a build that includes the resolver. Open each screen that has a custom element, and verify that the native view appears and fits the custom element. If the view scrolls or responds to drags, test these gestures.
-
If the fallback appears instead of the native view, find this warning in Logcat:
custom element <type>:<id> is not served by a resolver. Then verify that:- The Type and ID in the warning match the ones in your code, letter for letter.
- Your app has the file, data, or permission that the view needs.
- Your app sets the app-wide resolver.
- A resolver for this flow, if you pass one, returns a view for the Type and ID.
If the warning doesn’t appear, verify that the app uses Adapty Android SDK 4.4 or later.
-
If the custom element stays empty, find one of these warnings in Logcat:
custom element <type>:<id> is not served by a resolver: The custom element has no fallback content, and no resolver returns a view for it. Verify each item in step 4.content does not report its size: The composable has no height of its own. Give the custom element a Fixed height.
The SDK only logs the size warning for composables. If an Android
Viewstays empty with no warning, give the custom element a Fixed height too. -
To preview the fallback, return
nullfor the Type, and open the screen again.
Examples
Each recipe shows the setup in the builder and the code for your app:
- Show user progress with a Lottie animation: A ring that fills as a streak grows.
- Show an interactive weight goal chart in a paywall: A weight goal chart, in the paywall flow that follows the onboarding flow.
- Show nearby places on a map in a flow: A map of fitness centers near each user.