Package es.situm.sdk.location

Class LocationRequest.Builder

  • Enclosing class:
    LocationRequest
    public static final class LocationRequest.Builder
extends java.lang.Object
    Builder constructor that allows to configure all the LocationRequest parameters.

    • Constructor Detail

      • Builder

        public Builder()

    • Method Detail

      • buildingIdentifier

        @NonNull
public LocationRequest.Builder buildingIdentifier​(@NonNull
                                                  java.lang.String buildingIdentifier)
        (Building Mode only) Sets the identifier of the building where you want to compute the positioning. This value configures Situm SDK to work either in Global or Building Mode.
        • Global Mode. Default mode, provides positioning anywhere, detecting automatically the building where the user is and providing her Indoor Position in it. If the user is not within a building calibrated with Situm, an Outdoor Position will be returned.
        • Building Mode. This mode is selected when a valid buildingIdentifier is specified. Situm will produce Indoor Positions only within the specified building and nowhere else. Therefore, if the user is outside this building, neither Outdoor Positions nor Indoor Positions in other buildings will be produced.

        Requirements. Global Mode requires the permission android.permission.ACCESS_FINE_LOCATION.

        Parameters:
        buildingIdentifier - the identifier of the building where you want to compute positioning. Default value is "-1" (no building identifier has been set), which means the Global Mode will be used.

      • interval

        @NonNull
