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.
Contents
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.
ParticipantSession.surveyPresentation(surveyName:)
to construct a model object for the survey you wish to present.SurveyViewController
using the init(presentation:, completion:)
initializer.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.
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.
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.
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)
}
In the MyDataHelpsKit example app, see: