Apps Sampling Package

carp_apps_package adds two measures to a CARP Mobile Sensing (CAMS) study: the installed apps and how long each app was in the foreground. Use them when a study looks at how participants use their phone.

The package reads the app list with the installed_apps plugin and the usage times from Android's usage statistics with the app_usage plugin.

Features

Measure types

The package has two one-time measure types, which collect once each time their trigger fires:

For the measure types of the other sampling packages, see Measure types.

Requirements

How it works

Adding the package to a study takes three steps:

1. Register the package

   Registering an AppsSamplingPackage in the SamplingPackageRegistry makes the two measure types and their data classes known to CAMS.

2. Add the measures with a repeating trigger

   One-time measures collect only when their trigger fires, so use a trigger that repeats, such as a PeriodicTrigger. App usage also needs its own HistoricSamplingConfiguration, so that each collection continues where the previous one ended, also after an app restart.

3. Deploy and grant usage access

   After you deploy the protocol, CAMS collects both measures each time the trigger fires. For app usage, the participant must also turn on Usage access for the app in Android settings. The app_usage plugin opens that screen when access is missing.

This example registers the package and collects both measures once a day:

import 'package:carp_core/carp_core.dart' hide Smartphone;
import 'package:carp_mobile_sensing/carp_mobile_sensing.dart';
import 'package:carp_apps_package/apps.dart';

void main() {
  CarpMobileSensing.ensureInitialized();
  SamplingPackageRegistry().register(AppsSamplingPackage());

  final phone = Smartphone();
  final protocol = SmartphoneStudyProtocol(
    ownerId: 'owner@example.com',
    name: 'Daily app use',
    dataEndPoint: SQLiteDataEndPoint(),
  )..addPrimaryDevice(phone);

  // One-time measures collect when the trigger fires: here once a day
  protocol.addTaskControl(
    PeriodicTrigger(period: const Duration(days: 1)),
    BackgroundTask(
      measures: [
        Measure(type: AppsSamplingPackage.APPS),
        Measure(
          type: AppsSamplingPackage.APP_USAGE,
          samplingConfiguration: HistoricSamplingConfiguration( 
            past: const Duration(days: 1),
          ),
        ),
      ],
    ),
    phone,
  );

  // ... deploy the protocol and start sampling
}

Next steps