SITLocationRequest

Objective-C

@interface SITLocationRequest : NSObject <NSCopying, SITMapperProtocol>

Swift

class SITLocationRequest : NSObject, NSCopying, SITMapperProtocol

A data object that contains parameters for the location service (SITLocationManager)

Initializers

  • Constructor.

    Declaration

    Objective-C

    - (instancetype _Nonnull)initWithBuildingId:(NSString *_Nonnull)buildingId;

    Swift

    init(buildingId: String)

    Parameters

    buildingId

    Unique identifier of the building in which you want to locate a user.

    Return Value

    Initialized SITLocationRequest object.

Properties

  • Determines how often the SDK attempts to upload eligible location updates to Situm Platform.

    @note Unit: milliseconds.

    @note Default value: kSITUpdateIntervalRealtime.

    Overview

    This property controls how often the SDK uploads eligible location updates to Situm Platform. It does not affect how often locations are computed or delivered to the application.

    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.

    Accepted Values

    • kSITUpdateNever: Disable uploads to Situm Platform.
    • kSITUpdateIntervalRealtime: Upload each eligible location as soon as it becomes available.
    • Values between kSITUpdateIntervalRealtime and kSITUpdateNever: Buffer eligible locations and upload them together when the configured interval elapses.

    Reliability

    If an upload cannot be completed, for example because of a network failure or an unexpected application termination, the SDK retries the upload when possible.

    This property is independent of SITLocationRequest.interval, SITLocationRequest.outdoorOptions.computeInterval, and SITLocationRequest.outdoorOptions.updateInterval.

    SITLocationRequest.interval determines which indoor location updates become eligible for upload.

    SITLocationRequest.outdoorOptions.computeInterval determines how often outdoor locations are computed.

    SITLocationRequest.outdoorOptions.updateInterval determines which outdoor location updates become eligible for upload.

    Whereas this property determines when those eligible location updates are uploaded. If no new eligible location updates are available when an upload is scheduled, no data is uploaded.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SITRealtimeUpdateInterval realtimeUpdateInterval;

    Swift

    var realtimeUpdateInterval: SITRealtimeUpdateInterval { get }

  • The time interval indicating how often the position should be uploaded to realtime.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SITMotionMode motionMode;

    Swift

    var motionMode: SITMotionMode { get }

  • Set if you want to use dead reckoning to get fast position updates using only the inertial sensors, between the server position updates. This parameter is incompatible with interval and smallestDisplacement. If interval or smallestDisplacement are set, dead reckoning will be deactivated for this request.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useDeadReckoning;

    Swift

    var useDeadReckoning: Bool { get set }

  • Set if you want to use Gps for positioning indoor.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useGps;

    Swift

    var useGps: Bool { get set }

  • Unique identifier of the building in which you want to locate a user. From SDK version 2.43.0, if this value is not set (it is nil or an empty string), the positioning will start in indoor-outdoor mode, regardless of the value of the deprecated property useGlobalLocation.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSString *_Nullable buildingID;

    Swift

    var buildingID: String? { get set }

  • The thread where the location updates will be provided. If not provided, the main thread will be used.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSOperationQueue *_Nullable operationQueue;

    Swift

    var operationQueue: OperationQueue? { get set }

  • Additional options to modify the internal operation of the Location provider (private usage only).

    Declaration

    Objective-C

    @property (nonatomic, strong) NSDictionary *_Nullable options;

    Swift

    var options: [AnyHashable : Any]? { get set }

  • Custom UUIDs. The system will also scan beacons with the specified UUIDs. Prior to SDK version 2.45.0 these scans were used only to position the user inside a building. From SDK version 2.45.0 on, if Global Location is active, these scans are also used to detect in which building the user is located.

    Declaration

    Objective-C

    @property (nonatomic, strong) NSArray<SITBeaconFilter *> *_Nullable beaconFilters;

    Swift

    var beaconFilters: [SITBeaconFilter]? { get set }

  • Determines how often indoor location updates are delivered to the application and become eligible for upload to Situm Platform.

    @note Unit: milliseconds.

    @note Default value: 0.

    Overview

    The SDK computes indoor locations at a fixed rate of once per second. This property does not change that computation rate. Instead, it determines how often those computed locations are delivered to the application through SITLocationDelegate -locationManager:didUpdateLocation:.

    Only the locations delivered according to this interval become eligible for upload to Situm Platform. As a result, increasing this interval reduces the amount of location data stored in Situm Platform without affecting positioning accuracy or battery consumption.

    Accepted Values

    • 0: Deliver each newly computed indoor location immediately.
    • 1000 or greater: Deliver the latest computed indoor location at approximately the specified interval.
    • Values between 1 and 999 milliseconds are treated as 1000 milliseconds.

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

    This property is incompatible with dead reckoning. Setting a value greater than 1000 milliseconds automatically disables SITLocationRequest.useDeadReckoning.

    If SITLocationRequest.smallestDisplacement is configured, both conditions must be satisfied before a location update is delivered: the configured time interval must have elapsed and the user must have moved at least the configured displacement.

    This property is independent of SITLocationRequest.realtimeUpdateInterval. This property determines which indoor locations become eligible for upload, whereas realtimeUpdateInterval determines when those eligible locations are actually uploaded.

    This property provides the indoor equivalent of SITLocationRequest.outdoorLocationOptions.updateInterval, which determines how often computed outdoor locations are delivered to the application and become eligible for upload to Situm Platform.

    Example

    If this property is set to 10000 milliseconds (10 seconds), the SDK continues computing one indoor location every second. However, the application receives only the latest computed location every 10 seconds, and only those delivered locations become eligible for upload to Situm Platform.

    Declaration

    Objective-C

    @property (nonatomic) int interval;

    Swift

    var interval: Int32 { get set }

  • Minimum displacement between location updates

    Declaration

    Objective-C

    @property (nonatomic) float smallestDisplacement;

    Swift

    var smallestDisplacement: Float { get set }

  • Set if you want to use barometer data for positioning.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useBarometer;

    Swift

    var useBarometer: Bool { get set }

  • Set if you want to use compass sensor for positioning (default to true).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL useCompass;

    Swift

    var useCompass: Bool { get }

  • Set if you want to use bluetooth sensor for positioning (default to true).

    Declaration

    Objective-C

    @property (nonatomic, readonly) BOOL useBle;

    Swift

    var useBle: Bool { get }

  • Object containing several options to configure the indoor/outdoor positioning. This parameter will only be read if useGlobalLocation is set to YES

    Declaration

    Objective-C

    @property (nonatomic, strong) SITOutdoorLocationOptions *_Nullable outdoorLocationOptions;

    Swift

    var outdoorLocationOptions: SITOutdoorLocationOptions? { get set }

  • Object that specifies options related to remote diagnostic and telemetry data.

    Declaration

    Objective-C

    @property (nonatomic, strong) SITDiagnosticsOptions *_Nullable diagnosticsOptions;

    Swift

    var diagnosticsOptions: SITDiagnosticsOptions? { get set }

  • Boolean value indicating if the floorplan images and the POI categories images for the building should be download to cache while starting positioning. Set to YES to preload the images. Set to NO to skip that process. Default value is NO.

    Declaration

    Objective-C

    @property (nonatomic) BOOL preloadInfo;

    Swift

    var preloadInfo: Bool { get set }

  • Activate to use the location cache. It will smooth dispersion of initial positions on starts that occur shortly after stopping.

    Declaration

    Objective-C

    @property (nonatomic) BOOL useLocationsCache;

    Swift

    var useLocationsCache: Bool { get set }

  • Configure to use route adjustment on the location engine.

    Declaration

    Objective-C

    @property (nonatomic, readonly) SITRouteAdjustment *_Nullable routeAdjustment;

    Swift

    var routeAdjustment: SITRouteAdjustment? { get }

