Skip to content
Developers Docs

Mapsted Maps - Mobile Docs
Mapsted Maps - Mobile Docs Mapsted Analytics - Docs

v4

Mapsted Mobile SDK (v4.6)

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

Getting Started for Mobile SDK Version 4.6. If you are looking to upgrade to the latest version of the Mapsted Mobile SDK, please find the latest latest getting started here.

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

You must be running jdk 11 or higher. In Android Studio, open Files > Settings. Under Gradle options, Choose Gradle JDK to use jdk 11 or higher.

2. Setup Permissions

Our libraries include the permissions it require in its AndroidManifest file.

If you are not specifically removing any permissions, then continue to next step. Otherwise please make sure following permissions are not removed.

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

If you are using the kotlin gradle build.gradle.kt, please refer to Migrating build logic from Groovy to Kotlin

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

buildscript {
    repositories {
        google()
        mavenCentral()
    }
    dependencies {
                classpath 'com.android.tools.build:gradle:7.4.2'
    }
}

allprojects {
    repositories {
        google()
        mavenCentral()
        maven { url 'https://jitpack.io' }
        maven { url "https://mobilesdk.mapsted.com:8443/artifactory/gradle-mapsted" }
    }
}

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

apply plugin: 'com.android.application'    

android {
    compileSdkVersion 33

    defaultConfig {
        applicationId "your.packagename"
        minSdkVersion 24
        targetSdkVersion 33
        versionCode = 1
        versionName = "1"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
    }

    buildTypes {
        //...
    }

    buildFeatures {
        dataBinding true
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }

    configurations {
        implementation.exclude group: 'org.jetbrains', module: 'annotations'
    }

    packagingOptions {
        exclude 'META-INF/gradle/incremental.annotation.processors'
    }
}

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])

    // Import Mapsted SDKs
    // Note: Order is important. 
    // Top resources overwrite bottom. Ensure that more "core" SDKs are lower

    // Set SDK version once to ensure all imports have same version
    def mapstedSdkVersion = '5.3.1'

    // If using app-templates, import here:
    implementation("com.mapsted:app-template-mall:${mapstedSdkVersion}") // Example app-template
    implementation("com.mapsted:app-template-core:${mapstedSdkVersion}")

    // Optionally, if you want location marketing or alerts (both depend on inapp-notification)
    implementation("com.mapsted:sdk-loc-marketing:${mapstedSdkVersion}")
    implementation("com.mapsted:sdk-alerts:${mapstedSdkVersion}")
    implementation("com.mapsted:sdk-inapp-notification:${mapstedSdkVersion}")

    // Optionally, if your want programmatic geofences
    implementation("com.mapsted:sdk-geofence:${mapstedSdkVersion}")

    // Optionally, if you want prebuilt Mapsted UI/UX, include this dependency
    implementation("com.mapsted:sdk-ui-components:${mapstedSdkVersion}")    

    // Optionally, If you want access to the Mapsted Map UI, include this dependency
    implementation("com.mapsted:sdk-map-ui:${mapstedSdkVersion}")

    // If you want access to the Mapsted map, include this dependency
    implementation("com.mapsted:sdk-map:${mapstedSdkVersion}")

    // This is always required to use the Mapsted SDK
    implementation("com.mapsted:sdk-core:${mapstedSdkVersion}")
}

5. Proguard exclusion

If you have proguard enabled in your project, please keep all mapsted related public classes and interfaces.

Add the following in your proguard file.

-keep interface com.mapsted.** { *; }    
-keep public class com.mapsted.** { public protected *; }
-keep public class com.carto.** { public protected *; }
-keep interface com.carto.** { *; }

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 (No Prebuilt UI/UX)

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(context)
            .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 stored 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 onCoreInitialized() {
        // CoreSDK initialized (This will occur first)
    }

    @Override
    public void onMapInitialized() {
        // MapSDK initialized (This will occur second)
    }

    @Override
    public void onSuccess() {
        // Initialize succeeded
        // optionally you can initialize the LocationMarketing sdk after this.
    }

    @Override
    public void onMessage(MessageType messageType, String message) {
        //you may receive onMessage before onSucess or onFailure. 
        //They can be ignored or used for debugging purpose.    
    }

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

Note

The above example initializes MapUiApi. Internally, MapUiApi initializes CoreApi, then initializes MapApi and then finally initializes MapUiApi in that order.

