Skip to content
Developers Docs

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

Migration Guide: 6.x → 26.7.1 (Flutter)

This guide covers everything you need to upgrade a Flutter app from the old Mapsted mapsted_flutter plugin (the pub.dev 0.0.x / 6.x line) to the officially-distributed mapsted_flutter 26.7.1. 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. The changes are almost entirely distribution, packaging, and consumer toolchain — the plugin's Dart/method-channel API is unchanged — so most apps upgrade by switching to the git dependency 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 Flutter app upgrading from the pub.dev 0.0.x plugin. All of the required changes live in your pubspec.yaml, your app's android/ Gradle configuration, and your ios/Podfile — a project that only switches the dependency, without the toolchain updates, will not resolve the native artifacts or will fail to build. Your own Dart code does not need to change (B8).

Minimum changes to compile

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

  1. Switch to the git dependency pinned to v26.7.1 — replace the pub.dev mapsted_flutter: ^0.0.x entry with the git dependency, then run flutter pub get (see B1).
  2. Be on Flutter 3.29 or newer (certified on a current stable channel) (B2).
  3. Android — set minSdkVersion to 26 and confirm your Kotlin/AGP/Gradle toolchain meets the floors below; the plugin's scaffolder injects the SDK's required manifestPlaceholders and the GitHub-Pages Maven repository for you (B3, B4, B7).
  4. iOS — raise the deployment target to 16.0 and add the Mapsted podspec source to your Podfile, then run pod install (B5, B6).

If your app is a standard flutter create project, the steps above are sufficient to build and run — the plugin handles the Android manifest placeholders and Maven repository automatically.

Recommended (non-blocking) cleanup

Remove any leftover Artifactory/JitPack Maven URLs from your android/ configuration and any explicit mapsted-sdk-geofence pod from your Podfile — the 26.7.1 plugin provides the Maven repository automatically (B7) 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 dependency pinned to tag v26.7.1 (was pub.dev mapsted_flutter@0.0.x) High All apps
B2 Flutter 3.29 is the minimum (certified on a current stable channel) High All apps
B3 Android toolchain floor: Kotlin 2.3.20, AGP 8.9.1, Gradle 8.13; gson:2.11.0 must be declared High Android
B4 Android minSdkVersion is now 26 High Android
B5 iOS deployment target is now 16.0 High iOS
B6 iOS Podfile needs the MapstedHQ podspec source; geofence pod folded into core High iOS
B7 Android SDK now served from GitHub Pages Maven; manifestPlaceholders injected by the plugin Medium Apps with custom repos / legacy Groovy layout
B8 The plugin Dart API is unchanged None (informational) All apps

B1 — Distribution changed to a git dependency pinned to v26.7.1

The plugin is no longer published on pub.dev. It is distributed as a git dependency by tag (v26.7.1) from the official MapstedHQ GitHub organization, and its version is aligned to the native SDK. Replace your pub.dev entry with the git dependency:

# Before — pubspec.yaml
dependencies:
  mapsted_flutter: ^0.0.9

# After — pubspec.yaml
dependencies:
  mapsted_flutter:
    git:
      url: https://github.com/MapstedHQ/mapsted-flutter.git
      ref: v26.7.1

Then run flutter pub get. The plugin version tracks the native SDK exactly: plugin 26.7.1 wraps native SDK 26.7.1. This is a major upgrade, not a drop-in bump — the native SDK underneath changed from 6.x to 26.7.1, which is what drives the toolchain requirements below.

Commercial licence

Use of the SDK requires a valid Mapsted commercial licence, bundled as LICENSE; using the SDK requires a valid signed agreement. Contact support@mapsted.com for licensing.

B2 — Flutter 3.29 minimum

The 26.7.1 plugin is certified on Flutter 3.29+ (a current stable channel). Upgrade your app to at least Flutter 3.29 before adopting the plugin; older channels ship an Android Gradle toolchain that cannot consume the 26.7.1 Android artifacts (see B3).

B3 — Android toolchain floor: Kotlin 2.3.20 / AGP 8.9.1 / Gradle 8.13 + Gson

The 26.7.1 Android artifacts require an updated Gradle toolchain. Confirm your android/ build uses at least:

  • Kotlin 2.3.20
  • Android Gradle Plugin 8.9.1
  • Gradle 8.13

In addition, com.google.code.gson:gson:2.11.0 must be declared explicitly — it is no longer pulled in transitively at 26.7.1. Add it to your app module's dependencies:

// android/app/build.gradle (Groovy)
dependencies {
    implementation "com.google.code.gson:gson:2.11.0"
}

// android/app/build.gradle.kts (Kotlin DSL)
dependencies {
    implementation("com.google.code.gson:gson:2.11.0")
}

Match the toolchain floor exactly

A Kotlin, AGP, or Gradle version below the floors above will fail to read the 26.7.1 Android artifacts' metadata during the build. Bring all three up to at least the versions listed before building.

B4 — Android minSdkVersion is now 26

The SDK's map UI requires API 26, so the native SDK requires minSdkVersion 26. A project on a lower minimum fails manifest-merge against the SDK modules.

// Before — android/app/build.gradle
minSdkVersion 24
// After
minSdkVersion 26

// android/app/build.gradle.kts
defaultConfig {
    minSdk = 26
}

This is a bump from the old 24 minimum on the 6.x line.

B5 — iOS deployment target is now 16.0

The 6.x plugin targeted iOS 13.0. The 26.7.1 pods cannot resolve on a 13.x deployment target. Raise it to 16.0 in both your Xcode target and your Podfile:

# Before — ios/Podfile
platform :ios, '13.0'

# After — ios/Podfile
platform :ios, '16.0'

Setting only the Xcode target without updating the Podfile platform will leave the CocoaPods-generated pod targets on the old minimum — update both.

B6 — iOS Podfile: MapstedHQ podspec source + geofence fold

The 26.7.1 pods live in the MapstedHQ spec repo — the old github.com/Mapsted/podspec-simulator.git (and the old pub-distributed source) no longer serve 26.7.1. Update the podspec source at the top of your Podfile:

# Before
source 'https://cdn.cocoapods.org/'
source 'https://github.com/Mapsted/podspec-simulator.git'

# After
source 'https://cdn.cocoapods.org/'
source 'https://github.com/MapstedHQ/podspec.git'

The Mapsted pods themselves are renamed and bumped, and the standalone geofence pod is dropped — geofencing is folded into the core SDK at 26.7.1:

Pod (6.1.x) Pod (26.7.1)
mapsted-sdk-map:6.1.x mapsted-sdk-map:26.7.1
mapsted-sdk-map-ui:6.1.x mapsted-sdk-map-ui:26.7.1
mapsted-sdk-geofence:6.1.x (removed — folded into MapstedCore)

If your Podfile added mapsted-sdk-geofence explicitly, remove that line — geofencing is available through the core module with no separate pod:

# ios/Podfile — remove if present (no replacement pod needed)
pod 'mapsted-sdk-geofence'

After editing the Podfile, run pod install (or pod update).

Info.plist usage-description keys

The SDK requires the standard location, Bluetooth, and motion usage-description keys — iOS terminates the app on location access without them. Ensure your Info.plist includes NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, and NSMotionUsageDescription.

B7 — Android GitHub Pages Maven + manifestPlaceholders

