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 more

      Declaration

      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 is nil then the file will be formatted using JSON encoding.

      Declaration

      Swift

      override public func stringEncodingFormat() -> RSDStringSeparatedEncodingFormat?