Classes

EmbeddableSurveyViewController

final class EmbeddableSurveyViewController : UIViewController

Presents a MyDataHelps embeddable survey or task inside a web view. This view controller implements the complete user experience for a MyDataHelps survey, including step navigation, sending results to MyDataHelps, etc., and is intended for modal presentation.

Enabling MyDataHelps Embeddable Surveys

In order to use EmbeddableSurveyViewController to present a MyDataHelps embeddable survey, this feature must be enabled for both the project and the survey in MyDataHelps Designer:

  • Enable “Allow Survey Completion Via Link” in project settings.
  • Enable “Allow Task Completion Via Link” and/or “Allow Survey Completion Via Link” in survey settings.

See Completing Surveys with Survey Links for more information.

Initializing and Presenting

Create an EmbeddableSurveyViewController using one of its init methods, identifying the participant by their participantLinkIdentifier and the survey or task by surveyName or taskLinkIdentifier.

For the best user experience, present this view controller modally, and do not wrap it in a UINavigationController, etc. The embedded survey content itself will display all of the controls necessary for navigation, such as localized Cancel/Done buttons.

Completion and Dismissal

Once the participant has finished interacting with the survey, EmbeddableSurveyViewController will invoke the completion callback. The view controller will not dismiss itself. In all cases—success and failure—your completion callback must dismiss the EmbeddableSurveyViewController.

Use the Result object sent to the completion callback to determine whether the survey interaction was successful or failed. If the result is a failure, consider displaying an error alert to the user.

init(client: taskLinkIdentifier: participantLinkIdentifier: completion:)
init(client: MyDataHelpsClient, taskLinkIdentifier: String, participantLinkIdentifier: String, completion: @escaping (Result<EmbeddableSurveyCompletionReason, MyDataHelpsError>) -> Void)

Initializes an EmbeddableSurveyViewController that will display a survey task assigned to a participant.

client

The client through which to access the embedded survey.

taskLinkIdentifier

Identifies the survey task to present to the participant. This is the linkIdentifier property of SurveyTask, as retrieved via ParticipantSession.querySurveyTasks.

participantLinkIdentifier

Auto-generated participant identifier used to complete surveys via link. This is the linkIdentifier property of ParticipantInfo, as retrieved via ParticipantSession.getParticipantInfo.

completion

Called when the participant has completed interaction with the survey. The completion callback must always dismiss the EmbeddableSurveyViewController.

init(client: surveyName: participantLinkIdentifier: completion:)
init(client: MyDataHelpsClient, surveyName: String, participantLinkIdentifier: String, completion: @escaping (Result<EmbeddableSurveyCompletionReason, MyDataHelpsError>) -> Void)

Initializes an EmbeddableSurveyViewController that will display a survey identified by name.

client

The client through which to access the embedded survey.

surveyName

The name of the survey to present.

participantLinkIdentifier

Auto-generated participant identifier used to complete surveys via link. This is the linkIdentifier property of ParticipantInfo, as retrieved via ParticipantSession.getParticipantInfo.

completion

Called when the participant has completed interaction with the survey. The completion callback must always dismiss the EmbeddableSurveyViewController.

MyDataHelpsClient

final class MyDataHelpsClient

Access to the MyDataHelps API endpoints. You can create a single instance of this for the lifetime of your app.

MyDataHelpsClient instances do not track the authentication state or identity of a participant. Use ParticipantSession in conjunction with MyDataHelps client to perform authenticated actions.

SDKVersion
static let SDKVersion: String

Version number for this release of MyDataHelpsKit.

init(baseURL:)
init(baseURL: URL? = nil)

Initializes a newly created client with the specified configuration.

baseURL

Optional. If specified, overrides the base URL to use for MyDataHelps API requests. Production apps should not supply this parameter, and use the default base URL.

ParticipantSession

final class ParticipantSession

Provides a context for performing authenticated actions on behalf of the participant.

An instance of ParticipantSession should be retained for the lifetime of a participant’s access token. Callers are responsible for tracking the state of an access token and renewing as needed.

Asynchronous Behavior

Requests to the MyDataHelps platform are typically asynchronous. All asynchronous requests in ParticipantSession are implemented with a completion parameter of type (Result<ModelType, MyDataHelpsError>) -> Void, where ModelType is the type of the data model object returned upon success. All completion blocks are invoked on the main thread.

init(client: accessToken:)
init(client: MyDataHelpsClient, accessToken: ParticipantAccessToken)

Initializes a new session using an access token.

client

The client to use for all API access by this session.

accessToken

An authentication token. Must be valid and not expired, or all actions performed with this session will fail with authorization failures.

getParticipantInfo(completion:)
func getParticipantInfo(completion: @escaping (Result<ParticipantInfo, MyDataHelpsError>) -> Void)

Retrieves basic information about the participant.

completion

Called when the request is complete, with a ParticipantInfo instance on success or an error on failure.

getProjectInfo(completion:)
func getProjectInfo(completion: @escaping (Result<ProjectInfo, MyDataHelpsError>) -> Void)

Retrieves general project information.

completion

Called when the request is complete, with a ProjectInfo instance on success or an error on failure.

getDataCollectionSettings(completion:)
func getDataCollectionSettings(completion: @escaping (Result<ProjectDataCollectionSettings, MyDataHelpsError>) -> Void)

Retrieves settings related to data collection for the participant and their project.

completion

Called when the request is complete, with a ProjectDataCollectionSettings instance on success or an error on failure.

queryDeviceData(_: completion:)
func queryDeviceData(_ query: DeviceDataQuery, completion: @escaping (Result<DeviceDataResultPage, MyDataHelpsError>) -> Void)

Queries device data for the participant.

To fetch the first page of results, call this with a new DeviceDataQuery object. If there are additional pages available, the next page can be fetched by using DeviceDataQuery.page(after:) to construct a query for the following page.

query

Specifies how to filter the data, and optionally which page of data to fetch.

completion

Called when the request is complete, with a DeviceDataResultPage instance on success or an error on failure. Results are ordered by most recent date.

persistDeviceData(_: completion:)
func persistDeviceData(_ dataPoints: [DeviceDataPointPersistModel], completion: @escaping (Result<Void, MyDataHelpsError>) -> Void)

Creates new and/or updates existing device data points. Each device data point is uniquely identified by a combination of its properties, called a natural key, as identified in DeviceDataPointPersistModel. Data points are always persisted with the project namespace.

To update an existing device data point, persist one whose natural key properties exactly match the one to be updated. All non-natural key properties will be updated to your persisted point.

To add a new device data point, provide enough natural key properties to uniquely identify it. Recommended properties include identifier, type and observationDate; these can be made into a unique combination for most device data points.

dataPoints

A set of data points to persist.

completion

Called when the request is complete, with an empty .success on success or an error on failure.

querySurveyTasks(_: completion:)
func querySurveyTasks(_ query: SurveyTaskQuery, completion: @escaping (Result<SurveyTaskResultPage, MyDataHelpsError>) -> Void)

Query a list of tasks, often used to display a list of certain tasks to a participant.

To fetch the first page of results, call this with a new SurveyTaskQuery object. If there are additional pages available, the next page can be fetched by using SurveyTaskQuery.page(after:) to construct a query for the following page.

query

Specifies how to filter the data, and optionally which page of data to fetch.

completion

Called when the request is complete, with a SurveyTaskResultPage instance on success or an error on failure. Results are ordered by the task creation date.

querySurveyAnswers(_: completion:)
func querySurveyAnswers(_ query: SurveyAnswersQuery, completion: @escaping (Result<SurveyAnswersPage, MyDataHelpsError>) -> Void)

Retrieve past survey answers from QuestionSteps, FormSteps, or WebViewSteps. Often this is used to display past answers to the participant.

To fetch the first page of results, call this with a new SurveyAnswersQuery object. If there are additional pages available, the next page can be fetched by using SurveyAnswersQuery.page(after:) to construct a query for the following page.

query

Specifies how to filter the data, and optionally which page of data to fetch.

completion

Called when the request is complete, with a SurveyAnswersPage instance on success or an error on failure. Results are ordered by answer date.

deleteSurveyResult(surveyResultID: completion:)
func deleteSurveyResult(surveyResultID: String, completion: @escaping (Result<Void, MyDataHelpsError>) -> Void)

Deletes a survey result for a participant. This feature is only available for surveys with “Results Can Be Deleted” enabled. This option can be enabled from the survey editor Settings pane in MyDataHelps Designer.

This operation CANNOT be undone.

surveyResultID

Auto-generated, globally-unique identifier for the survey submission to delete.

completion

Called when the request is complete, with an empty .success on success or an error on failure.

queryNotifications(_: completion:)
func queryNotifications(_ query: NotificationHistoryQuery, completion: @escaping (Result<NotificationHistoryPage, MyDataHelpsError>) -> Void)

Queries the history of notifications sent to this participant.

To fetch the first page of results, call this with a new NotificationHistoryQuery object. If there are additional pages available, the next page can be fetched by using NotificationHistoryQuery.page(after:) to construct a query for the following page.

query

Specifies how to filter the data, and optionally which page of data to fetch.

completion

Called when the request is complete, with a NotificationHistoryPage instance on success or an error on failure. Results are ordered by date.

queryExternalAccountProviders(_: completion:)
func queryExternalAccountProviders(_ query: ExternalAccountProvidersQuery, completion: @escaping (Result<[ExternalAccountProvider], MyDataHelpsError>) -> Void)

Query the list of external account providers supported by MyDataHelps.

query

Specifies how to filter the providers.

completion

Called when the request is complete, with an array of ExternalAccountProvider on success or an error on failure.

connectExternalAccount(provider: finalRedirectURL: completion:)
func connectExternalAccount(provider: ExternalAccountProvider, finalRedirectURL: URL, completion: @escaping (Result<ExternalAccountAuthorization, MyDataHelpsError>) -> Void)

Initiates a new connected external account. Grants access to a secure OAuth connection to the specified external account provider, where the participant can provide their provider credentials and authorize MyDataHelps to retrieve data from the account.

Upon receiving the completion callback, you must present an SFSafariViewController to the user using the secure URL in the callback’s result object to complete the provider authorization flow.

Upon completion of the connection flow in the Safari view, the participant is sent to the finalRedirectURL to indicate that the browser can be dismissed. Your app should intercept this URL via the AppDelegate’s application(_:open:options:) or application(_:continue:restorationHandler:) or the SwiftUI onOpenURL modifier, and programmatically dismiss the SFSafariViewController when the URL is opened. Your app can use a specific path in this URL in order to differentiate it from other URLs your app may support.

The user should also be allowed to manually dismiss the Safari view at any time to cancel the authorization or escape if there is an error. In these cases the finalRedirectURL will not be invoked, but you can use SFSafariViewControllerDelegate to be notified of manual dismissal if needed.

There are two options for configuringfinalRedirectURL:

  • Universal Link, e.g. https://my.app/linkprovidercompletion. The Universal Link domain and path must be fully configured in your app’s entitlements file, the apple-app-site-association file hosted at the my.app domain, etc.
  • Custom scheme, e.g. myapp://linkprovidercompletion. Your app’s Info.plist file must register the scheme myapp in the URL Types list.

Contact CareEvolution support to have your finalRedirectURL added to the list of allowed URLs in MyDataHelps. If the URL is not in the allow list, this API will produce an error result.

provider

The external account provider to connect.

finalRedirectURL

A URL that is configured to open your app via a custom scheme or Universal Link.

completion

Called when the request is complete, with the provider authorization URL and supporting information on success, or an error on failure.

listExternalAccounts(completion:)
func listExternalAccounts(completion: @escaping (Result<[ExternalAccount], MyDataHelpsError>) -> Void)

Fetches a list of all of the participant’s connected external accounts.

completion

Called when the request is complete, with a list of connected accounts on success or an error on failure.

refreshExternalAccount(_: completion:)
func refreshExternalAccount(_ account: ExternalAccount, completion: @escaping (Result<Void, MyDataHelpsError>) -> Void)

Requests the refresh of data from a connected external account.

This API only begins the process of refreshing an account; the process may take additional time to complete. To track the status of a refresh, use ParticipantSession.listExternalAccounts to poll the status value of an account, checking for fetchingData or fetchComplete status values.

account

The external account to refresh.

completion

Called when the request is complete, with an empty .success on success or an error on failure.

deleteExternalAccount(_: completion:)
func deleteExternalAccount(_ account: ExternalAccount, completion: @escaping (Result<Void, MyDataHelpsError>) -> Void)

Deletes an external account.

This API is idempotent: the result will indicate success even if the account was already disconnected, or the participant had no such account.

account

The external account to disconnect.

completion

Called when the request is complete, with an empty .success on success or an error on failure.