Skip to content

GitToTheHub/cordova-plugin-googlemaps-2

BranchesTags
 
 

Repository files navigation

Cordova GoogleMaps plugin for Android, iOS and Browser

This is the continuation of the discontinued plugin cordova-plugin-googlemaps.

This plugin allows you to display a native Google Maps layer in your application and uses the following libraries:

Guides

Installation

GitHub

cordova plugin add https://github.com/GitToTheHub/cordova-plugin-googlemaps-2

Then set your Google Maps API keys into your config.xml (Android / iOS).

<widget ...>
  <preference name="GOOGLE_MAPS_ANDROID_API_KEY" value="(api key)" />
  <preference name="GOOGLE_MAPS_IOS_API_KEY" value="(api key)" />
</widget>

For browser platform,

// If your app runs this program on browser,
// you need to set `API_KEY_FOR_BROWSER_RELEASE` and `API_KEY_FOR_BROWSER_DEBUG`
// before `plugin.google.maps.Map.getMap()`
//
//   API_KEY_FOR_BROWSER_RELEASE for `https:` protocol
//   API_KEY_FOR_BROWSER_DEBUG for `http:` protocol
//
plugin.google.maps.environment.setEnv({
  'API_KEY_FOR_BROWSER_RELEASE': '(YOUR_API_KEY_IS_HERE)',
  'API_KEY_FOR_BROWSER_DEBUG': ''  // optional
});

// Create a Google Maps native view under the map_canvas div.
var map = plugin.google.maps.Map.getMap(div);

iOS

This plugin uses Cocoapods since Version 2.8.0 to add the Google Maps SDK as a dependency and requires iOS 15.5 to be set as deployment-target in your config.xml. This is no problem, because all phones which support iOS 13/14 support also iOS 15. The latest phones which support iOS 15 as last OS, are the iPhone 6s & 6s Plus, first-generation iPhone SE, iPhone 7 & 7 Plus, and iPod Touch. These devices are from 2015 and 2016.

The plugin uses Google Maps SDK version 9.3.0, which is the latest version as of March 2025.

Since Google Maps SDK version 7.3.0 it's possible to run the plugin on a simulator on a Mac with a M CPU (Apple Silicon), but there are some problems with the Metal Renderer (see https://issuetracker.google.com/issues/338162114). As a workaround OpenGL will be used, but which is slower. On a simulator with iOS 15, it can also crash with OpenGL, so it's recommended to test only from iOS 16 onwards in a simulator. See Problems with Google Maps SDK for more details.

If you upgrade from plugin version 2.7.1 to Version 2.8.0 you have to remove the old GoolgeMaps dependency:

cordova plugin remove com.googlemaps.ios

Also you have to remove the old GoogleMaps dependency from your package.json:

  "cordova-plugin-googlemaps-sdk": "github:mapsplugin/cordova-plugin-googlemaps-sdk",

If you used the the old repository, you have to remove it also:

cordova plugin remove cordova-plugin-googlemaps

After that, you can add this plugin.

You can see a changelog of all Google Maps SDK versions here:

https://developers.google.com/maps/documentation/ios-sdk/release-notes

Problems with Google Maps SDK

EXC_BAD_ACCESS (KERN_INVALID_ADDRESS) gmscore::vector::TextureAtlasElement::height() const

Since Google Maps SDK 7.4.0 an EXC_BAD_ACCESS can occur when using the map. This is a known bug and currently not fixed: https://issuetracker.google.com/issues/338162114. This happens only on a simulator. The issue does say that the problem also occurs on a real device, but after testing on a real device with iOS 18, this could not be confirmed. Otherwise this will happen on every iOS version on a simulator. As long the issue is not resolved, OpenGL will be used for a simulator instead of Metal.

EXC_BAD_ACCESS in glvmRasterOpDepthStencilTest (gmscore::renderer::GLEntity::Draw)

Happens only on a simulator with iOS 15 since Google Maps SDK 6.0.0 when using OpenGL: https://issuetracker.google.com/issues/224584852

Install optional variables (config.xml)