public LocationRequest.Builder interval​(@IntRange(from=1000L)
                                        int interval)
        Sets the desired interval (in milliseconds) between consecutive Indoor Positions communicated via LocationListener.onLocationChanged(Location) callback.

        This value doesn't affect accuracy or battery consumption: Indoor Positions will always be computed at a rate of 1 per second. For example, if you set this value to 10000 milliseconds (10 seconds), Situm SDK will compute 1 Indoor Position per second, but only communicate through the LocationListener.onLocationChanged(Location) callback 1 out of 10 Indoor Positions.

        Side effects.

        • Values over 1000 milliseconds will automatically disable the Dead Reckoning (useDeadReckoning(boolean).
        • If you set a custom value for smallestDisplacement(float), you may not receive Indoor Position updates at the desired interval. E.g. if smallestDisplacement is 10 meters, you will only receive Indoor Position updates after the user moves 10 meters (irregardless of the interval(int) value).
        Parameters:
        interval - Interval in milliseconds between consecutive Indoor Positions communicated via LocationListener.onLocationChanged(Location) callback. Accepted values are 1000 milliseconds and above. Any value below 1000 milliseconds will be rounded up to 1000. Default value is LocationRequest.DEFAULT_INTERVAL.

      • useBle

        @NonNull
public LocationRequest.Builder useBle​(boolean useBle)
        Sets if you want to use BLE scanning for Indoor Positioning. Default value is true.

        The building in question must have BLE beacons and must have been calibrated with BLE beforehand. To scan BLE signals the Bluetooth should be enabled in the smartphone. You may do this in the smartphone settings or in the system's tray.

        Setting this method to true has a side effect: when the positioning starts Situm SDK enables the smartphone's Bluetooth. You may notice this if you take a look at the system's tray: the Bluetooth symbol will appear (if it wasn't already there).

        Take into account that, during positioning, the user may disable the Bluetooth in the smartphone settings or system tray. In this case, Situm SDK will not be able to perform BLE scanning. To prevent this from happening, you may use the method autoEnableBleDuringPositioning(Boolean).

        Parameters:
        useBle - boolean where true means that Situm SDK will scan BLE signals for positioning. Default value is true.

      • useWifi

        @NonNull
public LocationRequest.Builder useWifi​(boolean useWifi)
        Sets if you want to use WiFi scanning for Indoor Positioning. Default value is true.

        The building in question must have WiFi coverage and must have been calibrated with WiFi beforehand.

        If possible, the smartphone should not be connected to a WiFi network while positioning, since this decreases the Indoor Positioning accuracy.

        Parameters:
        useWifi - boolean where true means that WiFi scans will be used for Indoor Positioning. Default value is true.

      • useCompass

        @NonNull
public LocationRequest.Builder useCompass​(boolean useCompass)
        Sets if you want to use the compass for Indoor Positioning. Default value is true.

        In Situm SDK, gyroscope and compass are used together to measure the device's orientation. Gyroscope measures angular velocity of the smartphone: that is, the rate at which the smartphone turns. Compass measures the absolute smartphone orientation with respect to the Earth's North. Situm combines them together with a smart fusion algorithm, so that both compensate each other's flaws to provide the most accurate orientation.

        The smartphone compass may fail in a number of situations (e.g. it may provide wrong readings under heavy magnetic interferences, typical of indoor environments). Situm SDK is able to compensate most of these failures with the help of the gyroscope sensor. Therefore, we highly recommend to use both sensors together.

        If, for however reason, you feel that compass is harming the orientation estimation, you may try to disable it.

        Parameters:
        useCompass - boolean where true means that the compass will be used to improve the orientation estimate. Default value is true.

      • useGyro

        @NonNull
public LocationRequest.Builder useGyro​(boolean useGyro)
        Sets if you want to use the gyroscope for Indoor Positioning.

        In Situm SDK, gyroscope and compass are used together to measure the device's orientation. Gyroscope measures angular velocity of the smartphone: that is, the rate at which the smartphone turns. Compass measures the absolute smartphone orientation with respect to the Earth's North. Situm combines them together with a smart fusion algorithm, so that both compensate each other's flaws to provide the most accurate orientation.

        The smartphone gyroscope usually introduces a small drifting error that accumulates over time. Situm SDK is able to compensate this error with the help of the compass sensor. Therefore, we highly recommend to use both sensors together.

        If, for however reason, you feel that the gyroscope is harming the orientation estimation, you may try to disable it.

        Parameters:
        useGyro - boolean where true means that the gyroscope will be used. Default value is true.

      • useBarometer

        @NonNull
public LocationRequest.Builder useBarometer​(boolean useBarometer)
        Sets if the barometer should be used to compute Indoor Positioning (helps with floor changes).

        Some smartphones have a barometer sensor, which measures the atmospheric pressure. Situm SDK can use this information to provide a more robust and accurate estimation of the floor where the user is. Typically, using the barometer results in faster floor detection changes when the user moves from one floor to another.

        In order to use this feature, you must also configure in Situm Dashboard the height of each floor of your building(s).

        Parameters:
        useBarometer - boolean where true means that the barometer will be used. Default value is false.

      • ignoreWifiThrottling

        @NonNull
public LocationRequest.Builder ignoreWifiThrottling​(boolean ignoreWifiThrottling)
        (Android 10 only) Sets if you want to ignore (not use) the WiFi Throttling protections implemented by Situm SDK, therefore scanning WiFi as fast as possible.

        Traditionally, Android allowed apps to scan WiFi signals at a rate of 1 every 1-3 seconds. However, from Android 9 onwards, Android implements a limitation called WiFi Throttling,. which limits WiFi scanning to 1 every 30 seconds. Scanning WiFi at a higher frequency carries a penalty, so Situm SDK implements WiFi Throttling protections, avoiding going over this limit.

        Luckily, Android 10 and above allow to disable this WiFi Throttling limitation in the smartphone Developer's Settings.

        In you (or your user) have disabled it, you should set this method to true so that Situm SDK ignores the WiFi Throttling protections and scans as fast as possible.

        This parameter has different behaviour depending on the Android version:

        • Android 5, 6, 7, 8. These versions do not have the WiFi Throttling limitation, therefore this method has no effect (Situm SDK always scans WiFi at full speed).
        • Android 9. This version enforces WiFi Throttling and there is no way to disable it. Therefore, this method has no effect: Situm SDK always scans once every 30 seconds.
        • Android 10.
          • If you set this method to false, WiFi Throttling protections will not be ignored, therefore Situm SDK will scan once every 30 seconds even if WiFi Throttling has been disabled.
          • If you set this method to true, WiFi Throttling protections will be ignored, and the behaviour will depends on whether WiFi Throttling has been disabled by the user (in the smartphone Developer's Settings).
            • If WiFi Throttling has been disabled, Situm SDK will scan WiFi at full speed (once every 1-3 seconds)
            • Otherwise, Situm SDK will scan 4 times at full speed and then Android will block WiFi scans for 2 minutes approximately (as a penalty). After that, Situm SDK will start scanning once every 30 seconds in order to avoid further penalties.
        • Android 11 and above. These versions introduced a new API to get the persisted WiFi scan throttle state. This enables Situm SDK to detect the current device state and automatically update the WiFi scan rate. Therefore Situm SDK will scan at full speed if WiFi Throttling is disabled, elsewhere it will start scanning once every 30 seconds. This avoids the 2 minutes penalty produced in Android 10.

        Requirements. Before you use this method, make sure you understand WiFi Throttling, its implications, and how to disable it.

        Parameters:
        ignoreWifiThrottling - boolean, true means that WiFi Throttling protections should be ignored and therefore WiFi will be scanned as fast as possible. Default value is false.

      • preloadInfo

        @NonNull
public LocationRequest.Builder preloadInfo​(boolean preloadInfo)
        Set if you want to load floor plan images and POI category images to cache while starting the LocationManager. If you set it to true the floor plan and POI category images will be fetched when obtaining the building info. Otherwise, the images will not be fetched. It's up to the user when to download the images. The default value is false.

      • useGps

        @NonNull
public LocationRequest.Builder useGps​(boolean useGps)
        (Global Mode only) Sets if you want to use GPS for Indoor Positioning. Some buildings have outdoor areas where GPS can be used confidently: opensky areas, floors with glass ceilings, outdoors parking lots, etc. In these areas, Situm is able to fuse GPS with WiFi/BLE to provide more robust Indoor Positioning.

        Situm provides two ways to integrate the GPS information: Calibrated and Uncalibrated Indoor GPS. Both methods can use the GPS within the building canvas, providing Indoor Positions both in indoor and outdoor areas within the building.

        Requirements.Requiers the permission android.permission.ACCESS_FINE_LOCATION.

        Parameters:
        useGps - boolean where true means that GPS information will be used to improve Indoor Positioning. Default value is false.

      • motionMode

        @NonNull
public LocationRequest.Builder motionMode​(@NonNull
                                          LocationRequest.MotionMode motionMode)
        Sets the LocationRequest.MotionMode, which specifies how the user moves (e.g. by walk) and adapts the positioning algorithm accordingly. Situm SDK is able to estimate the user movement from inercial data, and use this estimation to improve the positioning accuracy. The user might move in a miriad of ways, and each of them requires a different treatment. This method allows you to indicate how your user will move so that Situm SDK can treat the movement information adequately.
        Parameters:
        motionMode - the LocationRequest.MotionMode object that specifies how the user moves. Default value is LocationRequest.MotionMode.BY_FOOT.

      • useForegroundService

        @NonNull
public LocationRequest.Builder useForegroundService​(boolean useForegroundService)
        Runs the LocationManager as a Foreground Service (prevents Android from killing the app while on background).

        By default, the LocationManager runs as a Background Service, therefore Android may kill the app at any moment when it runs in the background (e.g. to free memory space, to save battery, etc.). This method allows you to run the LocationManager as a Foreground Service, preventing Android from killing your app when it runs in the background.

        Whether or not you should use this method depends on your application:

        • Foreground-only applications: e.g. guidance apps. If your app computes the position only when the user is interacting with the screen, you can safely set this method to false.
        • Always-on applications (foreground and background): e.g. tracking and geomarketing apps. If your app is meant to keep computing locations even if it is running in the background or the screen has been turned off, you should set this method to true.

        Side effects.A notification will be shown to the user while the app is running. You can configure this notification with foregroundServiceNotificationOptions(ForegroundServiceNotificationOptions). If you want to use a completely customized notification, see foregroundServiceNotification(Notification).

        Parameters:
        useForegroundService - true to run the LocationManager as a Foreground Service, false otherwise
        See Also:
        Using Situm SDK in the background

      • useDeadReckoning

        @NonNull
public LocationRequest.Builder useDeadReckoning​(boolean useDeadReckoning)
        Enables the use of Dead Reckoning to get sub-second orientation updates (allows to provide smooth turns in wayfinding apps). By default, Situm provides 1 location update per second, which may not be enough to account for orientation changes: the user may turn around in an instant, and your app will look "delayed". To solve this, Situm implements Dead Reckoning to provide faster orientation updates. It does so by computing intermediate orientations between every two locations, by using the information provided by inertial sensors (accelerometer, gyroscope, magnetometer).
        Parameters:
        useDeadReckoning - boolean where true means that Situm SDK will use Dead Reckoning to provide sub-second orientation updates via LocationListener.onLocationChanged(Location) callback. Default value is false.

      • foregroundServiceNotification

        @NonNull
public LocationRequest.Builder foregroundServiceNotification​(@NonNull
                                                             android.app.Notification foregroundServiceNotification)
        Sets the Notification that will be shown in the system's tray when the app is running as a Foreground Service.

        If you have set useForegroundService(boolean) to true, the LocationManager will run as a Foreground Service. As a side effect, a Notification will be shown to the user. You may configure that Notification with this method.

        Parameters:
        foregroundServiceNotification - the Notification that will be shown to the user

      • foregroundServiceNotificationOptions

        public LocationRequest.Builder foregroundServiceNotificationOptions​(@Nullable
                                                                    ForegroundServiceNotificationOptions options)
        Customize the Notification that will be shown in the system's tray when the app is running as a Foreground Service.

        If you have set useForegroundService(boolean) to true, the LocationManager will run as a Foreground Service. As a side effect, a Notification will be shown to the user. You may configure that Notification with this method.

        Parameters:
        options - options available to configure the Notification.
        Returns:
        Builder

      • outdoorLocationOptions

        @NonNull
public LocationRequest.Builder outdoorLocationOptions​(@NonNull
                                                      OutdoorLocationOptions outdoorLocationOptions)
        (Global Mode only) Sets the OutdoorLocationOptions, which specify configuration related to the Global Mode (e.g. building detector to be used, outdoor positioning frequency configuration, etc.). Situm positioning has 2 different modes: Global Mode (positioning anywhere with automatic building selection) and Building Mode (positioning only in 1 building). See method LocationRequest.getBuildingIdentifier() for more information on how to configure both modes.

        Global Mode has different configuration options, which can be set by using this method. Take a look at OutdoorLocationOptions for details.

        Parameters:
        outdoorLocationOptions - the OutdoorLocationOptions object that specifies the Global Mode configuration. See OutdoorLocationOptions for details on the default values.

      • addBeaconFilter

        public LocationRequest.Builder addBeaconFilter​(@NonNull
                                               BeaconFilter beaconFilter)
        Through a BeaconFilter object, adds a beacon UUID whose signals will be taken into account when using BLE for positioning.

        If you deploy your own BLE beacons, you may add their UUIDs with this method. This way, Situm will take their signals into account when scanning BLE signals. As an alternative, you may add these UUIDs from the Situm Dashboard.

        You may invoke this method to add as many beacon filters as you want.

        Requirements. useBle(boolean) should be set to true (BLE scanning enabled).

        Parameters:
        beaconFilter - the BeaconFilter that specifies the UUID of the beacons that you want to scan. By default, Situm SDK will scan BLE signals from beacons with the standard Situm UUID ("73697475-6D73-6974-756D-736974756D15"). Situm UUID will always be scanned for.

      • useBatterySaver

        public LocationRequest.Builder useBatterySaver​(java.lang.Boolean useBatterySaver)
        Activates Battery Saver mode (stopping geolocation computations after prolonged smartphone inactivity).

        From accelerometer data, Battery Saver mode detects if the smartphone has been still for a long time period (few minutes). In this case, Situm SDK stops reading and processing sensor data, and just repeats the last computed location as the current location. This location can be an Indoor or Outdoor Position, and will be treated as a normal location (e.g. communicated via the LocationListener.onLocationChanged(Location) callback, and sent to Situm Platform, etc.)

        When the smartphone moves again, sensor reading and regular location processing is restored.

        Parameters:
        useBatterySaver - boolean where true means that Battery Saver mode will be activated. Default value is false.

      • smallestDisplacement

        public LocationRequest.Builder smallestDisplacement​(@FloatRange(from=0.0)
                                                    float smallestDisplacement)
        Sets the smallest smartphone displacement required between every two consecutive Indoor Position updates communicated via LocationListener.onLocationChanged(Location) callback.

        This value doesn't affect accuracy or battery consumption: Indoor Positions will always be computed at a rate of 1 per second. For example, if you set this value to 10 meters, Situm SDK will compute 1 Indoor Position per second even if the user does not move, but only communicate through the LocationListener.onLocationChanged(Location) callback a new Indoor Position after the user has moved at least 10 meters (from the last Indoor Position communicated).

        Dependencies.

        • Values over 0.00 meters will automatically disable the Dead Reckoning (useDeadReckoning(boolean)).
        • If you set a custom value for interval(int), you may not receive Indoor Position updates even if the user moves smallestDisplacement from the last Indoor Position. E.g. if smallestDisplacement is 1 meters, and interval 100 seconds, the user may move more than 1 meter but you will have to wait 100 seconds to receive the next Indoor Position update.
        Parameters:
        smallestDisplacement - the displacement (in meters) required between consecutive Indoor Position updates communicated via LocationListener.onLocationChanged(Location) callback. Accepted values are 0 meters and above. Any value below 0 will be rounded up to 0. Default value is LocationRequest.DEFAULT_SMALLEST_DISPLACEMENT.

      • autoEnableBleDuringPositioning

        public LocationRequest.Builder autoEnableBleDuringPositioning​(java.lang.Boolean autoEnableBleDuringPositioning)
        If true, Situm will re-enable Bluetooth even if user disables it from system's tray.

        The user may at any time turn off the Bluetooth in the smartphone. This prevents Situm SDK to scan BLE signals. This method configures Situm SDK so that it is able to re-enable Bluetooth whenever the user disables it.

        Requirements. useBle(boolean) should be set to true.

        This option is not compatible with Android >= 13 or Huawei devices. If you start positioning on those devices using this option, you will receive a status change notification LocationStatus.AUTO_ENABLE_BLE_FORBIDDEN. If so, enable Bluetooth by yourself:

        1. Android >= 13 : throw the BluetoothAdapter.ACTION_REQUEST_ENABLE intent

        2. Huawei : just call BluetoothAdapter.enable() (Huawei already implements this dialog)

        Parameters:
        autoEnableBleDuringPositioning - a boolean value where true means that Situm will re-enable Bluetooth even if user disables it from system's tray. Default value is true.

      • avoidDoze

        @NonNull
public LocationRequest.Builder avoidDoze​(java.lang.Boolean avoidDoze)
        This should not be used in normal cases. If you set this to true you must add the permissions USE_EXACT_ALARM and SCHEDULE_EXACT_ALARM in your manifest. This prevents the doze mode from activating in your device It may be neccesary to do this in some tracking scenarios but it is a very rare case so unless you really need it, it's not recommended.
        Parameters:
        avoidDoze -

      • useLocationsCache

        @NonNull
public LocationRequest.Builder useLocationsCache​(java.lang.Boolean useLocationsCache)
        Activates the Location Cache, which uses the last known Indoor Position (from a previous positioning session) as a hint to accelerate convergence when positioning starts.

        Every time you initialize Indoor Positioning, Situm SDK starts from from the ground up: starts the sensors, gathers the first readings, etc. It takes some time to converge to a first accurate geolocation (usually below 10 seconds). Also, sometimes the first geolocations can be a bit "jumpy".

        If your app stops and starts Indoor Positioning frequently, this may be a bit annoying for your user. A common example is an app that stops positioning when going to background, and starts again when going back to foreground.

        The Location Cache alleviates this issue. It stores the last Indoor Position when the positioning stops, and if it starts again before 30 seconds, it uses this last location as a hint to provide a first Indoor Position quickly. This results in an smoother user experience, typically avoiding most of the initial "location jumps".

        Parameters:
        useLocationsCache - boolean where true means that the Location Cache will be used. Default value is false.

      • locationDelimitedByRoute

        public LocationRequest.Builder locationDelimitedByRoute​(boolean locationDelimitedByRoute)