Les skills couvrent l'intégration du SDK, la création de flows et de paywalls, les audits avant publication, la migration des placements et bien plus encore. Décrivez la tâche en langage courant et votre agent choisira le skill adapté.
Suivez cette recette pour intégrer une carte interactive dans un flow. La carte affiche vos lieux, comme des salles de sport partenaires, dans un rayon de 2 km autour de l’utilisateur. Votre application affiche la carte sous forme de vue native dans un élément personnalisé, avec MapLibre. Votre application demande l’accès à la localisation sur l’écran du flow.
Avant de commencer
Mettez à jour votre application avec le SDK Android Adapty 4.4 ou une version ultérieure. Les versions antérieures du SDK affichent le contenu de secours pour chaque élément personnalisé.
Pour demander l’accès à la localisation aux utilisateurs, affichez les flows dans une activité qui étend ComponentActivity, comme AppCompatActivity.
Ajoutez MapLibre à votre application avec Gradle, depuis org.maplibre.gl:android-sdk-opengl. Avec cet artefact, Google Play propose également votre application aux appareils sans Vulkan, que l’artefact android-sdk par défaut requiert.
Définissez minSdk à 23 ou supérieur, comme l’exige MapLibre.
Pour limiter votre application à la localisation approximative, ajoutez ce qui suit à l’intérieur de l’élément <manifest> du fichier AndroidManifest.xml. Assurez-vous que l’élément <manifest> déclare xmlns:tools="http://schemas.android.com/tools".
Height : Conservez la hauteur Fixed par défaut. La carte remplit l’élément personnalisé.
Veillez à ne pas placer l’élément personnalisé dans des conteneurs qui réagissent au toucher, comme un carousel, afin que seule la carte réponde au glissement.
Dans l’élément personnalisé, ajoutez une Image avec une photo de carte. Les utilisateurs la voient comme contenu de secours dans les cas suivants :
Leur version de l’application n’affiche pas la carte.
Ils ont refusé l’accès à la localisation avant l’ouverture de l’écran.
Si l’utilisateur n’a pas encore répondu à la demande d’accès à la localisation, votre application l’affiche lorsque la carte apparaît. Pour expliquer aux utilisateurs pourquoi votre application a besoin de leur localisation, ajoutez un élément texte au-dessus de l’élément personnalisé, par exemple « Trouvez des centres de fitness près de chez vous. »
2. Créer la vue de la carte
Créez un type pour vos lieux et un modèle pour l’accès à la localisation :
// 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()
// 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; }}
Créez une vue avec une carte. La vue demande l’accès à la localisation et affiche un marqueur pour chacun de vos lieux situés dans un rayon de 2 km autour de l’utilisateur :
// 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 }) }}
La vue charge la carte depuis OpenFreeMap, un service gratuit qui ne nécessite pas de clé API et n’offre aucune garantie de disponibilité. Pour utiliser une autre source de tuiles, modifiez la constante MAP_STYLE_URL.
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); }}
La vue charge la carte depuis OpenFreeMap, un service gratuit ne nécessitant aucune clé API et sans garantie de disponibilité. Pour passer à une autre source de tuiles, modifiez la constante MAP_STYLE_URL.
Si l’utilisateur refuse l’accès à la localisation sur l’écran, la vue remplace la carte par un message expliquant comment autoriser l’accès dans les Paramètres.
3. Associer la carte à l’élément personnalisé
Dans votre resolver global, ajoutez les propriétés du modèle LocationAccess et de vos lieux. Renvoyez ensuite la vue carte pour le Type map et l’ID fitness_centers. Les lignes surlignées indiquent ce qui doit être ajouté ou modifié. Si votre application ne possède pas encore de resolver global, copiez l’intégralité du code :
class 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 }}
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; }}
Le SDK appelle le resolver à l’ouverture de l’écran, puis à chaque fois qu’il redessine l’élément personnalisé tant que l’écran est ouvert. L’accès à la localisation détermine ce que le resolver renvoie à chaque appel :
Pas encore répondu : La vue de la carte, pour que la vue puisse demander l’accès.
Autorisé : La vue de la carte, qui affiche vos lieux à proximité de l’utilisateur.
Refusé avant l’ouverture de l’écran : Aucune vue, les utilisateurs voient donc le paywall de secours au lieu du message concernant les Paramètres.
Refusé sur l’écran : La vue de la carte, car la vue définit isMapOnScreen pendant qu’elle est affichée à l’écran. Si le resolver ne renvoyait aucune vue ici, le SDK remplacerait le message concernant les Paramètres par le paywall de secours au prochain appel.
Créez le résolveur avec vos emplacements et définissez-le comme résolveur global de l’application. Appelez AdaptyUI.setCustomElementsResolver une seule fois, par exemple au lancement de l’application :
class 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) }}
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. Tester sur un appareil
Le Flow & Paywall Builder ne peut pas exécuter le code de votre application, donc son canvas n’affiche que le fallback. Pour prévisualiser la carte :
Publiez le flow. Pour voir la dernière version publiée plutôt qu’une version en cache, enregistrez l’appareil comme appareil de test.
Pour voir un marqueur sur la carte, ajoutez un lieu à moins de 2 km de votre position dans votre liste de lieux.
Lancez un build de votre application incluant le resolver. Ouvrez l’écran et autorisez l’accès à la localisation. Vérifiez que la carte affiche votre position ainsi qu’un marqueur pour le lieu que vous avez ajouté.
Pour tester le fallback, dans l’application Settings, désactivez l’accès à la localisation pour votre application. Ouvrez l’écran et, si la demande d’autorisation apparaît, refusez l’accès à la localisation. La vue de la carte affiche le message relatif aux paramètres. Ouvrez à nouveau l’écran et vérifiez que le fallback s’affiche.
Pour comprendre pourquoi le fallback s’affiche à la place de la carte, suivez les instructions de la section Tester sur un appareil du guide Android.