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.

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

1. Call ParticipantSession.surveyPresentation(surveyName:) to construct a model object for the survey you wish to present.
2. Construct a SurveyViewController using the init(presentation:, completion:) initializer.
3. 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.

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)

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)
}

Additional Sample Code

In the MyDataHelpsKit example app, see:

• Tasks/TasksView.swift: Presents surveys for tasks assigned to the participant.
• SurveyPresentation/PresentedSurveyView.swift: SwiftUI wrapper for SurveyViewController.
• SurveyPresentation/SurveyLauncherView.swift: Experiment with launching any survey in your project.

SDK Reference

• SurveyViewController
• ParticipantSession.surveyPresentation(surveyName:)
• SurveyTask