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.
Follow this recipe to include an interactive map in a flow. The map shows your places, such as partner fitness centers, within 2 km of the user. Your app renders the map as a native view in a custom element, with MapLibre. Your app requests location access on the flow screen.
Before you start
Update your app to Adapty Android SDK 4.4 or later. Earlier SDK versions show the fallback content for every custom element.
To ask users for location access, display flows in an activity that extends ComponentActivity, such as AppCompatActivity.
Add MapLibre to your app with Gradle, from org.maplibre.gl:android-sdk-opengl. With this artifact, Google Play also offers your app to devices without Vulkan, which the default android-sdk artifact requires.
Set minSdk to 23 or higher, as MapLibre requires.
To limit your app to approximate location, add the following inside the <manifest> element of AndroidManifest.xml. Make sure that the <manifest> element declares xmlns:tools="http://schemas.android.com/tools".
In the Flow & Paywall Builder, add a custom element to a flow screen, and set it up for the map:
Type: map.
ID: fitness_centers.
Height: Keep the default Fixed height. The map fills the custom element.
Keep the custom element out of containers that respond to touch, such as a carousel, so that only the map responds to a drag on it.
Inside the custom element, add an Image with a picture of a map. Users see it as the fallback when:
Their version of your app doesn’t display the map.
They denied location access before the screen opened.
If the user hasn’t answered the location access prompt yet, your app shows it when the map appears. To tell users why your app needs their location, add a text element above the custom element, such as “Find fitness centers near you.”
2. Create the map view
Create a type for your places, and a model for location access:
import android.Manifestimport android.content.Contextimport android.content.ContextWrapperimport android.content.pm.PackageManagerimport androidx.activity.ComponentActivityimport androidx.activity.result.ActivityResultLauncherimport androidx.activity.result.contract.ActivityResultContracts.RequestPermissionimport androidx.core.content.ContextCompat// a place of your app, such as a partner fitness centerdata class Place(val name: String, val latitude: Double, val longitude: Double)private const val PERMISSION = Manifest.permission.ACCESS_COARSE_LOCATION // approximate location// one location access model for the resolver and the map viewclass LocationAccess(context: Context) { private val appContext = context.applicationContext // checkSelfPermission returns the same value before the first request and after a denial: save the answer private val answers = appContext.getSharedPreferences("location_access", Context.MODE_PRIVATE) private var isAsking = false var isMapOnScreen = false val isAllowed: Boolean get() = ContextCompat.checkSelfPermission(appContext, PERMISSION) == PackageManager.PERMISSION_GRANTED val isDenied: Boolean get() = !isAllowed && answers.getBoolean("denied", false) // requests location access and saves the answer // unregister the returned launcher when the view leaves the screen fun requestAccess(activity: ComponentActivity, onAnswer: (Boolean) -> Unit): ActivityResultLauncher<String> { val isPromptOpen = isAsking // after a screen rotation, this request receives the answer from the open prompt val request = activity.activityResultRegistry.register("location_access", RequestPermission()) { granted -> isAsking = false answers.edit().putBoolean("denied", !granted).apply() onAnswer(granted) } if (!isPromptOpen) { isAsking = true request.launch(PERMISSION) } return request }}// the activity that shows the flowtailrec fun Context.findComponentActivity(): ComponentActivity = this as? ComponentActivity ?: (this as ContextWrapper).baseContext.findComponentActivity()
import android.Manifest;import android.content.Context;import android.content.ContextWrapper;import android.content.SharedPreferences;import android.content.pm.PackageManager;import androidx.activity.ComponentActivity;import androidx.activity.result.ActivityResultCallback;import androidx.activity.result.ActivityResultLauncher;import androidx.activity.result.contract.ActivityResultContracts.RequestPermission;import androidx.core.content.ContextCompat;// a place of your app, such as a partner fitness centerpublic class Place { public final String name; public final double latitude; public final double longitude; public Place(String name, double latitude, double longitude) { this.name = name; this.latitude = latitude; this.longitude = longitude; }}// one location access model for the resolver and the map viewpublic class LocationAccess { private static final String PERMISSION = Manifest.permission.ACCESS_COARSE_LOCATION; // approximate location private final Context appContext; // checkSelfPermission returns the same value before the first request and after a denial: save the answer private final SharedPreferences answers; private boolean isAsking; public boolean isMapOnScreen; public LocationAccess(Context context) { appContext = context.getApplicationContext(); answers = appContext.getSharedPreferences("location_access", Context.MODE_PRIVATE); } public boolean isAllowed() { return ContextCompat.checkSelfPermission(appContext, PERMISSION) == PackageManager.PERMISSION_GRANTED; } public boolean isDenied() { return !isAllowed() && answers.getBoolean("denied", false); } // requests location access and saves the answer // unregister the returned launcher when the view leaves the screen public ActivityResultLauncher<String> requestAccess(ComponentActivity activity, ActivityResultCallback<Boolean> onAnswer) { boolean isPromptOpen = isAsking; // after a screen rotation, this request receives the answer from the open prompt ActivityResultLauncher<String> request = activity.getActivityResultRegistry().register( "location_access", new RequestPermission(), granted -> { isAsking = false; answers.edit().putBoolean("denied", !granted).apply(); onAnswer.onActivityResult(granted); }); if (!isPromptOpen) { isAsking = true; request.launch(PERMISSION); } return request; } // the activity that shows the flow public static ComponentActivity findComponentActivity(Context context) { while (!(context instanceof ComponentActivity)) { context = ((ContextWrapper) context).getBaseContext(); } return (ComponentActivity) context; }}
Create a view with a map. The view requests location access and displays a marker for each of your places within 2 km of the user:
import android.annotation.SuppressLintimport android.content.Contextimport android.graphics.Colorimport android.location.Locationimport android.os.Looperimport android.view.Gravityimport android.widget.FrameLayoutimport android.widget.TextViewimport androidx.activity.result.ActivityResultLauncherimport androidx.lifecycle.DefaultLifecycleObserverimport androidx.lifecycle.LifecycleOwnerimport org.maplibre.android.MapLibreimport org.maplibre.android.camera.CameraUpdateFactoryimport org.maplibre.android.geometry.LatLngimport org.maplibre.android.location.LocationComponentActivationOptionsimport org.maplibre.android.location.engine.LocationEngineCallbackimport org.maplibre.android.location.engine.LocationEngineDefaultimport org.maplibre.android.location.engine.LocationEngineRequestimport org.maplibre.android.location.engine.LocationEngineResultimport org.maplibre.android.maps.MapViewimport org.maplibre.android.style.layers.CircleLayerimport org.maplibre.android.style.layers.PropertyFactoryimport org.maplibre.android.style.sources.GeoJsonSourceimport org.maplibre.geojson.Featureimport org.maplibre.geojson.FeatureCollectionimport org.maplibre.geojson.Point// map tiles without an API keyconst val MAP_STYLE_URL = "https://tiles.openfreemap.org/styles/liberty"class NearbyFitnessCentersMap( context: Context, private val access: LocationAccess, private val places: List<Place>,) : FrameLayout(context), DefaultLifecycleObserver, LocationEngineCallback<LocationEngineResult> { private val activity = context.findComponentActivity() private val locationEngine = LocationEngineDefault.getDefaultLocationEngine(context) private val mapView: MapView private var permissionRequest: ActivityResultLauncher<String>? = null init { MapLibre.getInstance(context) mapView = MapView(context) mapView.onCreate(null) mapView.getMapAsync { map -> map.setStyle(MAP_STYLE_URL) } addView(mapView) } override fun onAttachedToWindow() { super.onAttachedToWindow() access.isMapOnScreen = true // tells the resolver that the map is on the screen activity.lifecycle.addObserver(this) when { access.isAllowed -> showUser() access.isDenied -> showAccessOff() else -> permissionRequest = access.requestAccess(activity) { granted -> if (granted) showUser() else showAccessOff() } } } override fun onDetachedFromWindow() { access.isMapOnScreen = false permissionRequest?.unregister() locationEngine.removeLocationUpdates(this) activity.lifecycle.removeObserver(this) // the SDK creates a new view each time the custom element appears: release this map mapView.onPause() mapView.onStop() mapView.onDestroy() super.onDetachedFromWindow() } // passes the lifecycle of the activity to the map override fun onStart(owner: LifecycleOwner) = mapView.onStart() override fun onResume(owner: LifecycleOwner) = mapView.onResume() override fun onPause(owner: LifecycleOwner) = mapView.onPause() override fun onStop(owner: LifecycleOwner) = mapView.onStop() @SuppressLint("MissingPermission") // runs only after the user allows location access private fun showUser() = mapView.getMapAsync { map -> map.getStyle { style -> val options = LocationComponentActivationOptions.builder(context, style).locationEngine(locationEngine) map.locationComponent.activateLocationComponent(options.build()) map.locationComponent.isLocationComponentEnabled = true val request = LocationEngineRequest.Builder(1_000).build() // milliseconds between updates locationEngine.requestLocationUpdates(request, this, Looper.getMainLooper()) // calls onSuccess } } // the first location of the user override fun onSuccess(result: LocationEngineResult) { val user = result.lastLocation ?: return locationEngine.removeLocationUpdates(this) showPlaces(user) } override fun onFailure(exception: Exception) = Unit // a teal circle for each of your places within 2 km of the user private fun showPlaces(user: Location) = mapView.getMapAsync { map -> val distance = FloatArray(1) val pins = places.filter { place -> Location.distanceBetween(user.latitude, user.longitude, place.latitude, place.longitude, distance) distance[0] <= 2_000 // meters }.map { place -> Feature.fromGeometry(Point.fromLngLat(place.longitude, place.latitude)) } map.getStyle { style -> style.addSource(GeoJsonSource("places", FeatureCollection.fromFeatures(pins))) val teal = PropertyFactory.circleColor(Color.rgb(0, 128, 128)) style.addLayer(CircleLayer("pins", "places").withProperties(teal, PropertyFactory.circleRadius(8f))) } // zoom in on the area around the user map.animateCamera(CameraUpdateFactory.newLatLngZoom(LatLng(user.latitude, user.longitude), 12.0)) } private fun showAccessOff() { mapView.visibility = GONE addView(TextView(context).apply { text = "Location access is off. To see fitness centers near you, allow location access in Settings." gravity = Gravity.CENTER }) }}
The view loads the map from OpenFreeMap, a free service that needs no API key and has no uptime guarantee. To switch to another tile source, change the MAP_STYLE_URL constant.
import android.annotation.SuppressLint;import android.content.Context;import android.graphics.Color;import android.location.Location;import android.os.Looper;import android.view.Gravity;import android.widget.FrameLayout;import android.widget.TextView;import androidx.activity.ComponentActivity;import androidx.activity.result.ActivityResultLauncher;import androidx.lifecycle.DefaultLifecycleObserver;import androidx.lifecycle.LifecycleOwner;import java.util.ArrayList;import java.util.List;import org.maplibre.android.MapLibre;import org.maplibre.android.camera.CameraUpdateFactory;import org.maplibre.android.geometry.LatLng;import org.maplibre.android.location.LocationComponentActivationOptions;import org.maplibre.android.location.engine.*;import org.maplibre.android.maps.MapView;import org.maplibre.android.style.layers.CircleLayer;import org.maplibre.android.style.layers.PropertyFactory;import org.maplibre.android.style.sources.GeoJsonSource;import org.maplibre.geojson.Feature;import org.maplibre.geojson.FeatureCollection;import org.maplibre.geojson.Point;public class NearbyFitnessCentersMap extends FrameLayout implements DefaultLifecycleObserver, LocationEngineCallback<LocationEngineResult> { // map tiles without an API key public static final String MAP_STYLE_URL = "https://tiles.openfreemap.org/styles/liberty"; private final LocationAccess access; private final List<Place> places; private final ComponentActivity activity = LocationAccess.findComponentActivity(getContext()); private final LocationEngine locationEngine = LocationEngineDefault.INSTANCE.getDefaultLocationEngine(getContext()); private final MapView mapView; private ActivityResultLauncher<String> permissionRequest; public NearbyFitnessCentersMap(Context context, LocationAccess access, List<Place> places) { super(context); this.access = access; this.places = places; MapLibre.getInstance(context); mapView = new MapView(context); mapView.onCreate(null); mapView.getMapAsync(map -> map.setStyle(MAP_STYLE_URL)); addView(mapView); } @Override protected void onAttachedToWindow() { super.onAttachedToWindow(); access.isMapOnScreen = true; // tells the resolver that the map is on the screen activity.getLifecycle().addObserver(this); if (access.isAllowed()) showUser(); else if (access.isDenied()) showAccessOff(); else permissionRequest = access.requestAccess(activity, granted -> { if (granted) showUser(); else showAccessOff(); }); } @Override protected void onDetachedFromWindow() { access.isMapOnScreen = false; if (permissionRequest != null) permissionRequest.unregister(); locationEngine.removeLocationUpdates(this); activity.getLifecycle().removeObserver(this); // the SDK creates a new view each time the custom element appears: release this map mapView.onPause(); mapView.onStop(); mapView.onDestroy(); super.onDetachedFromWindow(); } // passes the lifecycle of the activity to the map @Override public void onStart(LifecycleOwner owner) { mapView.onStart(); } @Override public void onResume(LifecycleOwner owner) { mapView.onResume(); } @Override public void onPause(LifecycleOwner owner) { mapView.onPause(); } @Override public void onStop(LifecycleOwner owner) { mapView.onStop(); } @SuppressLint("MissingPermission") // runs only after the user allows location access private void showUser() { mapView.getMapAsync(map -> map.getStyle(style -> { map.getLocationComponent().activateLocationComponent( LocationComponentActivationOptions.builder(getContext(), style).locationEngine(locationEngine).build()); map.getLocationComponent().setLocationComponentEnabled(true); LocationEngineRequest request = new LocationEngineRequest.Builder(1000).build(); // milliseconds between updates locationEngine.requestLocationUpdates(request, this, Looper.getMainLooper()); // calls onSuccess })); } // the first location of the user @Override public void onSuccess(LocationEngineResult result) { Location user = result.getLastLocation(); if (user == null) return; locationEngine.removeLocationUpdates(this); showPlaces(user); } @Override public void onFailure(Exception exception) {} // a teal circle for each of your places within 2 km of the user private void showPlaces(Location user) { List<Feature> pins = new ArrayList<>(); float[] distance = new float[1]; for (Place place : places) { Location.distanceBetween(user.getLatitude(), user.getLongitude(), place.latitude, place.longitude, distance); if (distance[0] > 2000) continue; // meters pins.add(Feature.fromGeometry(Point.fromLngLat(place.longitude, place.latitude))); } mapView.getMapAsync(map -> map.getStyle(style -> { style.addSource(new GeoJsonSource("places", FeatureCollection.fromFeatures(pins))); style.addLayer(new CircleLayer("pins", "places").withProperties( PropertyFactory.circleColor(Color.rgb(0, 128, 128)), PropertyFactory.circleRadius(8f))); // zoom in on the area around the user map.animateCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(user.getLatitude(), user.getLongitude()), 12)); })); } private void showAccessOff() { mapView.setVisibility(GONE); TextView message = new TextView(getContext()); message.setText("Location access is off. To see fitness centers near you, allow location access in Settings."); message.setGravity(Gravity.CENTER); addView(message); }}
The view loads the map from OpenFreeMap, a free service that needs no API key and has no uptime guarantee. To switch to another tile source, change the MAP_STYLE_URL constant.
If the user denies location access on the screen, the view replaces the map with a message about how to allow access in Settings.
3. Match the map to the custom element
In your app-wide resolver, add properties for the LocationAccess model and your places. Then return the map view for the map Type and the fitness_centers ID. The highlighted lines show what to add or change. If your app has no app-wide resolver yet, copy the whole code:
import android.content.Contextimport com.adapty.ui.AdaptyCustomElementContentimport com.adapty.ui.AdaptyCustomElementsResolverclass CustomElementsResolver( context: Context, private val places: List<Place>, // your app's places, such as partner fitness centers) : AdaptyCustomElementsResolver { private val locationAccess = LocationAccess(context) override fun resolve(type: String, id: String): AdaptyCustomElementContent? = when (type) { "map" -> when (id) { "fitness_centers" -> if (locationAccess.isDenied && !locationAccess.isMapOnScreen) { null // access denied before the screen opened: show the fallback } else { AdaptyCustomElementContent.view( factory = { context, _ -> NearbyFitnessCentersMap(context, locationAccess, places) }, ) } // the other maps of your resolver else -> null } // the other Types of your resolver else -> null }}
import android.content.Context;import com.adapty.ui.AdaptyCustomElementContent;import com.adapty.ui.AdaptyCustomElementsResolver;import java.util.List;public class CustomElementsResolver implements AdaptyCustomElementsResolver { private final LocationAccess locationAccess; private final List<Place> places; // your app's places, such as partner fitness centers public CustomElementsResolver(Context context, List<Place> places) { this.locationAccess = new LocationAccess(context); this.places = places; } @Override public AdaptyCustomElementContent resolve(String type, String id) { if (type.equals("map")) { if (id.equals("fitness_centers")) { if (locationAccess.isDenied() && !locationAccess.isMapOnScreen) { return null; // access denied before the screen opened: show the fallback } return AdaptyCustomElementContent.view( (context, elementContext) -> new NearbyFitnessCentersMap(context, locationAccess, places) ); } // the other maps of your resolver return null; } // the other Types of your resolver return null; }}
The SDK calls the resolver when the screen opens, and again each time it redraws the custom element while the screen is open. Location access determines what the resolver returns on each call:
Not answered yet: The map view, so that the view can request access.
Allowed: The map view, which shows your places near the user.
Denied before the screen opened: No view, so users see the fallback instead of the message about Settings.
Denied on the screen: The map view, because the view sets isMapOnScreen while it’s on the screen. If the resolver returned no view here, the SDK would replace the message about Settings with the fallback at the next call.
Create the resolver with your places, and set it as the app-wide resolver. Call AdaptyUI.setCustomElementsResolver once, such as at app launch:
import android.app.Applicationimport com.adapty.ui.AdaptyUIclass App : Application() { // your app's places, such as partner fitness centers val places = listOf( Place("Central Fitness", latitude = 52.5219, longitude = 13.4132), Place("Riverside Gym", latitude = 52.5163, longitude = 13.3777), ) // keep this instance: a resolver for one flow can reuse it // lazy: the context isn't attached yet while App is constructed val customElementsResolver by lazy { CustomElementsResolver(this, places) } override fun onCreate() { super.onCreate() AdaptyUI.setCustomElementsResolver(customElementsResolver) }}
import android.app.Application;import com.adapty.ui.AdaptyUI;import java.util.Arrays;import java.util.List;public class App extends Application { // your app's places, such as partner fitness centers private final List<Place> places = Arrays.asList( new Place("Central Fitness", 52.5219, 13.4132), new Place("Riverside Gym", 52.5163, 13.3777) ); // keep this instance: a resolver for one flow can reuse it private CustomElementsResolver customElementsResolver; @Override public void onCreate() { super.onCreate(); customElementsResolver = new CustomElementsResolver(this, places); AdaptyUI.setCustomElementsResolver(customElementsResolver); } public CustomElementsResolver getCustomElementsResolver() { return customElementsResolver; }}
4. Test on a device
The Flow & Paywall Builder can’t run your app code, so its canvas only shows the fallback. To preview the map:
Publish the flow. To see the latest published version instead of a cached one, register the device as a test device.
To see a marker on the map, add a place within 2 km of your location to your list of places.
Run a build of your app that includes the resolver. Open the screen, and allow location access. Verify that the map shows your location and a marker for the place that you added.
To test the fallback, in the Settings app, turn off location access for your app. Open the screen, and if the prompt appears, deny location access. The map view shows the message about Settings. Open the screen again, and verify that the fallback appears.
To find out why the fallback appears instead of the map, follow the instructions in the Test on a device section of the Android guide.