FAQs

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:

• iOS (native)
• Cordova (iOS)

What sensors does Situm SDK access? #

Android #

These are the most common things to take into account that Situm SDK needs to have access to sensors. We recommend the app developer to implement mechanisms to ensure that the user does not disable any option that is critical for its use case (e.g. detecting the state of each sensor and asking the user to change it if required).

Sensor	Take into account…
WiFi	WiFI ON/OFF. In the system’s tray, users can turn ON/OFF WiFi. Situm can scan WiFi either way, provided that the WiFi scan ability (see next paragraph) was not turned OFF by the user. We actually recommend that WiFi is turned OFF and the user is disconnected to the WiFi. WiFi Scanning ON/OFF. From Android >4, users can turn ON/OFF the capability to scan WiFi for positioning purposes. Usually, this is under Settings / Security & Location / Location / Scanning. If users turn OFF WiFi Scanning, Situm SDK will not be able to scan WiFi. WiFi Throttling. From Android 9 onwards, Android implements a limitation called WiFi Throttling, that limits number of WiFi scans to 1 every 30 seconds. More information here.
BLE	BLE ON/OFF. In the system’s tray, users can turn ON/OFF BLE. In case BLE is turned OFF, Situm Situm will not be able to scan BLE beacons. To avoid this, Situm SDK provides an option to automatically re-enable BLE. BLE scanning ON/OFF. From Android >4, users can turn ON/OFF the capability to scan BLE for positioning purposes. Usually, this is under Settings / Security & Location / Location / Scanning. If users turn OFF WiFi Scanning, Situm SDK will not be able to scan BLE.
Location	From the system’s tray, user may turn ON/OFF the smartphone Location Services. Before Android 6.0, turning this OFF only restricted access to the GPS and WiFi scanning. From Android 6.0, it restricts access to any sensor that could be used to provide a Location, including GPS, WiFi, and BLE. Therefore, turning Location OFF will cause Situm SDK to not work at all.

iOS #

Contrary to Android, iOS does not allow to scan WiFi signals. However, BLE and Location are used in iOS, just like in Android. As in Android, the developer should implement the appropriate mechanisms to ensure that the user does not disable any option that is critical for its use case (e.g. detecting the state of each sensor and asking the user to change it if required).

Sensor	Take into account…
BLE	BLE ON/OFF (system’s tray). In the system’s tray, users can turn ON/OFF BLE. Even if BLE is turned OFF here, Situm still be able to scan BLE beacons. BLE ON/OFF (Settings). In the device Settings, in the “Bluetooth” section, you may turn OFF the Bluetooth. If you do, Situm will not be able to scan BLE beacons.
Location	From the device Settings, in the “Privacy & Security” section, and “Location Services” subsection, you might: 1 – Disable Location Services. 2 – Deny Location Permissions to your application (by selecting your application and choosing “Never” under “Allow Location Access” subsection) 3 – Disable Precise Location (by selecting your application and toggling this setting off) In all these cases, Situm will not be able to provide the user location, neither indoors or outdoors.

In Android, which install-time permissions does Situm SDK declare? #

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. 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? #

Both in Android and iOS, you will need to ask a number of permissions to enable some of the SDK functionality, such as scanning BLE, accessing GPS data, and more. Please take a look at these guides (Android, iOS) to know which permissions to request.

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. If you are using the Altimeter you would need to request also NSMotionUsageDescription permission. 

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.

When should I request NSMotionUsage permission in iOS and why it is needed? #

From OS 17.4 you should request NSMotionUsage permission to use the barometer. Situm SDK uses the barometer to improve the quality of floor change detection. NSMotionUsage permission can be a bit intrusive, as when it is presented to the user it requests permission to access their Motion and Fitness Activity (see image below).

NSMotionUsage permission will be requested only when SITLocationRequest.useBarometer is set to true (default value).

Therefore:

• Use the barometer if the quality of floor transitions is important for your app. If you use the barometer we recommend adding a descriptive reason to your app Info.plist Motion Usage Description like “We use your phone sensors (giroscope, accelerometer and altimeter) to improve location quality”.
• Do not use the barometer if you find this permission too intrusive and you can afford a lower floor transitions quality. You can deactivate the use of the barometer by setting SITLocationRequest.useBarometer to false.

Is Situm SDK (Android) compatible with multi-process? #

No, the Situm SDK is not compatible with Android multi-process.

Android multiprocess allows an application to run different components (like services or activities) in separate processes. Each process has its own instance of the Android runtime, including its own garbage collector, heap, and thread pool. Due to the nature of the Situm SDK and its reliance on consistent access to phone sensors, running in a multi-process setup can cause conflicts and crashes. The SDK requires all components to run within the same process to function correctly.

For optimal performance and stability, ensure that all components using the Situm SDK are configured to run in a single process. Avoid using multi-process configurations in your application when working with the Situm SDK.

Please remember! Multi-process is different from multi-thread. In multi-thread, different components run on separate threads within the same process. Multi-thread is indeed supported and recommended, especially for running heavy operations without blocking the main thread.

References:

• Android Developer Guide: Processes and Threads
• Android Developer Guide: Application Manifest – Process