Android

  • GOOGLE_MAPS_PLAY_SERVICES_VERSION
    • Defaults to 19.0.0
  • GOOGLE_MAPS_PLAY_SERVICES_LOCATION_VERSION
    • Defaults to 21.3.0

iOS

  • LOCATION_WHEN_IN_USE_DESCRIPTION
    • This message is displayed when your application requests LOCATION PERMISSION for only necessary times.
  • LOCATION_ALWAYS_USAGE_DESCRIPTION
    • This message is displayed when your application requests LOCATION PERMISSION for always.

Release Notes

See CHANGELOG.md

Demos

You can see a demo in your browser:

https://mapsplugin.github.io/HelloGoogleMap

Documentation

You can find the documentation in its own repository:

https://github.com/GitToTheHub/cordova-plugin-googlemaps-doc

It's sourced out, so this repository gets not too big and takes less space when added to a project.

Quick examples


Map		 
var options = {
  camera: {
    target: {lat: ..., lng: ...},
    zoom: 19
  }
};
var map = plugin.google.maps.Map.getMap(mapDiv, options)

Marker		 
var marker = map.addMarker({
  position: {lat: ..., lng: ...},
  title: "Hello Cordova Google Maps for iOS and Android",
  snippet: "This plugin is awesome!"
})

MarkerCluster		 
var markerCluster = map.addMarkerCluster({
  //maxZoomLevel: 5,
  boundsDraw: true,
  markers: dummyData(),
  icons: [
      {min: 2, max: 100, url: "./img/blue.png", anchor: {x: 16, y: 16}},
      {min: 100, max: 1000, url: "./img/yellow.png", anchor: {x: 16, y: 16}},
      {min: 1000, max: 2000, url: "./img/purple.png", anchor: {x: 24, y: 24}},
      {min: 2000, url: "./img/red.png",anchor: {x: 32,y: 32}}
  ]
});

HtmlInfoWindow		 
var html = "<img src='./House-icon.png' width='64' height='64' >" +
           "<br>" +
           "This is an example";
htmlInfoWindow.setContent(html);
htmlInfoWindow.open(marker);

Circle		 
var circle = map.addCircle({
  'center': {lat: ..., lng: ...},
  'radius': 300,
  'strokeColor' : '#AA00FF',
  'strokeWidth': 5,
  'fillColor' : '#880000'
});

Polyline		 
var polyline = map.addPolyline({
  points: AIR_PORTS,
  'color' : '#AA00FF',
  'width': 10,
  'geodesic': true
});

Polygon		 
var polygon = map.addPolygon({
  'points': GORYOKAKU_POINTS,
  'strokeColor' : '#AA00FF',
  'strokeWidth': 5,
  'fillColor' : '#880000'
});

GroundOverlay		 
var groundOverlay = map.addGroundOverlay({
  'url': "./newark_nj_1922.jpg",
  'bounds': [
    {"lat": 40.712216, "lng": -74.22655},
    {"lat": 40.773941, "lng": -74.12544}
  ],
  'opacity': 0.5
});

TileOverlay		 
var tileOverlay = map.addTileOverlay({
  debug: true,
  opacity: 0.75,
  getTile: function(x, y, zoom) {
    return "../images/map-for-free/" + zoom + "_" + x + "-" + y + ".gif"
  }
});

KmlOverlay		 
map.addKmlOverlay({
  'url': 'polygon.kml'
}, function(kmlOverlay) { ... });

Geocoder		 
plugin.google.maps.Geocoder.geocode({
  // US Capital cities
  "address": [
    "Montgomery, AL, USA", ... "Cheyenne, Wyoming, USA"
  ]
}, function(mvcArray) { ... });

poly utility		 
var GORYOKAKU_POINTS = [
  {lat: 41.79883, lng: 140.75675},
  ...
  {lat: 41.79883, lng: 140.75673}
]
var contain = plugin.google.maps.geometry.poly.containsLocation(
                    position, GORYOKAKU_POINTS);
marker.setIcon(contain ? "blue" : "red");

encode utility		 
var GORYOKAKU_POINTS = [
  {lat: 41.79883, lng: 140.75675},
  ...
  {lat: 41.79883, lng: 140.75673}
]
var encodedPath = plugin.google.maps.geometry.
                       encoding.encodePath(GORYOKAKU_POINTS);

