Installation

The package runs on CARP Mobile Sensing (CAMS), so complete the CAMS setup in Installation first. Adding surveys on top of it takes four steps:

1. Add the packages

   flutter pub add carp_core carp_mobile_sensing carp_survey_package research_package
   flutter pub add cognition_package

   carp_survey_package does not re-export the packages it builds on. Add research_package to build your own surveys, and cognition_package only if you add cognitive tests. flutter pub add picks research_package 3.2.0, the newest version that carp_survey_package supports.

2. Configure Android

   research_package 3.x depends on the health plugin, which requires API level 26 or later. Raise minSdk in android/app/build.gradle.kts:

   android {
       defaultConfig {
           minSdk = flutter.minSdkVersion 
           minSdk = 26
       }
   }

   Surveys and cognitive tests need no Android permissions. To ask for health data, for example in an informed consent flow, also set up Google Health Connect. See Android in the Health section.

3. Configure iOS

   The health plugin also links HealthKit into the iOS app. Add the two HealthKit usage descriptions to ios/Runner/Info.plist:

   <key>NSHealthShareUsageDescription</key>
   <string>Your health data is read only if the study asks for it.</string>
   <key>NSHealthUpdateUsageDescription</key>
   <string>The study does not write to Apple Health, but HealthKit requires this description.</string>

   To ask for health data, also add the HealthKit capability: without it, the authorization sheet does not appear. The minimum iOS version stays at 15.0, as for CAMS.

   Warning

   The research_package 4.0.0 release notes report that App Store review rejects apps that link HealthKit without using it. Version 4.0.0 drops the health dependency for this reason, but carp_survey_package 2.1.1 requires 3.x.

   cognition_package plays its sounds with just_audio. Its documentation says that App Store review then asks for a microphone usage description, because the audio session code includes a microphone API. Add NSMicrophoneUsageDescription to Info.plist, or, if the app does not record audio, compile the microphone code out:

   Swift Package ManagerCocoaPods

   Clean the build, then set the environment variable for every build, including flutter build ios:

   flutter clean
   AUDIO_SESSION_MICROPHONE=0 flutter run

   Add the macro to the post_install block of the Podfile. If the block already sets GCC_PREPROCESSOR_DEFINITIONS, for example for permission_handler, add the macro to that list instead.

   post_install do |installer|
     installer.pods_project.targets.each do |target|
       flutter_additional_ios_build_settings(target)
       target.build_configurations.each do |config|
         config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= [
           '$(inherited)',
           'AUDIO_SESSION_MICROPHONE=0'
         ]
       end
     end
   end

4. Register the sampling package

   Register SurveySamplingPackage in main(), before configure():

   import 'package:flutter/material.dart';
   import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
   import 'package:carp_survey_package/survey.dart';
   
   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
     CarpMobileSensing.ensureInitialized();
     SamplingPackageRegistry().register(SurveySamplingPackage());
     await SmartPhoneClientManager().configure();
   
     // ... the rest of your app
   }

   Call CarpMobileSensing.ensureInitialized() before register(): registering a sampling package before CAMS is initialized throws a null check error.

   Registering the package:

   • adds the dk.cachet.carp.survey measure type;
   • registers RPAppTask, RPTaskResultData and all Research Package and Cognition Package classes for JSON deserialization;
   • registers the user task factory that turns a triggered survey, cognition or informed_consent app task into a SurveyUserTask.

   configure() restores the saved studies and survey tasks from JSON, which only works for registered types.

Add optional assets

Two Research Package features read files from fixed paths in your app's assets:

Declare the folders in pubspec.yaml:

flutter:
  assets:
    - assets/audio/
    - assets/lang/

The Research Package example app ships a timer sound, RPTimerStepSound.mp3. CPLocalizations.delegate needs no files in your app. For the translation files, see Translate the survey.

Troubleshooting

import 'package:flutter/material.dart' hide TimeOfDay;

Next step