Two Android distribution changes are handled by the plugin but may require you to remove old configuration or, on a legacy layout, add one block:

  • GitHub Pages Maven — the SDK is now served from the public GitHub Pages Maven repository (https://mapstedhq.github.io/mapsted-android-maven); the previous Artifactory/JitPack URLs no longer serve the Mapsted artifacts. The plugin injects the correct repository during the build, so remove any hand-added Mapsted Artifactory/JitPack maven { url ... } entries from your android/ configuration to avoid a stale resolution. Native coordinates were also renamed and bumped — com.mapsted:sdk-*:6.x → com.mapsted:android-sdk-{core,map,ui}:26.7.1 (note the sdk-map-ui → android-sdk-ui rename) — but these are resolved for you from the injected repository.

  • manifestPlaceholders — the 26.7.1 Android artifacts require two manifest placeholders (versionCode and dateString) during the manifest merge. The plugin's scaffolder injects them for you and supports both the Groovy android/app/build.gradle and the modern Kotlin-DSL android/app/build.gradle.kts that recent flutter create projects emit — so a fresh Flutter app builds without manual manifest edits.

Legacy Groovy layout only

A project on a very old Groovy android/app/build.gradle layout may need to add the placeholders to the app android {} block by hand:

groovy // android/app/build.gradle — only if the scaffolder cannot inject them android { defaultConfig { manifestPlaceholders += [versionCode: <n>, dateString: <yyyyMMdd>] } }

A standard flutter create project (Groovy or Kotlin DSL) does not need this — the scaffolder handles it.

B8 — The plugin Dart API is unchanged

There are no changes to the API surface of your Flutter code. The widgets and functions the plugin exports — MapstedMapView, MapstedFlutter.launchMapActivity(), and their properties/callbacks (propertyId, onMapReady, …) — keep the same names and shapes as the 0.0.x line. This is a distribution, packaging, and toolchain migration, not a source-API rewrite. Your existing Dart call sites continue to work as written after you switch the dependency (B1):

import 'package:mapsted_flutter/mapsted_flutter.dart';

// Embedded indoor map for a property (unchanged):
MapstedMapView(
  propertyId: 504,
  onMapReady: () {},
);

// Fullscreen property picker → indoor map (unchanged):
await MapstedFlutter.launchMapActivity();

Use the embedded MapstedMapView for production surfaces

The embedded MapstedMapView is the recommended, certified integration path — validated on real arm64 hardware on both platforms, including first launch — and is the best choice for production surfaces. The fullscreen launchMapActivity() opens the native SDK's own full-screen map screen and is well suited to quick previews and simple full-screen use.

Build & packaging

  • Plugin: mapsted_flutter at tag v26.7.1, distributed as a git dependency from https://github.com/MapstedHQ/mapsted-flutter.git (governed by the Mapsted commercial licence). Plugin 26.7.1 wraps native SDK 26.7.1.
  • Flutter: 3.29 minimum (certified on a current stable channel).
  • Android: minSdkVersion 26, Kotlin 2.3.20, AGP 8.9.1, Gradle 8.13; declare com.google.code.gson:gson:2.11.0 (B3). The SDK resolves from https://mapstedhq.github.io/mapsted-android-maven (anonymous) — injected by the plugin during the build; the plugin's scaffolder also injects the required manifestPlaceholders for both Groovy and Kotlin-DSL layouts (B7).
  • iOS: deployment target 16.0; pods from cdn.cocoapods.org + github.com/MapstedHQ/podspec.git; build with Xcode 26.3 or newer. The geofence pod is folded into core (B6).
  • Info.plist (iOS): NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, NSMotionUsageDescription.
  • Licence: add your platform licence to the app — android/app/src/main/assets/your_android_license.key (Android) and Copy Bundle Resources → your_ios_license.key (iOS). Licences are bound to OS and bundle id.

Upgrade checklist

  • [ ] Replace the pub.dev mapsted_flutter entry with the git dependency pinned to v26.7.1, then run flutter pub get (B1).
  • [ ] Confirm your app is on Flutter 3.29 or newer (B2).
  • [ ] Bring Android to Kotlin 2.3.20, AGP 8.9.1, Gradle 8.13, and declare gson:2.11.0 (B3).
  • [ ] Set minSdkVersion 26 (Groovy or Kotlin DSL) (B4).
  • [ ] Raise the iOS deployment target to 16.0 in the Podfile and Xcode target (B5).
  • [ ] Update the podspec source to github.com/MapstedHQ/podspec.git and remove any explicit mapsted-sdk-geofence pod (B6).
  • [ ] Remove any old Artifactory/JitPack Maven URLs from android/ (B7).
  • [ ] Add the iOS Info.plist usage-description keys the SDK requires (NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, NSMotionUsageDescription).
  • [ ] Run flutter pub get and pod install, then build Android (flutter build apk) and iOS to confirm a clean build.

Troubleshooting

Symptom Likely cause Fix
Could not resolve com.mapsted:android-sdk-* Stale Artifactory/JitPack repo, or the plugin's Maven injection was bypassed Remove old Mapsted Maven URLs; let the plugin inject the GitHub-Pages repo (B7)
Android build fails reading Kotlin metadata Kotlin/AGP/Gradle below the 26.7.1 floor Set Kotlin 2.3.20, AGP 8.9.1, Gradle 8.13 (B3)
NoClassDefFoundError / missing com.google.gson.* at build or runtime Gson no longer transitive at 26.7.1 Declare com.google.code.gson:gson:2.11.0 (B3)
Manifest merge fails on missing versionCode / dateString placeholder Legacy Groovy layout the scaffolder could not patch Add manifestPlaceholders += [versionCode: <n>, dateString: <yyyyMMdd>] (B7)
uses-sdk:minSdkVersion … cannot be smaller than version 26 minSdkVersion below 26 Set minSdkVersion 26 (B4)
CocoaPods cannot find the Mapsted pods Old podspec source still configured Use source 'https://github.com/MapstedHQ/podspec.git' (B6)
CocoaPods cannot find mapsted-sdk-geofence Geofence pod folded into core Remove the mapsted-sdk-geofence line (B6)
Pods fail to resolve on a 13.x deployment target iOS deployment target below 16.0 Set platform :ios, '16.0' (B5)

Estimated effort

For a typical integration already on Flutter 3.29+, under an hour — the changes are confined to pubspec.yaml, your android/ Gradle configuration, and ios/Podfile, and your Dart code is untouched (B8). Apps still on an older Flutter channel should budget separately for the Flutter upgrade itself (B2) before adopting the plugin.

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