Objective-C Java JavaScript Ruby
Latest commit bc2bf07 Aug 13, 2018

README.md

Cordova GoogleMaps plugin for iOS and Android (version 2.3.11)

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

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.11">
    <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.

Donate


Release Notes

  • v2.3.11

    • Fix: can't load local files if wkwebview hosts the index.html on file:// protocol
    • Fix: Some people can't build because of Java errors
    • Fix: Some JS errors
  • v2.3.10

    • Fix: Can't find variable: onTransitionFinish
  • v2.3.9

    • Fix: polyline.setPoints() does not work in iOS
    • Fix: App crashes on iOS if icon url is redirected to another url
    • Fix: touch is incorrect if another div size is changed
    • Fix: can not interact with maps at all on ionic 3
    • Remove debug code
    • Update: code update for ionic v4 beta (You need to use @ionic-native/google-maps@5.0.0-beta.14 )
    • Maybe fix: app crash when map.addMarker() with icon on ionic.
  • v2.3.8

    • Hot fix: v2.3.7 does not work for iOS. Sorry about that.😔
  • 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.


Contributing change

Please read the CONTRIBUTING.md for details on how to contribute to this project.


Official Communities