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.
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:
See Completing Surveys with Survey Links for more information.
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.
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.
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.
static let SDKVersion: String
Version 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.
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.
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
:
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.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.
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.