Building mode vs global mode, which one should I use ? #
Building Mode was designed for use cases that only contain a single building for the account. This way Situm knows that there is only one building where we need to calculate the user location. To use this mode remember to obtain the identifier of your building, and then specify it inside the location request used when calling requestLocationUpdates():
// 1. Import our plugin import SitumPlugin, {requestPermission} from '@situm/react-native'; // Call this method whenever you want to start positioning const startPositioning = async () => { // 2. Remember to initialize our SDK, authenticate and set all the callbacks // mentioned in this section https://situm.com/docs/integrate-our-sdk/#requesting-permissions // 3. Request the permissions to the user, // then request location updates to start positioning. await requestPermission() .then(() => { // Building Mode (specifying a certain building identifier) // Find out how to obtain the identifier of your building at https://situm.com/docs/sdk-cartography/#building-details SitumPlugin.requestLocationUpdates({ buildingIdentifier: 'YOUR_BUILDING_IDENTIFIER'}); // Global Mode (hardcoding -1, so we offer positioning in multiple buildings) SitumPlugin.requestLocationUpdates({ buildingIdentifier: '-1'}); }) .catch(err => { console.error(`ERR> requestPermission()> ${JSON.stringify(err)}`); }); }
On the other hand, you may have multiple buildings in your account where the user may appear. Therefore, Global Mode will be the right choice for you. This mode calculates which is the nearest building to the user and tries to locate him near it.
For further information take a look at this documentation where we explain this modes in detail.
How should I configure my mobile application to support offline functionality? #
The MapView allows users to access the application offline, even if they do not have internet connectivity. In order to work, the SDK downloads and caches some essential information when it has internet access (i.e. information about the building, its POIs, etc).
Currently, offline functionality is supported in:
- Flutter: both Android & iOS
- React Native: both Android & iOS
- Cordova: Android only.
- Android (native)
On Android devices, offline supports works out of the box so there is no need for any additional configuration, other than following the steps recommended in the Quickstart Guides.
However, to enable offline support on iOS devices, an extra step is required. You must modify your application’s Info.plist
, typically located under the ios/YOUR_APP_NAME/
directory. Within this file you need to add the key WKAppBoundDomains
, where you should specify the underlying MapViewer domain, which will most likely be map-viewer.situm.com
(unless you’ve deployed it on your own cloud). After making the modification, your Info.plist
should resemble the following:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> ... <key>WKAppBoundDomains</key> <array> <string>map-viewer.situm.com</string> </array> </dict> </plist>
The following frameworks/os will be supported soon:
Which install-time permissions does Situm SDK declare in Android ? #
These permissions allow access to data and actions that extend beyond your app’s sandbox, but the data and actions present very little risk to the user’s privacy, and the operation of other apps. Situm SDK declares a series of these permissions in its AndroidManifest.xml, that will be granted by the user when he installs the app. So the following permissions are used by the Situm SDK (Android), but do not need to be requested by your app:
Permission | Description |
---|---|
ACCESS_NETWORK_STATE | To know if we have network or we don’t |
ACCESS_WIFI_STATE | To know if WiFi is ON/OFF |
CHANGE_WIFI_STATE | To turn WiFi ON/OFF |
INTERNET | To have access to communications |
BLUETOOTH_ADMIN | To turn BLE ON/OFF |
BLUETOOTH | To scan BLE |
WAKE_LOCK | To keep CPU active while in Situm is running in the background as a Foreground Service. |
FOREGROUND_SERVICE | To be able to launch Situm SDK as a Foreground Service. |
HIGH_SAMPLING_RATE_SENSORS | Allows to read some sensor data (e.g. gyroscope) at a high rate, needed for accurate positioning. |
Which runtime permissions should I request ? #
Situm uses the location and bluetooth sensors of Android and iOS devices. Also known as dangerous, they give the app additional access to restricted data, and/or allow the app to perform restricted actions that more substantially affect the system. Situm may require the following runtime permissions for Android and iOS.
Android
Permission | Description |
---|---|
ACCESS_COARSE_LOCATION | Required for positioning in Building Mode. If you want to perform positioning in Global Mode, you will need the ACCESS_FINE_LOCATION permission. This permission is already declared in our SDK and should be requested alongside the ACCESS_FINE_LOCATION. |
ACCESS_FINE_LOCATION | Required for positioning in Global Mode (it also allows positioning in Building Mode). You must declare this permission in your AndroidManifest.xml and then request it at runtime. |
BLUETOOTH_SCAN | To scan BLE in Android 12 and above. This permission is already declared in our SDK and you should request it at runtime when using bluetooth to scan beacons. |
BLUETOOTH_CONNECT | To turn BLE ON/OFF in Android 12 and above. This permission is already declared in our SDK and you should request it at runtime when using bluetooth to scan beacons. |
POST_NOTIFICATIONS (OPTIONAL) | Allows to show our push notifications inside the notification drawer in Android 13 and above. If not granted, user won’t receive alerts associated with foreground services in their notification drawer. Nevertheless, notices pertaining to these foreground services will still be visible in the Task Manager, irrespective of the user’s decision on the notification permission. See Android docs for more info. |
iOS
Permission | Description |
---|---|
NSLocationAlwaysAndWhenInUseUsageDescription. In XCode: “Privacy – Location Always and When In Use Usage Description”. | Required to locate the user with every geolocation mode Situm provides. |
NSLocationWhenInUseUsageDescription. In XCode: “Privacy – Location When In Use Usage | Required to locate the user with every geolocation mode Situm provides. |
I do not use beacons in my building, which permissions and sensors I need to request ? #
In case you don’t need to use beacons in your building, you won’t need to request the permission in Android and you won’t also need the user to enable the bluetooth sensor. Anyway, you will need to declare and request the location permissions:
- For Android: declare the ACCESS_FINE_LOCATION permission in your AndroidManifest.xml and request it at runtime.
- For iOS: request both NSLocationAlwaysAndWhenInUseUsageDescription & NSLocationWhenInUseUsageDescription.
Remember to ask the user to enable the location sensor after requesting the permissions. You will also need to configure your geofences and your remote configuration to be able to locate the user with the uncalibrated indoor gps mode.