Migration Guide: 6.2.x → 26.7.1 (Android)

This guide covers everything you need to upgrade an Android app from Mapsted Mobile SDK 6.2.x to 26.7.1. Version 26.7.1 is engine-synced with the iOS 26.7.1 release. For Android the changes are almost entirely distribution and packaging — the client Java/Kotlin API is unchanged — so most apps upgrade by updating their Gradle 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 Android app upgrading from 6.2.x. All of the required changes live in your build.gradle, AndroidManifest.xml, and ProGuard files — a project that changes only its application code, without the packaging updates, will not resolve the dependencies or will fail to build.

Minimum changes to compile

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

Point the Maven repository at GitHub Pages (the old Artifactory URL no longer serves the SDK): groovy // root build.gradle — repositories { } maven { url "https://mapstedhq.github.io/mapsted-android-maven" }
Adopt the BOM and the renamed android-sdk-* coordinates (see B3): groovy dependencies { implementation platform('com.mapsted:android-sdk-bom:26.7.1') implementation 'com.mapsted:android-sdk-core' implementation 'com.mapsted:android-sdk-map' implementation 'com.mapsted:android-sdk-ui' // ...add the other modules you use, without a version }
Raise minSdkVersion to 26 (see B1).
Add the two required manifest placeholders to defaultConfig (see B6): groovy defaultConfig { manifestPlaceholders = [versionCode: "1", dateString: "2026-07-09"] }
If you minify/obfuscate release builds, add the joda-time rule (see B7): -dontwarn org.joda.convert.**

If you do not use the sdk-alerts module (removed — see B5) and do not include the app templates, the steps above are sufficient to build.

Breaking changes (complete reference)

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

ID	Change	Severity	Applies to
B1	Minimum Android SDK version is now 26	High	All apps
B2	SDK is now served from GitHub Pages Maven, not Artifactory	High	All apps
B3	Module coordinates renamed `com.mapsted:sdk-` → `com.mapsted:android-sdk-` (+ BOM)	High	All apps
B4	Map-UI module renamed `sdk-map-ui` → `android-sdk-ui`	Medium	Apps using the Map UI
B5	`sdk-alerts` module removed	Medium	Apps using Alerts on Android
B6	Two manifest placeholders (`versionCode`, `dateString`) now required	High	All apps
B7	R8 / minified builds require `-dontwarn org.joda.convert.**`	Medium	Apps with minify enabled
B8	`android-app-template` requires `tools:replace="android:label"`	Low	Apps that include the app template

B1 — Minimum Android SDK version is now 26

The SDK now requires minSdkVersion 26. A project on 24 fails manifest-merge against the SDK modules.

// Before
minSdkVersion 24
// After
minSdkVersion 26

B2 — SDK is served from GitHub Pages Maven

The client artifacts are now published to a public Maven repository hosted on GitHub Pages. The previous JFrog Artifactory URL does not serve 26.7.1.

// Before — root build.gradle
maven { url "https://mobilesdk.mapsted.com:8443/artifactory/gradle-mapsted" }
// After
maven { url "https://mapstedhq.github.io/mapsted-android-maven" }

The repository is anonymous (no credentials required).

B3 — Module coordinates renamed to `android-sdk-*` + BOM

Every Mapsted module was renamed from com.mapsted:sdk-* to com.mapsted:android-sdk-*. A BOM (android-sdk-bom) now pins all module versions, so you declare each module without a version.

// Before
def mapstedSdkVersion = '6.2.10'
implementation("com.mapsted:sdk-core:${mapstedSdkVersion}")
implementation("com.mapsted:sdk-map:${mapstedSdkVersion}")

// After
implementation platform('com.mapsted:android-sdk-bom:26.7.1')
implementation 'com.mapsted:android-sdk-core'
implementation 'com.mapsted:android-sdk-map'

The client Java/Kotlin package names (com.mapsted.positioning, com.mapsted.map, com.mapsted.geofence, …) are unchanged — only the Gradle coordinates changed, so no import statements need to change for these modules.

B4 — Map-UI module renamed `sdk-map-ui` → `android-sdk-ui`

The prebuilt Map UI module coordinate changed.

// Before
implementation("com.mapsted:sdk-map-ui:${mapstedSdkVersion}")
// After
implementation 'com.mapsted:android-sdk-ui'

The public API package for this module is com.mapsted.ui (e.g., MapstedMapUiApi) — unchanged from 6.2.x.

B5 — `sdk-alerts` module removed

The standalone sdk-alerts module is no longer part of the Android SDK (it was removed after 26.4.1-dev). Remove the dependency:

// Remove this line — no replacement on Android
implementation("com.mapsted:sdk-alerts:${mapstedSdkVersion}")

iOS is unaffected

The Alerts SDK is still shipped on iOS (pod 'mapsted-sdk-alerts'). This removal applies only to the Android SDK.

B6 — Manifest placeholders now required

The SDK declares VersionCode and CreatedDate manifest meta-data using placeholders. Your app must supply them in defaultConfig, or the manifest merge fails:

defaultConfig {
    // ...
    manifestPlaceholders = [versionCode: "1", dateString: "2026-07-09"]
}

Any integer for versionCode and any date string for dateString are accepted.

B7 — R8 / minified builds require a joda-time rule

joda-time (a transitive dependency) references optional compile-only annotations that are absent at runtime. Without a -dontwarn, R8 fails minified/release builds. Add to your proguard-rules.pro:

-dontwarn org.joda.convert.**

Keep your existing Mapsted/Carto keep-rules as well.

B8 — `android-app-template` requires `tools:replace="android:label"`

If you include the optional app-template modules, android-app-template ships its own <application> element. Add xmlns:tools and tools:replace="android:label" to your <application> tag so the manifest merge succeeds:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          xmlns:tools="http://schemas.android.com/tools">
    <application
        tools:replace="android:label"
        android:label="YourAppName">
        <!-- ... -->
    </application>
</manifest>

Most integrations do not need the app templates; skip this if you are not including them.

Build & packaging

Repository: https://mapstedhq.github.io/mapsted-android-maven (anonymous).
BOM: com.mapsted:android-sdk-bom:26.7.1 pins every module.
Native libraries are bundled inside the AARs (positioning engine in android-sdk-core, Carto in android-sdk-map); there are no separate native dependencies to add.
compileSdk 34 (or higher) and JDK 11+ remain the recommended toolchain.
Build toolchain minimums: the 26.7.1 SDK is built with Kotlin 2.3, so your app must use Kotlin 2.3.20 or newer, Android Gradle Plugin 8.9.1 or newer, and Gradle 8.13 or newer. Older Kotlin versions cannot read the SDK’s metadata and will fail to compile.

Upgrade checklist

[ ] Replace the Artifactory repo URL with the GitHub Pages Maven URL (B2).
[ ] Switch to the BOM and rename all coordinates to android-sdk-* (B3).
[ ] Rename sdk-map-ui → android-sdk-ui (B4).
[ ] Remove the sdk-alerts dependency (B5).
[ ] Set minSdkVersion 26 (B1).
[ ] Add the versionCode / dateString manifest placeholders (B6).
[ ] Add -dontwarn org.joda.convert.** if you minify (B7).
[ ] Ensure your build toolchain is Kotlin 2.3.20+, AGP 8.9.1+, and Gradle 8.13+.
[ ] If using app templates, add tools:replace="android:label" (B8).
[ ] Run ./gradlew assembleDebug assembleRelease to confirm a clean build.

Troubleshooting

Could not find com.mapsted:sdk-core — you are still using the old coordinate or repo. Apply B2 + B3.
Manifest merger failed … android:label — you included android-app-template; add tools:replace="android:label" (B8).
Manifest merger failed … versionCode / dateString — add the manifest placeholders (B6).
R8 Missing class org.joda.convert.* — add -dontwarn org.joda.convert.** (B7).
uses-sdk:minSdkVersion 24 cannot be smaller than version 26 — raise minSdkVersion to 26 (B1).
Class '…' was compiled with an incompatible version of Kotlin … metadata version 2.3.0 — your Kotlin/AGP toolchain is too old for the 26.7.1 SDK; upgrade to Kotlin 2.3.20+, AGP 8.9.1+, and Gradle 8.13+.

Estimated effort

For a typical integration, under an hour: the changes are confined to build.gradle, AndroidManifest.xml, and proguard-rules.pro. Apps that used the sdk-alerts module on Android will additionally need to remove that integration.