@situm/react-native-wayfinding v0.3.2
Integrate plug&play navigation experience with floorplans, POIs, routes and turn-by-turn directions in no time. with the power of SITUM.
Introduction
Situm SDK is a set of utilities that allow any developer to build location based apps using Situm's indoor positioning system. Among many other capabilities, apps developed with Situm SDK will be able to:
- Obtain information related to buildings where Situm's positioning system is already configured: floor plans, points of interest, geotriggered events, etc.
- Retrieve the location of the smartphone inside these buildings (position, orientation, and floor where the smartphone is).
- Compute a route from a point A (e.g. where the smartphone is) to a point B (e.g. any point of interest within the building).
- Trigger notifications when the user enters a certain area.
In this tutorial, we will guide you step by step to set up your first react-native application using Situm SDK. Before starting to write code, we recommend you to set up an account in our Dashboard (https://dashboard.situm.es), 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 Android application. With this application you will be able to configure and test Situm's indoor positioning system in your buildings.
Perfect! Now you are ready to develop your first indoor positioning application.
Prerequisites
First, you need to setup a React Native development environment. You will also need a functional React Native app (where you will integrate this plugin). The instructions under section React Native CLI Quickstart on this guide will be helpful.
Installation
On the root folder of your project, execute:
yarn add @situm/react-native-wayfinding
or with yarn:
npm install @situm/react-native-wayfinding
You may have warnings advicing you about a few peer dependencies, make sure you also install them via npm install dependecy-name
or yarn add dependency-name
yarn add react-native-permissions react-native-situm-plugin react-native-webview
Situm repository (Android only)
To allow Gradle to compile your Android application, add the Situm artifact repository to the build.gradle
file at the root of your project:
buildScript {
// ...
}
allprojects {
repositories {
// ...
maven { url "https://repo.situm.es/artifactory/libs-release-local" }
}
}
Permissions
In order to work correctly the user will have to confirm the use of location and Bluetooth services.
- In Android, this is handled automatically by the plugin.
- In iOS, you will need to include a pair of keys and its descriptions on the Info.plist file of the native .xcworkspace project. See below:
- NSLocationAlwaysAndWhenInUseUsageDescription : Location is required to find out where you are
- NSBluetoothAlwaysUsageDescription : Bluetooth is required to find where you are
Usage
Copy & paste this in your App.tsx or App.js file for a quick start!
Minimal usage:
import React from 'react';
import { MapView, SitumProvider } from '@situm/react-native-wayfinding';
import { StyleSheet, View } from 'react-native';
const SITUM_EMAIL = 'YOUR_EMAIL_HERE';
const SITUM_API_KEY = 'YOUR_APIKEY_HERE';
const SITUM_BUILDING_ID = 'YOUR_BUILDING_ID_HERE';
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
});
const App: React.FC = () => {
return (
<View style={styles.container}>
<SitumProvider email={SITUM_EMAIL} apiKey={SITUM_API_KEY}>
<MapView
user={SITUM_EMAIL}
apikey={SITUM_API_KEY}
buildingId={SITUM_BUILDING_ID}
// other props
/>
</SitumProvider>
</View>
);
};
export default App;
More elaborated usage:
import * as React from 'react';
import { StyleSheet, View, Text } from 'react-native';
import {
MapView,
OnFloorChangedResult,
OnNavigationResult,
OnPoiDeselectedResult,
OnPoiSelectedResult,
WayfindingResult,
} from '@situm/react-native-wayfinding';
export default function App() {
const onMapReady = (event: WayfindingResult) => {
console.log('Map is ready now' + JSON.stringify(event));
};
const onFloorChanged = (event: OnFloorChangedResult) => {
console.log('on floor change detected: ' + JSON.stringify(event));
};
const onPoiSelected = (event: OnPoiSelectedResult) => {
console.log('on poi selected detected: ' + JSON.stringify(event));
};
const onPoiDeselected = (event: OnPoiDeselectedResult) => {
console.log('on poi deselected detected: ' + JSON.stringify(event));
};
const onNavigationRequested = (event: OnNavigationResult) => {
console.log('on navigation requested detected: ' + JSON.stringify(event));
};
const onNavigationStarted = (event: OnNavigationResult) => {
console.log('on navigation started detected: ' + JSON.stringify(event));
};
const onNavigationError = (event: OnNavigationResult) => {
console.log('on navigation error detected: ' + JSON.stringify(event));
};
const onNavigationFinished = (event: OnNavigationResult) => {
console.log('on navigation finished detected: ' + JSON.stringify(event));
};
return (
<View style={styles.container}>
<SitumProvider email="SITUM_USER" apiKey="SITUM_APIKEY">
<MapView
style={styles.mapview}
user="SITUM_USER" //Your Situm user account (e.g. user@email.com)
apikey="SITUM_APIKEY" //Your Situm APIKEY
buildingId="BUILDING_ID" //The identifier of the building where you want to center the view (e.g. "1234")
onMapReady={onMapReady} //Called when the maps is ready
onFloorChanged={onFloorChanged} //Called when the user moves to another floor
onPoiSelected={onPoiSelected} //Called when the user selects a POI
onPoiDeselected={onPoiDeselected} //Called when the user de-selects a POI
onNavigationRequested={onNavigationRequested} //Called when the user requests a route / navigation
onNavigationStarted={onNavigationStarted} // Called when the navigation starts
onNavigationError={onNavigationError} //Called when the route / navigation stops unexpectedly
onNavigationFinished={onNavigationFinished} //Called when the route / navigation finishes
enablePoiClustering={true} //Clusters close POIs together
showPoiNames={true} //Shows the POI name on top of each POI
useRemoteConfig={true} // Use the Remote Configuration
initialZoom={18} //Initial zoom level (Android Only)
minZoom={16} //Minimum zoom level (user can't zoom out further)
maxZoom={21} //Maximum zoom level (user can't zoom in further)
useDashboardTheme={true} //Use the primary color & logo of your organization as configured in Situm Dashboard
/>
</SitumProvider>
</View>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
mapview: {
width: '100%',
height: '100%',
},
});
API
This plugin is just a (partial) wrapper over our native Android / iOS Situm WYF module. Therefore, you should take a look at it's documentation to have an understanding of how it works and the configurations that can be applied. You will also benefit from taking a look at our SDKs documentation, which Situm WYF uses heavily. Specifically, concepts about positioning, cartography, routes, navigation and remote configuration.
MapView
Properties
Type | Default | Description | |
---|---|---|---|
user | string | - | Your Situm user account (e.g. user@email.com) |
apikey | string | - | Your Situm APIKEY |
buildingId | string | - | The identifier of the building where you want to center the view (e.g. "1234"). More info. |
enablePoiClustering | boolean | true | Clusters close POIs together. More info. |
showPoiNames | boolean | true | Shows the POI name on top of each POI. More info. |
useRemoteConfig | boolean | true | Use the Remote Configuration. More info. |
initialZoom | number 15-21 | 18 | Initial zoom level. More info. |
minZoom | number 15-21 | - | Minimum zoom level (user can't zoom out further). More info. |
maxZoom | number 15-21 | - | Maximum zoom level (user can't zoom in further). More info. |
useDashboardTheme | boolean | true | Use the primary color & logo of your organization as configured in Situm Dashboard. More info. |
Callbacks
Callback | Data | Description |
---|---|---|
onMapReady | WayfindingResult | Map has been loaded |
onFloorChanged | OnFloorChangedResult | User has moved from one floor to another |
onPoiSelected | OnPoiSelectedResult | User has selected a POI |
onPoiDeselected | OnPoiDeselectedResult | User has deselected a POI |
onNavigationRequested | OnNavigationResult | User has requested a route |
onNavigationStarted | OnNavigationResult | Navigation has started |
onNavigationError | OnNavigationResult | Route could not be computed or navigation finished unexpectedly |
onNavigationfinished | OnNavigationResult | User has reached its destination point |
Interfaces
WayfindingResult
Prop | Type | Description |
---|---|---|
status | String | "SUCCESS" when the map is ready |
message | String | Human readable message |
OnPoiSelectedResult
Prop | Type | Description |
---|---|---|
buildingId | String | ID of the building where the POI was selected |
buildingName | String | Name of the building where the POI was selected |
floorId | String | ID of the floor where the POI was selected |
floorName | String | Name of the floor where the POI was selected |
poiId | String | ID of the POI that was selected |
poiName | String | Name of the POI that was selected |
OnPoiDeselectedResult
Prop | Type | Description |
---|---|---|
buildingId | String | ID of the building where the POI was deselected |
buildingName | String | Name of the building where the POI was deselected |
OnFloorChangedResult
Prop | Type | Description |
---|---|---|
buildingId | String | ID of the building where the floor change happened |
buildingName | String | Name of the building where the floor change happened |
fromFloorId | String | ID of the floor from which the user moved |
toFloorId | String | ID of the floor to which the user moved |
fromFloorName | String | Name of the floor from which the user moved |
toFloorName | String | Name of the floor to which the user moved |
Point
Prop | Type | Description |
---|---|---|
buildingId | String | ID of the building where the point is |
floorId | String | ID of the floor where the point is |
latitude | Number | Latitude where the point is in WSG84 |
longitude | Number | Longitude where the point is in WSG84 |
Destination
Prop | Type | Description |
---|---|---|
category | String | Type of destination. Options: "POI" or "LOCATION" |
identifier | String? | (Optional) POI identifier (only when category="POI") |
name | String? | (Optional) POI name (only when category="POI") |
point | Point? | Destination point |
Navigation
Prop | Type | Description |
---|---|---|
status | String | Status of the navigation request. Options: "REQUESTED" (navigation has been requested, received by "onNavigationRequested" callback), "CANCELED" (navigation stopped by the user, received by "onNavigationFinished" callback), "DESTINATION_REACHED" (user has arrived to the destination, received by "onNavigationFinished" callback) |
destination | Destination | Destination of the navigation |
OnNavigationResult
Prop | Type | Description |
---|---|---|
navigation | Navigation | Result of the navigation provided to callbacks "onNavigationRequested" and "onNavigationFinished" callbacks |
error | Error? | (Optional) Error detected during the navigation |
Error
Prop | Type |
---|---|
code | Number |
message | String |
Versioning
Please refer to CHANGELOG.md for a list of notable changes for each version of the plugin.
You can also see the tags on this repository.
Submitting contributions
You will need to sign a Contributor License Agreement (CLA) before making a submission. Learn more here.
License
This project is licensed under the MIT - see the LICENSE file for further details.
More information
More info is available at our Developers Page.
Support information
For any question or bug report, please send an email to support@situm.es
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
12 months ago
11 months ago
12 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago