CarpParticipationService

A CARP Core ParticipationService that talks to CAWS.

A participant app uses it first: to find the study invitations of the signed-in user, and to read and write participant data (like informed consent or address) for a study deployment.

Key points:

• A singleton; call configure (or configureFrom) and authenticate with CarpAuthService before use.
• getStudyInvitation can show an ActiveParticipationInvitationDialog to let the user pick an invitation.
• participation returns a ParticipationReference bound to one study deployment, which is the easier way to handle participant data.

The selected invitation gives the study deployment used by CarpDeploymentService to fetch the deployment.

CarpParticipationService().configureFrom(CarpService());
final invitation =
    await CarpParticipationService().getStudyInvitation(context);

Inheritance

• Object
• CarpBaseService
• CarpParticipationService

Implemented types

• ParticipationService

Constructors

CarpParticipationService

CarpParticipationService()

Returns the singleton default instance of the CarpParticipationService. Before this instance can be used, it must be configured using the configure method.

Properties

rpcEndpointName

1. @override

String get rpcEndpointName

override

The name of this service's RPC endpoint at CAWS, like deployment-service.

Methods

getActiveParticipationInvitations

1. @override

Future<List<ActiveParticipationInvitation>> getActiveParticipationInvitations({

1. String? accountId,
2. String? applicationName,

})

override

Gets the list of active participation invitations for an accountId and for an app named applicationName.

Note that the accountId is the unique CARP account id (and not the username). The applicationName is typically the Flutter application name specified in the pubspec.yaml file.

If accountId is not specified, the account id of the currently authenticated CarpUser is used. If applicationName is not specified, all types of applications are considered. Otherwise only invitations whose applicationData holds a matching applicationName are returned.

getParticipantData

1. @override

Future<ParticipantData> getParticipantData(

1. String studyDeploymentId

)

override

Get currently set data for all expected participant data in the study deployment with studyDeploymentId. Data which is not set equals null.

getParticipantDataList

1. @override

Future<List<ParticipantData>> getParticipantDataList(

1. List<String> studyDeploymentIds

)

override

Get currently set data for all expected participant data for a set of study deployments with studyDeploymentIds. Data which is not set equals null.

getStudyInvitation

Future<ActiveParticipationInvitation?> getStudyInvitation(

1. BuildContext context, {
2. bool showInvitations = true,
3. String? device,
4. bool allowClose = false,

})

Gets a study invitation for the current user, letting the user select one if more than one is available.

Returns the selected invitation. Returns null if the user has no invitation(s) or if the user cancels the dialog.

If the user is invited to more than one study and showInvitations is true, an ActiveParticipationInvitationDialog is shown in context. If not, the first invitation is returned. If device is specified, it is used as the applicationName filter of getActiveParticipationInvitations.

allowClose controls whether the dialog can be dismissed by tapping outside it. The Cancel button is always shown.

Throws a CarpServiceException if this service is not configured or no user is authenticated.

participation

ParticipationReference participation([

1. String? studyDeploymentId

])

Gets a ParticipationReference for a studyDeploymentId.

studyDeploymentId can be omitted if specified as part of this service's study.

setParticipantData

1. @override

Future<ParticipantData> setParticipantData(

1. String studyDeploymentId,
2. Map<String, Data> data, [
3. String? inputByParticipantRole

])

override

Set data that was inputByParticipantRole in the study deployment with studyDeploymentId.

If inputByParticipantRole is null, all roles can set it. If you want to set data that was assigned to a specific participant role, inputByParticipantRole needs to be set.

Returns all data for the specified study deployment, including the newly set data.