Skip to content

Latest commit

 

History

History
462 lines (383 loc) · 18.5 KB

README.md

File metadata and controls

462 lines (383 loc) · 18.5 KB
Raw

Cordova GoogleMaps plugin for iOS and Android (version 2.2.9)

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

Both PhoneGap and Apache Cordova are supported.

Quick install

Stable version(npm)

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

(Optional variables)
  // [Android]
  //    The Google Play Services SDK version
  //    You need to specify the same version number with all other plugins.
  //    Check out the latest version is here.
  //    https://developers.google.com/android/guides/releases
  PLAY_SERVICES_VERSION="11.8.0" (for Android)

  // [Android]
  //    This plugin requires the Android support library v4.
  //    The minimum version is 24.1.0
  //    Check out the latest version is here.
  //    https://developer.android.com/topic/libraries/support-library/revisions.html
  ANDROID_SUPPORT_V4_VERSION="24.1.0" (for Android)

  // [iOS]
  //    These variable messages are displayed when application requests
  //    end-user location.
  LOCATION_WHEN_IN_USE_DESCRIPTION="(your custom message)"  (for iOS)
  LOCATION_ALWAYS_USAGE_DESCRIPTION="(your custom message)"  (for iOS)

PhoneGap Build settings

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

    <!-- these are optional settings -->
    <variable name="PLAY_SERVICES_VERSION" value="11.8.0" />
    <variable name="ANDROID_SUPPORT_V4_VERSION" value="24.1.0" />
    <variable name="LOCATION_WHEN_IN_USE_DESCRIPTION" value="(your custom message)" />
    <variable name="LOCATION_ALWAYS_USAGE_DESCRIPTION" value="(your custom message)" />
  </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>

Release Notes

  • v2.2.0

    • No longer supported for Android 4.3 or lower versions. At least Android 4.4 is required.
    • Implement the CSS/HTML element hierarchy correctly.
    • Implement map.addKmlOverlay()
    • other updates

  • v2.2.1

    • Bug fix: can not use Geocoder

  • v2.2.2

    • Bug fix: the icon property of Marker class does not affect

  • v2.2.3

    • Bug fix: the icon property of Marker class does not affect if the html is hosted on file://android_assets/.
    • Update: cordova-android@7 is finally supported.
    • Fix: can not build with PhoneGap Build (see the above settings)

  • v2.2.4

    • Bug fix: can not click html element when you device is rotated.
    • Add: Use android-support-library-v4
    • Fix: cordova-plugin-gooelmaps.CordovaGoogleMaps is already defined warning message.
    • Update: com.googlemaps.ios@2.6.0 is required. Please reinstall the plugin.
    • Add: This plugin messages are localized for English and Japanese.

  • v2.2.5 (small update)

    • Bug fix: setMyLocationEnabed(true) hide the MyLocationButton.
    • Fix: Conflict with cordova-plugin-geolocation

  • v2.2.6

    • Add: support languages (Russian, Ukrainian, Brazilian Portuguese, German, French, Hindi)
    • Fix: [OK]button of <select>tag is displayed as Japanese
    • Fix: Cannot build with Java 1.7
    • Fix: INFO_CLOSE event is triggered twice
    • Fix: map.setOptions() does not work very after soon from the MAP_READY event.

  • v2.2.7

    • Add: support languages (Arabic and Dutch)
    • Fix: Can not build on iOS.

  • v2.2.8

    • Add: support languages (Polish)
    • Add: plugin remove helper script.
    • Fix: can not build on iOS completely.
    • Fix: localize function is incorrect.
    • Fix: can not use backbutton event.
    • Fix: marker cluster does not work correctly if position data contains id field.
    • Update: Wait MAP_READY until map.getVisibleRegion() is ready.

  • v2.2.9

    • Add: support languages (Denmark)
    • Add: hook scripts to prevent unknown property GOOGLE_PLAY_SERVICES_VERSION problem with older version Cordova.
    • Refactoring internal code
    • Fix: Cannot find module '../node_modules/xml2js' error.
    • Fix: getMyLocation() does not work on Genymotion.
    • Fix: map disappears sometime on changing ionic tab.

Quick demo

<script type="text/javascript">
var map;
document.addEventListener("deviceready", function() {
  var div = document.getElementById("map_canvas");

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

  // Wait until the map is ready status.
  map.addEventListener(plugin.google.maps.event.MAP_READY, onMapReady);
}, false);

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

function onButtonClick() {

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

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

      // 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!");

      });
    });
  });
}
</script>

Documentation

All documentations are here!!

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

Quick examples


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

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

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}}
  ]
}, function(markerCluster) { ... });

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

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

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

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

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

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

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(["Current your 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"));
});

How different between Google Maps JavaScript API v3?

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

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

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

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

Features compare table

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

Class compare 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 (not available)
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 put them under the browser.

The map views are not an HTML element. It means they are not kind of <div> or something. But you can specify the size, position of the map view using <div>.

This plugin changes the background as transparent of your app. Then the plugin detects your finger tap position which is for: native map or html element.

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

In the below image, you tap on the header div, which is over the map view. This plugin detects your tap is for the header div or the map view, then pass the mouse event.

It means you can use the native Google Maps views similar like HTML element.

Official Communities

Buy us a beer

Thank you for supporting our activities.

Donate

The donated amount is used for buying testing machine (such as iPhone, Android) or new software.

Buy us a beer (by bitcoin)

Thank you for supporting us by bitcoin.

3LyVAfANZwcitEEnFbsHup3mDJfuqp8QFb