Calls and text messages

Three measures collect calls and text messages (SMS) from the phone that runs the study, on Android only. iOS gives apps no access to the call log or to text messages, so CARP Mobile Sensing (CAMS) skips these measures on iOS. Their constants are on CommunicationSamplingPackage:

For the two kinds, see Event-based and one-time measures.

Add the measures to a protocol

A one-time measure collects once each time its task is triggered, so add the two logs with a trigger that repeats:

// Collect the call log every 3 hours
protocol.addTaskControl(
  PeriodicTrigger(period: const Duration(hours: 3)),
  BackgroundTask(
    measures: [Measure(type: CommunicationSamplingPackage.PHONE_LOG)],
  ),
  phone,
);

// Collect the text message log once a day
protocol.addTaskControl(
  PeriodicTrigger(period: const Duration(days: 1)),
  BackgroundTask(
    measures: [Measure(type: CommunicationSamplingPackage.TEXT_MESSAGE_LOG)],
  ),
  phone,
);

The text message log returns every message on each run, so trigger it less often than the phone log.

Configuration

The phone log takes its time window from a HistoricSamplingConfiguration:

past only matters for the first run. Later runs start at lastTime, so each run continues where the previous one ended.

The default configuration lives in memory, so lastTime is lost when the app restarts, and the next run goes back past again. To keep lastTime across restarts, set the configuration on the measure; CAMS then saves it with the deployment:

protocol.addTaskControl(
  PeriodicTrigger(period: const Duration(hours: 3)),
  BackgroundTask(
    measures: [
      Measure(type: CommunicationSamplingPackage.PHONE_LOG)
        ..overrideSamplingConfiguration = HistoricSamplingConfiguration(
          past: const Duration(days: 7),
        ),
    ],
  ),
  phone,
);

This phone log goes back 7 days on its first run and then continues from the previous run, also after a restart. The text message log ignores the configuration.

Phone log

PHONE_LOG reads the Android call log through the call_e_log plugin. Each run adds one PhoneLog measurement with the calls between the start of the window and now, newest first. The window starts at lastTime, or past before now on the first run.

CAMS asks the participant for Permission.phone and starts the measure only when it is granted. The plugin reads the call log with READ_CALL_LOG and READ_PHONE_STATE.

Phone log data

Each PhoneLog holds the window and the calls in it:

Each PhoneCall has these fields; a field without a value is left out of the JSON:

For the measurement envelope around the data, see Measurements and data. Without the privacy schema, the data looks like this:

{
  "__type": "dk.cachet.carp.phonelog",
  "start": "2026-10-25T13:00:00.514Z",
  "end": "2026-10-26T13:00:00.531877Z",
  "phoneLog": [
    {
      "timestamp": "1970-01-21T19:03:22.445",
      "callType": "outgoing",
      "duration": 125,
      "formattedNumber": "+45 25 55 04 46",
      "number": "+4525550446",
      "name": "Jakob"
    }
  ]
}

Text message log

TEXT_MESSAGE_LOG reads the inbox and the sent folder through the another_telephony plugin and adds them as one TextMessageLog measurement. Every run returns all messages in both folders, so consecutive measurements repeat the same messages. Drafts, messages in the outbox, and failed or queued messages are not included.

CAMS asks the participant for Permission.sms and starts the measure only when it is granted. The plugin reads the messages with READ_SMS.

Text message log data

Each TextMessageLog holds the messages:

Each TextMessage has these fields; a field without a value is left out of the JSON:

Without the privacy schema, the data looks like this:

{
  "__type": "dk.cachet.carp.textmessagelog",
  "textMessageLog": [
    {
      "__type": "dk.cachet.carp.textmessage",
      "id": 1234,
      "address": "+4525550446",
      "body": "See you at 5",
      "size": 12,
      "read": true,
      "date": "1970-01-21T18:03:24.087153Z",
      "dateSent": "1970-01-21T18:03:24.085Z",
      "type": "MESSAGE_TYPE_INBOX",
      "status": "STATUS_NONE"
    }
  ]
}

Incoming text messages

TEXT_MESSAGE listens for text messages as they arrive and is meant to add one TextMessage measurement per message. It is event-based: add it with an ImmediateTrigger(), and it listens from when its task starts until the task stops.

CAMS asks the participant for Permission.phone, not Permission.sms, before it starts the measure. The app must declare RECEIVE_SMS and the IncomingSmsReceiver receiver, as described in Installation.

Limitations

• Android only: iOS gives apps no access to the call log or to text messages, so CAMS skips the three measures on iOS.
• Repeated messages: each run of the text message log returns all messages again. Use id to remove the duplicates.
• Restarts: with the default configuration, the first phone log after an app restart goes back past again and can repeat calls from the previous measurement. Set the configuration on the measure, as shown in Configuration.
• Google Play: the call log and SMS permissions are restricted. See Google Play policy.
• Privacy: numbers, names and texts are stored in clear text unless the protocol uses the privacy schema. See Privacy.