If you want to only use CoreApi, you can use CoreApi coreApi = MapstedCoreApi.newInstance(context); followed by coreApi.initialize(detail, callback).

If you take this approach, please remember that you should pass this coreApi when instantiating MapApi using MapstedMapApi.newInstance(context, coreApi) so that it is reused.

Location Marketing SDK

If you are using Location Marketing SDK, please note that you should initialize it only after the CoreSDK is initialized. 

locMarketing = new LocMarketing(context, coreApi, new LocMarketing.LocMarketingListener() {
    @Override
    public void navigateToMap(String campaignId, List<HomeEntity> homeEntityList) {
        Logger.d("navigateToMap: ");
    }

    @Override
    public void openWebsite(String campaignId, String websiteURL) {
        Logger.d("openWebsite: ");
    }

    @Override
    public void showInInAppNotificationBar(Campaign campaign) {
        Logger.d("show in-app pop-up: ");
    }
});
Mapsted Alert SDK

If you are using Alerts SDK, please note that you should initialize it only after the CoreSdk is initialized.

AlertsManager can be used to receive scheduled alerts and emergency alerts.

AlertsManager supports two callbacks. OnAlertChangeListener to get changes in active alerts at a location. The other UserAtLocationCallback to detect when an active alert triggers.

AlertsManager alertsManager = AlertsManagerImpl.getInstance(context, coreApi);

//To receive emergency alerts, submit your firebase token. Then configure FirebaseMessagingService by extending EmergencyAlertsFirebaseMessagingService.
//remember to register the service in your manifest.
alertsManager.sendFirebaseTokenForEmergencyAlerts(context, firebaseToken);

//to receive scheduled alerts for property Id 504
int propertyId = 504;
AlertsOnChangeListener onAlertChangeListener = new AlertsOnChangeListener(propertyId) {
    @Override
    public void onChangeInOngoingAlerts(Set<ScheduledAlert> before, Set<ScheduledAlert> after) {
        //use the diff of these sets of alerts to get alerts that were added or removed.
    }
}
alertsManager.registerListener(onAlertChangeListener);
//to get alert notifications for property if the user is at the property
alertsManager.setUserAtLocationCallback(new UserAtLocationCallback{
    @Override
    public void onNotifyAlert(ScheduledAlert scheduledAlertRow, boolean autoDismiss){
        //There is alert for the user while at this location. This notification callback event 
        //happens based on the trigger setting of the scheduled alerts. For example, it could be 
        //set when user enters the building or exits the building.
        //in this callback, you can use the scheduledAlert object to show a notification etc.
    }
})
...

Unregister from the listeners during teardown process

//teardown
...
alertsManager.unregisterListener(onAlertChangeListener);
alertsManager.onDestroy();
Mapsted Prebuilt UI/UX Components

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.

Mapsted App Template

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.

7. Testing Mapsted Sdk

By mocking your location, you can test MapstedSDK to simulate being at the property. There are a number of apps that can mock gps data on your android device. Once installed, that app needs to be set as the Mock Location app in your device’s Settings. This setting is in devices Setting > Developer Option.

Here are the steps.

  1. Install any gps mocking app in your device from Google Play store. Here is one we have verified to be working. FakeGPS on Google Play Store

  2. Enable Developer Option in your device. Follow the instructions on this link to enable developer options. Once the developer option menu is enabled, open the Developer option menu. Find Select mock location app. Then select the fake gps app. This will set that app as the mock location provider.

  3. Open the Fake GPS app. To simulate your device’s gps location to ‘Square One’ property, please set the location to 43.59305369537576, -79.64327301294524

  4. Depending on fakegps app feature, you may be able to save this location so that you do not have to enter the coordinates again. It might also show up in location history in the app. The fakegps app may or may not contain this feature. The suggested FakeGps app has this convenience.

  5. Test Mapsted SDK by launching the Sample app

  6. If you need to simulate walking movement, you can shake/oscillate your device. When using mocked location, this simulated walking is limited to work for few meters only.

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
Project target iOS 13.0 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', '~> 5.1.3'

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

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

# If you want prebuilt Mapsted UI/UX, include this pod
pod 'mapsted-sdk-ui-components', '~> 5.1.3'

# If you want to incorporate the Mapsted Location Marketing SDK, include this pod
pod 'mapsted-sdk-loc-marketing', '~> 5.1.3'
end