spherical utility		 
var heading = plugin.google.maps.geometry.spherical.computeHeading(
                        markerA.getPosition(), markerB.getPosition());
label.innerText = "heading : " + heading.toFixed(0) + "°";

Location service		 
plugin.google.maps.LocationService.getMyLocation(function(result) {
  alert(["Your current location:\n",
      "latitude:" + location.latLng.lat.toFixed(3),
      "longitude:" + location.latLng.lng.toFixed(3),
      "speed:" + location.speed,
      "time:" + location.time,
      "bearing:" + location.bearing].join("\n"));
});

StreetView		 
var div = document.getElementById("pano_canvas1");
var panorama = plugin.google.maps.StreetView.getPanorama(div, {
  camera: {
    target: {lat: 42.345573, lng: -71.098326}
  }
});

What is the difference between this plugin and Google Maps JavaScript API v3?

Google Maps JavaScript API v3 works on any platforms, but it does not work if device is offline.

This plugin uses three different APIs:

In Android and iOS applications, this plugin displays native Google Maps views, which is faster than Google Maps JavaScript API v3. And it even works if the device is offline.

In Browser platform, this plugin displays JS map views (Google Maps JavaScript API v3). It should work as PWA (progressive web application), but the device has to be online.

In order to work for all platforms, this plugin provides own API instead of each original APIs. You can write your code similar to the Google Maps JavaScript API v3.

Feature comparison table

Google Maps JavaScript API v3 Cordova-Plugin-GoogleMaps(Android,iOS) Cordova-Plugin-GoogleMaps(Browser)
Rendering system JavaScript + HTML JavaScript + Native API's JavaScript
Offline map Not possible Possible (only your displayed area) Not possible
3D View Not possible Possible Not possible
Platform All browsers Android and iOS applications only All browsers
Tile image Bitmap Vector Bitmap

Class comparison table

Google Maps JavaScript API v3 Cordova-Plugin-GoogleMaps
google.maps.Map Map
google.maps.Marker Marker
google.maps.InfoWindow Default InfoWindow, and HtmlInfoWindow
google.maps.Circle Circle
google.maps.Rectangle Polygon
google.maps.Polyline Polyline
google.maps.Polygon Polygon
google.maps.GroundOverlay GroundOverlay
google.maps.ImageMapType TileOverlay
google.maps.MVCObject BaseClass
google.maps.MVCArray BaseArrayClass
google.maps.Geocoder plugin.google.maps.geocoder
google.maps.geometry.spherical plugin.google.maps.geometry.spherical
google.maps.geometry.encoding plugin.google.maps.geometry.encoding
google.maps.geometry.poly plugin.google.maps.geometry.poly
(not available) MarkerCluster
google.maps.KmlLayer KmlOverlay
(not available) LocationService
google.maps.StreetView StreetView ✨
google.maps.Data (not available)
google.maps.DirectionsService (not available)
google.maps.DistanceMatrixService (not available)
google.maps.TransitLayer (not available)
google.maps.places.* (not available)
google.maps.visualization.* (not available)

How does this plugin work (Android, iOS)?

This plugin generates native map views, and puts them under the browser.

The map views are not HTML elements. This means that they are not a <div> or anything HTML related. But you can specify the size and position of the map view using its containing <div>.

This plugin changes the background to transparent in your application. Then the plugin detects your touch position, which is either meant for the native map or an html element (which can be on top of your map, or anywhere else on the screen).

The benefit of this plugin is the ability to automatically detect which HTML elements are over the map or not.

For instance, in the image below, say you tap on the header div (which is over the map view). The plugin will detect whether your tap is for the header div or for the map view and then pass the touch event appropriately.

This means you can use the native Google Maps views similar to HTML elements.

About

Google Maps plugin for Cordova

Resources

Readme

License

Apache-2.0 license
Activity

Stars

5 stars

Watchers

1 watching

Forks

2 forks
Report repository

Releases 1

Release 2.8.0 Latest
Mar 24, 2025

Packages

No packages published

Languages

  • JavaScript 37.3%
  • Objective-C 32.6%
  • Java 30.0%
  • Shell 0.1%