RSDDistanceRecorder
@available(iOS 10.0, *)
public class RSDDistanceRecorder : RSDSampleRecorder, CLLocationManagerDelegate
RSDDistanceRecorder
is intended to be used for recording location where the participant is walking,
running, cycling, or other activities outdoors where the distance travelled is of interest. By
default, this recorder only logs the relative distance, altitude, course, and speed travelled by
the participant. To log GPS coordinates, the configuration file must explicitly be set to do so,
and it is recommended to only log the coordinates if the user is a tester in order to ensure the
participant’s privacy is respected.
At the end of the motion travelled step, the recorder also uses CoreMotion to query the pedometer
for the overall distance and step count as measured by the pedometer which are then added to the
RSDCollectionResult
returned by this recorder when it is stopped.
This recorder is only available on iOS devices. CoreMotion is not supported by other platforms. Additionally, for a watchOS application that needs to measure distance travelled, creating an HKWorkoutSession offers a more efficient use of the device battery with equivalent accuracy in determining the distance travelled by the participant while performing a distance measuring activity.
This recorder is designed to be run in the background so that the user can lock the screen and place the phone in their pocket or bag. This requires setting the capabilities in your app to include background audio.
Additionally, you will need to add the privacy permission for location and motion sensors to the
application Info.plist
file. As of this writing (syoung 02/08/2018), those keys are:
Privacy - Motion Usage Description
Privacy - Location Always and When In Use Usage Description
Privacy - Location When In Use Usage Description
Note
Both location privacy keys are required.
Seealso
RSDDistanceRecorderConfiguration
and RSDDistanceRecord
-
The result identifiers used for the additional results recorded by the distance recorder.
See moreDeclaration
Swift
public enum ResultIdentifier : String, CodingKey
-
Convenience property for getting the location configuration.
Declaration
Swift
public var locationConfiguration: RSDDistanceRecorderConfiguration? { get }
-
Should relative distance only be saved to the log? Default =
true
.Declaration
Swift
public var relativeDistanceOnly: Bool
-
Whether or not the user is expected to be standing still or moving. This is used to mark when to start calculating distance travelled while moving as a part of a larger overall data gathering effort that might include how much a person is moving during other steps when they should be standing still (while recording heart rate, for example).
Declaration
Swift
public var isStandingStill: Bool { get set }
-
Total distance (measured in meters) from the start of recording.
Declaration
Swift
@objc dynamic public private(set) var totalDistance: Double { get }
-
Most recent location recorded.
Declaration
Swift
public private(set) var mostRecentLocation: CLLocation? { get }
-
Is the participant outdoors?
Declaration
Swift
public func isOutdoors() -> Bool
Return Value
true
if the horizontal accuracy indicates that the participant is outdoors.
-
Override to request GPS and motion permissions.
Declaration
Swift
override public func requestPermissions(on viewController: UIViewController, _ completion: @escaping RSDAsyncActionCompletionHandler)
-
Override to start updating the GPS location.
Declaration
Swift
override public func startRecorder(_ completion: @escaping ((RSDAsyncActionStatus, Error?) -> Void))
-
Override to stop updating GPS location.
Declaration
Swift
override public func stopRecorder(_ completion: @escaping ((RSDAsyncActionStatus) -> Void))
-
Override to stop updating GPS location.
Declaration
Swift
override public func pause()
-
Override to start updating the GPS location.
Declaration
Swift
override public func resume()
-
Override to check if the step being moved to is the step when the participant’s distance should be tracked and to add the pedometer reading once the participant is standing still.
Declaration
Swift
override public func moveTo(step: RSDStep, taskViewModel: RSDPathComponent)
-
If the location manager failed, then check if the manager was requesting permission and call the completion handler if appropriate.
Declaration
Swift
public func locationManager(_ manager: CLLocationManager, didFailWithError error: Error)
-
If the authorization changes, then check if authorization has been granted.
Declaration
Swift
public func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus)
-
When location updates are received, process them on the processing queue.
Declaration
Swift
public func locationManager(_ manager: CLLocationManager, didUpdateLocations locations: [CLLocation])
-
Returns the string encoding format to use for this file. Default is
nil
. If this isnil
then the file will be formatted using JSON encoding.Declaration
Swift
override public func stringEncodingFormat() -> RSDStringSeparatedEncodingFormat?