Skip to content

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: 3.7.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-positioning:3.7.1.+'

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

    // 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:3.7.1.+'

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

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 two FrameLayout objects. The first, shown in the sample code below as flMapUITool, allows you to add your own UI elements onto MapView. The second, flMapstedMap, is a container for the Mapsted MapView.

    FrameLayout flMapUITool = findViewById(R.id.my_map_ui_tool);
    FrameLayout flMapstedMap = findViewById(R.id.my_map_container);

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, 24.0f))
                .build();

You can initialize the Mapsted SDK as shown below.

    MapstedSdkController.getInstance().initializeMapstedSDK(this, flMapUITool, flMapstedMap, 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 11.0
Project target iOS 12 or higher
Swift projects Swift 5
CocoaPods 1.2.0 or higher

2. Setup Permissions

Add location usage description for NSLocationAlwaysUsageDescription key in project's Info.plist file. Location is 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. Include Licence Files

Place the Mapsted iOS licence file (ios_licence.key) in the app bundle, preferably under a folder called Resources.

4. Import the Mapsted SDK

Your application must use CocoaPods in order to install the Mapsted SDK. Rename target to your target name.

platform :ios, '11.0'

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

target 'Sample' do
  use_frameworks!

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

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

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

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

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

$ pod update
$ open your-project.xcworkspace

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.

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

MNMapApi.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.