ORKTask Protocol Reference
| Conforms to | NSObject |
|---|---|
| Declared in | ORKTask.h |
The ORKTask protocol defines a task to be carried out by a participant
in a research study. To present the ResearchKit framework UI in your app, instantiate an
object that implements the ORKTask protocol (such as ORKOrderedTask) and
provide it to an ORKTaskViewController object.
Implement this protocol to enable dynamic selection of the steps for a given task.
By default, ORKOrderedTask implements this protocol for simple sequential tasks.
Each step (ORKStep) in a task roughly corresponds to one screen, and represents the
primary unit of work in any task presented by a task view controller. For example,
an ORKQuestionStep object corresponds to a single question presented on screen,
together with controls the participant uses to answer the question. Another example is ORKFormStep, which corresponds to a single
screen that displays multiple questions or items for which participants provide information, such as first name, last name, and birth date.
Each step corresponds to one
ORKStepViewController object, which may manage child view controllers in a particular
sequence. The correspondence of step to view controller holds even though some steps, such as ORKVisualConsentStep and
ORKConsentReviewStep, can produce multiple screens.
identifier
required method
The unique identifier for this task.
@property (nonatomic, copy, readonly) NSString *identifierDiscussion
The identifier should be a short string that identifies the task. The identifier is copied
into the ORKTaskResult objects generated by the task view controller for this
task. You can use a human-readable string for the task identifier
or a UUID; the exact string you use depends on your app.
In the case of apps whose tasks come from a server, the unique identifier for the task may be in an external database.
The task view controller uses the identifier when constructing the task result. The identifier can also be used during UI state restoration to identify the task that needs to be restored.
Declared In
ORKTask.h
– stepAfterStep:withResult:
required method
Returns the step after the specified step, if there is one.
- (nullable ORKStep *)stepAfterStep:(nullable ORKStep *)step withResult:(ORKTaskResult *)resultParameters
step |
The reference step. Pass |
|---|---|
result |
A snapshot of the current set of results. |
Return Value
The step that comes after the specified step, or nil if there isn’t one.
Discussion
This method lets you use a result to determine the next step.
The task view controller calls this method to determine the step to display after the specified step. The task view controller can also call this method every time the result updates, to determine if the new result changes which steps are available.
If you need to implement this method, take care to avoid creating a confusing sequence of steps. As much as possible, use ORKOrderedTask instead.
Declared In
ORKTask.h
– stepBeforeStep:withResult:
required method
Returns the step that precedes the specified step, if there is one.
- (nullable ORKStep *)stepBeforeStep:(nullable ORKStep *)step withResult:(ORKTaskResult *)resultParameters
step |
The reference step. Pass |
|---|---|
result |
A snapshot of the current set of results. |
Return Value
The step that precedes the reference step, or nil if there isn’t one.
Discussion
The task view controller calls this method to determine the step to display before the specified step. The task view controller can also call this method every time the result changes, to determine if the new result changes which steps are available.
If you need to implement this method, take care to avoid creating a confusing sequence of steps. As much as possible, use ORKOrderedTask instead. Returning nil prevents the user from navigating back to a previous step.
Declared In
ORKTask.h
– stepWithIdentifier:
Returns the step that matches the specified identifier.
- (nullable ORKStep *)stepWithIdentifier:(NSString *)identifierParameters
identifier |
The identifier of the step to restore. |
|---|
Return Value
The step that matches the specified identifier.
Discussion
Implementing this method allows state restoration of a task
to a particular step. If you don’t implement this method, ORKTaskViewController restores the state
to the first step of the task.
Declared In
ORKTask.h
– progressOfCurrentStep:withResult:
Returns the progress of the current step.
- (ORKTaskProgress)progressOfCurrentStep:(ORKStep *)step withResult:(ORKTaskResult *)resultParameters
step |
The current step. |
|---|---|
result |
A snapshot of the current set of results. |
Return Value
The current step’s index and the total number of steps in the task, as an ORKTaskProgress object.
Discussion
During a task, the task view controller can display the progress (that is, the current step number
out of the total number of steps) in the navigation bar. Implement
this method to control what is displayed; if you don’t implement this method, the progress label does not appear.
If the returned ORKTaskProgress object has a count of 0, the progress is not displayed.
Declared In
ORKTask.h
– validateParameters
Validates the task parameters.
- (void)validateParametersDiscussion
The implementation of this method should check that all the task parameters are correct. An invalid task
is considered an unrecoverable error: the implementation should throw an exception on parameter validation failure.
For example, the ORKOrderedTask implementation makes sure that all its step identifiers are unique, throwing an
exception otherwise.
This method is usually called by a task view controller when its task is set.
Declared In
ORKTask.h
requestedHealthKitTypesForReading
The set of HealthKit types that steps in the task need to be able to read. (read-only)
@property (nonatomic, copy, readonly, nullable) NSSet<HKObjectType*> *requestedHealthKitTypesForReadingDiscussion
The value of this property is a set of HKObjectType values to request for reading from HealthKit during this task. After the last of the initial instruction steps, the task view controller
requests access to these HealthKit types.
To set this property, you can scan the steps in the task
and collate the HealthKit types that are requested by each active step, question, or
form step that has a Health answer format, and then include any additional types known
to be required. (Note that ORKOrderedTask does something similar for this property.)
See also: requestedHealthKitTypesForWriting.
Declared In
ORKTask.h
requestedHealthKitTypesForWriting
The set of HealthKit types for which the task needs to request write access.
@property (nonatomic, copy, readonly, nullable) NSSet<HKObjectType*> *requestedHealthKitTypesForWritingDiscussion
The requested HKObjectType values for writing can be returned by an extended task,
to request write access to these HealthKit types together with the read access
requested by the task view controller by calling requestedHealthKitTypesForReading.
See also: requestedHealthKitTypesForReading.
Declared In
ORKTask.h
requestedPermissions
The set of permissions requested by the task.
@property (nonatomic, readonly) ORKPermissionMask requestedPermissionsDiscussion
By default in ORKOrderedTask object, these permissions are collected from the
recorder configurations associated with the active steps in the task.
Declared In
ORKTask.h
providesBackgroundAudioPrompts
A Boolean value indicating whether this task involves spoken audio prompts. (read-only)
@property (nonatomic, readonly) BOOL providesBackgroundAudioPromptsDiscussion
If the value of this property is YES, the shared AVAudioSession is configured for playback in the background.
The audio UIBackgroundMode value must be set in the application’s Info.plist file
for this to be effective.
By default, this property looks for active steps that have
audio prompts or count down enabled, and returns YES if such steps exist in
the task.
Declared In
ORKTask.h