Skip to content
Developers Docs

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

Migration Guide: 6.x → 26.7.1 (Ionic / Cordova)

This guide covers everything you need to upgrade an Ionic or Apache Cordova app from the old Mapsted mapsted-cordova-plugin (the 6.x line) to the 26.7.1 plugin. The 26.7.1 plugin is built on the 26.7.1 native SDK, which is engine-synced with the iOS and Android 26.7.1 releases. Its version tracks the native SDK exactly — plugin 26.7.1 wraps native SDK 26.7.1, always the same number. The changes are almost entirely distribution, packaging, and consumer toolchain — the plugin's JavaScript bridge API is unchanged — so most apps upgrade by switching how the plugin is installed and updating their Android and iOS build configuration. The Minimum changes to compile section below is enough for a typical integration; the remaining sections document every breaking change in full, with before/after code.

Who needs to read this

Every Ionic / Cordova app upgrading from the 6.x plugin. All of the required changes live in how you install the plugin, in your config.xml, and in your Android and iOS build toolchain — a project that keeps the old vendored plugin, without the toolchain updates, will not resolve the 26.7.1 native artifacts or will fail to build. Your own JavaScript that calls the plugin does not need to change (B7).

Minimum changes to compile

For a typical integration, these are the changes required to build against 26.7.1:

  1. Remove the old vendored plugin and add the git-tag plugin — delete any vendored plugins/mapsted-cordova-plugin copy and run cordova plugin add https://github.com/MapstedHQ/mapsted-cordova-plugin.git#v26.7.1 (B1).
  2. Be on Cordova CLI 12+, with cordova-android 15.0.0 and cordova-ios 8.x (B2).
  3. Android — set minSdkVersion to 26 in config.xml, install Android SDK Platform 36 (compileSdk 36), and put a Gradle 8.13 distribution on PATH to bootstrap the cordova-android 15 wrapper (B3, B4).
  4. iOS — raise the deployment target to 16.0, keep use_frameworks!, and let the plugin add the MapstedHQ podspec source and pods (B5, B6).

The plugin wires the GitHub-Pages Maven repository, the gson dependency, the manifestPlaceholders, the iOS podspec source/pods, and the iOS Info.plist usage-description keys into your project for you — so once the plugin is added and the toolchain is in place, the build resolves the native artifacts automatically.

Recommended (non-blocking) cleanup

Remove any leftover vendored plugins/mapsted-cordova-plugin folder, any hand-added Artifactory/JitPack Maven URLs for the Mapsted artifacts, and any explicit mapsted-sdk-geofence pod — the 26.7.1 plugin provides the Maven repository automatically (B4) and the geofence module is folded into core (B6).

Breaking changes (complete reference)

The table summarizes all breaking changes; each is detailed below.

ID Change Severity Applies to
B1 Distribution changed: git-tag plugin add (was vendored plugins/mapsted-cordova-plugin) High All apps
B2 Cordova toolchain: CLI 12+, cordova-android 15.0.0, cordova-ios 8.x High All apps
B3 Android minSdkVersion is now 26 High Android
B4 Android: compileSdk 36, Kotlin 2.3.20, Gradle 8.13, GitHub-Pages Maven, gson declared High Android
B5 iOS deployment target is now 16.0 High iOS
B6 iOS: MapstedHQ podspec source; framework coordinates renamed; geofence pod folded into core High iOS
B7 The plugin JavaScript bridge API is unchanged None (informational) All apps

B1 — Distribution: git-tag plugin add (no vendoring)

The 6.x plugin was vendored into the sample project as plugins/mapsted-cordova-plugin, wrapping the 6.x native line (Android com.mapsted:sdk-*:6.0.11, iOS mapsted-sdk-*:6.1.7). The 26.7.1 plugin is distributed by git tag from the official MapstedHQ GitHub organization — no vendoring. Remove any vendored copy and add the plugin by tag:

# Before — vendored copy in the project (remove it)
cordova plugin remove mapsted-cordova-plugin
# (and delete any leftover plugins/mapsted-cordova-plugin folder)

# After — add by git tag from MapstedHQ
cordova plugin add https://github.com/MapstedHQ/mapsted-cordova-plugin.git#v26.7.1

The plugin version tracks the native SDK exactly: plugin 26.7.1 wraps native SDK 26.7.1 — the two are always the same number. This is a major upgrade, not a drop-in bump — the native SDK underneath changed from 6.x to 26.7.1, which drives the toolchain requirements below.

Commercial licence

