Survey Sampling Package

Run surveys, cognitive tests and informed consent as app tasks in a CARP Mobile Sensing study.

carp_survey_package runs surveys, cognitive tests and informed consent flows as app tasks in a CARP Mobile Sensing (CAMS) study. CAMS schedules each task, notifies the participant and stores the answers as measurements.

The questions and their screens come from research_package, and the cognitive tests from cognition_package. Use the package for questionnaires, ecological momentary assessment and repeated cognitive testing.

pub.dev

API reference

GitHub

Research Package 3.x

carp_survey_package 2.1.1 depends on research_package 3.x, so a CAMS app resolves research_package 3.2.0 and cannot use 4.0.0. The Research Package section documents 4.0.0; its pages on tasks, answer formats, results, branching, localization and theming also apply to 3.2.0. For permissions, which 3.2.0 asks for itself, see Permissions.

Features

Surveys

Build questionnaires from Research Package steps and answer formats, or start with the built-in WHO-5 well-being survey.

Cognitive tests

Add any of the 14 tests in Cognition Package, such as Flanker, Stroop effect and Trail making, as steps of a task.

Notifications

CAMS schedules each task with its trigger and can notify the participant when the task is due.

Survey data

Each submitted or canceled task becomes a measurement that holds the full Research Package result.

Measure types

The package adds one measure type, which RPAppTask adds to every survey task by itself:

Measure type	Data	Android	iOS
`dk.cachet.carp.survey`	The result of a survey, cognitive test or consent task	Yes	Yes

See Survey data for the fields, and for the dk.cachet.carp.completedapptask.<type> measurement that CAMS adds for every completed task.

Requirements

Component	Requirement
Dart SDK	3.12 or later
Flutter	3.44 or later
`carp_mobile_sensing`	2.3.0 or later
`research_package`	`^3.0.0`, which resolves to 3.2.0, not 4.0.0
`cognition_package`	`^1.9.0`, which resolves to 1.9.1
Android	API level 26 (Android 8.0) or later, required by the `health` plugin that `research_package` 3.x depends on
iOS	15.0 or later

How it works

A survey reaches the participant as an app task:

sequenceDiagram
    participant C as CAMS
    participant A as Your app
    participant P as Participant
    Note over C: the trigger fires
    C->>C: enqueue() a SurveyUserTask
    C->>P: notification
    C->>A: userTaskEvents
    P->>A: taps the task
    A->>C: onStart()
    A->>P: task.widget
    P->>A: submits the answers
    A->>C: onSubmit with the RPTaskResult
    Note over C: stores a dk.cachet.carp.survey<br/>measurement and marks the task done

In detail:

When the trigger fires, CAMS creates a SurveyUserTask and puts it on its task queue. With notification: true, CAMS also notifies the participant.
Your app lists the tasks on the queue and rebuilds the list on userTaskEvents.
When the participant opens a task, the app calls onStart() and shows task.widget, a full-screen Research Package task.
When the participant submits the answers, the package stores them as a dk.cachet.carp.survey measurement and marks the task as done.

In a protocol, a survey is an RPAppTask with a trigger:

CarpMobileSensing.ensureInitialized();
SamplingPackageRegistry().register(SurveySamplingPackage());

protocol.addTaskControl(
  RecurrentScheduledTrigger(
    type: RecurrentType.daily,
    time: const TimeOfDay(hour: 13),
  ),
  RPAppTask( 
    type: AppTask.SURVEY_TYPE,
    name: 'WHO-5 Survey',
    title: 'Well-being survey',
    description: 'Five questions about how you have been feeling',
    notification: true,
    rpTask: who5Task,
  ),
  phone,
);

who5Task is the WHO-5 well-being survey that ships with the package.

Next steps

Installation

Add the package to a CAMS app and configure Android and iOS.

Quickstart

Build an app that schedules a daily WHO-5 survey.

Building surveys

Build a survey from Research Package steps and add it to a protocol.

Scheduling and notifications

Choose triggers, notify participants and keep the task list in sync.