Installation

The package builds on the CARP Mobile Sensing (CAMS) setup and adds the permissions that its measures need. Set it up in four steps:

1. Add the packages

   flutter pub add carp_core carp_mobile_sensing carp_communication_package

   The package runs on top of CAMS, so complete the CAMS setup in Installation first. The steps below add only what the communication measures need.

2. Configure Android

   Each measure needs its own manifest entries, and CAMS asks the participant for one permission_handler permission per measure:

   Measure	Manifest entries	CAMS asks for
   PHONE_LOG	READ_CALL_LOG and READ_PHONE_STATE, which call_e_log adds by itself	Permission.phone
   TEXT_MESSAGE_LOG	READ_SMS	Permission.sms
   TEXT_MESSAGE	RECEIVE_SMS and the IncomingSmsReceiver receiver	Permission.phone
   CALENDAR	READ_CALENDAR and WRITE_CALENDAR	Permission.calendarFullAccess

   Add the permissions of the measures you use to android/app/src/main/AndroidManifest.xml, directly above <application:

   <uses-permission android:name="android.permission.READ_SMS"/>
   <uses-permission android:name="android.permission.RECEIVE_SMS"/>
   <uses-permission android:name="android.permission.READ_CALENDAR"/>
   <uses-permission android:name="android.permission.WRITE_CALENDAR"/>

   The calendar needs both calendar permissions, although the package only reads: permission_handler and device_calendar_plus refuse calendar access unless both are declared.

   For TEXT_MESSAGE, also declare the receiver of another_telephony inside <application>. It passes incoming messages to the app:

   <receiver android:name="com.shounakmulay.telephony.sms.IncomingSmsReceiver"
       android:permission="android.permission.BROADCAST_SMS"
       android:exported="true">
       <intent-filter>
           <action android:name="android.provider.Telephony.SMS_RECEIVED"/>
       </intent-filter>
   </receiver>

   In version 2.1.0, TEXT_MESSAGE adds no measurements. See Incoming text messages.

   On Android, CAMS starts a measure only when permission_handler reports its permission as granted. permission_handler reports a group as granted only when the participant granted every permission of the group that the merged manifest declares. If your app or another plugin declares more phone permissions, such as CALL_PHONE, the participant must grant them too before PHONE_LOG starts.

   The package needs minSdk 24 or later. If android/app/build.gradle.kts sets a lower value, raise it to 24.

3. Configure iOS

   Only CALENDAR runs on iOS. Add the calendar usage descriptions to ios/Runner/Info.plist:

   <key>NSCalendarsUsageDescription</key>
   <string>This app reads your calendar events for a research study.</string>
   <key>NSCalendarsFullAccessUsageDescription</key>
   <string>This app reads your calendar events for a research study.</string>

   device_calendar_plus refuses to read calendars without NSCalendarsUsageDescription, on every iOS version. iOS 17 or later shows the NSCalendarsFullAccessUsageDescription text when the app asks for full calendar access.

   CAMS asks for calendar access through permission_handler, which includes only the permissions your build enables:

   Swift Package ManagerCocoaPods

   permission_handler_apple enables calendar access when it finds the two keys in Info.plist, so no other change is needed. After you change the keys, delete Xcode's derived data once so that Xcode reads them again:

   rm -rf ~/Library/Developer/Xcode/DerivedData

   Enable calendar access in the post_install block of the Podfile. If the block already sets GCC_PREPROCESSOR_DEFINITIONS, add the two macros to that list:

   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)',
           'PERMISSION_EVENTS=1',
           'PERMISSION_EVENTS_FULL_ACCESS=1',
         ]
       end
     end
   end

   Without calendar access in permission_handler, CAMS cannot ask when the study is deployed, and iOS asks the participant when the calendar measure first runs.

4. Register the sampling package

   Register the package in main(), before you configure the client:

   import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
   import 'package:carp_communication_package/communication.dart';
   
   void main() {
     CarpMobileSensing.ensureInitialized();
     SamplingPackageRegistry().register(CommunicationSamplingPackage());
     // ... 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 makes its four measure types and the JSON types of their data known to CAMS. It also adds its privacy transformers to the default privacy schema. configure() restores the studies saved on the phone and needs these types to read them.

Google Play policy

Google Play treats READ_SMS, RECEIVE_SMS, SEND_SMS and READ_CALL_LOG as restricted SMS and Call Log permissions. Only apps with an approved use can request them, and research is not one of the exceptions.

An app that collects calls or text messages can therefore be rejected. See Google Play's policy on SMS and Call Log permissions.

Two plugins add permissions to every app that depends on the package, also when it only collects the calendar:

To publish an app that collects only the calendar, remove the restricted permissions from the merged manifest. Add the tools namespace to <manifest> and the marked lines:

<manifest xmlns:android="http://schemas.android.com/apk/res/android" xmlns:tools="http://schemas.android.com/tools">
    <uses-permission android:name="android.permission.READ_CALL_LOG" tools:node="remove"/>
    <uses-permission android:name="android.permission.READ_SMS" tools:node="remove"/>
    <uses-permission android:name="android.permission.SEND_SMS" tools:node="remove"/>
    <uses-permission android:name="android.permission.RECEIVE_SMS" tools:node="remove"/>
    <!-- ... the rest of your manifest -->
</manifest>

tools:node="remove" drops a permission even when a plugin's manifest adds it. Use only CALENDAR in the protocols of such an app.

If no other package in the app uses location, remove ACCESS_COARSE_LOCATION the same way. To check the result, open AndroidManifest.xml in Android Studio and select the Merged Manifest tab.

Troubleshooting

Next step