Introduction
Welcome to Mappy.
We build geospatial platforms connecting venues to their guests. Our turnkey solutions (developer tools, including the Mappy API and Mappy SDK, for mobile apps), improve the guest experience using interactive and social custom maps. Our data analytics platform and operations dashboards are designed to inform data driven decisions.
Mappy SDKs provide an elegant and composable interface for mapping, geocoding, and routing.
The Mappy SDKs leverages the power of best in class technology, including ESRI using the ArcGIS Runtime SDKs as dependencies.
This guide describes how to use the latest version of the Mappy SDK for iOS and Android for ski resorts. Terms of Service for our developer tools, data analytics platform, and mapping services portal are found here.
Get started with Mappy SDK
iOS
Install the following:
- Xcode
13.x
or later - Make sure that your project meets these requirements:
- Targets these platform versions or later: iOS
13
- Targets these platform versions or later: iOS
- Set up a physical Apple device or use a simulator to run your app.
If you don't have an Xcode project and want to try out a Mappy product, you can download a quick-start sample.
Android
Install the following:
- Android SDK, latest version is recommended.
- Android Studio, latest version is recommended.
- Set up a physical Android device with Android version major or equal to 6 (Marshmallow)
If you don't have an Android project and want to try out a Mappy product, or want to see a code example, you can download or clone this quick-start sample.
Register your App with Mappy
Your app needs to be registered with Mappy to use the Mappy SDK in your app. For a quote, please email info@beMappy.io. Mappy will provide customers a Client Id and a secret key associated with your app. Make sure you store them securely.
Add Mappy SDK to your App
iOS
- If you don't have Cocoapods installed on your machine, install it by following this guide.
- Add pod 'Mappy' to your project's podfile.
- Run the
pod install
command from the root directory of the project. - When finished, open the project's workspace and find the Mappy dependency under the Pod’s project.
Android
Localize the module level build.gradle file where you want the SDK installed and add the dependency full qualified name, you can find an example code at the right.
dependencies {
implement("io.mappy.sdk:mappy:0.2.1")
}
The Mappy Android SDK, for now, is available through Github Packages. So add the following to the project/build.gradle file, you can find an example code at the right.
maven { url = uri("https://esri.jfrog.io/artifactory/arcgis") }
maven {
name = "GitHubPackages"
url = uri("https://maven.pkg.github.com/beMappy/Mappy-Kotlin")
credentials {
username = <GITHUB_USERNAME>
password = <GITHUB_PERSONAL_ACCESS_TOKEN>
}
}
The SDK is dependant on a special toolkit dependency stored in Jfrog. If you are not familiar to Github Personal Access Token, generate it using this guide: this guide
Initialize Mappy in Your App
Mappy needs to be initialized in your app by adding an initialization code.
iOS
To initialize use this code
import Mappy
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
MappyCore.initialize(clientId: <ClientId>, secret: <ClientSecret>, completion: <Block>)
return true
}
Make sure to replace
ClientId
andClientSecret
with your credentials.
- Import the Mappy module in your UIApplicationDelegate.
- Configure a Mappy shared instance, typically in your app's initializer or app delegate's
application(_:didFinishLaunchingWithOptions:)
method:
This function helps to instantiate the Mappy SDK. Post initialization, SDK APIs can be used internally across the project. This is the static method and requires a Client Id and a secret.
Android
val mappy = Mappy.createInstance(applicationContext)
//Using Kotlin Coroutines:
CoroutineScope(Dispatchers.IO).launch {
mappy.initialize(<ClientId>, <ClientSecret>)
}
//Using Callback:
mappy.initialize(<ClientId>, <ClientSecret>, object: CompletionCallback<Void?> {
override fun onSuccess(result: Void?) {
//Initialization Success
}
override fun onError(throwable: Throwable) {
//Initialization Error
}
})
Mappy mappy = Mappy.createInstance(getApplicationContext());
mappy.initialize(<ClientId>, <ClientSecret>, new CompletionCallback<Void>() {
@Override
public void onSuccess(Void result) {
//Initialization Success
}
@Override
public void onError(@NonNull Throwable throwable) {
//Initialization Error
}
});
- Import the Mappy module.
- Create a Mappy object instance through the code instruction displayed in the example, be sure to pass a valid context to the createInstance method.
- Give the SDK your ClientID and ClientSecret using the initialize method. Post initialization, SDK APIs can be used internally across the project.
Venues
Get All Venues
let venuesService = VenuesService()
venuesService.getVenues()
.receive(on: DispatchQueue.main)
.sink(receiveCompletion: { completion in
switch completion {
case .finished: break
case .failure(let error):
print("error: \(error)")
}
}, receiveValue: { [weak self] venues in
// Received venues
})
.store(in: &cancellables)
val venueService = VenueService.createInstance(applicationContext)
//Using Kotlin Coroutines
CoroutineScope(Dispatchers.IO).launch {
val venues = venueService.getVenues()
}
//Using Callback
venueService.getVenues(object: CompletionCallback<List<Venue>> {
override fun onSuccess(result: List<Venue>) {
//Get Venues Successful
}
override fun onError(throwable: Throwable) {
//Get Venues Error
}
})
VenueService venueService = VenueService.createInstance(getApplicationContext());
venueService.getVenues(new CompletionCallback<List<Venue>>() {
@Override
public void onSuccess(List<Venue> result) {
//Get Venues Successful
}
@Override
public void onError(@NonNull Throwable throwable) {
//Get Venues Error
}
});
This function provides a list of venues associated with a particular Client Id. The data returned includes all details of available venues.
Get a Specific Venue
let venuesService = VenuesService()
venuesService.getVenue(venueId: <VenueId>)
.receive(on: DispatchQueue.main)
.sink(receiveCompletion: { completion in
switch completion {
case .finished: break
case .failure(let error):
print("error: \(error)")
}
}, receiveValue: { [weak self] venue in
// Received Venue
})
.store(in: &cancellables)
val venueService = VenueService.createInstance(applicationContext);
//Using Kotlin Coroutines
CoroutineScope(Dispatchers.IO).launch {
venueService.getVenue(<ID>)
}
//Using Callback
venueService.getVenue(<ID>, object: CompletionCallback<Venue> {
override fun onSuccess(result: Venue) {
//Get Venue Successful
}
override fun onError(throwable: Throwable) {
//Get Venue Error
}
})
VenueService venueService = VenueService.createInstance(getApplicationContext());
venueService.getVenue(<ID>, new CompletionCallback<Venue>() {
@Override
public void onSuccess(Venue venue) {
//Get Venue Successful
}
@Override
public void onError(@NonNull Throwable throwable) {
//Get Venue Error
}
});
This function helps to get the details for a specific venue using its identifier.
Parameters
Parameter | DataType | Description |
---|---|---|
VenueId | String | The ID of the venue to retrieve |
Map Rendering
2D
Map
map = Map(info: <info>)
map.load {
DispatchQueue.main.async { [unowned map, weak mapView] in
mapView?.map = map
}
}
//Using XML UI (with View Binding or Data Binding)
val map = Map(venue)
map.load(this, object : LoadListener() {
fun onSuccess(map: Map) {
binding.mapView.setMap(map)
}
fun onError(throwable: Throwable) {
// Error Handling
}
})
//Using Jetpack Compose
MapView(
map = Map(venue),
modifier = Modifier,
mapController = MapController(),
loadingView = { },
errorView = { }
)
Map map = new Map(venue);
map.load(this, new Map.LoadListener() {
@Override
public void onSuccess(@NonNull Map map) {
binding.mapView.setMap(map);
}
@Override
public void onError(@NonNull Throwable throwable) {
// Error Handling
}
});
A map is an object that represents the 2D map. You need to inject all the required data associated with a venue to instantiate and load a Map.
MapView
MapView()
//Using XML UI
import io.bemappy.sdk.ui.MapView
MapView(context)
//Using Jetpack Compose
import io.bemappy.sdk.ui.compose.MapView
MapView(map, modifier, mapController,loadingView,errorView)
import io.bemappy.sdk.ui.MapView;
new MapView(context)
MapView is a UI object that helps in rendering the 2D map. Once the map is loaded, add the map to MapView and then you can add the same to your UI hierarchy.
3D
Scene
scene = Scene(info: <info>)
scene.load {
DispatchQueue.main.async { [unowned scene, weak sceneView] in
sceneView?.scene = scene
}
}
//Using XML UI (with View Binding or Data Binding)
val scene = Scene(venue)
scene.load(this, object : LoadListener() {
fun onSuccess(scene: Scene) {
binding.sceneView.setScene(scene)
}
fun onError(throwable: Throwable) {
// Error Handling
}
})
//Using Jetpack Compose
SceneView(
scene = Scene(venue),
modifier = Modifier,
sceneController = SceneController(),
loadingView = { },
errorView = { }
)
Scene scene = new Scene(venue);
scene.load(this, new Scene.LoadListener() {
@Override
public void onSuccess(@NonNull Scene scene) {
binding.sceneView.setScene(scene);
}
@Override
public void onError(@NonNull Throwable throwable) {
// Error Handling
}
});
A scene is an object that represents the 3D map. You need to inject all the required data associated with a venue to instantiate and load a Scene.
SceneView
SceneView()
//Using XML UI
import io.bemappy.sdk.ui.SceneView
SceneView(context)
//Using Jetpack Compose
import io.bemappy.sdk.ui.compose.SceneView
SceneView(scene, modifier, sceneController, loadingView, errorView)
import io.bemappy.sdk.ui.SceneView;
new SceneView(context)
SceneView is a UI object that helps in rendering the 3D map. Once the scene is loaded, add the scene to SceneView and then you can add the same to your UI hierarchy.