# If you want to incorporate the Mapsted Alerts SDK, include this pod
pod 'mapsted-sdk-alerts', '~> 5.1.3'
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 (No Prebuilt UI/UX)

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, callback: self)

Setting the callback parameter enables you to receive success or failure callbacks from the SDK. Your callback should implement the 'CoreInitCallback` protocol.

extension AppDelegate : CoreInitCallback {

    func onSuccess() {  
        //Handle success
    }

    func onFailure(errorCode: Int, errorMessage: String) {
        //Handle failure
    }
}
Mapsted Alerts

If you are using the Mapsted Alerts SDK, you can initialize it once Core SDK is successfully initialized

//Import the Alerts SDK first
import MapstedAlerts 

//Initialize Alerts API
AlertsApi.initialize() { success, error in 
        if let error = error {
            //handle Error
            print("Error: \(error.localizedDescription)")
        }
}

//You can check if LocMarketingApi is initialized using
let success = AlertsApi.hasInit()

//Once initialized, you can use its shared instance
let alertsManager = AlertsApi.shared

To receieve notifications when active alerts change for a specific property, you will need a delegate to the AlertsOnChangedListener protocol

let myPropertyId = 504;

//Add listener to get change events
alertsManager.addAlertChangeListener(propertyId: myPropertyId, listener: self)

//Your delegate needs to have implement the required methods
extension MyViewController : AlertsOnChangedListener {
    public func onChangeInOngoingAlerts(propertyId:Int, before: [AlertSearchable], after: [AlertSearchable]) {
        //Do something with the alerts
    } 
}

To be notified when user is at a particular property, you need a delegate to the UserAtLocationListener protocol 

//Add listener to get change events
alertsManager.addUserAtLocationListener(listener: self)

//Your delegate needs to have implement the required methods
extension MyViewController : UserAtLocationListener {
    public func onNotifyAlert(alert: AlertSearchable) {
        //Do something with the alert notification
    } 
}
Location Marketing

If you are using the Mapsted Location Marketing SDK, you can initialize it once Core SDK is successfully initialized

//Import the Location Marketing SDK first
import LocationMarketing 

//Initialize Location Marketing API
LocMarketingApi.initialize() { success, error in 
        if let error = error {
            //handle Error
            print("Error: \(error.localizedDescription)")
        }
}

//You can check if LocMarketingApi is initialized using
let success = LocMarktingApi.hasInit()
Mapsted Prebuilt UI/UX Components

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.

Mapsted App Template

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.

7. Location Simulation

Our Mapsted SDK provides extra features such as routing from your current location when you are at a supported property. To take advantage of these features even when you are not physically on site, you can simulate the location of your device via a number of possible approaches.

A quick search on the web with terms such as “fake gps” would bring up various suggestions including the risks and rewards involved. Here is one such search result: “4 Effective Methods to Fake GPS location on iPhone” (https://drfone.wondershare.com/virtual-location/fake-gps-ios.html)

Using Third Party Software

Due to Apple’s strict stance on user privacy, there are no straightforward solutions to fake gps on iOS devices. But there are workarounds that might work.

One example is “AnyTo” from iMyFone.net (https://www.imyfone.net/location-changer/)

Using Xcode

With an iOS App that you can build using our SDK, it is possible to simulate a location using Xcode. Here are the steps

  • Select your scheme and choose “Edit Scheme”

  • In the next window that appears, select “Run” from the left and “Options” on the right to reveal the option to “Allow Location Simulation”

  • Make sure Allow Location Simulation is selected and from the list next to Default Location you can choose from the list available. If you want a more precise location, there is an entry at the bottom titled Add GPS Exchange to Project …

  • Selecting “Add GPS Exchange to Project …” will present a file picker which will allow you to choose a “gpx” (GPS Exchange Format) file.

    You can generate one using websites such as https://gpx.studio which allows you to pan around a map and click on points to generate a file which contains those points. Once you are satisfied with your selection, you can download the generated file to your computer with extension “.gpx” and select it from the file picker.

How to Test Navigation Mode

Once you have set up for fake GPS location, you can follow these steps

  1. Launch the app built with Mapsted SDK

  2. In map view, use assisted positioning button to place marker more precisely if desired

  3. Since you are on location, you can request routing from "My Location"

  4. You can rotate phone to see vision code to get an idea of heading

  5. You can shake phone vertically slightly to simulate steps in that direction