UniApp Map Plugin Compatibility: 3 Common Mistakes to Avoid

In UniApp development, map plugins such as Gaode and Baidu are frequently used, yet developers often encounter compatibility, permission, and positioning issues. This article focuses on the three most common pitfalls and offers concrete solutions.

Pitfall 1: Map displays on iOS but appears blank on Android

Problem: Android fails to load the map because the AppKey is not configured or required permissions are missing, resulting in a blank map without error messages.

Solution: In the UniApp developer console, enable the map plugin for the Android app and fill in the Android AppKey. Then add the necessary Android permissions, for example:

<!-- pages.json configuration for permissions -->
"app-plus": {
  "permissions": {
    "android.permission.ACCESS_FINE_LOCATION": {
      "desc": "Used to obtain current location and display map positioning"
    },
    "android.permission.ACCESS_COARSE_LOCATION": {}
  }
}

Pitfall 2: Large location offset between reported and actual position

Problem: After calling the map plugin’s location API, the displayed position can deviate by dozens or even hundreds of meters, especially on Android devices.

Solution: Use high-accuracy positioning mode and avoid testing indoors or in heavily obstructed environments. Add calibration code such as:

// Optimized location method
uni.getLocation({
  type: 'gcj02', // Mars coordinate system, matches map plugins to reduce offset
  isHighAccuracy: true, // Enable high-accuracy positioning
  success: (res) => {
    this.latitude = res.latitude;
    this.longitude = res.longitude;
  },
  fail: (err) => {
    uni.showToast({ title: 'Location failed, please check permissions', icon: 'none' });
  }
});

Pitfall 3: App crashes due to conflicts between the map plugin and other plugins

Problem: When the map plugin is used together with push-notification or payment plugins, Android may crash on launch with log messages indicating “class conflict”.

Solution: Verify plugin version compatibility and prefer the versions recommended by UniApp. Ensure that different plugins do not depend on the same native library with mismatched versions. If the conflict cannot be resolved, replace the conflicting plugin (e.g., switch from Gaode to Baidu map).

Conclusion

The key to avoiding map-plugin pitfalls is proper configuration, complete permission setup, and version compatibility. Recommended practices: test basic functionality on real devices (both iOS and Android) after adding a plugin, keep the official plugin documentation for reference, and encapsulate map-related logic in a utility class to handle positioning and rendering uniformly.