Skip to content
Developers Docs

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

Ionic / Cordova getting started

This guide takes you through integrating the Mapsted Cordova plugin (mapsted-cordova-plugin) — usable from a plain Apache Cordova app or an Ionic app — against the native Mapsted SDK 26.7.1.

Breaking change from the 6.x plugin

The 26.7.1 plugin is built on the 26.7.1 native SDK, which raises the minimum toolchain (below). These are breaking for apps that were on the old 6.x plugin — treat this as a major upgrade, not a drop-in bump. See the Ionic / Cordova migration guide for the complete, step-by-step upgrade.

1. Install the plugin

cordova plugin add https://github.com/MapstedHQ/mapsted-cordova-plugin.git#v26.7.1

The plugin is distributed by git tag (v26.7.1) from the official MapstedHQ GitHub organization. Its version tracks the native SDK exactly: plugin 26.7.1 wraps native SDK 26.7.1 — the two are always the same number. Use of the SDK requires a valid Mapsted commercial licence (see the bundled LICENSE).

2. Consumer toolchain — minimum versions

Platform Minimum
Cordova CLI 12+; cordova-android 15.0.0 and cordova-ios 8.x
Android minSdkVersion 26; compileSdk 36; Kotlin 2.3.20; Gradle 8.13 available on PATH to bootstrap the cordova-android 15 wrapper
iOS deployment target 16.0; CocoaPods with use_frameworks!

3. Android setup

1. Set minSdkVersion 26 in config.xml (the SDK's map UI requires API 26):

<preference name="android-minSdkVersion" value="26" />

2. The plugin pulls the SDK from the GitHub-Pages Maven repo (https://mapstedhq.github.io/mapsted-android-maven) — no Artifactory or JitPack for the Mapsted artifacts. The plugin's add_repositories_hook.js wires this repository into your repositories.gradle automatically at cordova prepare time.

3. Build toolchain. cordova-android 15 requires compileSdk 36 and a system Gradle 8.13 on PATH to bootstrap the project's Gradle wrapper. Install Android SDK Platform 36 and a Gradle 8.13 distribution before your first cordova build android.

4. The plugin declares com.google.code.gson:gson:2.11.0 explicitly (it is required by the Java bridge and is no longer a transitive dependency at 26.7.1) and injects the SDK's required manifestPlaceholders via build-extras.gradle — no action needed on your side.

5. Add your licence file to the Android assets folder: platforms/android/app/src/main/assets/your_android_license.key.

4. iOS setup

The plugin's plugin.xml declares everything the iOS build needs; a normal cordova platform add ios + cordova build ios wires it up:

1. Podspec sources and pods (added for you) — the 26.7.1 pods live in the MapstedHQ spec repo:

source 'https://cdn.cocoapods.org/'
source 'https://github.com/MapstedHQ/podspec.git'
platform :ios, '16.0'
use_frameworks!
pod 'mapsted-sdk-map', '26.7.1'
pod 'mapsted-sdk-map-ui', '26.7.1'

2. The required Info.plist usage-description keys are added by the plugin (iOS terminates the app on location access without them): NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, NSMotionUsageDescription.

3. Add your licence file as a bundle resource, e.g. via config.xml:

<platform name="ios">
    <resource-file src="res/your_ios_license.key" />
</platform>

Licence is bound to your bundle id

Mapsted licences are issued for a specific OS and bundle id. An Android licence will not load on iOS — use the .key issued for your iOS bundle id (or the bundle-agnostic demo key for demo properties). The SDK loads the licence by scanning the app bundle for a .key file.

5. Usage

The plugin clobbers a global MapstedCordovaPlugin object. Call it after deviceready:

document.addEventListener('deviceready', function () {
    MapstedCordovaPlugin.launchMapActivity(
        function onSuccess() { /* map screen presented */ },
        function onError(err) { console.error('Mapsted:', err); }
    );
}, false);

launchMapActivity() opens the Mapsted map experience: the user picks a property and the indoor map for that property renders. The success/error callback resolves once the map screen is presented.

6. Indoor map loading (SDK 26.7.1)

Physical devices are fully supported. The indoor floorplan renders correctly on real arm64 hardware on both platforms. On the very first cold start the map database initializes once, then the selected property plots automatically.

A complete, working reference is the sample app — MapstedHQ/MapstedSampleCordovaIonic. The plugin is certified at 26.7.1 with the Square One Shopping Centre indoor map rendering on real iPhone 15 Pro (iOS 17), iPhone 14 (iOS 18) and iPhone 13 (iOS 18), and building green on Android (cordova-android 15, compileSdk 36, minSdk 26).