Cordova GoogleMaps plugin for iOS and Android (version 2.3.8)

This plugin is a thin wrapper for Google Maps Android API and Google Maps SDK for iOS.

Both PhoneGap and Apache Cordova are supported.

---

Guides

• How to generate API keys?
• Hello, World
• Hello, World (with PhoneGap Build)
• Trouble shootings

Quick install

• Stable version(npm)

$> cordova plugin add cordova-plugin-googlemaps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..."

• Development version(beta version)

$> cordova plugin add https://github.com/mapsplugin/cordova-plugin-googlemaps#multiple_maps \
    --variable API_KEY_FOR_ANDROID="..." \
    --variable API_KEY_FOR_IOS="..."

PhoneGap Build settings

<widget ...>
  <plugin name="cordova-plugin-googlemaps" spec="2.3.8">
    <variable name="API_KEY_FOR_ANDROID" value="(api key)" />
    <variable name="API_KEY_FOR_IOS" value="(api key)" />
  </plugin>

  <!--
    You need to specify cli-7.1.0 or greater version.
    https://build.phonegap.com/current-support
  -->
  <preference name="phonegap-version" value="cli-8.0.0" />
</widget>

Install optional variables

• PLAY_SERVICES_VERSION = (15.0.1)
  The Google Play Services SDK version. You need to specify the same version number with all other plugins. Check out the latest version here.

• ANDROID_SUPPORT_V4_VERSION = (27.1.1)
  This plugin requires the Android support library v4. The minimum version is 24.1.0. Check out the latest version here.

• 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.

---

Please support this plugin activity.

In order to keep this plugin as free, please consider to donate little amount for this project.

---

Release Notes

• v2.3.8

  • Hot fix: v2.3.7 does not work for iOS. Sorry about that.:pensive:

• v2.3.7

  • Update: Regenerate tbxml-android.aar with android:minSdkVersion="19" for the developers who use older cordova verions
  • Fix: Can't interact with map on Android 4.4.2 if body uses ResetCSS rule
  • Fix: Fixed bug in "getMyLocation" with last location result
  • Fix: HtmlInfo window content not clickable if HTML structure is very simple
  • Fix: MarkerCluster does not work with error "evaluating 'Object.keys(self._markerMap)'"
  • Fix: Conflicting with Kendo UI framework.
  • Fix: Clustered marker icons with specified dimensions reverting to default ones when redrawn [iOS]
  • Update: NSTimer scheduledTimerWithTimeInterval code
  • Fix: Map does not resize when map div is resized.

• v2.3.6

  • Fix: onPause causes app crashes on Android
  • Fix: Can't find variable: element
  • Fix: Can't interact with map on tutorial code

• v2.3.5

  • Fix: cordova.fireDocumentEvent('plugin_touch', {}) blocks HTML DOM tree parsing process.
  • Fix: Uncaught TypeError: evt.target.hasAttribute is not a function when device is rotated.
  • Fix: marker.setDisableAutoPan() does not work on iOS.
  • Fix: before_plugin_install.js does not work very if Cordova blows off dependency package installation.

• v2.3.4

  • Fix: plugin does not recognize HTML elements correctly after moving HTML elements with animations
  • Fix: map did not attach after coming back from stacked another page
  • Fix: map does not resize when keyboard is hiding.

• v2.3.3

  • Comment out debug code (only this)

• v2.3.2

  • Update: reduce the number of times of DOM tree parse process. (= improve performance.)
  • Fix: map.getMyLocation() and LocationService.getMyLocation() do not work.
  • Fix: can not execute any methods of the marker obtained from MARKER_CLICK event of marker cluster
  • Fix: can not touch Div element which is moved with css transition over map view.
  • Fix: internal event does not work well with ionic 1 project.

• v2.3.1

  • Fix: incompatible with @ionic-native/google-maps

• v2.3.0

  • New feature: StreetView
  • A callback is no longer required for the most part.
  • Promise is supported instead of callback

---

Quick demo

document.addEventListener("deviceready", function() {
  var div = document.getElementById("map_canvas");

  // Initialize the map view
  var map = plugin.google.maps.Map.getMap(div);


  var button = document.getElementById("button");
  button.addEventListener("click", function() {

    // Move to the position with animation
    map.animateCamera({
      target: {lat: 37.422359, lng: -122.084344},
      zoom: 17,
      tilt: 60,
      bearing: 140,
      duration: 5000
    });

    // Add a maker
    var marker = map.addMarker({
      position: {lat: 37.422359, lng: -122.084344},
      title: "Welcome to \n" +
             "Cordova GoogleMaps plugin for iOS and Android",
      snippet: "This plugin is awesome!",
      animation: plugin.google.maps.Animation.BOUNCE
    });

    // Show the info window
    marker.showInfoWindow();

    // Catch the click event
    marker.on(plugin.google.maps.event.INFO_CLICK, function() {

      // To do something...
      alert("Hello world!");

    });
  }
}, false);

---

Documentation

All documentations are here!!

https://github.com/mapsplugin/cordova-plugin-googlemaps-doc/blob/master/v2.3.0/README.md

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?

This plugin displays the map view using the native API's via (Java and Objective-C), which is faster than Google Maps JavaScript API v3.

The native map view even works if the device is offline.

This plugin provides the features of the native map view to JS developers.

You can write your code similar to the Google Maps JavaScript API v3.

Feature comparison table

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

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	KMLLayer
(not available)	LocationService
google.maps.StreetView	StreetView ✨
google.maps.Data	(not available)
google.maps.DirectionsService	(not available)
google.maps.DistanceMatrixService	(not available)
google.maps.FusionTablesLayer	(not available)
google.maps.TransitLayer	(not available)
google.maps.places.*	(not available)
google.maps.visualization.*	(not available)

How does this plugin work?

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.

---

Official Communities

• Google+ : (managed by @wf9a5m75)

  https://plus.google.com/communities/117427728522929652853

• Gitter : (managed by @Hirbod)

  https://gitter.im/nightstomp/cordova-plugin-googlemaps