Inherits from NSObject
Conforms to UALocationProviderDelegate
Declared in UALocationService.h

Overview

The UALocationService class provides an interface to both the location services on device and the Urban Airship API.

Properties

automaticLocationOnForegroundEnabled

Starts the GPS (Standard Location) and acquires a single location on every launch. Setting this property to YES has the side effect of calling reportCurrentLocation.

@property (nonatomic, assign, setter=setAutomaticLocationOnForegroundEnabled:) BOOL automaticLocationOnForegroundEnabled

Declared In

UALocationService.h

backgroundLocationServiceEnabled

Allows location services to continue in the background.

@property (nonatomic, assign, getter=isBackgroundLocationServiceEnabled) BOOL backgroundLocationServiceEnabled

Declared In

UALocationService.h

dateOfLastLocation

Date of last location event reported

@property (nonatomic, strong, readonly, nullable) NSDate *dateOfLastLocation

Declared In

UALocationService.h

delegate

UALocationServiceDelegate for location service callbacks

@property (nonatomic, weak, nullable) id<UALocationServiceDelegate> delegate

Declared In

UALocationService.h

lastReportedLocation

Last location reported to Urban Airship

@property (nonatomic, strong, readonly, nullable) CLLocation *lastReportedLocation

Declared In

UALocationService.h

minimumTimeBetweenForegroundUpdates

Minimum time between automatic updates that are tied to app foreground events. Default value is 120 seconds.

@property (nonatomic, assign) NSTimeInterval minimumTimeBetweenForegroundUpdates

Declared In

UALocationService.h

requestAlwaysAuthorization

Request “always” location authorization. If YES (the default), Urban Airship will request always-on location permission. If NO, “when in use” authorization will be requested. Always-On permission is required for background location monitoring, including significant change. Once location reporting is started and an authorization prompt is presented, changes to the authorization level are not possible without updating the app in the App Store.

@property (nonatomic, assign) BOOL requestAlwaysAuthorization

Declared In

UALocationService.h

significantChangeServiceStatus

Status for NETWORK (cell tower) events.

@property (nonatomic, assign, readonly) UALocationProviderStatus significantChangeServiceStatus

Declared In

UALocationService.h

singleLocationServiceStatus

Status for single location service

@property (nonatomic, assign, readonly) UALocationProviderStatus singleLocationServiceStatus

Declared In

UALocationService.h

standardLocationServiceStatus

Status for GPS service.

@property (nonatomic, assign, readonly) UALocationProviderStatus standardLocationServiceStatus

Declared In

UALocationService.h

Class Methods

airshipLocationServiceEnabled

Current setting allowing UA location services.

+ (BOOL)airshipLocationServiceEnabled

Return Value

YES UA location services are allowed, and will start if authorized and enabled

NO UA location services are not allowed, and will not start, even if authorized and enabled

Declared In

UALocationService.h

coreLocationWillPromptUserForPermissionToRun

This method checks the underlying Core Location service to see if a user will receive a prompt requesting permission for Core Location services to run.

+ (BOOL)coreLocationWillPromptUserForPermissionToRun

Return Value

NO If Core Location services are enabled and the user has explicitly authorized location services

YES If ANY of the following are true:

  • Location services are not enabled (The global location service setting in Settings is disabled)
  • Location services are explicitly not authorized (The per app location service setting in Settings is disabled)
  • The user has not been asked yet to allow location services. (Location services are enabled, and CLLocationManager reports kCLAuthorizationStatusNotDetermined)

Declared In

UALocationService.h

locationServiceAuthorized

Reports the current authorization status of location services as reported by the system.

+ (BOOL)locationServiceAuthorized

Return Value

YES if the user has authorized location services, or has yet to be asked about location services.

NO if the user has explicitly disabled location services

Declared In

UALocationService.h

locationServicesEnabled

Reports the current authorization status of location services as reported by the system. This refers to the global location service setting switch.

+ (BOOL)locationServicesEnabled

Return Value

YES if location services are reported as enabled by the system.

NO if location services are reported as not enabled by the system.

Declared In

UALocationService.h

setAirshipLocationServiceEnabled:

This method allows UA Location Services to report location.

+ (void)setAirshipLocationServiceEnabled:(BOOL)airshipLocationServiceEnabled

Parameters

airshipLocationServiceEnabled

If set to YES, all UA location services will run if the system reports that location services are available and authorized. This setting will not override the users choice to disable location services and is safe to enable when user preferences have not been established. If NO, UA Location Services are disabled. This setting is persisted in NSUserDefaults.

Declared In

UALocationService.h

Instance Methods

location

The most recently received location available from the CLLocationManager object. This may be more accurate than the last reported location, and it may also be nil. See CLLocationManager documentation for more details.

- (nullable CLLocation *)location

Return Value

The most recent location, or nil if no locations are available.

Declared In

UALocationService.h

purpose

