Skip to main content
This guide helps you migrate your application between major versions of the Open Mobile Maps SDK. Each major version may include breaking changes that require code updates.

​
Migrating to 3.x

Version 3.0.0 introduced significant changes including 3D globe rendering, improved spatial precision, and reverse geocoding capabilities.

​
Major Changes in 3.0.0

Version 3.0.0 was released on February 16, 2024, and includes several major improvements:

​
3D Globe Rendering

  • Added support for 3D globe rendering with most established layers and features
  • New camera and configuration options specifically for 3D mode
  • If you were using custom camera implementations, you may need to update them to work with the new 3D capabilities

​
Improved Spatial Precision

  • Massively improved the spatial precision of the map
  • This may affect coordinate calculations in your application
  • Review any custom coordinate handling code to ensure compatibility

​
Reverse Geocoding

  • Introduced reverse geocoding with closest feature detection
  • This is a new feature that you can now leverage in your applications

​
SwiftUI Support (iOS)

  • Exposed MapView in SwiftUI
  • If you’re building iOS apps with SwiftUI, you can now use the declarative MapView component

​
Android Updates

  • Updated to AGP 8.7.2 and Kotlin 2.0.21
  • Ensure your Android project meets the minimum requirements
  • Improved interceptor handling in the default DataLoader

​
Other Improvements

  • Fixed an issue with the internal asynchronous message handling
  • Added the option to animate the scale of elements in the IconLayer
  • Added support for feature dependent text-font in style.jsons

​
Breaking Changes in 3.8.0

Version 3.8.0 introduces a breaking change in the LocalDataProvider interface due to support for multiple sprite sources.
If you have implemented a custom LocalDataProvider, you will need to update your implementation to support multiple sprite sources:
  • Review the updated LocalDataProvider interface
  • Update your implementation to handle multiple sprite sources
  • Test your custom provider thoroughly with the new version

​
Breaking Changes in 3.3.0

@3x sprites are now opt-in by default. This may affect high-resolution displays.
Starting from version 3.3.0:
  • By default, the SDK no longer attempts to fetch @3x sprites
  • To enable @3x sprites, explicitly add the use3xSprites property to the metadata in your style JSON:
{
  "metadata": {
    "use3xSprites": true
  }
}

​
Migrating to 2.x

Version 2.0.0 was a major release with significant improvements in vector map performance, stability, and rendering.

​
Major Changes in 2.0.0

Version 2.0.0 was released on February 16, 2024:

​
Vector Map Improvements

  • Major improvements in vector map performance, stability, and rendering
  • Expanded options for style specifications and GeoJSON support
  • If you were experiencing performance issues with vector maps in 1.x, this version should provide significant improvements

​
Layer Enhancements

  • Enhanced stability and performance for raster, icon, polygon, and line layers
  • Review your layer implementations to take advantage of the new stability improvements

​
Testing Your Migration

Thoroughly test your application after upgrading to 2.0.0, especially if you use vector maps or custom layer implementations.
  • Test all map rendering functionality
  • Verify vector tile rendering
  • Check custom layer implementations
  • Test on both Android and iOS platforms

​
Version 2.6.0 iOS Changes

Version 2.6.0 increased the iOS deployment target to iOS 14.
If you’re upgrading to version 2.6.0 or later:
  • Ensure your iOS deployment target is set to iOS 14 or higher
  • Update your Xcode to version 16 or later for iOS builds
  • The Android OffscreenMapRenderer can now be reused

​
Migrating from 1.x

​
Key Considerations

If you’re migrating from version 1.x to 3.x:
  1. First review the 2.0.0 migration notes above
  2. Then review the 3.0.0 migration notes
  3. Pay special attention to:
    • Coordinate system changes (improved spatial precision in 3.0.0)
    • Camera API changes (3D support)
    • Style JSON format changes (sprite handling, feature-dependent fonts)
    • Platform version requirements (iOS 14+, updated Android tooling)

​
Incremental Migration

For large applications, consider migrating incrementally through major versions (1.x → 2.x → 3.x) rather than jumping directly to the latest version.
This approach allows you to:
  • Identify and fix breaking changes more easily
  • Test thoroughly at each step
  • Understand the impact of each major version’s changes

​
Platform-Specific Considerations

​
Android

  • Kotlin Version: Updated to 2.2.0 in version 3.4.0
  • AGP Version: Updated to 8.13.1 in version 3.7.0
  • Minimum SDK: Android 8.0+ (OpenGL ES 3.2)
  • 16KB Page Sizes: Supported starting from version 3.5.0 (target SDK 36)

​
iOS

  • Minimum iOS Version: iOS 14+ (as of version 2.6.0)
  • SwiftUI Support: Available starting from version 3.0.0 (requires iOS 17.0+)
  • Xcode: Version 16+ recommended for latest features

​
Getting Help

If you encounter issues during migration:
  1. Check the changelog for detailed version information
  2. Review the GitHub repository for known issues
  3. Consult the platform-specific documentation for Android and iOS

​
Best Practices

Always test your migration thoroughly before deploying to production.
  • Create a dedicated branch for the migration
  • Update dependencies incrementally
  • Run your full test suite after each update
  • Test on real devices, not just simulators
  • Review performance metrics before and after migration

Build docs developers (and LLMs) love

Get started for freeTalk to us