Presenting Surveys
You can use SurveyViewController in MyDataHelpsKit to present a survey for the participant to complete. This view controller implements the complete user experience for a MyDataHelps survey, including step navigation and sending results to MyDataHelps.
Note
See
Surveys for general information about MyDataHelps surveys and tasks, and related APIs for working with them.
Surveys presented to the participant are identified by their survey name. The survey must be published to the project that the participant is currently interacting with. SurveyViewController is only compatible with surveys with features that are supported on the web; see platform support for more information.
If the participant was assigned this survey in a task, then completing the survey will close the assigned task. If no task already exists, the survey results will be stored without any associated task.
Initializing and Presenting
- Call
ParticipantSession.surveyPresentation(surveyName:) to construct a model object for the survey you wish to present.
- Construct a
SurveyViewController using the init(presentation:, completion:) initializer.
- Present the view controller to the participant. SurveyViewController is designed to be presented modally, e.g. using
present(surveyViewController, animated: true) in UIKit or a .sheet presentation in SwiftUI.
Do not wrap the SurveyViewController with a UINavigationController or NavigationView. MyDataHelpsKit handles all navigation elements and controls internally, including localized Cancel/Done buttons.
SurveyViewController sets isModalInPresentation to true by default. In SwiftUI, it’s recommended to set interactiveDismissDisabled() on your UIViewControllerRepresentable wrapper for SurveyViewController.
Completion and Dismissal
Once the participant has finished interacting with the survey, or if there is a failure to present the survey, SurveyViewController will invoke the completion callback you passed to its initializer.
Note
The SurveyViewController will not dismiss itself. In all cases—success and failure—your app must dismiss the SurveyViewController from the completion callback.
The completion callback includes a Result value that indicates whether the participant successfully completed the survey, and any error that may have been encountered. If the result is a failure, consider displaying an error alert to the user.
Examples
Presenting a survey named ‘PHQ-9’ for completion by the participant:
let presentation = session.surveyPresentation(surveyName: "PHQ-9")
let surveyViewController = SurveyViewController(presentation: presentation) { viewController, result in
// Your app must always dismiss the SurveyViewController in this callback.
self.dismiss(animated: true)
switch result {
case .success(.completed):
print("Survey completed, and the result was saved to MyDataHelps.")
case .success(.saved):
print("Survey not completed; progress was saved for later completion.")
case .success(.discarded):
print("Survey not completed; results were discarded.")
case let .failure(error):
print("Error: \(error)")
}
}
present(surveyViewController, animated: true)
let presentation = session.surveyPresentation(surveyName: "PHQ-9")
let surveyViewController = SurveyViewController(presentation: presentation) { viewController, result in
// Your app must always dismiss the SurveyViewController in this callback.
self.dismiss(animated: true)
switch result {
case .success(.completed):
print("Survey completed, and the result was saved to MyDataHelps.")
case .success(.saved):
print("Survey not completed; progress was saved for later completion.")
case .success(.discarded):
print("Survey not completed; results were discarded.")
case let .failure(error):
print("Error: \(error)")
}
}
present(surveyViewController, animated: true)
If your app presents a list of assigned tasks to the participant using SurveyTaskQuery, it can easily launch surveys when the participant selects a SurveyTask to complete:
func presentSurvey(assignedTask: SurveyTask) {
let presentation = session.surveyPresentation(surveyName: assignedTask.surveyName)
let surveyViewController = SurveyViewController(presentation: presentation) { viewController, result in
// Always dismiss the SurveyViewController upon completion.
self.dismiss(animated: true)
// Update your app's UI upon survey completion or dismissal...
self.showMessage(result)
// ...including re-fetching tasks via SurveyTaskQuery.
self.updateTaskList()
}
present(surveyViewController, animated: true)
}
func presentSurvey(assignedTask: SurveyTask) {
let presentation = session.surveyPresentation(surveyName: assignedTask.surveyName)
let surveyViewController = SurveyViewController(presentation: presentation) { viewController, result in
// Always dismiss the SurveyViewController upon completion.
self.dismiss(animated: true)
// Update your app's UI upon survey completion or dismissal...
self.showMessage(result)
// ...including re-fetching tasks via SurveyTaskQuery.
self.updateTaskList()
}
present(surveyViewController, animated: true)
}
Additional Sample Code
In the MyDataHelpsKit example app, see:
SDK Reference