getStudyInvitation method

Future<ActiveParticipationInvitation?> getStudyInvitation(BuildContext context, { bool showInvitations = true, bool allowClose = false, })

Get a study invitation from CARP by allowing the user to select from multiple invitations (if more than one is available).

Returns the selected invitation. Returns null if the user has no invitation(s) or if the user closes the dialog (if allowClose is true).

If the user is invited to more than one study and showInvitations is true, a user-interface dialog for selecting amongst the invitations is shown. If not, the study id of the first invitation is returned.

allowClose specifies whether the user can close the window.

Throws a CarpServiceException if not successful.

Implementation

Future<ActiveParticipationInvitation?> getStudyInvitation(
  BuildContext context, {
  bool showInvitations = true,
  bool allowClose = false,
}) async {
  if (!isConfigured) {
    throw CarpServiceException(
        message:
            "CARP Service not initialized. Call 'CarpService().configure()' first.");
  }

  if (!CarpAuthService().authenticated) {
    throw CarpServiceException(
        message:
            "The current user is not authenticated to CAWS. Call 'CarpAuthService().authenticate...()' first.");
  }

  List<ActiveParticipationInvitation> invitations =
      await getActiveParticipationInvitations();

  ActiveParticipationInvitation? invitation;

  if (invitations.isEmpty) return null;

  if (invitations.length == 1 || !showInvitations) {
    invitation = invitations[0];
  } else {
    if (context.mounted) {
      invitation = await showDialog<ActiveParticipationInvitation>(
          context: context,
          barrierDismissible: allowClose,
          builder: (BuildContext context) =>
              ActiveParticipationInvitationDialog()
                  .build(context, invitations));
    }
  }

  // make sure that the correct study and deployment ids are saved in the app
  CarpService().app.studyId = invitation?.studyId;
  CarpService().app.studyDeploymentId = invitation?.studyDeploymentId;

  return invitation;
}