iOS SDK
Classes
Structures
- APIRateLimit
- DeviceDataNamespace
- DeviceDataPoint
- DeviceDataPointPersistModel
- DeviceDataPointSource
- DeviceDataQuery
- DeviceDataResultPage
- EmbeddableSurveyCompletionReason
- ExternalAccount
- ExternalAccountAuthorization
- ExternalAccountProvider
- ExternalAccountProviderCategory
- ExternalAccountProvidersQuery
- ExternalAccountStatus
- HTTPResponseError
- NotificationHistoryModel
- NotificationHistoryPage
- NotificationHistoryQuery
- NotificationSendStatusCode
- Organization
- ParticipantAccessToken
- ParticipantDemographics
- ParticipantGender
- ParticipantInfo
- ProjectDataCollectionSettings
- ProjectInfo
- ProjectType
- QueryableDeviceDataType
- SurveyAnswer
- SurveyAnswersPage
- SurveyAnswersQuery
- SurveyTask
- SurveyTaskQuery
- SurveyTaskResultPage
- SurveyTaskStatus
Enumerations
Classes
EmbeddableSurveyViewController
final class EmbeddableSurveyViewController : UIViewControllerPresents 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: MyDataHelpsClient, taskLinkIdentifier: String, participantLinkIdentifier: String, completion: @escaping (Result<EmbeddableSurveyCompletionReason, MyDataHelpsError>) -> Void)Initializes an EmbeddableSurveyViewController that will display a survey task assigned to a participant.
The client through which to access the embedded survey.
Identifies the survey task to present to the participant. This is the linkIdentifier property of SurveyTask, as retrieved via ParticipantSession.querySurveyTasks.
Auto-generated participant identifier used to complete surveys via link. This is the linkIdentifier property of ParticipantInfo, as retrieved via ParticipantSession.getParticipantInfo.
Called when the participant has completed interaction with the survey. The completion callback must always dismiss the EmbeddableSurveyViewController.
init(client: MyDataHelpsClient, surveyName: String, participantLinkIdentifier: String, completion: @escaping (Result<EmbeddableSurveyCompletionReason, MyDataHelpsError>) -> Void)Initializes an EmbeddableSurveyViewController that will display a survey identified by name.
The client through which to access the embedded survey.
The name of the survey to present.
Auto-generated participant identifier used to complete surveys via link. This is the linkIdentifier property of ParticipantInfo, as retrieved via ParticipantSession.getParticipantInfo.
Called when the participant has completed interaction with the survey. The completion callback must always dismiss the EmbeddableSurveyViewController.
MyDataHelpsClient
final class MyDataHelpsClientAccess 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.
static let SDKVersion: StringVersion number for this release of MyDataHelpsKit.
init(baseURL: URL? = nil)Initializes a newly created client with the specified configuration.
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 ParticipantSessionProvides 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: MyDataHelpsClient, accessToken: ParticipantAccessToken)Initializes a new session using an access token.
The client to use for all API access by this session.
An authentication token. Must be valid and not expired, or all actions performed with this session will fail with authorization failures.
func getParticipantInfo(completion: @escaping (Result<ParticipantInfo, MyDataHelpsError>) -> Void)Retrieves basic information about the participant.
Called when the request is complete, with a ParticipantInfo instance on success or an error on failure.
func getProjectInfo(completion: @escaping (Result<ProjectInfo, MyDataHelpsError>) -> Void)Retrieves general project information.
Called when the request is complete, with a ProjectInfo instance on success or an error on failure.
func getDataCollectionSettings(completion: @escaping (Result<ProjectDataCollectionSettings, MyDataHelpsError>) -> Void)Retrieves settings related to data collection for the participant and their project.
Called when the request is complete, with a ProjectDataCollectionSettings instance on success or an error on failure.
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.
Specifies how to filter the data, and optionally which page of data to fetch.
Called when the request is complete, with a DeviceDataResultPage instance on success or an error on failure. Results are ordered by most recent date.
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.
A set of data points to persist.
Called when the request is complete, with an empty .success on success or an error on failure.
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.
Specifies how to filter the data, and optionally which page of data to fetch.
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.
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.
Specifies how to filter the data, and optionally which page of data to fetch.
Called when the request is complete, with a SurveyAnswersPage instance on success or an error on failure. Results are ordered by answer date.
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.
Auto-generated, globally-unique identifier for the survey submission to delete.
Called when the request is complete, with an empty .success on success or an error on failure.
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.
Specifies how to filter the data, and optionally which page of data to fetch.
Called when the request is complete, with a NotificationHistoryPage instance on success or an error on failure. Results are ordered by date.
func queryExternalAccountProviders(_ query: ExternalAccountProvidersQuery, completion: @escaping (Result<[ExternalAccountProvider], MyDataHelpsError>) -> Void)Query the list of external account providers supported by MyDataHelps.
Specifies how to filter the providers.
Called when the request is complete, with an array of ExternalAccountProvider on success or an error on failure.
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 themy.appdomain, etc. - Custom scheme, e.g.
myapp://linkprovidercompletion. Your app’s Info.plist file must register the schememyappin 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.
The external account provider to connect.
A URL that is configured to open your app via a custom scheme or Universal Link.
Called when the request is complete, with the provider authorization URL and supporting information on success, or an error on failure.
func listExternalAccounts(completion: @escaping (Result<[ExternalAccount], MyDataHelpsError>) -> Void)Fetches a list of all of the participant’s connected external accounts.
Called when the request is complete, with a list of connected accounts on success or an error on failure.
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.
The external account to refresh.
Called when the request is complete, with an empty .success on success or an error on failure.
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.
The external account to disconnect.
Called when the request is complete, with an empty .success on success or an error on failure.
