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.
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:
$ npx react-native init my_indoor_location_app
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
Requesting permissions #
Since the requestPermission method has been removed in @situm/react-native 3.9.0, you now have the flexibility to request permissions using your preferred method (more info here). Installing react-native-permissions is no longer necessary, which avoids potential compatibility issues.
For your convenience, the file requestPermission.tsx remains available in the React Native sample app. You can easily integrate it into your own code and modify it to fit your needs.
If you choose to integrate the requestPermission.tsx file and consequently the react-native-permissions plugin, you need to make sure to use the correct version of react-native-permissions dependency, in the package.json
"react-native-permissions": "^3.8.4",
iOS #
You will also need to configure the required permissions for iOS (more info here). Follow the first step of this guide.
Then add the following permissions to your podfile:
setup_permissions([ 'LocationAccuracy', 'LocationAlways', 'LocationWhenInUse', 'Motion', ])
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>
Finally install the Permission Handlers by adding this to your package.json:
{
...
"reactNativePermissionsIOS": [
"LocationAccuracy",
"LocationAlways",
"LocationWhenInUse",
"Motion"
],
...
}
Setup native projects #
You will also need to make some changes to the native projects of your React Native application.
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" />
Then, set the minSdkVersion to 23 or later on your app’s build.gradle file.
iOS #
AppBoundDomains #
Then, 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>map-viewer.situm.com</string> </array>
If you have other webviews in your app this might affect them, you can 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):
import React, {useEffect} from 'react';
import {SafeAreaView, StyleSheet} from 'react-native';
// 1. Importing dependencies
import SitumPlugin, { MapView, SitumProvider } from '@situm/react-native';
// Modify this import according to your project structure:
import requestPermission from 'YOUR_PATH_TO/requestPermission';
// 2. Define Situm SDK credentials and building identifier
const SITUM_API_KEY = 'YOUR_APIKEY';
const SITUM_BUILDING_ID = 'YOUR_BUILDING';
const styles = StyleSheet.create({
container: {
flex: 1,
alignItems: 'center',
justifyContent: 'center',
},
mapview: {
width: '100%',
height: '100%',
},
});
const Screen: React.FC = () => {
// 3. Initialize the Situm SDK and start positioning
useEffect(() => {
//Initialize Situm and set credentials
SitumPlugin.init();
SitumPlugin.setApiKey(SITUM_API_KEY);
// Set positioning configuration
SitumPlugin.setConfiguration({useRemoteConfig: true});
// Request necessary permissions to start positioning
requestPermission()
.then(() => {
SitumPlugin.requestLocationUpdates();
})
.catch(e => {
console.log(`Permissions rejected: ${e}`);
});
// Stop positioning when unmounting component
return () => SitumPlugin.removeLocationUpdates();
}, []);
// 4. Show the building cartography
return (
<MapView
style={{...styles.mapview}}
configuration={{
buildingIdentifier: SITUM_BUILDING_ID,
situmApiKey: SITUM_API_KEY,
}}
onPoiSelected={poi => {
console.log(`Situm > wayfinding > Poi selected: ${poi.identifier}`);
}}
onLoad={(event: any) => {
console.log('Map is ready now' + JSON.stringify(event));
}}
/>
);
};
const App = () => (
<SafeAreaView style={{...styles.container}}>
<SitumProvider>
<Screen />
</SitumProvider>
</SafeAreaView>
);
export default App;
And then run your app by executing the following terminal command:
$ yarn start
While executing your app, the following error may appear:
To avoid this error, make sure that you are only using the react-native-permissions 3.8.4 version. In order to resolve this error, change the version of the dependency to 3.8.4 in the package.json file, delete the yarn.lock file in the root directory of the project and then relaunch the project ‘yarn start’.
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.
- Request the required permissions, uses the library react-native-permissions under the hood. If you want to fine tune your permission handling manually, just check the code example that we provide in requestPermissions.tsx.
- Optionally set up your session to use the remote configuration with setConfiguration.
- 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.
Expo Support #
This package is not available in the Expo Go app. However, you can integrate it by following the steps described below:
Install the necessary dependencies as outlined in this guide:npx expo install @situm/react-native react-native-webview
Add Situm to your component as described in the example above.
Launch the application. Use the following command to run your project on Android or iOS:
npx expo run:android
npx expo run:ios
For Android, it is currently necessary to specify the repository in your project’s build.gradle file:
allprojects {
repositories {
maven {
url "https://repo.situm.com/artifactory/libs-release-local"
}
}
}
That’s it! Your Expo project should now be set up with the Situm plugin.
