Skip to content
Developers Docs

Getting Started

This section will guide you through the basic setup of both Android and iOS projects and how to integrate each with the Mapsted SDK.

Current Version: 4.1


Prerequisites

To use the Mapsted Mobile SDK, you will need to have either a Mapsted account or a Mapsted trial account. Please contact the Mapsted Sales Team for more information on how to set that up.

You must also register your app on your Mapsted account page in the Mapsted developer portal. You can access your mobile app licence file and baselayer.mbtiles file from there.


Android

This guide will take you through the process of installing and initializing the Mapsted Android SDK. By the end of this process, you will be able to verify that the SDK is running properly and is ready to be used.

1. Minimum Requirements

To import the Mapsted SDK, your Android project must meet the following minimum requirements.

Library Version
Minimum Android SDK Version 24

2. Setup Permissions

The following permissions are required on the AndroidManifest file to use the Mapsted SDK:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />

3. Include Licence Files

Place the Mapsted Android licence file (android_licence.key), in the assets folder located at $(ProjectPath)/app/src/main/assets. You will need to create the assets folder if it does not exist.

Add the Mapsted basemap layer file (baselayer.mbtiles) to the assets folder.

4. Import the Mapsted SDK

This section describes integrating the Mapsted SDK into your Android project.

Add the following code into your project's gradle file:

allprojects {
    repositories {
        google()
        jcenter()
        maven {
            url "http://sdk.mapsted.com:8081/artifactory/gradle-mapsted"
            credentials {
                username = "<UserName>"
                password = "<Password>"
            }
        }
    }
}

Make sure you have all the below settings in the app level build.gradle file.

//Apply androidX navigation safeargs plugin 
apply plugin: 'androidx.navigation.safeargs'

//Make sure the minSdkVersion is 24 in defaultConfig
defaultConfig {
    minSdkVersion 24
}

//Add databinding enabled to true under the android section
dataBinding {
    enabled = true
}
//Add source and target compatibility for Java
compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

// This is always required to use the Mapsted SDK
implementation 'com.mapsted:sdk-core:4.1.0'

// If you want access to the Mapsted map, include this depdenency
implementation 'com.mapsted:sdk-map:4.1.0'

// If you want prebuilt map-ui (e.g., routing UI), include these dependencies
implementation 'androidx.appcompat:appcompat:1.1.0'
annotationProcessor 'androidx.lifecycle:lifecycle-compiler:2.2.0-alpha01'
annotationProcessor 'androidx.room:room-compiler:2.1.0-rc01'
implementation 'com.mapsted:sdk-map-ui:4.1.0'

// If you want prebuilt Mapsted UI/UX, include this dependency  
implementation 'com.mapsted:sdk-ui-components:4.1.0'

5. Initialization of Mapsted SDK

The Mapsted SDK is very flexible and allows for multiple levels of integration. We will outline several different options for initializing the Mapsted SDK, based on your requirements and preferences, below.

Mapsted Map allows you to incorporate our map and/or positioning in a specific portion of your application, for example when a map button is clicked. Choose this mode when you want to use your own application and UI/UX.

To use this mode, start by creating a FrameLayout object, mapContainerView, which is a container for the Mapsted MapView.

FrameLayout mapContainerView = findViewById(R.id.mapContainerView);

Set your desired customization parameters.

// Some sample customization parameters
CustomParams.newBuilder()
            .setBaseMapStyle(BaseMapStyle.DEFAULT)
            .setMapPanType(MapPanType.RESTRICT_TO_SELECTED_PROPERTY)
            .setMapZoomRange(new MapstedMapRange(6.0f, 25.0f))
            .build();

You can initialize the Mapsted SDK key api classes, as shown below.

// Make sure you only initialize one version of this object in your app
// These can be sored in your activity and/or application
MapUiApi mapUiApi = MapstedSdkController.newInstance(this);
MapApi mapApi = mapUiApi.getMapApi();
CoreApi coreApi = mapApi.getCoreApi();

You can initialize the Mapsted SDK as shown below.

// activity is your activity
// mapViewContainer is your view container for the map (typically a frame layout)
mapUiApi.initializeMapstedSDK(activity, mapViewContainer, new MapstedInitCallback() {
    @Override
    public void onSuccess() {
        // Initialize succeeded
    }

    @Override
    public void onFailure(SdkError sdkError) {
        // Initialize failed
    }
});

Follow the same steps to initialize Mapsted Prebuilt UI/UX Components as you did for Mapsted Map. You can use a variety of prebuilt UI/UX components within your own application, and you also have the ability to add UI/UX components into the MapView. Please see Prebuilt UI Components to learn more.

Choose this mode when you want to create your own application using some of Mapsted's prebuilt UI/UX components.

Choose this option if you prefer to use Mapsted's out-of-the-box app template. This mode doesn’t require any additional customization on your part.

Please see Prebuilt App Templates for more details.


iOS

After obtaining your iOS licence, please follow the steps in this guide to complete the installation process and initialize the Mapsted iOS SDK.

1. Minimum Requirements

Requirement Version
Xcode 12.0
Project target iOS 12 or higher
Swift projects Swift 5
CocoaPods 1.8.0 or higher

2. Setup Permissions

In your project's Info.plist file, add appropriate location usage descriptions for these keys : NSLocationAlwaysUsageDescription (Privacy - Location Always Usage Description), NSLocationAlwaysAndWhenInUseUsageDescription (Privacy - Location Always and When In Use Usage Description), and NSLocationWhenInUseUsageDescription (Privacy - Location When In Use Usage Description). The descriptions you provide as values for these keys will be shown to the user when requesting permission to use their location.

Also in the same Info.plist file, add an appropriate bluetooth usage description for the key: NSBluetoothAlwaysUsageDescription (Privacy - Bluetooth Always Usage Description). This decription will be shown to the user when requesting permission to access bluetooth services on their device.

Location services are required to run in the background to support navigation. In Xcode, under app capabilities, enable location updates for background. Also, add Access WiFi information as a capability.

3. Update Project Settings.

With your project open in Xcode, select your target. Go to the Build Settings tab and make sure Enable Bitcode is set to No.



Our SDK requires that GLKit.framework be linked with your project. While this may not be a problem with our latest builds, older versions of our SDK may require you to explicitly add this to your target. To accomplish this, go the Build Phases tab with your target still selected, and make sure GLKit.framework is included under the section labeled Link Binary with Libraries. If it is not, click on the + button to add it.



4. Include Required Files

Add the Mapsted iOS licence file (ios_licence.key) to your project and place it in the app bundle, preferably under the Resources folder.


The colorful look in the map view requires some CSS code which is included in an asset file named mapstyle.zip. Add this file to your project and place it in the app bundle, preferably under the Resources folder.


5. Import the Mapsted SDK

Your application must use CocoaPods in order to install the Mapsted SDK. Rename Sample next to the target keyword to match the target name in your project.

platform :ios, '12.0'

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/Mapsted/podspec.git'

target 'Sample' do
use_frameworks!

# If you only need positioning, include this pod only!
pod 'mapsted-sdk-core', '4.1.0'

# If you are displaying maps, include the following two pods
pod 'mapsted-sdk-core-map'
pod 'mapsted-sdk-map', '4.1.0'

# If you want prebuilt map-ui (e.g., routing UI), include this pod
pod 'mapsted-sdk-map-ui', '4.1.0'

# If you want prebuilt Mapsted UI/UX, include this pod
pod 'mapsted-sdk-ui-components', '4.1.0'
end

Install the pods and open the .xcworkspace file to see the project in Xcode.

$ pod update
$ open your-project.xcworkspace

6. Initialization of Mapsted SDK

The Mapsted SDK is very flexible and allows for multiple levels of integration. We will outline several different options for initializing the Mapsted SDK, based on your requirements and preferences, below.

Mapsted Map allows you to incorporate our map and/or positioning in a specific portion of your application, for example when a map button is clicked. Choose this mode when you want to use your own application and UI/UX.

In AppDelegate in didFinishLaunchingWithOptions, paste the following code to initialize the MapstedMap sdk. This will initialize the MapstedCore sdk as well. Set prefetchProperties to true if you want to pre-download all properties at app launch.

MapstedMapApi.shared.setUp(prefetchProperties: false)

Add your view controller as observer for sdk initialized notification event.

override func viewDidLoad() {
    super.viewDidLoad()
    MNCoreNotificationManager.main.addObserver(type: .initialized, observer: self, selector: #selector(self.initialized(notification:)))
}

Handle the notification event.

@objc func initialized(notification: NSNotification) {
    let result = notification.userInfo?["result"] as? Bool
    if ( result == true ) {
        //Initialize succeded
    } else {
        //Initialize failed
    }
}

Follow the same steps to initialize Mapsted Prebuilt UI/UX Components as you did for Mapsted Map. Choose this mode when you want to create your own application using some of Mapsted's prebuilt UI/UX components.

Choose this option if you prefer to use Mapsted's out-of-the-box app template. This mode doesn’t require any additional customization on your part. You can use the same initialization process as for Mapsted Map.