ORKTask Protocol Reference
Conforms to | NSObject |
---|---|
Declared in | ORKTask.h |
Overview
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 *identifier
Discussion
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
- (nullable ORKStep *)stepAfterStep:(nullable ORKStep *)step withResult:(ORKTaskResult *)result
Declared In
ORKTask.h
– stepBeforeStep:withResult:
required method
- (nullable ORKStep *)stepBeforeStep:(nullable ORKStep *)step withResult:(ORKTaskResult *)result
Declared In
ORKTask.h
– stepWithIdentifier:
Returns the step that matches the specified identifier.
- (nullable ORKStep *)stepWithIdentifier:(NSString *)identifier
Parameters
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:
- (ORKTaskProgress)progressOfCurrentStep:(ORKStep *)step withResult:(ORKTaskResult *)result
Declared In
ORKTask.h
– validateParameters
Validates the task parameters.
- (void)validateParameters
Discussion
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*> *requestedHealthKitTypesForReading
Discussion
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*> *requestedHealthKitTypesForWriting
Discussion
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 requestedPermissions
Discussion
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 providesBackgroundAudioPrompts
Discussion
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