Surveys
Participants typically contribute data by completing surveys. Surveys can be completed in mobile apps, in web browsers, and even by project coordinators on the participants’ behalf.
Because surveys are a fundamental part of MyDataHelps projects, we strongly recommend reading about survey data concepts.
The topics below are for querying and managing survey and task data. Your app can also use the SDK to present surveys for participants to complete.
See Presenting Surveys for a detailed guide.
Query Survey Tasks
Construct a SurveyTaskQuery to specify filtering criteria, and execute the query using ParticipantSession.querySurveyTasks. This query returns a SurveyTaskResultPage containing SurveyTask values.
Consult the programming guide for best practices on working with queries and paged results in MyDataHelpsKit.
SDK Reference
Examples
Fetch all completed tasks, oldest task first:
let criteria = SurveyTaskQuery(statuses: Set([.complete]), sortOrder: .dateAscending)
let result = try await session.querySurveyTasks(criteria)
for task in result.surveyTasks {
print("Task: \(task.surveyDisplayName), completed \(task.endDate?.formatted())")
}
let criteria = SurveyTaskQuery(statuses: Set([.complete]), sortOrder: .dateAscending)
let result = try await session.querySurveyTasks(criteria)
for task in result.surveyTasks {
print("Task: \(task.surveyDisplayName), completed \(task.endDate?.formatted())")
}
Find the most recent task assigned for a ‘PHQ-9’ survey:
let criteria = SurveyTaskQuery(surveyNames: Set(["PHQ-9"]), sortOrder: .dateDescending, limit: 1)
if let task = try await session.querySurveyTasks(criteria).surveyTasks.first {
switch task.status {
case .complete:
print("\(task.surveyDisplayName): completed on \(task.endDate?.formatted())")
default:
print("\(task.surveyDisplayName): incomplete, due on \(task.dueDate?.formatted())")
}
} else {
print("No task was assigned to the participant for this survey.")
}
let criteria = SurveyTaskQuery(surveyNames: Set(["PHQ-9"]), sortOrder: .dateDescending, limit: 1)
if let task = try await session.querySurveyTasks(criteria).surveyTasks.first {
switch task.status {
case .complete:
print("\(task.surveyDisplayName): completed on \(task.endDate?.formatted())")
default:
print("\(task.surveyDisplayName): incomplete, due on \(task.dueDate?.formatted())")
}
} else {
print("No task was assigned to the participant for this survey.")
}
In the MyDataHelpsKit example app, see:
Query Past Survey Answers
Construct a SurveyAnswersQuery to specify filtering criteria, and execute the query using ParticipantSession.querySurveyAnswers. This query returns a SurveyAnswersPage containing SurveyAnswer values.
Consult the programming guide for best practices on working with queries and paged results in MyDataHelpsKit.
SDK Reference
Examples
// task is from the "Fetching a Single Task" example above:
let criteria = SurveyAnswersQuery(surveyID: task.surveyID)
let result = try await session.querySurveyAnswers(criteria)
for surveyAnswer in result.surveyAnswers {
print("Answer for step \(surveyAnswer.stepIdentifier):")
print(surveyAnswer.answers.joined(separator: ", "))
}
// task is from the "Fetching a Single Task" example above:
let criteria = SurveyAnswersQuery(surveyID: task.surveyID)
let result = try await session.querySurveyAnswers(criteria)
for surveyAnswer in result.surveyAnswers {
print("Answer for step \(surveyAnswer.stepIdentifier):")
print(surveyAnswer.answers.joined(separator: ", "))
}
In the MyDataHelpsKit example app, see:
Delete a Survey Result
Deletes a survey result for a participant.
SDK Reference
Examples
// surveyResultID is from the "Fetching Survey Answers" example above:
try await session.deleteSurveyResult(surveyAnswer.surveyResultID)
// surveyResultID is from the "Fetching Survey Answers" example above:
try await session.deleteSurveyResult(surveyAnswer.surveyResultID)
In the MyDataHelpsKit example app, see: