Skip to content
Developers Docs

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

Migration Guide: 6.x → 26.7.1 (React Native)

This guide covers everything you need to upgrade a React Native app from the old Mapsted mapsted-react-native wrapper (the 0.0.x / 6.x line) to the renamed, officially-scoped @mapsted/maps-react-native@26.7.2. The 26.7.2 wrapper 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 wrapper's JavaScript/TypeScript API is unchanged — so most apps upgrade by bumping the 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 React Native app upgrading from the 0.0.x wrapper. All of the required changes live in your package.json, your app's android/ Gradle configuration, and your ios/Podfile — a project that only bumps the npm dependency, without the toolchain and Podfile updates, will not resolve the native artifacts or will fail to build. Your own .ts/.tsx 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. Install the renamed, scoped wrapper — npm install @mapsted/maps-react-native@26.7.2 (replaces mapsted-react-native; see B1).
  2. Be on React Native 0.76 or newer (certified on 0.76.9); React Native 0.74 and older cannot load the 26.7.1 Android artifacts (B2).
  3. Android — set minSdkVersion to 26, add -Xskip-metadata-version-check to your app module's Kotlin options, and switch your app theme to a Material Components theme (B3, B4). Keep React Native 0.76.9's default Kotlin — do not force Kotlin 2.x.
  4. iOS — raise the deployment target to 16.0 and add the Mapsted podspec source to your Podfile (B5, B6).
  5. iOS — add the dynamic-framework linkage hook so the app does not crash at launch, then run pod install (B6).

If your app does not add Mapsted pods directly and does not use the fullscreen map path, the steps above are sufficient to build and run.

Recommended (non-blocking) cleanup

Remove any leftover Artifactory/JitPack Maven URLs or an explicit mapsted-sdk-geofence pod from your project — the 26.7.1 wrapper provides the Maven repository automatically (B7) and the geofence module is folded into core (B7).

Breaking changes (complete reference)

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