The plugin is added directly from the official MapstedHQ GitHub organization, so cordova plugin add resolves without an access grant. Use of the SDK is governed by the Mapsted commercial licence bundled as LICENSE; using the SDK requires a valid signed agreement. Contact support@mapsted.com for licensing.

B2 — Cordova toolchain: CLI 12+, cordova-android 15, cordova-ios 8.x

The 26.7.1 native SDK requires a modern Cordova toolchain. Move to Cordova CLI 12 or newer, and upgrade the platforms — cordova-android from 13 to 15.0.0, and cordova-ios to 8.x. Pin cordova-android to 15 so the build is deterministic:

# Before
cordova platform add android@13

# After — pin cordova-android to 15
cordova platform add android@15.0.0
cordova platform add ios@8

cordova-android 15 is what drives the compileSdk 36 / Gradle 8.13 requirements in B4.

B3 — Android minSdkVersion is now 26

The native SDK's map UI requires minSdkVersion 26. Set it in config.xml — a project on a lower minimum fails manifest-merge against the SDK modules:

<!-- config.xml -->
<preference name="android-minSdkVersion" value="26" />

B4 — Android build toolchain, GitHub-Pages Maven, and gson

Several Android build requirements move together at 26.7.1. Most are wired in by the plugin; the toolchain pieces you must have on your machine are listed below.

  • compileSdk 36 and Gradle 8.13. 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.
  • Kotlin 2.3.20. The 26.7.1 Android artifacts are built with Kotlin 2.3.20.
  • GitHub-Pages Maven. The framework coordinates were renamed and the SDK is now served from the public GitHub-Pages Maven repository. The plugin's add_repositories_hook.js wires https://mapstedhq.github.io/mapsted-android-maven into your repositories.gradle automatically at cordova prepare time. Remove any hand-added Artifactory/JitPack maven { url ... } entries for the Mapsted artifacts to avoid stale resolution.

The framework coordinates changed (note the sdk-map-ui → android-sdk-ui rename):

// Before (6.x)
com.mapsted:sdk-map-ui:6.0.11
com.mapsted:sdk-map:6.0.11
com.mapsted:sdk-core:6.0.11

// After (26.7.1) — resolved by the plugin from GitHub-Pages Maven
com.mapsted:android-sdk-ui:26.7.1
com.mapsted:android-sdk-map:26.7.1
com.mapsted:android-sdk-core:26.7.1
  • gson is now declared explicitly. The plugin declares com.google.code.gson:gson:2.11.0 — it is required by the Java bridge (import com.google.gson.Gson) and is no longer a transitive dependency at 26.7.1. No action is needed on your side.
  • Manifest placeholders. The plugin injects the SDK's required manifestPlaceholders via build-extras.gradle — no action needed on your side.

B5 — iOS deployment target is now 16.0

The old plugin targeted iOS 13.0. The 26.7.1 pods require iOS 16.0. Raise the deployment target in both your Xcode target and the generated Podfile:

# Before
platform :ios, '13.0'
# After
platform :ios, '16.0'

Build with Xcode 26.3 or newer.

B6 — iOS podspec source, renamed pods, and geofence fold

The 26.7.1 pods live in the MapstedHQ spec repo, and the framework coordinates changed. The plugin's plugin.xml declares all of this for you — a normal cordova platform add ios + cordova build ios wires it up — but if you had customized the Podfile by hand, update it to match:

# Before (6.x) — old spec repo, geofence pod, 13.0
source 'https://cdn.cocoapods.org/'
source 'https://github.com/Mapsted/podspec-simulator.git'
platform :ios, '13.0'
pod 'mapsted-sdk-map', '6.1.7'
pod 'mapsted-sdk-map-ui', '6.1.7'
pod 'mapsted-sdk-geofence', '6.1.7'

# After (26.7.1) — MapstedHQ spec repo, use_frameworks!, geofence dropped
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'

Key changes:

  • Podspec source moved from github.com/Mapsted/podspec-simulator.git to github.com/MapstedHQ/podspec.git.
  • use_frameworks! is required.
  • The mapsted-sdk-geofence pod is dropped — geofencing is folded into the core SDK at 26.7.1. If a hand-maintained Podfile added it explicitly, remove that line; there is no replacement pod.
  • Info.plist usage-description keys are added for you by the plugin (iOS terminates the app on location access without them): NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, NSMotionUsageDescription.

This is a packaging change, not a source change

Your JavaScript code is unaffected — this step only ensures the native frameworks resolve and link correctly.

B7 — The plugin JavaScript bridge API is unchanged

There are no changes to the JavaScript API you call. The plugin still clobbers a global MapstedCordovaPlugin object, and MapstedCordovaPlugin.launchMapActivity(onSuccess, onError) works exactly as before — call it after deviceready:

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

