Skip to content
CARP Documentation

Step 1: Configure your study

A study is a few JSON files. The app reads them on your phone in Step 2, and you upload the same files to the CARP Portal when you go live.

How a study runs

Section titled “How a study runs”

Every study follows the same flow on the participant’s phone. The files on this page decide what happens at each step.

  1. Join. The participant joins with an email invitation (username and password) or, if the study allows it, anonymously with a QR code or a 5-character code. The app shows the invitation with the study’s purpose, from protocol.json.

  2. Give consent. The participant reads the informed consent and signs that you may collect their data, from consent.json.

  3. Allow permissions. The app asks for the permissions the protocol’s measures need, such as location or activity.

  4. Collect. The app runs the protocol: each task starts when its trigger fires, its measures collect data, and the data goes to the protocol’s data endpoint.

  5. Leave. The participant can leave the study at any time from their profile.

All texts along the way are shown in the phone’s language, from the translation files. See the screens in What participants see.

The files

Section titled “The files”
File What it holds Needed? Section
protocol.json What to collect, from which device, and when Yes Protocol
consent.json The informed consent the participant reads and signs No Consent
en.json, da.json, … The texts, one file per language If you use keys Translations

To generate a file, run the Dart code in a test or a small script and save the result with toJsonString(...). Try it with the buttons below.

Protocol

Section titled “Protocol”

The protocol answers four questions:

Question In the protocol In this example
Where is data collected? Device The phone
What is collected? Measures Steps and battery
When is it collected? Trigger Right away, all the time
Where does data go? Data endpoint A database on the phone
Dart
final protocol = SmartphoneStudyProtocol(
  name: 'My first study',
  // Texts are translation keys, see "Translations" below.
  studyDescription: StudyDescription(
    title: 'study.title',
    description: 'study.description',
    purpose: 'study.purpose',
  ),
  dataEndPoint: SQLiteDataEndPoint(),
);


// The phone collects the data, the participant is the person using it.
final phone = Smartphone();
protocol.addPrimaryDevice(phone);
protocol.addParticipantRole(ParticipantRole('Participant'));


// Start right away and keep collecting in the background.
protocol.addTaskControl(
  ImmediateTrigger(),
  BackgroundTask(name: 'Steps and battery', measures: [
    Measure(type: SensorSamplingPackage.STEP_EVENT),
    Measure(type: DeviceSamplingPackage.BATTERY_STATE),
  ]),
  phone,
);

CAMS adds the Monitoring Smartphone task itself. It records errors and task events.

To collect more, add a measure from Available packages. To collect at other times, change the trigger. To ask the participant something, add a task. Everything a protocol can hold is in Study protocol.

Section titled “Consent”

The informed consent is what a participant reads before the study starts. It is how you inform them: what the study is about, what data it collects, how their privacy is protected, what they will be asked to do, and that they can leave at any time. It can hold anything the participant should know before agreeing.

It is a short flow: the participant reads the sections, reviews them, signs with name and finger, and is done. Each section has a type (Overview, Data gathering, Privacy, Study tasks and more) that sets its icon and default title. See how it looks in the app in What participants see.

Dart
final document = RPConsentDocument(title: 'consent.title', sections: [
  RPConsentSection(
    type: RPConsentSectionType.Overview,
    summary: 'consent.overview.summary',
    content: 'consent.overview.content',
  ),
  RPConsentSection(
    type: RPConsentSectionType.DataGathering,
    summary: 'consent.data.summary',
    content: 'consent.data.content',
  ),
]);
document.addSignature(RPConsentSignature(identifier: 'signature'));


// Read the sections, review and sign, done.
final consent = RPOrderedTask(identifier: 'consent', steps: [
  RPVisualConsentStep(identifier: 'visual', consentDocument: document),
  RPConsentReviewStep(
    identifier: 'review',
    title: 'consent.review.title',
    consentDocument: document,
    reasonForConsent: 'consent.review.reason',
  ),
  RPCompletionStep(identifier: 'done', title: 'consent.done.title', text: 'consent.done.text'),
]);

No consent.json means there is nothing to sign, and the participant goes straight into the study.

Translations

Section titled “Translations”

The protocol and consent don’t contain the texts. They contain keys, such as study.purpose. Each language has a file that maps the keys to the text, and the app shows the file that matches the phone’s language. en.json is used when there is no file for that language.

assets/carp/lang/en.json
{
  "study.title": "My first study",
  "study.description": "We count your steps for two weeks.",
  "study.purpose": "To learn how much people walk in a normal week.",
  "consent.title": "Informed consent",
  "consent.overview.summary": "This study counts your steps.",
  "consent.overview.content": "For two weeks, the app counts your steps in the background.",
  "consent.data.summary": "We collect steps and battery level.",
  "consent.data.content": "Nothing else is collected. You can leave at any time.",
  "consent.review.title": "Review",
  "consent.review.reason": "I have read the information and agree to take part.",
  "consent.done.title": "Thank you",
  "consent.done.text": "Your consent is saved."
}

The three files have the same keys. Only the texts differ. Add as many languages as you need, one file each. Write en.json first, then let an AI tool translate it into the other languages, and have a native speaker check the result. Keep the keys unchanged, only the texts are translated.

Next: Step 2: Run your study