NAV
swift kotlin java

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:

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:

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

  1. If you don't have Cocoapods installed on your machine, install it by following this guide.
  2. Add pod 'Mappy' to your project's podfile.
  3. Run the pod install command from the root directory of the project.
  4. 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 and ClientSecret with your credentials.

  1. Import the Mappy module in your UIApplicationDelegate.
  2. 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
    }
});
  1. Import the Mappy module.
  2. Create a Mappy object instance through the code instruction displayed in the example, be sure to pass a valid context to the createInstance method.
  3. 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.

swift kotlin java