ORKActiveStep Class Reference

Inherits from	ORKStep : NSObject
Declared in	ORKActiveStep.h ORKActiveStep.m

Overview

The ORKActiveStep class is the base class for steps in active tasks, which are steps that collect sensor data in a semi-controlled environment, as opposed to the purely passive data collection enabled by HealthKit, or the more subjective data collected when users fill in surveys.

In addition to the behaviors of ORKStep, active steps have the concept of life cycle, which includes a defined start and finish.

The ResearchKit framework provides built-in behaviors that allow active steps to play voice prompts, speak a count down, and have a defined duration.

To present an active step in your app, it’s likely that you will subclass ORKActiveStep and ORKActiveStepViewController to present custom UI and custom prompts. For example subclasses, see ORKSpatialSpanMemoryStep or ORKFitnessStep. Active steps may also need ORKResult subclasses to record their results if these don’t come purely from recorders.

If you develop a new active step subclass, consider contributing your code to the ResearchKit project so that it’s available for others to use in their studies.

Other Methods

`stepDuration`

The duration of the step in seconds.

@property (nonatomic) NSTimeInterval stepDuration

Discussion

If the step duration is greater than zero, a built-in timer starts when the step starts. If shouldStartTimerAutomatically is set, the timer starts when the step’s view appears. When the timer expires, a sound or vibration may be played. If shouldContinueOnFinish is set, the step automatically navigates forward when the timer expires.

The default value of this property is 0, which disables the built-in timer.

Declared In

ORKActiveStep.h

`shouldShowDefaultTimer`

A Boolean value indicating whether to show a view with a default timer.

@property (nonatomic) BOOL shouldShowDefaultTimer

Discussion

The default timer UI is not used in any of the current predefined tasks, but it can be displayed in a simple active task that does not require custom UI and needs only a count down timer on screen during data collection.

Note that this property is ignored if stepDuration is 0.

The default value of this property is YES.

Declared In

ORKActiveStep.h

`shouldSpeakCountDown`

A Boolean value indicating whether to speak the last few seconds in the count down of the duration of a timed step.

@property (nonatomic) BOOL shouldSpeakCountDown

Discussion

When the value of this property is YES, AVSpeechSynthesizer is used to synthesize the countdown. Note that this property is ignored if VoiceOver is enabled.

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldSpeakRemainingTimeAtHalfway`

A Boolean value indicating whether to speak the halfway point in the count down of the duration of a timed step.

@property (nonatomic) BOOL shouldSpeakRemainingTimeAtHalfway

Discussion

When the value of this property is YES, AVSpeechSynthesizer is used to synthesize the countdown. Note that this property is ignored if VoiceOver is enabled.

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldStartTimerAutomatically`

A Boolean value indicating whether to start the count down timer automatically when the step starts, or require the user to take some explicit action to start the step, such as tapping a button.

@property (nonatomic) BOOL shouldStartTimerAutomatically

Discussion

Usually the explicit action needs to come from custom UI in an ORKActiveStepViewController subclass.

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldPlaySoundOnStart`

A Boolean value indicating whether to play a default sound when the step starts.

@property (nonatomic) BOOL shouldPlaySoundOnStart

Discussion

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldPlaySoundOnFinish`

A Boolean value indicating whether to play a default sound when the step finishes.

@property (nonatomic) BOOL shouldPlaySoundOnFinish

Discussion

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldVibrateOnStart`

A Boolean value indicating whether to vibrate when the step starts.

@property (nonatomic) BOOL shouldVibrateOnStart

Discussion

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldVibrateOnFinish`

A Boolean value indicating whether to vibrate when the step finishes.

@property (nonatomic) BOOL shouldVibrateOnFinish

Discussion

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldUseNextAsSkipButton`

A Boolean value indicating whether the Next button should double as a skip action before the step finishes.

@property (nonatomic) BOOL shouldUseNextAsSkipButton

Discussion

When the value of this property is YES, the ResearchKit framework hides the skip button and makes the Next button function as a skip button when the step has not yet finished.

The default value of this property is NO.

Declared In

ORKActiveStep.h

`shouldContinueOnFinish`

A Boolean value indicating whether to transition automatically when the step finishes.

@property (nonatomic) BOOL shouldContinueOnFinish

Discussion

When the value of this property is YES, the active step view controller automatically performs the continue action when the [ORKActiveStepViewController finish] method is called.

The default value of this property is NO.

Declared In

ORKActiveStep.h

`spokenInstruction`

Localized text that represents an instructional voice prompt.

@property (nonatomic, copy, nullable) NSString *spokenInstruction

Discussion

Instructional speech begins when the step starts. If VoiceOver is active, the instruction is spoken by VoiceOver.

Declared In

ORKActiveStep.h

`finishedSpokenInstruction`

Localized text that represents an instructional voice prompt for when the step finishes.

@property (nonatomic, copy, nullable) NSString *finishedSpokenInstruction

Discussion

Instructional speech begins when the step finishes. If VoiceOver is active, the instruction is spoken by VoiceOver.

Declared In

ORKActiveStep.h

`image`

An image to be displayed below the instructions for the step.

@property (nonatomic, strong, nullable) UIImage *image

Discussion

The image can be stretched to fit the available space. When choosing a size for this asset, be sure to take into account the variations in device form factors.

Declared In

ORKActiveStep.h

`recorderConfigurations`

An array of recorder configurations that define the parameters for recorders to be run during a step to collect sensor or other data.

@property (nonatomic, copy, nullable) NSArray<ORKRecorderConfiguration*> *recorderConfigurations

Discussion

If you want to collect data from sensors while the step is in progress, add one or more recorder configurations to the array. The active step view controller instantiates recorders and collates their results as children of the step result.

The set of recorder configurations is scanned when populating the requestedHealthKitTypesForReading and requestedPermissions properties.

Declared In

ORKActiveStep.h

Other Methods

`+ stepViewControllerClass`

+ (Class)stepViewControllerClass

Declared In

ORKStep.h

`– isRestorable`

A Boolean value indicating whether a task can be restored to the step during state restoration. (read-only)

- (BOOL)isRestorable

Discussion

By default, the value of this property is YES, but subclasses of ORKStep might use NO.

If a task cannot be restored to the step, the task is typically restored to the last restorable step in the task, or to the first step, if no restorable steps are available.

Declared In

ORKStep.h

`– initWithIdentifier:`

- (instancetype)initWithIdentifier:(NSString *)identifier

Declared In

ORKStep.h

`– initWithCoder:`

- (instancetype)initWithCoder:(NSCoder *)aDecoder

Declared In

ORKStep.h

`– requestedHealthKitTypesForReading`

The set of HealthKit types the step requests for reading. (read-only)

- (NSSet<HKObjectType*> *)requestedHealthKitTypesForReading

Discussion

The task view controller uses this set of types when constructing a list of all the HealthKit types required by all the steps in a task, so that it can present the HealthKit access dialog just once during that task.

By default, the property scans the recorders and collates the HealthKit types the recorders require. Subclasses may override this implementation.

Declared In

ORKStep.h

`– requestedPermissions`

The set of access permissions required for the step. (read-only)

- (ORKPermissionMask)requestedPermissions

Discussion

The permission mask is used by the task view controller to determine the types of access to request from users when they complete the initial instruction steps in a task. If your step requires access to APIs that limit access, include the permissions you require in this mask.

By default, the property scans the recorders and collates the permissions required by the recorders. Subclasses may override this implementation.

Declared In

ORKStep.h