Package es.situm.sdk.location

Class OutdoorLocationOptions.Builder

java.lang.Object
es.situm.sdk.location.OutdoorLocationOptions.Builder
Enclosing class:
OutdoorLocationOptions
public static final class OutdoorLocationOptions.Builder extends Object
Builder for the OutdoorLocationOptions class.

This class lets you configure all the parameters related

  • Constructor Details

    • Builder

      public Builder()
      Constructor.

    • Builder

      public Builder(@NonNull OutdoorLocationOptions copy)
      Copy constructor.

  • Method Details

    • buildingDetector

      @NonNull public OutdoorLocationOptions.Builder buildingDetector(OutdoorLocationOptions.BuildingDetector buildingDetector)
      (Global Mode only) Sets the OutdoorLocationOptions.BuildingDetector used to detect the building where the user is.

    • scansBasedDetectorAlwaysOn

      @NonNull public OutdoorLocationOptions.Builder scansBasedDetectorAlwaysOn(boolean scansBasedDetectorAlwaysOn)
      (Not available with BuildingDetector.GPS_PROXIMITY) If true, WiFi/BLE based building detectors will continuously scan and reevaluate WiFi/BLE signal matches, in order to detect building transitions as fast as possible.

      The WiFi/BLE based detectors may be slow to detect the transition between 2 buildings, because by default they only deselect a building if a valid Indoor Location can not be computed anymore in it. This method allows a faster building transition by recomputing and reevaluating continuously the WiFi/BLE match for all the buildings.

      Parameters:
      scansBasedDetectorAlwaysOn - if true, the BuildingDetector.WIFI_AND_BLE, BuildingDetector.WIFI and BuildingDetector.BLE detectors will scan and reevaluate continuously the WiFi/BLE signals to detect building transitions in a fast manner. Default value is false.

    • centerPositionInBuildingDuringTransition

      @NonNull public OutdoorLocationOptions.Builder centerPositionInBuildingDuringTransition(boolean centerPositionInBuildingDuringTransition)
      (Only applies if BuildingDetector has not been set to GPS_PROXIMITY) Sets whether Indoor Positions should be returned immediately after the BuildingDetector detects that the smartphone is in a certain building, even if these positions are not accurate yet.

      Situm starts Indoor Positioning when it detects that the smartphone is in a certain building. After a period period of 3-10 seconds (on average), Situm SDK converges to a valid Indoor Location and only at this point your application will be aware that the user has been detected in a new building. However, there may be situations where waiting this few seconds to know the building where the user is will not be desirable.

      If set to true, this method will generate preliminary fake positions in the detected building with a very low precision. This fake locations will be generated exactly in the center position of the building, in the floor that corresponds to Level 0. After Situm converges to a valid Indoor Position, normal positioning will be restored. If set to false, Outdoor Positioning will be returned until a valid Indoor Position can be computed.

      Parameters:
      centerPositionInBuildingDuringTransition - boolean, true if a preliminary fake Indoor Position should be returned immediately after the smartphone is detected in a building. Default value is false.

    • minimumOutdoorLocationAccuracy

      @NonNull public OutdoorLocationOptions.Builder minimumOutdoorLocationAccuracy(@IntRange(from=0L) int minimumOutdoorLocationAccuracy)
      Set the minimum accuracy in meters that an Outdoor Location must have to be returned via LocationListener and uploaded to Situm Platform.
      Parameters:
      minimumOutdoorLocationAccuracy - minimum acceptable Outdoor Location accuracy. Default value is 0, meaning that all the locations will be returned/uploaded independently of their accuracy.

    • enableOutdoorPositions

      @NonNull public OutdoorLocationOptions.Builder enableOutdoorPositions(boolean enable)
      If true, Situm SDK delivers Outdoor Positions computed from GPS signals. GPS provider data remains available internally to the BuildingDetector.GPS_PROXIMITY detector.

      Generated Outdoor Positions will be returned to the app via the LocationListener.onLocationChanged callback and uploaded to Situm Platform.

      If set to false, Outdoor Positions are not delivered to the application. GPS provider data may still be used internally for building detection, including by the BuildingDetector.GPS_PROXIMITY detector.

      Parameters:
      enable - if true, outdoor locations will be computed. Default value is true.

    • useGeofencesInBuildingSelector

      @NonNull public OutdoorLocationOptions.Builder useGeofencesInBuildingSelector(boolean useGeofencesInBuildingSelector)
      (Uncalibrated Indoor GPS mode only) If true, an user will be detected to be within a building if she is within one or more of the special geofences that have been set up in that building.

      This method applies only if:

      If this method is set to true, Situm SDK will detect that the user is within a certain building not only if WiFi and/or BLE signals perceived match with those of the calibrations, but also if the GPS location falls within one of the special geofences of the building (see above).

      Take into account that "Uncalibrated Indoor GPS mode" requires LocationRequest.useGps() to be activated, among other configurations.

      Parameters:
      useGeofencesInBuildingSelector - if true, this building detection additional mechanism will be enabled. Default value is false.

    • updateInterval

      public OutdoorLocationOptions.Builder updateInterval(int updateInterval)
      Controls how often computed Outdoor Locations are delivered through the LocationListener.onLocationChanged callback.

      This is a delivery cadence only. It does not change how often the SDK acquires Android GPS/Fused provider samples, so it does not reduce GPS usage, battery consumption or building-detection frequency — use computeInterval(int) for that — and it does not change what is uploaded to Situm Platform: each computed Outdoor Location is stored once, when it is computed, however many times it is delivered.

      Possible values:

      • Values less than or equal to 0 are normalized to 0. Each newly computed Outdoor Location is delivered as soon as it is available, without repeating previous locations.
      • Values greater than 0 deliver the latest computed Outdoor Location at approximately the configured interval. If no new Outdoor Location has been computed since the previous delivery, the latest one is delivered again.

      LocationRequest.Builder.realtimePersistenceInterval(int) limits how often locations are stored locally, and computeInterval(int) bounds how many there are to store. In all modes, LocationRequest.RealtimeUpdateInterval controls upload batching.

      LocationRequest.Builder.interval(int) and LocationRequest.Builder.smallestDisplacement(float) can further filter locations before they reach the application callback.

      Parameters:
      updateInterval - interval in milliseconds. The resolved default value is 0.

    • computeInterval

      public OutdoorLocationOptions.Builder computeInterval(int computeInterval)
      Controls how often the SDK starts Android GPS/Fused provider acquisition cycles to compute Outdoor Locations. Increasing this interval reduces GPS usage and battery consumption. It can also make GPS-based and geofence-based building detection react more slowly.

      Possible values:

      • Values less than or equal to 0 are normalized to 0. The SDK keeps Android location providers active and processes each accepted sample as it becomes available.
      • Values greater than 0 pause the providers after a fresh accepted sample, or after a bounded 10-second acquisition timeout when no acceptable sample arrives. The SDK starts the next acquisition cycle after the configured interval. Typical values are 5000, 10000, and 30000 milliseconds.

      Restarting Android location providers is not instantaneous. The time until an accepted location becomes available depends on the device, provider, and system power policies. Intervals shorter than the provider restart time may not increase the effective update rate and can delay successive locations. Intervals of 15 seconds or longer generally provide more predictable behavior.

      This value does not determine application callback cadence — use updateInterval(int) for that — nor is it the realtime storage throttle, which is LocationRequest.Builder.realtimePersistenceInterval(int). It does however bound how many Outdoor Locations there are to store: each computed location is stored once, so this interval sets the supply and the persistence interval the ceiling.

      This method also affects BuildingDetector.GPS_PROXIMITY, which uses the GPS location to determine the closest building.

      Parameters:
      computeInterval - idle interval in milliseconds between acquisition cycles. Default value is 0.

    • build

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