UALocationService Class Reference
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.
Tasks
Standard Location Accuracy and Distance
-
– standardLocationDistanceFilter
-
– setStandardLocationDistanceFilter:
-
– standardLocationDesiredAccuracy
-
– setStandardLocationDesiredAccuracy:
Location Services Authorization
-
+ airshipLocationServiceEnabled
-
+ setAirshipLocationServiceEnabled:
-
+ locationServicesEnabled
-
+ locationServiceAuthorized
-
+ coreLocationWillPromptUserForPermissionToRun
Recent Activity
-
– location
-
lastReportedLocation
property -
dateOfLastLocation
property -
delegate
property
Automatic Location Services
-
automaticLocationOnForegroundEnabled
property -
requestAlwaysAuthorization
property -
backgroundLocationServiceEnabled
property -
minimumTimeBetweenForegroundUpdates
property
Status of Services
-
standardLocationServiceStatus
property -
significantChangeServiceStatus
property -
singleLocationServiceStatus
property
Purpose
Starting and Stopping Location Services
-
– startReportingStandardLocation
-
– stopReportingStandardLocation
-
– startReportingSignificantLocationChanges
-
– stopReportingSignificantLocationChanges
Analytics
Single Location Service
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
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