ORKActiveStep Class Reference

Inherits from	ORKStep : NSObject
Declared in	ORKActiveStep.h

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.

`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