This is a distribution, packaging, and toolchain migration — not a JavaScript-API rewrite. Your existing call sites continue to work as written; the success/error callback resolves once the map screen is presented.

Build & packaging

  • Plugin: added by git tag — cordova plugin add https://github.com/MapstedHQ/mapsted-cordova-plugin.git#v26.7.1 (from the official MapstedHQ organization; governed by the Mapsted commercial licence). Plugin 26.7.1 wraps native SDK 26.7.1.
  • Cordova: CLI 12+; cordova-android 15.0.0 and cordova-ios 8.x (B2).
  • Android: minSdkVersion 26, compileSdk 36, Kotlin 2.3.20, and a system Gradle 8.13 on PATH to bootstrap the wrapper (B3, B4). The SDK resolves from https://mapstedhq.github.io/mapsted-android-maven (anonymous) — wired in by the plugin's add_repositories_hook.js; com.google.code.gson:gson:2.11.0 and the required manifestPlaceholders are declared by the plugin.
  • iOS: deployment target 16.0; use_frameworks!; pods from cdn.cocoapods.org + github.com/MapstedHQ/podspec.git (mapsted-sdk-map and mapsted-sdk-map-ui at 26.7.1); Xcode 26.3+. The Info.plist usage-description keys are added by the plugin.
  • Licence: add your platform licence to the app — platforms/android/app/src/main/assets/your_android_license.key (Android) and a bundle resource-file such as res/your_ios_license.key (iOS). Licences are bound to OS and bundle id.

Upgrade checklist

  • [ ] Remove any vendored plugins/mapsted-cordova-plugin and add the git-tag plugin (...#v26.7.1) (B1).
  • [ ] Confirm Cordova CLI 12+, cordova-android 15.0.0, cordova-ios 8.x (B2).
  • [ ] Set <preference name="android-minSdkVersion" value="26" /> in config.xml (B3).
  • [ ] Install Android SDK Platform 36 (compileSdk 36) and put Gradle 8.13 on PATH (B4).
  • [ ] Remove any hand-added Artifactory/JitPack Maven URLs for the Mapsted artifacts (B4).
  • [ ] Raise the iOS deployment target to 16.0 and keep use_frameworks! (B5).
  • [ ] If you hand-maintained a Podfile, switch the source to github.com/MapstedHQ/podspec.git, move the pods to 26.7.1, and remove any explicit mapsted-sdk-geofence pod (B6).
  • [ ] Add your licence files — platforms/android/app/src/main/assets/your_android_license.key (Android) and an iOS .key bundle resource.
  • [ ] Run cordova prepare, then cordova build android and cordova build ios to confirm a clean build.

Troubleshooting

Symptom Likely cause Fix
Could not resolve com.mapsted:android-sdk-* Old vendored plugin still present, or a stale Artifactory/JitPack repo Remove the vendored plugin and add the git-tag plugin; remove old Mapsted Maven URLs (B1, B4)
Android build fails on SDK platform / Failed to find target with hash string 'android-36' Android SDK Platform 36 not installed Install SDK Platform 36 (compileSdk 36 is required by cordova-android 15) (B4)
Gradle wrapper fails to bootstrap No system Gradle 8.13 on PATH Put a Gradle 8.13 distribution on PATH (B4)
uses-sdk:minSdkVersion … cannot be smaller than version 26 minSdkVersion below 26 Set android-minSdkVersion to 26 in config.xml (B3)
cannot find symbol: class Gson / package com.google.gson does not exist Old plugin without the explicit gson declaration Add the 26.7.1 plugin, which declares com.google.code.gson:gson:2.11.0 (B4)
CocoaPods cannot find the Mapsted pods Old podspec source, or plugin not added Use github.com/MapstedHQ/podspec.git; re-add the plugin (B6)
iOS pods fail to resolve on a 13.x deployment target iOS deployment target below 16.0 Set platform :ios, '16.0' (B5)
iOS app closes on location access Missing Info.plist usage-description keys Re-add the 26.7.1 plugin, which supplies the required keys (B6)

Estimated effort

For a typical integration, under an hour — the changes are confined to how the plugin is installed, config.xml, and your Android/iOS toolchain, and your JavaScript is untouched (B7). Apps still on Cordova CLI 11 or cordova-android 13 should budget separately for installing the newer toolchain (Cordova CLI 12+, cordova-android 15, Android SDK Platform 36, Gradle 8.13) before adopting the plugin (B2, B4).

See the v26.7.1 release notes for the full list of new features and improvements in this release.