Methods

  • Check if the request is valid.

    Declaration

    Objective-C

    - (BOOL)isValid;

    Swift

    func isValid() -> Bool

    Return Value

    BOOL value that indicates if the request is valid (YES) or not (NO).

  • Check if indoor-outdoor mode is being used. From SDK version 2.43.0, indoor-outdoor mode is activated if location request, either the deprectated property useGlobalLocation is set to YES or buildingID is not set (it is nil or an empty string).

    Declaration

    Objective-C

    - (BOOL)isUsingGlobalLocation;

    Swift

    func isUsingGlobalLocation() -> Bool

    Return Value

    BOOL value that indicates if indoor-outdoor mode is being used (YES) or not (NO).

Private

  • Method that combines two location request updating the values of the receiving object with the ones on the request.

    Note

    You should not use this method directly. Insted you can use the method SITCommunicationManager.fetchRemoteConfig(...) or [SITLocationInterface locationManager:didInitiatedWithRequest:] methods.

    Declaration

    Objective-C

    - (SITLocationRequest *_Nonnull)merge:(SITLocationRequest *_Nonnull)request;

    Swift

    func merge(_ request: SITLocationRequest) -> SITLocationRequest

    Return Value

    new ‘SITLocationRequest` with merged values.

Deprecated

  • Deprecated

    Location provider is no longer selectable. Provider will always be kSITInPhoneProvider

    One of SITLocationProvider.

    Declaration

    Objective-C

    @property (nonatomic) SITLocationProvider provider;

    Swift

    var provider: SITLocationProvider { get set }

  • Deprecated

    Use realtimeUpdateInterval instead

    The time interval indicating how often the position should be uploaded to realtime. Deprecated, use realtimeUpdateInterval instead.

    Declaration

    Objective-C

    @property (nonatomic) NSInteger updateInterval;

    Swift

    var updateInterval: Int { get set }

  • Set to true if you want to use indoor/outdoor positioning. Deprecated on SDK version 2.43.0. From that version on if buildingID is not set (it is nil or an empty string), indoor/outdoor positioning will be used, regardless of the value of this variable.

    @deprecated v2.43.0

    Declaration

    Objective-C

    @property (nonatomic) BOOL useGlobalLocation;

    Swift

    var useGlobalLocation: Bool { get set }

  • Deprecated

    Use base constructor instead

    Constructor.

    Declaration

    Objective-C

    - (instancetype _Nonnull)initWithPriority:(SITLocationPriority)priority
                                 provider:(SITLocationProvider)provider
                           updateInterval:(NSInteger)updateInterval
                               buildingID:(NSString *_Nonnull)buildingID
                           operationQueue:
                               (NSOperationQueue *_Nonnull)operationQueue
                                  options:(NSDictionary *_Nullable)options;

    Swift

    init(priority: SITLocationPriority, provider: SITLocationProvider, updateInterval: Int, buildingID: String, operationQueue: OperationQueue, options: [AnyHashable : Any]? = nil)

    Parameters

    priority

    one of SITLocationPriority
    provider

    one of SITLocationProvider
    updateInterval

    The time interval at which location will be uploaded to realtime
    buildingID

    unique identifier of the building in which you want to locate a user. (This property is mandatory).
    operationQueue

    the thread where the location updates will be provided. If not provided, the main thread will be used.
    options

    additional options to modify the internal operation of the Location provider (private usage only).

    Return Value

    initialized object.

  • Deprecated

    Use base constructor instead

    Constructor.

    Declaration

    Objective-C

    - (instancetype _Nonnull)initWithPriority:(SITLocationPriority)priority
                                 provider:(SITLocationProvider)provider
                           updateInterval:(NSInteger)updateInterval
                               buildingID:(NSString *_Nonnull)buildingID
                           operationQueue:
                               (NSOperationQueue *_Nonnull)operationQueue
                         useDeadReckoning:(BOOL)useDeadReckoning
                                  options:(NSDictionary *_Nullable)options;

    Swift

    init(priority: SITLocationPriority, provider: SITLocationProvider, updateInterval: Int, buildingID: String, operationQueue: OperationQueue, useDeadReckoning: Bool, options: [AnyHashable : Any]? = nil)

    Parameters

    priority

    one of SITLocationPriority
    provider

    one of SITLocationProvider
    updateInterval

    The time interval at which location will be uploaded to realtime
    buildingID

    unique identifier of the building in which you want to locate a user. (This property is mandatory).
    operationQueue

    the thread where the location updates will be provided. If not provided, the main thread will be used.
    useDeadReckoning

    determines if dead reckoning should be used
    options

    additional options to modify the internal operation of the Location provider (private usage only).

    Return Value

    initialized object.

  • Compares the receiving locationRequest to another locationRequest

    Declaration

    Objective-C

    - (BOOL)isEqualToLocationRequest:(SITLocationRequest *_Nonnull)aLocationRequest;

    Swift

    func isEqual(to aLocationRequest: SITLocationRequest) -> Bool

    Parameters

    aLocationRequest

    SITLocationRequest The location Request to compare with the receiver

    Return Value

    YES if aLocationRequest is equivalent to the receiving locationRequest, otherwise NO.