Package es.situm.sdk.location

Class LocationRequest.Builder

java.lang.Object
es.situm.sdk.location.LocationRequest.Builder
Enclosing class:
LocationRequest
public static final class LocationRequest.Builder extends Object
Builder constructor that allows you to configure all LocationRequest parameters.

  • Constructor Details

    • Builder

      public Builder()

    • Builder

      public Builder(@NonNull LocationRequest copy)

  • Method Details

    • buildingIdentifier

      @NonNull public LocationRequest.Builder buildingIdentifier(@NonNull 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 by automatically detecting the building where the user is and providing an Indoor Position there. 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. By default, no building identifier is set, which enables Global Mode.

    • interval

      @NonNull public LocationRequest.Builder interval(@IntRange(from=1000L) int interval)
      Sets how often Indoor Positions are delivered through LocationListener.onLocationChanged(Location).

      The SDK computes Indoor Positions at a rate of one per second. This value does not change that computation rate, positioning accuracy, or battery consumption. Instead, it filters how often computed positions are delivered to the application. For example, with an interval of 10000 milliseconds, the SDK continues computing one Indoor Position per second but delivers the latest position approximately every 10 seconds.

      This value does not control uploads to Situm Platform. Use realtimePersistenceInterval(int) to configure local storage frequency and realtimeUpdateInterval(RealtimeUpdateInterval) to configure upload batching.

      Related properties.

      Location updates are delivered on a best-effort basis; the configured interval is not guaranteed to be exact.

      Parameters:
      interval - interval in milliseconds. Values below LocationRequest.DEFAULT_INTERVAL are normalized to LocationRequest.DEFAULT_INTERVAL. The default value is LocationRequest.DEFAULT_INTERVAL.

    • indoorProvider

      @NonNull public LocationRequest.Builder indoorProvider(@NonNull LocationRequest.IndoorProvider indoorProvider)
      Deprecated.
      Do not use. The indoor provider is LocationRequest.IndoorProvider.INPHONE by default and cannot be changed.

    • useBle

      @NonNull public LocationRequest.Builder useBle(boolean useBle)
      Sets whether 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. Bluetooth must be enabled on the smartphone to scan BLE signals. You may do this in the smartphone settings or system tray.

      Setting this method to true has a side effect: when positioning starts, Situm SDK enables the smartphone's Bluetooth. You may notice this in the system tray: the Bluetooth symbol appears if it was not already enabled.

      During positioning, the user may disable Bluetooth in the smartphone settings or system tray. In this case, Situm SDK cannot 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 whether 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 whether to use the compass for Indoor Positioning. Default value is true.

      In Situm SDK, the gyroscope and compass are used together to measure the device's orientation. The gyroscope measures the smartphone's angular velocity: 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 with a sensor fusion algorithm so that they compensate for each other's shortcomings and 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 whatever reason, you feel that the compass harms orientation estimation, you may try disabling 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 whether to use the gyroscope for Indoor Positioning.

      In Situm SDK, the gyroscope and compass are used together to measure the device's orientation. The gyroscope measures the smartphone's angular velocity: 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 with a sensor fusion algorithm so that they compensate for each other's shortcomings and 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 whatever reason, you feel that the gyroscope harms orientation estimation, you may try disabling 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 whether 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 whether to ignore the WiFi Throttling protections implemented by Situm SDK, therefore scanning WiFi as fast as possible.

      Traditionally, Android allowed apps to scan WiFi signals once every 1-3 seconds. However, starting with Android 9, Android imposes a limitation called WiFi Throttling, which limits WiFi scanning to once 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 later allow you to disable this WiFi Throttling limitation in the smartphone Developer's Settings.

      If you or your user has disabled it, set this method to true so that Situm SDK ignores the WiFi Throttling protections and scans as fast as possible.

      This parameter has different behavior 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 behavior 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 four times at full speed and then Android will block WiFi scans for approximately 2 minutes 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 scans at full speed if WiFi Throttling is disabled; otherwise, it scans once every 30 seconds. This avoids the two-minute 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)
      Sets whether floor plan and POI category images are loaded into the cache while starting the LocationManager. If set to true, the images are fetched when the SDK obtains building information. Otherwise, the images are not fetched; you choose when to download them. The default value is false.

    • useGps

      @NonNull public LocationRequest.Builder useGps(boolean useGps)
      (Global Mode only) Sets whether to use GPS for Indoor Positioning. Some buildings have outdoor areas where GPS can be used confidently: open-sky areas, floors with glass ceilings, outdoor 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 GPS within the building canvas, providing Indoor Positions in both indoor and outdoor areas within the building.

      Requirements. Requires 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. on foot) and adapts the positioning algorithm accordingly. Situm SDK can estimate user movement from inertial data and use this estimation to improve positioning accuracy. The user might move in a myriad of ways, and each requires 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 in the background).

      By default, the LocationManager runs as a Background Service, so Android may kill the app at any moment when it runs in the background (e.g. to free memory space or save battery). 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:

    • 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 each pair of consecutive locations, using information provided by inertial sensors (accelerometer, gyroscope, and 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 two modes: Global Mode (positioning anywhere with automatic building selection) and Building Mode (positioning only in one building). See buildingIdentifier(String) for information about configuring 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.

    • routeAdjustment

      @NonNull public LocationRequest.Builder routeAdjustment(@Nullable RouteAdjustment routeAdjustment)

    • addBeaconFilter

      public LocationRequest.Builder addBeaconFilter(@NonNull BeaconFilter beaconFilter)
      Adds a beacon UUID through a BeaconFilter object. Its 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 scans BLE signals from beacons with the standard Situm UUID ("73697475-6D73-6974-756D-736974756D15"). The standard Situm UUID is always scanned for.

    • addBeaconFilters

      public LocationRequest.Builder addBeaconFilters(@NonNull List<BeaconFilter> beaconFilters)
      Adds beacon UUIDs through a list of BeaconFilter objects. Their signals will be taken into account when using BLE for positioning. See addBeaconFilter(BeaconFilter) for details.
      Parameters:
      beaconFilters - the list of BeaconFilter objects that specify the UUIDs of the beacons that you want to scan.

    • useBatterySaver

      public LocationRequest.Builder useBatterySaver(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 stationary for a long period of time (a 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.)

      The last computed location is repeated at the cadence set by interval(int), and each repeat is stored for upload as a position in its own right, subject to realtimePersistenceInterval(int). While the smartphone is stationary, realtimeUpdateInterval(RealtimeUpdateInterval) is also forced to at least LocationRequest.RealtimeUpdateInterval.SLOW, and the configured value is restored when the smartphone moves again.

      When the smartphone moves again, sensor reading and regular location processing are 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 each pair of 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 computes one Indoor Position per second even if the user does not move, but delivers a new Indoor Position through the LocationListener.onLocationChanged(Location) callback only after the user has moved at least 10 meters from the last communicated Indoor Position.

      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 by smallestDisplacement from the last Indoor Position. For example, if smallestDisplacement is 1 meter and the interval is 100 seconds, the user may move more than 1 meter but must 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.

    • realtimeUpdateInterval

      public LocationRequest.Builder realtimeUpdateInterval(LocationRequest.RealtimeUpdateInterval realtimeUpdateInterval)
      Sets how often buffered location updates are uploaded to Situm Platform.

      This setting does not change location computation or application callback cadence.

      Use realtimePersistenceInterval(int) to control how often locations are stored locally before they are batched for upload.

      Uploading multiple locations in a single request is generally more efficient than uploading each location individually, reducing network overhead, battery usage, and data consumption. The trade-off is increased latency: with longer intervals, the Realtime Panel will show the last location that was uploaded, not the user's true real-time location.

      See LocationRequest.RealtimeUpdateInterval for the available upload intervals and their buffering behavior.

      Parameters:
      realtimeUpdateInterval - the upload interval, or LocationRequest.RealtimeUpdateInterval.NEVER to disable realtime storage and uploads. The resolved default is LocationRequest.DEFAULT_REALTIME_UPDATE_INTERVAL.

    • realtimePersistenceInterval

      @NonNull public LocationRequest.Builder realtimePersistenceInterval(@IntRange(from=1000L) int realtimePersistenceInterval)
      Sets how often locations are stored locally for upload to Situm Platform.

      This setting controls how often computed locations are stored locally for later upload. It applies to Indoor Locations, Global Mode Indoor Locations, and Outdoor Locations. At most one location is stored in each interval window, so locations on opposite sides of a window boundary may be stored closer together.

      It does not affect location computation, the cadence of callbacks delivered to the application (see interval(int)), or when stored locations are uploaded (see realtimeUpdateInterval(RealtimeUpdateInterval)).

      Values below LocationRequest.DEFAULT_REALTIME_PERSISTENCE_INTERVAL are clamped to LocationRequest.DEFAULT_REALTIME_PERSISTENCE_INTERVAL. If not explicitly set, the value may be provided by Remote Configuration; otherwise the default value is LocationRequest.DEFAULT_REALTIME_PERSISTENCE_INTERVAL.

      Parameters:
      realtimePersistenceInterval - interval window size in milliseconds

    • autoEnableBleDuringPositioning

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

      The user may at any time turn off the Bluetooth in the smartphone. This prevents Situm SDK from scanning BLE signals. This method configures Situm SDK 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 and later or Huawei devices. If you start positioning on those devices with this option, you will receive a status change notification LocationStatus.AUTO_ENABLE_BLE_FORBIDDEN. If so, enable Bluetooth yourself:

      1. Android 13 and later: send the BluetoothAdapter.ACTION_REQUEST_ENABLE intent.
      2. Huawei: call BluetoothAdapter.enable() (Huawei already implements this dialog).
      Parameters:
      autoEnableBleDuringPositioning - a Boolean value where true means that Situm will re-enable Bluetooth even if the user disables it from the system tray. Default value is true.

    • avoidDoze

      @NonNull public LocationRequest.Builder avoidDoze(Boolean avoidDoze)
      This should not be used in normal use cases. If you set this to true you must add the permissions USE_EXACT_ALARM and SCHEDULE_EXACT_ALARM in your manifest. This prevents Doze mode from activating on your device. It may be necessary 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 - true to prevent Doze mode from activating; false otherwise.

    • useLocationsCache

      @NonNull public LocationRequest.Builder useLocationsCache(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 scratch: it 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 the background and starts again when returning to the 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 a smoother user experience, typically avoiding most initial "location jumps".

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

    • diagnosticsOptions

      @NonNull public LocationRequest.Builder diagnosticsOptions(@NonNull DiagnosticsOptions options)
      Sets the desired DiagnosticsOptions, which specifies options related to remote diagnostic and telemetry data.
      Parameters:
      options - DiagnosticsOptions

    • assetTrackingOptions

      @NonNull public LocationRequest.Builder assetTrackingOptions(@NonNull AssetTrackingOptions options)
      Sets the desired AssetTrackingOptions, which specifies options related to asset tracking using BLE beacons. When asset tracking is enabled, the SDK sends beacon readings that are processed to determine their positions.
      Parameters:
      options - AssetTrackingOptions

    • build

      @NonNull public LocationRequest build()
      Builds the LocationRequest.
      Returns:
      a LocationRequest instance

    • routeId

      public LocationRequest.Builder routeId(int routeId)

    • locationDelimitedByRoute

      public LocationRequest.Builder locationDelimitedByRoute(boolean locationDelimitedByRoute)

    • addRoutePoints

      public LocationRequest.Builder addRoutePoints(@NonNull List<Point> routePoints)