Situm-capacitor-googlemaps-native NPM

Purpose

Under the hood this package makes use of the native Maps SDK for Android and iOS. The native Maps SDK has much better performance than the JS equivalent. It also adds support for offline caching. On top of that it is completely free to use (native pricing), in contrary to the JS SDK (JS pricing).

Maintainers

Maintainer	GitHub	Mail
Hemang Kumar	hemangsk	hemangsk@gmail.com

Support Development

If you like this plugin and use it on your projects, please consider donating to support the development. Thank you!

Getting Started

Installation

Install package from npm

npm i --save @capacitor-community/capacitor-googlemaps-native
npx cap sync

Setup

Obtain API Keys

You must add an API key for the Maps SDK to any app that uses the SDK.

Before you start using the Maps SDK, you need a project with a billing account and the Maps SDK (both for Android and iOS) enabled.

Extensive and detailed steps can be found here:

You should have two API keys by the end of this step. Lets proceed:

Adding API keys to your App

Android

Please follow the guide here: https://developers.google.com/maps/documentation/android-sdk/get-api-key#add_key

Alternatively, you can (but really should not) use the following quick and dirty way:

In your AndroidManifest.xml add the following lines:

<application>
...
+  <meta-data
+    android:name="com.google.android.geo.API_KEY"
+    android:value="YOUR_ANDROID_MAPS_API_KEY"/>
...
</application>

where YOUR_ANDROID_MAPS_API_KEY is the API key you aqcuired in the previous step.

iOS

On iOS, the API key needs to be set programmatically. This is done using the initialize method.

Initializing a Map instance

After following all installation steps, you can follow this small guide to quickly setup a simple Map instance.

Setting up your HTML

The Maps SDK renders a native element (MapView) behind your webapp (WebView). You need to specify the boundaries (which is explained later) that is rendered in. So it is NOT an HTMLElement, but rather a native element. It can therefore not be styled, mutated or listened to like you would with a 'normal' HTMLElement.

At the moment,the only drawback of this is, that the map instance does not size and move along with the div that it is attached to. This is a known issue and it will be solved in the future as there are some known solutions as well. However, most use cases would use a Map instance that stays at a fixed position anyway.

Therefore the only requirement right now is to make sure the 'foster element' (the element which you are going to attach the Map instance to) remains at the same position. This can be achieved by preventing it to be able to scroll and to make the current view portrait (or landscape) only.

So let's get to it. Let's assume you have the following layout:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width,initial-scale=1.0" />
    <title>Maps SDK for Capacitor - Basic Example</title>
    <style>
      body {
        margin: 0;
      }
      #container {
        width: 100vw;
        height: 100vh;
        background: #000;
      }
    </style>
  </head>
  <body>
    <div id="container"></div>
  </body>
</html>

Note that it can be anything really. Like with Capacitor itself, it does not matter what framework you are using. Angular, Vue, React, Svelte... they are all supported.

Setting up your JavaScript

The Plugin can be imported as follows:

import { CapacitorGoogleMaps } from "@capacitor-community/capacitor-googlemaps-native";

Let's assume you have imported the Plugin correctly. A simple Maps instance can then be initialized as follows:

const initializeMap = async () => {
  // first of all, you should initialize the Maps SDK:
  await CapacitorGoogleMaps.initialize({
    key: "YOUR_IOS_MAPS_API_KEY",
    devicePixelRatio: window.devicePixelRatio, // this line is very important
  });

  // then get the element you want to attach the Maps instance to:
  const element = document.getElementById("container");

  // afterwards get its boundaries like so:
  const boundingRect = element.getBoundingClientRect();

  // we can now create the map using the boundaries of #container
  try {
    const result = await CapacitorGoogleMaps.createMap({
      boundingRect: {
        width: Math.round(boundingRect.width),
        height: Math.round(boundingRect.height),
        x: Math.round(boundingRect.x),
        y: Math.round(boundingRect.y),
      },
    });

    // remove background, so map can be seen
    element.style.background = "";

    // finally set `data-maps-id` attribute for delegating touch events
    element.setAttribute("data-maps-id", result.googleMap.mapId);

    alert("Map loaded successfully");
  } catch (e) {
    alert("Map failed to load");
  }
};

(function () {
  // on page load, execute the above method
  initializeMap();

  // Some frameworks and a recommended lifecycle hook you could use to initialize the Map:
  // Ionic: `ionViewDidEnter`
  // Angular: `mounted`
  // Vue: `mounted`
  // React: `componentDidMount`

  // Of course you can also initialize the Map on different events, like clicking on a button.
  // Just make sure you do not unnecessarily initialize it multiple times.
})();

What's next?

As the previous example shows, it is really easy to integrate the Maps SDK into your app. But, of course, there are many more possibilities.

Refer to API Reference to learn more everything about the Maps API.
Take a look at some examples here.

Known Issues

Right now, its not possible to allow Map view in the template to scroll along with the Page, it remains at its fixed position.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

capacitor plugin native

@capacitor/cli @capacitor/core

@infinitebrahmanuniverse/nolb-sit @everything-registry/sub-chunk-2772 situm-capacitor-plugin-wayfinding

0.0.3

2 years ago

0.0.2

2 years ago

0.0.1

2 years ago