ID Change Severity Applies to
B1 Package renamed and scoped: @mapsted/maps-react-native@26.7.2 (was mapsted-react-native@0.0.x) High All apps
B2 React Native 0.76 is the minimum (certified on 0.76.9) High All apps
B3 Android: add -Xskip-metadata-version-check and a Material Components host theme (keep RN 0.76's default Kotlin) 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 Mapsted podspec source + a dynamic-framework linkage hook High iOS
B7 Android SDK now served from GitHub Pages Maven; iOS geofence pod folded into core Medium Apps with custom repos / geofence pod
B8 The wrapper JavaScript API is unchanged None (informational) All apps

B1 — Package renamed and scoped to @mapsted/maps-react-native

The wrapper is now published under Mapsted's official @mapsted npm scope, and its version is aligned to the native SDK. Both the package name and the version change — update your dependency and every import:

# Before
npm install mapsted-react-native@^0.0.13
# After
npm install @mapsted/maps-react-native@26.7.2

Then update every import to the new specifier, '@mapsted/maps-react-native' (the exported names are unchanged — see B8). 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.

Public package, commercial licence

@mapsted/maps-react-native is a public npm package under Mapsted's official @mapsted scope, so npm install resolves without an access grant. It 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 — React Native 0.76 minimum

React Native 0.74 and older cannot consume the 26.7.1 Android artifacts: their Kotlin 1.9.0 toolchain and Gradle plugin cannot read the artifacts' Kotlin 2.3.20 metadata, and forcing a newer Kotlin on the 0.74 Gradle plugin breaks it outright (Found interface KotlinTopLevelExtension, but class was expected). Upgrade your app to at least React Native 0.76 — the wrapper and sample are certified on React Native 0.76.9 (Gradle 8.10.2, AGP 8.6) — before adopting the wrapper.

B3 — Android: Kotlin metadata flag + Material Components theme

The 26.7.1 Android artifacts are compiled with Kotlin 2.3.20 and carry its metadata. Keep React Native 0.76.9's default Kotlin (1.9.25) — do not force the Kotlin Gradle plugin to 2.x, which breaks React Native 0.76's own Gradle plugin. Instead, tell the compiler to skip the metadata-version gate by adding -Xskip-metadata-version-check to your app module (android/app/build.gradle):

// android/app/build.gradle
android {
    kotlinOptions {
        freeCompilerArgs += ["-Xskip-metadata-version-check"]
    }
}

Separately, the SDK's fullscreen map UI inflates com.google.android.material widgets, so your app's theme must derive from a Material Components theme — otherwise the map screen crashes on open with InflateException … Error inflating class com.google.android.material.button.MaterialButton. The .Bridge variant keeps React Native's AppCompat views working:

<!-- android/app/src/main/res/values/styles.xml -->
<style name="AppTheme" parent="Theme.MaterialComponents.DayNight.NoActionBar.Bridge">

B4 — Android minSdkVersion is now 26

The native SDK requires minSdkVersion 26. A project on a lower minimum fails manifest-merge against the SDK modules.

// Before — android/build.gradle (buildscript ext)
minSdkVersion = 24
// After
minSdkVersion = 26

Android Gradle Plugin 8.6+ and Gradle 8.10+ are also required; these are the defaults that ship with React Native 0.76, so no separate change is normally needed.

B5 — iOS deployment target is now 16.0

React Native's default iOS deployment target (15.1) cannot resolve the 26.7.1 pods. Raise it to 16.0 in both your Xcode target and your Podfile:

# ios/Podfile
platform :ios, '16.0'

B6 — iOS Podfile: podspec source + dynamic-framework linkage hook

The 26.7.1 pods live in the MapstedHQ spec repo, and two transitive prebuilt-dynamic dependencies must be forced to build as dynamic frameworks, or the app crashes at launch with Library not loaded: @rpath/SDWebImage.framework.

Add the Mapsted podspec source at the top of your Podfile:

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

Then choose one of the two linkage options below and run pod install (or pod update).

Option A (recommended for a standard RN app without use_frameworks!) — force the two dependencies to build as dynamic frameworks:

dynamic_frameworks = ['SDWebImage', 'SSZipArchive']
pre_install do |installer|
  installer.pod_targets.each do |pod|
    if dynamic_frameworks.include?(pod.name)
      def pod.build_type; Pod::BuildType.dynamic_framework; end
    end
  end
end

Option B — set use_frameworks! on your app target. Everything links dynamically, so the hook above is unnecessary. Simpler, but it changes linkage for your whole app.

This is a packaging change, not a source change

Your Swift/Objective-C and JavaScript code is unaffected — this step only ensures the native frameworks link and load correctly.

B7 — Android GitHub Pages Maven + iOS geofence fold

Two distribution changes are handled by the wrapper but may require you to remove old configuration:

  • Android — 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 26.7.1. The wrapper injects the correct repository during install, so remove any hand-added Mapsted Artifactory/JitPack maven { url ... } entries from your android/build.gradle to avoid a stale resolution.
  • iOS — the standalone mapsted-sdk-geofence pod was folded into the core SDK at 26.7.1. If your Podfile added it 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'

B8 — The wrapper JavaScript API is unchanged

There are no changes to the API surface of your React Native code. The components and functions the wrapper exports — MapstedMapView, launchMapActivity, and their props/callbacks (propertyId, destinations, startNavigation, onMapReady, onRouteReady, onNavigationInstructionStarted, onMapLoadError, …) — keep the same names and shapes as the 0.0.x line. The only change is the import specifier: replace from 'mapsted-react-native' with from '@mapsted/maps-react-native' (B1); all call sites otherwise continue to work as written.

Use the embedded MapstedMapView for production surfaces

The embedded MapstedMapView is the recommended, certified integration path — validated on real arm64 hardware, 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

  • npm package: @mapsted/maps-react-native@26.7.2 (public on npm; governed by the Mapsted commercial licence).
  • React Native: 0.76 minimum (certified on 0.76.9).
  • Android: minSdkVersion 26, AGP 8.6+ / Gradle 8.10+ and Kotlin 1.9.25 (RN 0.76.9 defaults) plus -Xskip-metadata-version-check and a Material Components host theme (B3). The SDK resolves from https://mapstedhq.github.io/mapsted-android-maven (anonymous) — injected by the wrapper during install; the positioning engine and Carto renderer are bundled inside the native artifacts, so there are no separate native dependencies to add.
  • iOS: deployment target 16.0; pods from cdn.cocoapods.org + github.com/MapstedHQ/podspec.git; the dynamic-framework linkage hook from B6.
  • Licence: add your platform licence to the app — 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.
  • Expo: the wrapper is a native module, so it requires bare React Native or an Expo prebuild / development build (it cannot run in Expo Go).

Upgrade checklist

  • [ ] Replace mapsted-react-native with @mapsted/maps-react-native@26.7.2 and update every import (B1).
  • [ ] Confirm your app is on React Native 0.76 or newer (B2).
  • [ ] Set Kotlin 2.3.20 in android/build.gradle (B3).
  • [ ] Set minSdkVersion 26 (B4).
  • [ ] Raise the iOS deployment target to 16.0 in the Podfile and Xcode target (B5).
  • [ ] Add the Mapsted podspec source and the dynamic-framework linkage hook to the Podfile (B6).
  • [ ] Remove any old Artifactory/JitPack Maven URLs and any explicit mapsted-sdk-geofence pod (B7).
  • [ ] Add the iOS Info.plist usage-description keys the SDK requires (NSLocationWhenInUseUsageDescription, NSLocationAlwaysAndWhenInUseUsageDescription, NSBluetoothAlwaysUsageDescription, NSMotionUsageDescription).
  • [ ] Run pod install, then build Android (./gradlew assembleRelease from android/) and iOS to confirm a clean build.

Troubleshooting

Symptom Likely cause Fix
Could not resolve com.mapsted:android-sdk-* Stale Artifactory/JitPack repo, or wrapper install did not inject the Maven repo Reinstall the wrapper; remove old Mapsted Maven URLs (B7)
Android build fails reading Kotlin metadata / Module was compiled with an incompatible version of Kotlin Kotlin compiler older than 2.3.20 Set kotlinVersion = "2.3.20" (B3)
uses-sdk:minSdkVersion … cannot be smaller than version 26 minSdkVersion below 26 Set minSdkVersion 26 (B4)
serviceOf / Gradle 8.9 error, or artifacts won't load on an older RN React Native 0.74 or older Upgrade to React Native 0.76+ (B2)
CocoaPods cannot find the Mapsted pods Missing podspec source Add source 'https://github.com/MapstedHQ/podspec.git' (B6)
App crashes at launch: Library not loaded: @rpath/SDWebImage.framework Missing dynamic-framework linkage Add the pre_install hook or use_frameworks! (B6)
Pods fail to resolve on a 15.x deployment target iOS deployment target below 16.0 Set platform :ios, '16.0' (B5)

Estimated effort

For a typical integration already on React Native 0.76+, under an hour — the changes are confined to package.json, android/build.gradle, and ios/Podfile, and your React Native code is untouched (B8). Apps still on React Native 0.74 or older should budget separately for the React Native upgrade itself (B2) before adopting the wrapper.

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