situm-capacitor-plugin-wayfinding-getting-started

Important

This guide refers to the old version of the Wayfinding module, which is no longer maintained. We strongly recommend adopting MapView, the new visual component available at @situm/cordova for both Cordova and Capacitor. To stay up to date, checkout the Cordova SDK Changelog and the example app at the public repository.

This sample application has been designed to test Situm Wayfinding Module for Capacitor. Situm Wayfinding Module for Capacitor has been designed to create indoor location applications in the simplest way, using Capacitor. It has been built in the top of the Situm SDK and its functionalities has been widely tested. If you are interested in building applications using the Situm SDK, please refer to Situm Android SDK Sample app.

With this application you can:

Load a native Situm Map that is integrated into your Capacitor views.
Start positioning at any building of your Situm account.
Start navigation in your buildings.
Interact with both HTML and native elements.

When you first run this app you will see a header, body and footer HTML elements (plus a floating overlay). Touch the body to load the native Situm Map. You can also touch the HTML elements and display a dialog responding to the event.

Initial View	SitumWayfinding Loaded	Navigation

Submitting Contributions

You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.

Requirements

Setup your Situm Account

Before running this application you must set up an account in our Dashboard, retrieve your API KEY and configure your first building.

Go to the sign in form and enter your username and password to sign in.
Go to the account section and on the bottom, click on “generate one” to generate your API KEY.
Go to the buildings section and create your first building.
Download Situm Mapping Tool in Play Store (Only Android devices) and calibrate your building. Check out our user guide for detailed information.
Go to the main app file in the Angular Framework, it is in angular/src/app/app.component.ts. Your Situm user name, API KEY and building ID must be set in the LibrarySettings object of this example app:

const librarySettings = {
          user: "YOUR_SITUM_USER",
          apiKey: "YOUR_SITUM_APIKEY",
          buildingId: "YOUR_BUILDING_ID",
          ...
        };

For your convenience, we have added the file app.constants.json where you can establish this data. This file is imported from the main app file and used to fill the LibrarySettings object.

See Situm Wayfinding Module for Capacitor for more detailed information on the LibrarySettings.

Setup your Google Maps API KEY:

A Google Maps API KEY is required to run this example app. More info is available in the official Google Documentation. Make sure to enable your API KEY for the platforms of your choice.

iOS: put your API KEY in the LibrarySettings object of this example app (or app.constants.json).

const librarySettings = {
          ...
          iosGoogleMapsApiKey: "YOUR_IOS_GOOGLE_MAPS_APIKEY",
          ...
        };

Android: put your API KEY in AndroidManifest.xml. You will find this file in the android/src/main folder of your project.

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

Dependencies

Android

The Situm Wayfinding Module for Capacitor depends on the Situm Wayfinding for Android visual component. This has been already done for you in this sample application, but keep in mind for new projects that the Situm Repository must be added to your project build.gradle file to resolve the dependency:

allprojects {
    repositories {
        maven { url "https://repo.situm.com/artifactory/libs-release-local" }
        ...

If you are targeting Android Pie devices (or above), add Apache Http Legacy to your AndroidManifest.xml:

<uses-library
  android:name="org.apache.http.legacy"
  android:required="false"/>

How to Run

Change into the Angular Framework directory, then run npm install.
Build the web app: npm run build.
Copy the built web app into the native platform: npx cap sync.
Open the native IDE and run the app: npx cap open android/ios (or run with npx cap run android/ios).

Troubleshooting

Check your current node and npm versions:
```
  $ node -v
  vX.Y.X
  $ npm -v
  A.B.C
```
Update them if necessary. We recommend using a node version manager such us:
- Linux and MacOS: nvm.
- Windows: NVS or nvm-windows.
npm may produce an error installing the Capacitor Google Maps dependency. If so, install it manually first and finally complete the dependency tree executing:
```
$ npm install https://github.com/situmtech/capacitor-google-maps.git#situm-alpha.0
$ npm install
```
For Android developers we assume that Android Studio is installed. If not, install it. Check your environmment variable JAVA_HOME, make sure it points to the jre bundled with your Android Studio installation.
- Linux and MacOS:
```
  export JAVA_HOME=/your/path/to/android/studio/jre
```
Add the previous line to your .bashrc if you want to keep its value between sessions.
- Windows:
```
  set JAVA_HOME=C:\your\path\to\android\studio\jre
```
Again, add the JAVA_HOME variable to your environment variables if you want to keep its value between sessions.
We assume you have git installed on your system. If not, install it.

situmtech / situm-capacitor-plugin-wayfinding-getting-started