In this Section, we provide an Android and iOS step-by-step guide to build your first Situm app using React Native. For more advanced use cases, take a look at our React Native sample app and at the Plugin Method Reference.
Note for devs using Expo: Even though Situm’s React Native plugin is not avaliable in the Expo Go app, it can be integrated in projects using Expo. Keep an eye on the bach scripts’ tabs to see if you need to run a different command for an project that uses Expo.
Pre-requisites: Installing React Native #
First, you need to setup react-native development environment. To get started please follow instructions under section React Native CLI Quickstart on this guide and finally execute the react-native cli to create a new app:
npm uninstall -g react-native-cli @react-native-community/cli npx @react-native-community/cli@latest init my_indoor_location_app
npx create-expo-app@latest --template
Installing Situm SDK for React Native #
Then, you may install Situm SDK for React Native by using npm or yarn (plus some dependencies that are needed):
# You may use yarn yarn add @situm/react-native react-native-webview # or you may also use npm npm install --save @situm/react-native react-native-webview
# Command to install dependencies for situm plugin npm install expo-dev-client react-native-webview # Command to install the plugin npx expo install @situm/react-native
Note for devs using Expo: If you are using Expo, it is currently necessary to specify the repository in your project’s build.gradle file. Add the following repository to your maven repository list.
allprojects {
repositories {
maven {
url "https://repo.situm.com/artifactory/libs-release-local"
}
}
}
Requesting permissions #
Starting in @situm/react-native@3.15.0 the SDK can automatically request the necessary permissions for positioning.
You can enable this powerful feature by simply calling the SitumSdk.enableUserHelper method:
SitumPlugin.init(); // ... // Automatically manage positioning permissions and sensor issues: SitumPlugin.enableUserHelper();
You can also customize the UI with your own color scheme by calling SitumPlugin.configureUserHelper(UserHelperOptions).
If you prefer, you can also choose to request permissions yourself using your preferred method (more info here).
Android #
Add the ACCESS_FINE_LOCATION permission declaration to your AndroidManifest.xml (you can omit this step if you have configured Situm SDK not to use GPS):
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
iOS #
You will also need to include the following permissions in your app’s Info.plist file (modify the permission’s informative texts as you wish):
<key>NSLocationWhenInUseUsageDescription</key> <string>Location is required to find out where you are</string> <key>NSLocationAlwaysAndWhenInUseUsageDescription</key> <string>Location is required to find out where you are</string> <key>NSMotionUsageDescription</key> <string>We use your phone sensors (giroscope, accelerometer and altimeter) to improve location quality</string>
Setup native projects #
iOS #
AppBoundDomains #
If you want the MapViewer (built-in Wayfinding UI) to work offline, you will need to add the underlying web application’s domain inside the entry WKAppBoundDomains, also on Info.plist as follows:
<key>WKAppBoundDomains</key> <array> <string>maps.situm.com</string> </array>
Warning! If you have other Webviews in your app this might affect them. Learn more about this here.
Finally, execute these lines:
$ cd ios $ pod install
Optional steps #
Sometimes, you may need to add a Header Search Path:
$(SRCROOT)/../node_modules/react-native-situm-plugin/lib/ios
Under some React Native versions, you might also need to remove the “use_frameworks!” directive in the Podfile of your iOS project, or else configure the Podfile. This is needed because Situm SDK is a static library
Run your first app! #
The following code contains a fully functional React Native app. You may copy & paste it in your App.tsx file (you may obtain your credentials as explained here, and your building ID as explained here):
Remember: You must introduce you API key | Building ID | Profile name | POI ID in the snippet below or the app will throw an error or not work properly.
import React, { useEffect, useRef, useState } from 'react';
import { StyleSheet } from 'react-native';
// 1) Importing dependencies
import SitumPlugin, {
MapView,
MapViewRef,
SitumProvider,
} from '@situm/react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
// 2) Define your Situm API key (required), building identifier(required),
// profile(optional) and POI ID to navigate to (optional).
const SITUM_API_KEY = 'YOUR_API_KEY';
const SITUM_BUILDING_ID = 'YOUR_BUILDING';
const SITUM_PROFILE = 'YOUR_PROFILE';
const YOUR_POI_ID = 'YOUR_POI_ID';
const App = () => (
<SafeAreaProvider>
<SafeAreaView style={styles.mapContainer} edges={['top', 'bottom']}>
{/** 3) Initialize & authenticate by specifying `SitumProvider.apiKey` */}
<SitumProvider apiKey={SITUM_API_KEY}>
<Screen />
</SitumProvider>
</SafeAreaView>
</SafeAreaProvider>
);
const Screen: React.FC = () => {
// This mapViewRef is used to make direct calls to the MapView component
// methods, such as navigateToPoi() or selectPoi()
const mapViewRef = useRef<MapViewRef>(null);
const [controller, setController] = useState<MapViewRef | null>();
// 4) Configure Situm SDK and start positioning
useEffect(() => {
// Automatically manage positioning permissions and sensor issues
SitumPlugin.enableUserHelper();
// Listen for Location, LocationStatus and Error updates
setLocationCallbacks();
// Start positioning:
SitumPlugin.requestLocationUpdates();
return () => {
// You may want to prevent from displaying UserHelper dialogs in other screens.
SitumPlugin.disableUserHelper();
// You may want to stop positioning when unmounting component
// SitumPlugin.removeLocationUpdates();
};
}, []);
const setLocationCallbacks = () => {
SitumPlugin.onLocationUpdate(location => {
console.log(
`SitumPlugin> sdk> Location update: ${JSON.stringify(location)}`,
);
});
// The main errors and states will be handled automatically by the UserHelper,
// but in this example we show how to manually listen to these events.
SitumPlugin.onLocationStatus(status => {
console.log(`SitumPlugin> sdk> Status: ${status.statusName}`);
});
SitumPlugin.onLocationError(error => {
console.log(`SitumPlugin> sdk> Error(${error.code}): ${error.message}`);
});
};
// Once the map has loaded, mapViewRef is available so set this variable to be able
// to start calling MapViewRef methods like selectPoi(), navigateToPoi(), ...
useEffect(() => {
if (!mapViewRef) {
return;
}
setController(mapViewRef.current);
}, [mapViewRef]);
// 5) Show the building cartography
return (
<MapView
ref={mapViewRef}
configuration={{
buildingIdentifier: SITUM_BUILDING_ID,
profile: SITUM_PROFILE,
}}
onPoiSelected={(poi: any) => {
console.log(`Situm > wayfinding > Poi selected: ${poi.identifier}`);
}}
onLoad={(event: any) => {
console.log('Map is ready now' + JSON.stringify(event));
// Now controller can be used. Try to set a valid poi identifier
// and see how it gets selected programatically over the map
controller?.selectPoi(Number(YOUR_POI_ID));
}}
/>
);
};
const styles = StyleSheet.create({
mapContainer: {
flex: 1,
},
});
export default App;
And then run your app by executing the following terminal command:
# You may run your app in Android or iOS yarn run android # or iOS yarn run ios
# You may run your app in Android or iOS npx expo run:android # or iOS npx expo run:ios
You should see something like this:
Code explanation: step-by-step #
1. Importing dependencies #
The 1st thing the example does is importing the @situm/react-native package.
2. Setting credentials and building identifier #
Right after the import, we set:
- User credentials: APIKEY.
- Building identifier: identifier of the building whose cartography will be shown. It should be the same as the one where you’ll perform positioning.
You may obtain your credentials as explained here, and your building ID as explained here.
3. Initialize the SDK and start positioning #
You may initialize and start positioning by using the SDK API provided by our @situm/react-native plugin detailed in the example above. To do so, you may execute the following steps:
- Initialize the SDK with init.
- Optionally set up your session to use the remote configuration with setConfiguration.
- Request permissions manually, or use SitumPlugin.enableUserHelper() to automatically manage permission and sensor related issues.
- Starts positioning with Remote Configuration. Alternatively, you may define your positioning options when calling requestLocationUpdates.
4. Show the cartography using the MapView #
Then, the example shows the cartography of the selected building. You may see that the wayfinding library exposes two main classes to this extent:
- MapView. The React Native component that you can add to your view hierarchy.
- SitumProvider. This is a wrapper for your aplication that the Situm plugin uses to handle internal state. You must wrap the screen that uses Situm with this Provider or you can wrap your entire application with it as well.
Advanced configuration #
To further configure the user experience see our Advanced Topics section that explains additional capabilities of both Situm SDK and MapView as well as how to configure them on your projects. Topics you can be interested in are: battery efficiency, location cache, working offline with cached data, foreground & background execution, external provider locations, listen to geofences entries & exits, how to provide your iOS app’s privacy manifest, how to configure the MapView UX.