Purpose for location services shown to user when prompted to allow location services to begin. The default value is the NSLocationUsageDescription listed in the info.plist. This value cannot be set programatically.

- (nullable NSString *)purpose

Return Value

An NSString with the current purpose.

Declared In

UALocationService.h

reportCurrentLocation

Starts the single location service (standard location) long enough to obtain a location an then uploads it to Urban Airship. This method will send the first location that meets the accuracy set in the singleLocationDesiredAccuracy property. If a location is not found before the timeout, the most accurate location returned by CoreLocation is returned. If no location is found, the service is simply terminated.

- (void)reportCurrentLocation

Declared In

UALocationService.h

reportLocationToAnalytics:fromProvider:

Creates a UALocationEvent and enqueues it with the Analytics service.

- (void)reportLocationToAnalytics:(CLLocation *)location fromProvider:(nullable id<UALocationProviderProtocol>)provider

Parameters

location

The location to be sent to the Urban Airship analytics service

provider

The provider that generated the location. Data is pulled from the provider for analytics

Discussion

Warning: This must be called on the main thread. Not doing so will result in a crash

Declared In

UALocationService.h

setSingleLocationDesiredAccuracy:

Sets the desiredAccuracy for the single location service. Used by the reportCurrentLocation: method and the automatic foreground location.

- (void)setSingleLocationDesiredAccuracy:(CLLocationAccuracy)desiredAccuracy

Parameters

desiredAccuracy

CLLocationAccuracy The new desiredAccuracy

Discussion

Warning: Setting this value to high (such as kCLLocationAccuracyBest) will result in timeouts on every location service call in areas with poor GPS. This will result in degraded device battery life.

Declared In

UALocationService.h

setStandardLocationDesiredAccuracy:

Sets the standard location desired accuracy.

- (void)setStandardLocationDesiredAccuracy:(CLLocationAccuracy)desiredAccuracy

Parameters

desiredAccuracy

The new desired accuracy

Declared In

UALocationService.h

setStandardLocationDistanceFilter:

Sets the distance filter on the standard location provider.

- (void)setStandardLocationDistanceFilter:(CLLocationDistance)distanceFilter

Parameters

distanceFilter

The new distance filter.

Declared In

UALocationService.h

setTimeoutForSingleLocationService:

Time interval representing the length of time the single location service will attempt to acquire a location that meets accuracy requirements. At the end of the time interval, the most accurate location received will be sent. If no location has been received, the service is shut down.

- (void)setTimeoutForSingleLocationService:(NSTimeInterval)timeoutForSingleLocationService

Parameters

timeoutForSingleLocationService

NSTimeInterval for the new timeout value

Declared In

UALocationService.h

singleLocationDesiredAccuracy

Desired accuracy for single location service. Used by the reportCurrentLocation: method and the automatic foreground location.

- (CLLocationAccuracy)singleLocationDesiredAccuracy

Return Value

CLLocationAccuracy representing the desired accuracy for single location service.

Declared In

UALocationService.h

standardLocationDesiredAccuracy

The desired accuracy on the standard location provider.

- (CLLocationAccuracy)standardLocationDesiredAccuracy

Return Value

CLLocationAccuracy The current desired accuracy

Declared In

UALocationService.h

standardLocationDistanceFilter

The distance filter on the standard location provider.

- (CLLocationDistance)standardLocationDistanceFilter

Return Value

CLLocationDistance The current distance filter on the standard location provider

Declared In

UALocationService.h

startReportingSignificantLocationChanges

Starts the Significant Change location service and sends location data to Urban Airship. This service will continue in the background if stopMonitoringSignificantLocationChanges is not called before the app enters the background.

- (void)startReportingSignificantLocationChanges

Discussion

This will not start the location service if the app is not enabled and authorized. To force location services to start, set the UALocationServicesAllowed property to YES and call this method.

This will prompt the user for permission if location services have not been started previously, or if the user has purposely disabled location services. Given that location services were probably disabled for a reason, this prompt might not be welcomed.

Warning: If the kCLErrorDenied or kCLErrorNetwork errors are returned from the Core Location service, this service will be automatically shut down before the locationService:didFailWithError: delegate call to conserve battery. Be aware of this, and take appropriate action to restart the service if necessary.

Declared In

UALocationService.h

startReportingStandardLocation

Start the standard location service.

- (void)startReportingStandardLocation

Declared In

UALocationService.h

stopReportingSignificantLocationChanges

Stops the Significant Change location service.

- (void)stopReportingSignificantLocationChanges

Declared In

UALocationService.h

stopReportingStandardLocation

Stops the standard location service.

- (void)stopReportingStandardLocation

Declared In

UALocationService.h

timeoutForSingleLocationService

Time interval representing the amount of time that the single location service will run while waiting for a location value that meets the desired accuracy.

- (NSTimeInterval)timeoutForSingleLocationService

Return Value

NSTimeInterval representing the current timeout value

Declared In

UALocationService.h